Uh oh!
There was an error while loading. Please reload this page.
Attributes MVP (experimental and write-only) - #2088
Merged
VaguelySerious merged 26 commits intoMay 28, 2026
Merged
Conversation
Contributor
📊 Benchmark Results
workflow with no steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) workflow with 1 step💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) workflow with 10 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) workflow with 25 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) workflow with 50 sequential steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) Promise.all with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) Promise.all with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) Promise.all with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) Promise.race with 10 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) Promise.race with 25 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) Promise.race with 50 concurrent steps💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) workflow with 10 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) workflow with 25 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) workflow with 50 sequential data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) workflow with 10 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) workflow with 25 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) workflow with 50 concurrent data payload steps (10KB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) Stream Benchmarks(includes TTFB metrics)workflow with stream💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) stream pipeline with 5 transform steps (1MB)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) 10 parallel streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) fan-out fan-in 10 streams (1MB each)💻 Local Development
▲ Production (Vercel)
🔍 Observability: Next.js (Turbopack) SummaryFastest Framework by WorldWinner determined by most benchmark wins
Fastest World by FrameworkWinner determined by most benchmark wins
Column Definitions
Worlds:
❌ Some benchmark jobs failed:
Check the workflow run for details. |
🦋 Changeset detectedLatest commit: 45db5ae The changes in this PR will be included in the next version bump. This PR includes changesets to release 20 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
Contributor
🧪 E2E Test Results✅ All tests passed Summary
Details by Category✅ ▲ Vercel Production
✅ 💻 Local Development
✅ 📦 Local Production
✅ 🐘 Local Postgres
✅ 🪟 Windows
✅ 📋 Other
|
Outlines the bare-MVP, write-only attributes design that defers the `attr_set` event type (and the associated SPEC_VERSION_CURRENT bump) to the full 5.0.0 feature. Forward-compatible SDK surface and wire format. `experimentalSetAttributes` is optional on the World interface so third-party worlds keep working. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Implements the V5 Workflow Attributes MVP per the changelog plan:
- @workflow/world: shared validation + apply helpers; optional
experimentalSetAttributes on Storage.runs; attributes field on
WorkflowRunBaseSchema. Optional so third-party worlds keep working.
- @workflow/core: setAttributes() helper. Detects workflow VM vs step
context, normalizes undefined→null, validates client-side, dispatches
via an internal "use step" function. Feature-detects the world method
and no-ops with a one-time warning if missing.
- @workflow/world-local: file-backed impl with a per-run async mutex
so concurrent writes do not lose updates within a process. Threads
attributes through the run lifecycle event reconstructions so they
survive subsequent run_started/_completed/_failed/_cancelled writes.
- @workflow/world-postgres: jsonb column with SQL-side atomic merge
(jsonb_set / `-`); 0013 migration.
- @workflow/world-vercel: HTTP wrapper posting the documented
{ changes: [...] } body to /v2/runs/:runId/attributes.
Tests: 18 validation unit + 10 SDK unit + 10 world-local integration +
3 world-postgres integration. End-to-end coverage in the workbench is
deferred until the paired workflow-server endpoint is deployed to a
preview.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>The V5 attributes field on WorkflowRunBaseSchema widened the AttributeKey union in web-shared's attribute-panel exhaustive Record, causing the CI Build Packages job to fail. Add a JsonBlock renderer gated on hasDisplayContent so missing/empty maps don't render at all.
CI build error: the umbrella workflow package re-exports \`@workflow/core/_workflow\`, which (via my earlier setAttributes export) transitively pulled \`step/context-storage\` and therefore \`node:async_hooks\`. The workflow VM bundle's no-Node-module constraint rejected it. Split into three modules: - set-attributes-shared.ts: validation + 'use step' dispatcher. No contextStorage import, safe in both bundles. - set-attributes.ts (step/host): looks up runId via contextStorage, falls back to WORKFLOW_CONTEXT_SYMBOL. Re-exported from core/index. - workflow/set-attributes.ts (VM): reads only WORKFLOW_CONTEXT_SYMBOL. Re-exported from core/_workflow. Mirrors the same dual-context layout as getWorkflowMetadata. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The previous design used a 'use step' indirection inside @workflow/core so setAttributes could be called from both workflow and step bodies via a single SDK surface. That broke nextjs-webpack Local Dev: the deferred- entries discoverer in webpack dev mode walks transitive imports from 'use step' files, and putting a step file inside @workflow/core/dist pulled host-side world adapters and @vercel/queue into the step-discovery graph. Webpack's regex-based import extractor then blew the call stack with "RangeError: Maximum call stack size exceeded at RegExpStringIterator.next" on tarball-installed deployments. runtime/start.ts and runtime/run.ts get away with the same directive because they're never reachable from packages/core/src/workflow/index.ts (the VM bundle entry); ours was. A host-side bridge comparable to sleep would have fixed it but is substantial wiring for a feature whose end state (event-sourced attr_set) replaces the bridge mechanism entirely. Pragmatic MVP path: restrict to step body and let users wrap in a step explicitly. Full 5.0.0 lifts the restriction via attr_set events through the workflow controller; SDK signature is stable across the cutover. - Workflow-VM-side setAttributes throws FatalError with wrap-in-step instructions - Step-side setAttributes works (validates, dispatches, world-detects) - set-attributes-shared.ts is now pure validation; no 'use step', no world imports - Test updated to assert the FatalError on workflow-body calls - Changelog MDX updated with the new scope + a "Why workflow-body dispatch is deferred" implementation note Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… setAttributes is "supported via the host-side bridge in `set-attributes.ts`, which calls into an actual step via `registerStepFunction`" — no such bridge or registerStepFunction usage exists. This commit fixes the issue reported at packages/core/src/set-attributes-shared.ts:25 **Bug:** The comment on lines 24-26 of `packages/core/src/set-attributes-shared.ts` describes an intermediate design approach that was abandoned before the final implementation. It states: "workflow-body use is supported only via the host-side bridge in `set-attributes.ts`, which calls into an actual step via `registerStepFunction`." In the actual final implementation: 1. `packages/core/src/workflow/set-attributes.ts` (the workflow-VM-side export) unconditionally throws `FatalError` — there is no bridge support at all. 2. `packages/core/src/set-attributes.ts` (the host-side export) explicitly checks for workflow-body context and throws `FatalError` with a message telling users to wrap the call in a `'use step'` function. 3. A grep for `registerStepFunction` in combination with `setAttributes` returns zero results — no such wiring exists. The comment is misleading to any developer reading the codebase: it implies workflow-body use works via a bridge mechanism, when in fact it throws a fatal error. **Fix:** Updated lines 24-26 to accurately describe the actual behavior: "workflow-body use throws FatalError — users must wrap the call in their own `'use step'` function." This aligns with the implementation in both `set-attributes.ts` and `workflow/set-attributes.ts`, and with the JSDoc on `setAttributes` which explicitly documents the step-body-only restriction and the workaround pattern. Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com> Co-authored-by: VaguelySerious <mittgfu@gmail.com>
For local e2e validation against the workflow-server attributes-mvp preview deployment. Do not merge — this constant must be empty on main. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…n step Workflow-body `setAttributes` calls now dispatch through an internal `__builtin_set_attributes` step rather than throwing FatalError. The workflow-VM helper validates input and then invokes a host-side useStep dispatcher pre-bound under WORKFLOW_SET_ATTRIBUTES; the step body forwards to the same world adapter call the step-body path uses. Putting the 'use step' directive inside `packages/workflow/src/internal/builtins.ts` (next to the existing `__builtin_response_*` builtins) instead of `@workflow/core/dist/` avoids the deferred-entry discoverer hazard that motivated the prior MVP-only step-body restriction. - Add `WORKFLOW_SET_ATTRIBUTES` symbol + workflow.ts wiring - New `step-set-attributes.ts` host helper (`applySetAttributesChanges`) shared between step-body and workflow-body paths - `__builtin_set_attributes` builtin step - Refactor workflow-side `setAttributes` to dispatch via the bridge - Update changelog MDX + add tests (16 unit, 2 e2e) - e2e workflows `setAttributesFromStepWorkflow` and `setAttributesFromWorkflowBodyWorkflow` cover both paths Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The comment described the prior FatalError-on-workflow-body workaround; update it to reflect the current bridge-via-builtins design. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…verer
`__builtin_set_attributes` dynamically imported
`@workflow/core/_step-set-attributes` as a literal string. The Next.js
deferred-entries discoverer in `@workflow/next/builder-deferred.ts`
matches `import('...')` regex-style and walks the resolved file's
transitive imports — which reach the world adapter and `@vercel/queue`,
triggering `RangeError: Maximum call stack size exceeded` inside
`RegExpStringIterator.next` on tarball-installed nextjs-webpack
builds. The build never completes, so dev-mode e2e tests time out
across the board.
Assemble the specifier at runtime (same trick `get-world-lazy.ts`
uses for `./world.js`) so the discoverer doesn't see a literal target.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>…idge The runtime-built specifier broke step bundle resolution across every framework — `Cannot find package '@workflow/core' imported from .../node_modules/.nitro/workflow/steps.mjs`. Bundlers can't statically resolve a concatenated string, so the dependency never lands in the step bundle and Node's loader fails at runtime. Reverts fbb0c59. The original webpack-dev discoverer-overflow it tried to fix only affected 3 jobs; this regression took down 30+ jobs across all frameworks. The discoverer issue needs a different fix. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ngle dispatch path
Drops step-body support for the MVP. The architecture becomes:
- workflow VM `setAttributes` validates inline and dispatches via the
standard `globalThis[WORKFLOW_USE_STEP]('__builtin_set_attributes')`
mechanism — same as every other step call from a workflow body
- host-side `setAttributes` is a stub that throws FatalError telling
callers to use a workflow body
- `__builtin_set_attributes` step body reads world + run id directly
from `globalThis` symbols populated by the runtime, with no imports
from `@workflow/core`
This deletes the bridge plumbing the previous design needed:
- `WORKFLOW_SET_ATTRIBUTES` global symbol + the workflow.ts pre-bind
- `packages/core/src/set-attributes-shared.ts` (normalize helper)
- `packages/core/src/step-set-attributes.ts` (host-side helper)
- the `@workflow/core/_step-set-attributes` package export and the
dynamic import that pulled it in from the step bundle
Side benefit: the Next.js deferred-entries discoverer can no longer
walk from `__builtin_set_attributes` into the world adapter / queue
chain that broke webpack-dev builds in the previous shape, because the
step body holds zero @workflow/core imports.
Workbench example and e2e tests reduced to a single
`setAttributesWorkflow` covering workflow-body dispatch. World-side
implementations are unchanged; step-body support can be added later
without touching the workflow-body contract.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>`extractBundleSourceFiles` used `matchAll` with `/...[A-Za-z0-9+/=]+.../g` to pull inline base64 source maps out of generated bundles. V8's irregexp uses recursion for greedy character-class quantifiers, and on bundles with multi-MB inline sourcemaps the engine exhausts the stack mid-match with `RangeError: Maximum call stack size exceeded at RegExpStringIterator.next`. That broke nextjs-webpack-dev e2e jobs on this branch after main enabled inline sourcemaps across all workspace packages (#1799). Switch to a literal-prefix scan with a manual base64 alphabet loop — linear time, no recursion. The character-code check inlines what the regex was doing (`[A-Za-z0-9+/=]`), so behaviour is unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… post-merge cap - Rename the public SDK export from `setAttributes` → `experimental_setAttributes` to signal the unstable surface at every call site (workbench, docs, e2e + unit tests updated). Internal step name stays `__builtin_set_attributes`. - `validateAttributeChanges`: replace `existingCount?: number` with `existingKeys?: Iterable<string>`. With keys, the cap check uses real net adds/deletes (an update to an already-present key is zero net); without keys it falls back to the conservative "every upsert is +1" shape. Fixes the off-by-design rejection of single-key updates at the cap boundary. - `world-local`: rename `withRunAttributeLock` → `withRunFileLock`, export it, and acquire it from the events-storage run-lifecycle branches (`run_started`/`run_completed`/`run_failed`/`run_cancelled`). Each lifecycle write re-reads the run JSON inside the lock so an attribute write that landed between the pre-validation read and the write is no longer silently overwritten. - `world-postgres`: atomic per-run cap. The cap check now lives in the same `UPDATE` statement as the merge (`WHERE (SELECT COUNT(*) FROM jsonb_object_keys(merged_expr)) <= ATTRIBUTE_MAX_PER_RUN`), so two concurrent writers adding disjoint keys at the cap boundary can no longer both succeed and push the row past 64. A separate re-read on rejection disambiguates "run not found" from "cap rejected". - `__builtin_set_attributes`: one process-wide `console.warn` when the active world adapter doesn't implement `experimentalSetAttributes`, matching the changelog and `Storage.runs.experimentalSetAttributes` JSDoc. Verified #17 (bare-name step lookup) by precedent: the SWC plugin already special-cases names starting with `__builtin` at `naming.rs`-adjacent path in `lib.rs:1906` to use the bare function name as the step ID, which is exactly how `__builtin_response_json` etc. ship today. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…nderLifecycleLock The previous shape took `(baselineRun, overrides)` and spread them inside the helper, which collapses the run's discriminated union (`status: 'pending' | 'running' | 'completed' | ...`) into an unassignable intersection. tsc rejected the call sites in CI. Switch the helper to take an already-constructed `WorkflowRun` and a generic `<T extends WorkflowRun>` so the caller-side narrowing survives. Each lifecycle branch builds the full run object inline (as it did before the lock refactor) and the helper only swaps in the freshest `attributes` snapshot from the on-disk read. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…-after e2e tests, normalize empty attributes - Revert WORKFLOW_SERVER_URL_OVERRIDE to '' now that workflow-server PR #442 has shipped to production. - Normalize attributes to `{}` after Zod parse (was optional, so world-local returned undefined while world-postgres returned `{}`). Run construction sites in world-local (events-storage + legacy) seed `attributes: {}` on `run_created`. - Add three new e2e workflows + tests in workbench/nextjs-turbopack exercising the world-vercel wire path against the production endpoint: 1. Fire-and-forget (`void experimental_setAttributes`) 2. Promise.all of disjoint-key writes 3. Workflow throws after an awaited setAttributes (attribute persists on the failed run via the per-run file lock) - Add cap-boundary and idempotency unit tests in world-local. - Document the three call patterns (awaited / fire-and-forget / Promise.all) explicitly in the changelog. Includes the honest caveat: a `void` call placed immediately before `return` with no intervening await on a runtime primitive will not land — drain on completion commits `step_created` but doesn't queue the step body. In practice workflows always have an await after the last fire-and-forget call (a step, a sleep, a hook). - Refresh the changelog's Test coverage section to reflect what actually ships; drop the stale "e2e deferred" line; tighten the Concurrent writes section so the awaited-call serialization claim doesn't generalize to Promise.all / fire-and-forget. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…created events
`drainPendingQueueItems` calls `handleSuspension` to commit `step_created` /
`hook_created` / `wait_created` events for any operations the workflow body
spawned but didn't await. The drain commit message claimed "Unawaited steps
and sleeps are queued (will execute / fire later)" but in practice only the
event was committed — the step body was never enqueued for execution,
because `handleSuspension`'s comment explicitly says
> Unlike V1, we do NOT queue step messages from here — the caller decides
> which steps to execute inline vs. queue to background.
The normal runtime loop in `runtime.ts:1019` iterates the returned
`pendingSteps` and calls `queueMessage` for each one. The drain caller in
`workflow.ts` discarded the return value and never queued, so fire-and-forget
step calls with side effects (`void experimental_setAttributes(...)`,
`void someStep()` placed right before `return`) committed step_created but the
step body never ran.
Existing fire-and-forget consumers in the codebase didn't catch this:
- Abort hooks work via `hook_received` whose landing is itself the abort
signal (no queue worker needed).
- `void sleep('Xs')` has no observable side effect when no one awaits it.
setAttributes is the first fire-and-forget consumer with a real side effect
(the row write), so it exposed the gap. The fix mirrors `runtime.ts`'s
post-suspension enqueue: iterate `pendingSteps`, filter by
`createdStepCorrelationIds` (only enqueue steps THIS drain owns — concurrent
crash-recovery handlers dedupe via the correlationId idempotency key), and
fire `queueMessage` calls in parallel.
Also drops the workaround in the fire-and-forget e2e workflow (the trailing
`await sleep('100ms')` that papered over the gap) and the changelog caveat
that warned users about the "last void before return won't land" footgun.
Both are no longer relevant.
Verified by:
- `pnpm --filter '@workflow/core' test` — 1020/1020 pass
- The e2e fire-and-forget workflow now drops three `void` calls (the third
immediately before `return`) and asserts all three attributes land
- CI will exercise the full path against the deployed Vercel preview /
production workflow-server
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>…o, revert drain queueing Investigation showed the drain queueMessage addition (f46faa1) is dead code in practice: the step worker calls `executeStep` → `world.events.create('step_started')`, which the platform rejects with `RunExpiredError` (HTTP 410) once the run has transitioned to terminal. By the time the queue worker picks up a message queued by drain, `run_completed` has landed and the worker logs "Workflow run X has already completed, skipping step Y" (step-executor.ts:165) and returns `{ type: 'gone' }`. The step body never executes. For attribute writes specifically, the side effect bypasses the event log (direct row update), so running against a terminal run would be safe — but the platform doesn't special-case `__builtin_set_attributes`. Either the worker needs to keep accepting step_started for drain-queued steps, or attributes need a non-step dispatch path (planned for V1 with the attr_set event type). Changes: - Revert the drain queueMessage logic in workflow.ts. Keep the doc comment honest about what drain does and doesn't do. - Mark the fire-and-forget e2e test as `test.todo` with a detailed TODO explaining the platform-level issue and what's needed to fix it. - Workbench workflow keeps the no-final-sleep shape — it's the eventual contract we want to support; the .todo flags that the test will start passing once the platform-level fix lands. - Update the changelog "Usage patterns" section to honestly document the last-void-before-return limitation. Mid-workflow fire-and-forget (the common case for tracking attributes) works correctly via the regular suspension path. CI before this commit had 1 PR-related failure (`fire-and-forget` on every adapter). That's now marked .todo. Other 54 failures are pre-existing on nextjs-webpack and unrelated to this PR. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The "Awaited / Fire-and-forget / Promise.all" examples in the MVP changelog
reference free-floating identifiers (`processOrder`, `result.id`, `orderId`)
that aren't in scope as written — they're illustrative snippets, not runnable
code. Add `{/*@skip-typecheck - snippet, not runnable code*/}` directives
matching the existing usage above (interface and SDK examples). Also tighten
the Promise.all snippet to use a literal `'ord_123'` rather than a bare `id`.
Caught by the Docs Code Samples CI job.User code calling experimental_setAttributes({ '$foo': 'bar' }) continues
to throw FatalError — the $ namespace is reserved for framework / library
code (telemetry tags, agent metadata, future platform attributes) and
accidental collisions there break tooling.
Framework callers that own a $-prefixed sub-namespace can now opt in
per-call: experimental_setAttributes({'$kind':'agent'}, {allowReservedAttributes: true}).
The flag is per-call (no run-level mode), so each call site explicitly
declares intent. SDK TSDoc warns this is framework-only and misuse can
conflict with observability surfaces.
Plumbing:
- validateAttributeKey / validateAttributeChanges accept
allowReservedAttributes. Default false at every layer.
- SDK helper takes a 2nd ExperimentalSetAttributesOptions argument and
forwards the flag to the step body via useStep('__builtin_set_attributes').
- World interface method gains a 3rd options argument. world-local and
world-postgres pass through to validateAttributeChanges. world-vercel
forwards in the HTTP body.
- Host-side stub keeps the matching signature for type consistency
(still throws — outside workflow body).
Tests:
- @workflow/world unit tests: accept reserved keys with opt-in, reject
without, reject when explicitly false (both validateAttributeKey and
validateAttributeChanges).
- @workflow/core SDK tests: opt-in dispatches with the flag, default
rejects, explicit false still rejects.
- @workflow/world-local integration test: framework write succeeds with
the opt-in; a follow-up write without the opt-in still rejects
(per-call, not sticky).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>Signed-off-by: Peter Wielander <mittgfu@gmail.com>
karthikscale3
approved these changes
May 28, 2026
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.
Implements the Workflow Attributes MVP — a minimal, write-only attributes API designed to land before the full event-sourced attributes feature in #1933 (which requires a
SPEC_VERSION_CURRENTbump and coordinated rollout across worlds, builders, and runtime).User surface:
Attributes are stored plaintext on the
WorkflowRunentity and visible viaworld.runs.get()/world.runs.list()(and any observability surface built on top). The wire format mirrors the futureattr_setevent'seventData.changes, so the SDK signature and wire body shape are stable across MVP → 5.0.0.experimental_setAttributesis callable from a workflow body only in this MVP. The call is dispatched through an internal__builtin_set_attributesstep bridge so the mutation gets astep_created → step_completedevent pair without inventing a new event type. The host-side export (resolved from step bodies or plain host code) throwsFatalErrordirecting the caller back to a workflow body — step-body support is a follow-up, not a hard architectural constraint.The public surface uses the
experimental_prefix so every call site signals "this WILL change" — when V1 lands the rename tosetAttributesdoubles as a forcing function for consumers to re-review the new contract.See
docs/content/docs/v5/changelog/attributes-mvp.mdxfor the full design, trade-offs, and implementation notes — including the call patterns (awaited, fire-and-forget, Promise.all), the platform-level limitation on fire-and-forget calls placed immediately beforereturn, and the decisions made during build-out (endpoint namespacing, concurrency semantics, usage-fact schema choice, optional-world fallback behavior, etc.).Paired with vercel/workflow-server#442 (merged) which adds the server-side
POST /api/v2/runs/:runId/attributesendpoint, ElectroDB column, and the newWORKFLOW_ATTRIBUTEusage-fact carrying the post-merge map.What's in this PR
@workflow/worldapplyAttributeChangeshelper. OptionalexperimentalSetAttributesonStorage.runs.attributesfield onWorkflowRunBaseSchemadefaults to{}after Zod parse, so consumers always receive a record regardless of world.@workflow/coreexperimental_setAttributes(record). VM-side helper validates inline and dispatches via the standardWORKFLOW_USE_STEPmechanism — no new global symbols, no bridge plumbing. Host-side export is aFatalError-throwing stub for non-workflow-body callers.workflowpackage__builtin_set_attributesstep body ininternal/builtins.ts. Reads world + run id directly fromglobalThissymbols populated by the runtime; zero imports from@workflow/coreso it stays a true leaf in the deferred-entries graph. Emits a one-timeconsole.warnif the active world adapter doesn't implementexperimentalSetAttributes.@workflow/world-localwithRunFileLock) extended to lifecycle handlers (run_started/run_completed/run_failed/run_cancelled) so an attribute write that lands between the pre-validation read and the lifecycle write is preserved. New runs seedattributes: {}so reads are uniform.@workflow/world-postgresattributes jsonbcolumn (migration0013_add_attributes.sql). SQL-side atomic merge usingjsonb_set/-operators in a singleUPDATE. Per-run cap is enforced atomically inside theUPDATE'sWHEREclause (COUNT(jsonb_object_keys(merged)) <= 64), so concurrent disjoint-key writers can't push the row past the cap.@workflow/world-vercel{ changes: [...] }to/v2/runs/:runId/attributes.docs/content/docs/v5/changelog/attributes-mvp.mdxwith full design + implementation notes + the three call patterns.Architecture (workflow-body dispatch)
experimental_setAttributes(attrs)from'use workflow'body.workflowpackage-exports condition topackages/core/src/workflow/set-attributes.ts, which validates the input inline and produces canonicalAttributeChange[].globalThis[WORKFLOW_USE_STEP]('__builtin_set_attributes')(changes)— same mechanism every other step call uses. The SWC plugin already special-cases__builtin*step names (packages/swc-plugin-workflow/transform/src/lib.rs:1906) to register them with the bare function name so the bare-name lookup at dispatch time resolves.__builtin_set_attributes(inpackages/workflow/src/internal/builtins.ts). The step body reads the world fromglobalThis[Symbol.for('@workflow/world//cache')]and the active run id fromglobalThis[Symbol.for('WORKFLOW_STEP_CONTEXT_STORAGE')], then callsworld.runs.experimentalSetAttributes(runId, changes). No imports from@workflow/core— this is what keeps the Next.js deferred-entries discoverer from walking into world adapters and triggering webpack's regex-extractor stack overflow.Validation rules
Shared helper (
@workflow/world/attributes.ts) used by both the SDK (in the VM, before dispatch) and the world (after the change reaches it):$(reserved for future system use)nullfor unset)existingKeysparameter onvalidateAttributeChanges). An update to an existing key counts as +0 net adds, so a run at the cap can still update its own keys.Violations throw
FatalErrorfrom@workflow/errors.Call patterns supported
Awaited (default). Workflow blocks on the write.
Fire-and-forget (
void). Drop theawait. The pending step queues on the workflow's next suspension. Canonical pattern for observability metadata where the workflow doesn't depend on the write.Parallel (
Promise.all). Disjoint-key writes all land; same-key writes are LWW-by-arrival.Known limitation:
voidcalls placed immediately beforereturnare not reliably executed. Drain commits thestep_createdevent, but by the time the queue worker dequeues the message the run has transitioned tocompletedand the worker rejectsstep_startedwithRunExpiredError. The fire-and-forget e2e test for this exact case is markedtest.todowith an explanatory TODO; mid-workflow fire-and-forget (the common case for tracking attributes) works correctly via the regular suspension path. Resolving this needs either platform-side support forstep_startedon drain-queued steps or a non-step dispatch path for attributes (planned for V1 alongside theattr_setevent type).What's NOT in this PR (not in MVP)
experimental_setAttributesfrom a step body or plain host code (throwsFatalError; can be added later — it's a scope cut, not an architectural constraint)getAttribute/getAttributes)start(workflow, input, { attributes })(initial attributes at run creation)runs.list({ attributes }),listAttributeKeys,listAttributeValues)attr_setevent type$-prefixed) namespace (just blocked at validation today)voidimmediately beforereturn(see above)Test coverage
Unit tests in
@workflow/world(validation) and@workflow/core(VM-side dispatch + host-side stub). Integration tests inworld-local(upsert / merge / unset / set-and-unset / cap-boundary updates / idempotency / concurrent writes via the per-run mutex / validation rejection) andworld-postgres(upsert / merge / unset, exercising the SQL-sidejsonb_set/-chain and the atomic cap enforcement in theWHEREclause).E2E in
workbench/nextjs-turbopackexercises the full SWC plugin + workflow VM + step worker +world-vercelwire path against the production workflow-server/v2/runs/:runId/attributesendpoint:__builtin_set_attributesstep bridge and merge correctly (also asserts thestep_created/step_completedpair lands on the event log)Promise.allof disjoint-key writes — every key persistsexperimental_setAttributes— the attribute persists on the now-failedrun (verifies the per-run file lock onrun_failedre-reads inside the critical section so attribute snapshots survive the lifecycle write)test.todopending the platform-level fix described above