Uh oh!
There was an error while loading. Please reload this page.
Add allowReservedAttributes option to start() - #2385
Merged
Conversation
experimental_setAttributes already exposes allowReservedAttributes for framework-level callers that own a $-prefixed sub-namespace, and the run_created / run_started event schemas plus the local and Postgres worlds already accept and validate the flag. start() was the one gap: it always validated initial attributes with the reserved prefix disallowed and had no way to opt out, so framework code could not seed reserved attributes at run creation. Thread the option through start(): - StartOptions.allowReservedAttributes, passed to client-side validation and forwarded on the run_created eventData - carried in the queue runInput (new RunInputSchema field) and forwarded to run_started so the resilient/lazy run creation path validates identically Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
🦋 Changeset detectedLatest commit: 0698fa2 The changes in this PR will be included in the next version bump. This PR includes changesets to release 21 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Contributor
📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express workflow with 1 step💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro | Express workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro workflow with 25 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) Promise.all with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express Promise.all with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Nitro | Express Promise.race with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) | Express | Nitro Promise.race with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 10 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express workflow with 25 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 50 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 10 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Nitro | Next.js (Turbopack) | Express workflow with 25 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) workflow with 50 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) Stream Benchmarks(includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) stream pipeline with 5 transform steps (1MB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) 10 parallel streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Nitro | Next.js (Turbopack) fan-out fan-in 10 streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Express | Next.js (Turbopack) | Nitro SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
|
Contributor
🧪 E2E Test Results✅ All tests passed Summary
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
✅ 📋 Other
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR extends the start() API to optionally permit reserved $-prefixed attribute keys at run creation time (for framework/library callers), and ensures the same behavior is preserved for the resilient-start (queue → run_started) creation path.
Changes:
- Add
StartOptions.allowReservedAttributesand thread it through client-side attribute validation instart(). - Carry
allowReservedAttributesthrough the queuerunInputand intorun_startedeventData for resilient run creation. - Add unit tests and update v5
start()documentation and package changesets.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| packages/world/src/queue.ts | Extends RunInputSchema to optionally carry allowReservedAttributes (as true) alongside seeded attributes. |
| packages/core/src/runtime/start.ts | Adds allowReservedAttributes option, uses it during normalization/validation, and forwards it on run_created + queue runInput. |
| packages/core/src/runtime/start.test.ts | Adds coverage verifying flag presence/absence and that non-reserved validation still applies when the flag is enabled. |
| packages/core/src/runtime.ts | Forwards runInput.allowReservedAttributes into run_started eventData for resilient run creation. |
| docs/content/docs/v5/api-reference/workflow-api/start.mdx | Documents reserved $ keys and the allowReservedAttributes escape hatch for framework-level callers. |
| .changeset/start-allow-reserved-attributes.md | Declares a minor bump for the relevant packages to ship the new option and schema support. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…ributes Verified locally against the nextjs-turbopack dev server: the reserved key passes client and server validation, lands on the run at creation, and survives the workflow's own attr_set writes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
TooTallNate
approved these changes
Jun 12, 2026
TooTallNate
left a comment
Member
There was a problem hiding this comment.
Approve — minimal, correct gap-closure; every claimed precondition verified
This is the right shape for this change: the wire format and storage layers already supported seeding reserved attributes at creation — only the public start() API lacked the escape hatch. I verified each "already supported" claim in the PR description against the code:
normalizeAttributeChanges(attrs, { allowReservedAttributes })— the options parameter and semantics already exist (added with the attributes MVP), so client-side validation is byte-identical to theexperimental_setAttributespath ✓run_created,run_started, andattr_setevent schemas all already carryallowReservedAttributes: z.literal(true).optional()✓- world-local honors the flag on both creation paths (
events-storage.tshandles it forrun_createdand the resilientrun_startedbootstrap) ✓
So this PR is genuinely just threading: StartOptions → client validation → run_created eventData → queue runInput → resilient run_started eventData.
What I particularly like
- The resilient-start path is handled, not forgotten. The subtle failure mode here would be:
run_createdis lost, the run bootstraps from the queue message viarun_started, and the server-side validation rejects the reserved keys because the flag didn't ride along — making resilient starts behave differently from normal ones for exactly the callers using this option. The sharedattributeSeedobject + theRunInputSchemafield + theruntime.tsforwarding close that loop, and the unit test asserts the flag lands on both payloads. z.literal(true).optional()matches the established event-schema style — the flag is eithertrueor absent, neverfalsenoise on the wire, and the...(allowReservedAttributes ? { allowReservedAttributes: true as const } : {})spread keeps the payloads clean in the default case (also pinned by the not-requested test).- The negative test matters most:
still enforces non-reserved validation rules when allowReservedAttributes is setproves the flag only bypasses the$-prefix check, not size caps — the escape hatch doesn't accidentally become a validation bypass. - The option docstring is the best namespace-ownership explanation in the attributes surface so far ("only flip this to
trueif your caller is itself a framework or library that owns a$-prefixed sub-namespace"). - The e2e test smartly reuses
experimentalSetAttributesWorkflowand asserts the seeded reserved key survives the workflow's ownattr_setwrites — covering the merge path, not just creation. - No v4 docs this time — correctly scoped to v5 only, since attributes are a v5/spec-4 surface. (A pleasant break from the recurring sequencing flag.)
Verified locally
- 27 start tests, full core suite (1189), and world suite (50) all pass
- Docs link target (
experimental-set-attributes.mdx) exists - Changeset covers exactly the changed packages (
workflow/@workflow/corefixed pair +@workflow/world), allminor— correct for new API surface
One observation (no action needed)
Version-skew safety of the new RunInputSchema field: an older consumer parsing a queue message with the extra field would silently strip it (Zod non-strict) and reject the reserved keys on the resilient path — but queue messages are deployment-pinned to the SDK that enqueued them, so producer and consumer can't skew. Worth knowing, not worth changing.
CI fully green. LGTM.
Contributor
No backport to This change builds directly on the native run-attributes surface introduced only on To override, re-run the Backport to stable workflow manually via |
This was referenced Jun 13, 2026
pranaygp added a commit
that referenced
this pull request
Jun 13, 2026
…docs-run-idempotency * origin-https/main: test: e2e coverage for run-idempotency conflict-handling strategies (#2387) fix(docs): repair broken links, fix the link linter, and version-correct v5 Card + edit links (#2391) feat(web-shared): RelativeTimeCard with shared ContextCard provider (#2328) Add allowReservedAttributes option to start() (#2385) # Conflicts: # docs/content/docs/v4/cookbook/common-patterns/idempotency.mdx # docs/content/docs/v5/cookbook/common-patterns/idempotency.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
#2226 added
start(..., { attributes })to seed plaintext attributes at run creation, but always validates them with the reserved$prefix disallowed and exposes no opt-out. That leaves a gap relative to the rest of the attributes surface:experimental_setAttributesaccepts{ allowReservedAttributes: true }for framework-level callers, and therun_created/run_startedevent schemas plus the local and Postgres worlds already accept and validate the flag — so the wire format supports seeding reserved attributes at creation, just not through the publicstart()API.This closes that gap by threading the same option through
start():StartOptions.allowReservedAttributes(same semantics and guidance as theexperimental_setAttributesoption) is passed to client-side validation and forwarded on therun_createdeventData.runInput(new optional field onRunInputSchema) and is forwarded into therun_startedeventData, so the resilient-start path (run bootstrapped from the queue message whenrun_createdwas missed) validates the seeded attributes identically to the original attempt.No world changes needed — world-local and world-postgres already honor
allowReservedAttributeson both therun_createdandrun_startedcreation paths.This unblocks framework-level use cases like cross-run lineage (#2153,
$rootRunId/$parentRunId) that need reserved keys present from creation time.Testing
pnpm --filter @workflow/core testpnpm exec turbo run typecheck test --filter=@workflow/world --filter=@workflow/core --filter=@workflow/world-localrun_createdand the queuerunInput; flag absent from both payloads when not requested; size/cap validation still enforced with the flag set; reserved keys still rejected without the flag (existing test).start()with a$-prefixed key +allowReservedAttributes: truecompletes, the reserved key is persisted on the run, and it survives the workflow's ownattr_setwrites.InitialRunAttributesSchema) and forwards it on its own resilient path, so no server change is needed.Docs Preview
start()API reference🤖 Generated with Claude Code