* test(core): reproduce lazy resume disposal race
* Fix durable hook resume race
* Fail closed on unknown hook wakes
* Improve unsupported hook wake diagnostics
* Address durable hook resume review feedback
* Harden producer-committed wake handling
* Serialize durable hook resume: write, then wake
resumeHook() now dispatches strictly serially: the hook_received event
is made durable first, and the workflow wake is published only after
the write is acknowledged. The wake is a plain runId message (the shape
the sequential path always published), so the producer-committed wake
barrier, its queue-message field, and the HOOK_RESUME_INPUT_VERSION
bump are all removed — no consumer or backend coordination is needed,
and either side rolls back independently to today's behavior.
The pre-write ops flush now partitions serialization ops: producer-push
uploads are awaited before the event commits (the payload must not
point at bytes still in flight), while consumer-settled reader ops — a
dehydrated WritableStream, e.g. a manual webhook's responseWritable —
are backgrounded. Awaiting those deadlocked the resume against its own
wake (webhookWorkflow failing across the whole e2e matrix).
Also: wake retries stop on definitive 4xx errors instead of burning the
retry budget; WORKFLOW_DISABLE_LAZY_HOOK_RESUME no longer gates
anything and is ignored; the internal resumeHookDurable alias is
removed.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Address review: retry classification, wake dedup, 409 passthrough
- Wake retry classification now actually fires against @vercel/queue:
its errors carry no status field, so classify by the World's
deployment-unavailable hook, then numeric status, then the queue
client's definitive-4xx error names.
- The wake publish carries idempotencyKey `hook-<resumeId>` on the
claim path, so a retried publish whose response was lost dedups
instead of costing a duplicate full replay.
- EntityConflictError (HTTP 409) from the durable write is no longer
re-keyed to HookNotFoundError: every 409 the backend emits on this
write today is transient (slot conflict past the server's retry
budget, claim race) and committed nothing, so it surfaces retryable
instead of presenting as a permanent 404.
- Stamp workflow.hook.resume_committed / wake_published span
attributes after each leg resolves, making stranded resumes
(committed event, no wake) queryable from traces.
- Document on the public resumeHook signature that passing the token
(not a cached Hook) is what makes the write idempotent-on-retry.
- Changeset/changelog: note the ended-run behavior change (late
webhook deliveries to finished runs now 404 instead of 202) and the
409 passthrough.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Pranay Prakash <pranay.gp@gmail.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* [core] Make a duplicate attr_set inert instead of terminal
A workflow-body attribute write draws a correlation id that resolves exactly
once: the dispatcher's consumer takes the matching event and deregisters. A
second event under that id therefore has no callback left and never will.
`attr_set` had no entry in ENTITY_EVENT_CLASS_BY_TYPE, so the duplicate skip
could not take it, and `PARKABLE_EVENT_TYPES` does list the type, so it was
parked for a consumer that could never come. Parking is settled by the workflow
function returning, and a survivor there is reported through `strandedEvent` as
a replay divergence. So the run did all of its work, every step succeeded, and
the final replay failed it, deterministically enough to burn the whole
replay-divergence recovery budget and terminate with CORRUPTED_EVENT_LOG.
Give `attr_set` a class so the straggler is skipped like every other one:
committed but inert. Parking still covers the first arrival, for a replay that
walks past an attribute event before the body reaches the call that claims it.
An attribute write from a step body carries no correlation id and is consumed by
the structural lifecycle consumer, so it is unaffected.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* [core] Release a parked duplicate, and agree with the UI about one
The class map alone decides a straggler only where the walk meets it after a
consumption recorded the class. When neither copy has a consumer yet both
park — the walk steps over the first and re-enters in the same tick, with
nothing consumed and so no class recorded — and the drain then claims one and
holds the other for a callback that will never be registered. That survivor is
`strandedEvent`, which is the CORRUPTED_EVENT_LOG this branch set out to stop,
reached by the other road. `dropParkedDuplicates` releases it on the same terms
the walk skips one. Not an `attr_set` property: `wait_completed` parks in pairs
too, and `ONE_SHOT_EVENT_TYPES` only sees the order where the consumption came
first.
Giving `attr_set` a class also moved the observability UI, which reads the same
`entityEventClass` to grey out events a run passed over. It kept treating the
straggler as live, because its terminal-class set had no `attr_set` while the
dispatcher's consumer does deregister on the first event under an id. The two
now share `classifyEntityEvent` and `TERMINAL_EVENT_CLASSES` rather than each
keeping a copy of the rule.
That sharing needs the entity rule to be exact, because a step-written
`attr_set` carries no correlation id: keyed on the run it would collapse every
attribute write a run made into one class, and a captured production log in
`__fixtures__` holds forty. `classifyEntityEvent` gives such an event no class
at all, so neither side can read the second as a repeat of the first.
The shared fixture corpus had nothing for `attr_set`, which is why the drift
between the two halves went unseen. It has four now, and each of them fails on
both sides without the fix above it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Pranay Prakash <pranay.gp@gmail.com>
A successful run printed several lines that described the runtime working
correctly. Most of it was fallout from defaulting the events transport to
WebSockets (#3702): three breadcrumbs written while the transport was opt-in
became default-path output, because each one reported a choice the caller no
longer makes.
- `world-vercel: using ws events transport (…)` ran once per cold start on
every deployment, naming the transport it was always going to use.
- The `projectConfig` proxy fallback warned once per process. That World cannot
hold a socket, so with WS on by default every CLI command and the
observability app warned about a fallback nobody asked for and nobody can act
on. Debug-gated and reworded from "requested but" to "unavailable for".
- The `max_duration` / `auth_expiry` drain notice is routine: the transport
reconnects from the close that follows and no write is lost.
Swept for the same shape elsewhere:
- `world-local`'s queue-concurrency notice fired per message once a fan-out
exceeded the limit — the semaphore doing its job.
- `@workflow/world`'s active-run recovery line printed on every dev-server
restart with work in flight. The re-enqueue *failure* above it stays
unconditional; that one leaves a run unresumed.
- The port-detection diagnostics in `@workflow/utils` keyed off
`NODE_ENV=development`, which is the only environment that reaches them, so
the gate made them unconditional for their whole audience.
All of it moves behind `DEBUG=workflow:*` via a new `debugLog` in
`@workflow/utils`, joining world-vercel's existing `httpLog` and `logRetry`
output under one selector. Warnings and errors are untouched, so a run that
actually goes wrong is no quieter than before — the ws-transport tests that
assert failures are never silent still pass unchanged.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Pranay Prakash <1797812+pranaygp@users.noreply.github.com>
* Revert "[world] Make the sealed log opt-in instead of default-on (#3735)"
Reverts b2cac623d3. New runs are stamped at spec 7 again, now that a
read which cannot see past an unfilled position waits for it instead of
reporting a log that ends there (workflow-server: derive the in-request
seal poll budget from the staleness bound).
Two things are kept from #3735 rather than reverted:
- the world-testing conformance floor at mintedSpecVersion(), which was
wrong for any staged bump and not specific to this default
- a note on mintedSpecVersion recording what default-on rests on: the
events density requirement, and that a sealed log meets it by repair
rather than by construction, so the READ has to wait
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* TEMPORARY: point world-vercel at workflow-server#839 preview
Validating the seal-poll-budget fix end to end with spec 7 on. Reverted
before merge; the override lint guard is expected to fail meanwhile.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Revert "TEMPORARY: point world-vercel at workflow-server#839 preview"
This reverts commit 5e17cc9335.
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix(world-vercel,world-local): hold process-wide state on globalThis
Both packages are bundled into the host application's server build, and a
bundler keys module identity on (resource, layer) — Next.js alone builds
`instrument`, app-route, `ssr` and `edge` layers, so one process holds one
copy of each of these modules per layer. Every module-scope `const`/`let` in
them was therefore per-copy state wearing the costume of a process singleton.
vercel/workflow#3493 made `@workflow/world-vercel` bundled rather than
external and the events WebSocket transport regressed to HTTP for exactly
this reason: the queue consumer registered its channel in the `instrument`
copy's `Map` and the write path looked it up in the route copy's empty one. A
deterministic miss, for the life of the process. `@workflow/world-local` had
the same exposure all along — including `runFileLocks`, where a duplicated
mutex simply stops mutually excluding.
Add `globalSingleton()` to `@workflow/utils` (the primitive `@workflow/core`
already hand-rolls for its World cache) and route every mutable module-scope
binding in both worlds through it.
Regression cover, in three layers:
- `global-singleton.test.ts` pins the primitive's semantics.
- `ws-transport-module-copies.test.ts` imports the module twice in one
process and asserts a transport registered by one copy is found by the
other — it fails on a plain module-scope `Map`, which is the shipped bug.
- `scripts/lint/module-scope-state.mjs` fails the class: an AST rule banning
mutable module-scope state in these packages, with `// per-copy-ok: <why>`
as the deliberate escape. Wired into both packages' `vitest run src`, with
fixture self-tests so it cannot rot into a no-op.
* test(world-postgres): pin the module-scope-state rule for the postgres world
It is deduped today only because `getRuntimeRequire()` loads it — a property
of how it is loaded, not how it is written, and exactly what changed for
world-vercel in #3493. The package is already clean; this keeps it that way.
* docs(worlds): codify "a world must not hold mutable module state"
A world package is loaded one of two ways, and only one of them gives it a
single module instance: a runtime `require()` (deduped by Node) or the host's
bundler (one copy per layer). Which one you get is a property of how the world
is loaded, not of how it is written, and it changed under `world-vercel` in
#3493 — so the rule has to be "never rely on module scope", not "rely on it
until someone flips a config".
Written down in the four places someone can meet it:
- `docs/content/worlds/{v4,v5}/building-a-world.mdx` — a "Process-wide state"
section for custom-world authors, with the loading modes spelled out and a
nudge to prefer World-instance state over a global.
- `packages/world/README.md` — the same constraint on the contract package.
- `CLAUDE.md` — so the next contributor working in these packages sees it.
- `packages/core/src/runtime/world.ts` — at the two static imports, which is
where the difference between a bundled world and a required one originates.
The rule's own error message now teaches it too, rather than naming a helper.
Consolidates the guard while here: `@workflow/utils` owns the rule and its
fixture self-tests, and sweeps every *published* `packages/world-*` discovered
at runtime, so a world package added later is covered without anyone
remembering. Each world keeps a one-assertion mirror for locality.
* style: drop prose em dashes from this branch's new text
#3704 landed a repo-wide writing pass hours after this branch was written and
took `world-vercel/src` from 406 em dashes to 130 (`ws-transport.ts` alone went
35 to 1). This branch's docs section, README, comments and lint messages were
written before that and would have put 36 of them straight back into the files
that were just cleaned.
Rewritten sentence by sentence rather than by substitution: an em dash becomes a
colon, a comma, a full stop or a parenthetical depending on what it was doing.
Also fixes a real defect the sweep surfaced: `world-postgres`'s guard test was
generated through a shell heredoc and had literal backslash-backticks in its
doc comment.
* Update .changeset/world-module-scope-state.md
Co-authored-by: Peter Wielander <mittgfu@gmail.com>
Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
* fix(core): build the entrypoint's queue handler from getWorld()
Adopted from #3666 by @MintedKenny, which implements #3665 and could not run
CI as a fork PR. One line of behavior: `workflowEntrypoint`'s lazy handler
init calls `getWorld()` rather than `getWorldHandlers()`.
`getWorldHandlers()` owns a second, build-time-safe cache, so calling it from
the runtime route built a *second* World in the same process. That costs a
stateful World duplicate resources on every instance — world-postgres eagerly
constructs a `pg.Pool` (default `max: 10`) and a nested world-local World in
`createWorld()`, so self-hosted users have been paying for two of each — and,
for a bundled world package, the two Worlds are built by two different module
copies, which is the mechanism behind the WS transport regression the rest of
this branch contains.
The public `getWorldHandlers()` and its separate build-time cache are
unchanged; only the runtime route stops using it.
Kept from the original: the regression test asserting the factory runs exactly
once, and the api-reference wording (re-applied over #3704's list punctuation).
Not taken: renaming the `workflow.route.get_world_handlers` span. It is a
distinct span from the per-request `workflow.route.get_world` at the top of the
flow route, and reusing that name would collide with it in traces and in
`runtime-trace-mode.test.ts`; a comment records why the name outlived the call.
Co-authored-by: Kenneth <kenneth@standardforensics.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix: address AI review on the module-scope work
Two blocking findings, both real:
- **Cross-version state sharing** (`ws-transport.ts`). A process can hold two
*published versions* of `@workflow/world-vercel` (a transitive dependency
pinning an older `@workflow/core`, which depends on this package by exact
version). Both wrote to the same unversioned `Symbol.for` key, so one
version's write path could be handed a `WsEventsTransport` built by the
other's class and frame against a protocol it may not share — with no version
negotiation on the socket to catch it. `shapeVersion` cannot express this: the
container is stable, the hazard is its contents. The registry and the events
dispatcher recycler are now keyed by package version. The plain connection
pools stay unversioned; sharing those across copies is the point.
- **The documented pattern failed the rule this PR adds.** The custom-world docs
teach `store[StateKey] ??= …`, which the rule flagged as a field write. It now
recognizes state rooted at `globalThis`, following one alias hop, which is
also what `core/private.ts:23` and `next/src/index.ts:58` are already doing
correctly (core drops 26 findings to 22, next 7 to 6). The docs also now say
outright that `globalSingleton()` is the same thing, since AGENTS.md
prescribes it and the page did not mention it.
Rule precision, from the review's probes:
- `.mts`/`.cts` are scanned. `@workflow/world-testing` is authored in `.mts`, so
its entry in the sweep was passing vacuously — with the walk fixed it reports
a real finding, now annotated (it is a standalone `serve()` entry).
- Mutations in top-level statements no longer count. A table filled at module
evaluation is identical in every copy; divergence needs a later write.
- `static` class fields are collected, attributed to the class name.
- An *exported* binding initialized to an empty collection is a finding on its
own, which approximates the cross-file case the walk cannot resolve.
Six fixtures pin the new behavior. The rule's header now states what it does not
see, and AGENTS.md states where the sweep stops and why core is not gated yet.
Also tags `resetGlobalSingletonForTest` `@internal`.
* fix(lint): attribute a static-field write to the field, not the class
The static-field support added in the previous commit keyed `declared` on the
class name, so a class carrying more than one mutable static reported one
finding instead of one per field, and labelled the survivor with whichever
mutation was seen first. On a two-static fixture it reported
`static Registry.latch (`.set()`)`: the name of one field, the reason
belonging to the other, pointing the reader at the wrong line.
Key static fields `Class.field` and resolve a write to the same shape, via a
new `memberPath()` that takes the first two segments of a member chain and
tries that key before the bare root identifier. Two follow-ons fall out of
having the path:
- `this.field` inside a `static` member resolves to the class, which is the
ordinary way to write the mutation. `staticClassOf()` returns nothing for an
instance member, where `this` is an instance and the state is per-instance
rather than per-copy, and nothing inside a nested `function`, which rebinds
`this`.
- `state.count++` is now a finding, like the `state.count += 1` that
`assignment()` already reported.
Fixtures pin all four, including the instance-field case that must stay clean.
The four world packages still report zero, and the extracted `recordMutation()`
keeps the file at its previous two Biome complexity warnings.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* fix: make module duplication inert across every bundled package
`@workflow/core` is bundled into the host server build the same way the worlds
are, and always has been — the original repro measured three live copies in
every arm, including the pre-#3493 external one. One instance is not reachable:
layers cannot share a module, and core cannot be external because it *is*
workflow code (`runtime/start.ts:253` and nine methods in `runtime/run.ts` are
`'use step'`), so it must go through the SWC loader. The Next integration
already encodes that rule by removing workflow-bearing packages from
`serverExternalPackages`.
So the duplication stays and the hazard is removed instead, everywhere the
duplication can happen.
`@workflow/core` (22 findings to 0): warn-once latches in `constants.ts`,
`start.ts` and `telemetry.ts`; the source-map tracer cache; the VM script cache;
the QuickJS compiled-assets and baseline caches; the dev-server port cache (its
own comment already said "per process"); the text codecs; the zstd browser
decoder; and the `useStep` closure brand, where a function marked by one copy
was invisible to another.
The one with teeth was `step-single-flight.ts`: a per-copy map is not
single-flight. Two invocations reaching it through different layers would each
believe they were alone in the process and both run the step body, silently
degrading in-process dedup to the cross-process residual its own doc scopes out
to the ownership lease.
Also `@workflow/world` (a warn-once set, hand-rolled onto `globalThis` to keep
that package dependency-free), `@workflow/ai` (the lazy OTel API), and
`@workflow/nest` (bootstrap config in a module-level `let` and two static class
fields — configure one copy, read another, and the controller is unconfigured
for the life of the process).
Five sites are deliberately per-copy and now say why: state keyed on objects
that never cross copies (the barrier safety-net `WeakSet`, the QuickJS pending
byte `WeakMap`), the synchronously-scoped guest-code sink, and the OTel
diagnostic that reports what *this* copy sees.
The sweep now covers all of it. Packages with a single module graph stay out
(build-time code, the CLI, the o11y UI, the test runner) and AGENTS.md records
which and why.
Found while doing this: two static fields on one class collapsed into a single
entry in the rule, so `WorkflowModule.options` was invisible behind
`WorkflowModule.outDir`. Statics are now keyed `Class.field`.
* fix(world): suppress noAssignInExpressions on the globalThis idiom
The hand-rolled form trips Biome, as it does in `packages/core/src/private.ts`,
which carries the same suppression. Restructuring it into a helper function
instead would hide the state behind a call the module-scope rule cannot follow,
so the binding would stop being recognized as off-module and the package would
report a finding for correct code.
* fix: sweep every bundled package, and mark utils side-effect free
@shalabhc asked on review whether `@workflow/utils` needs this too. It does,
and so do three others: `utils`, `errors`, `serde` and `workflow` all end up in
the host application's server build and none were in the sweep. All four report
zero today, which is exactly the state `world-testing` appeared to be in before
the `.mts` walk was fixed and it turned out to have a real finding. Being clean
and being *checked* are different properties, and only the second one survives
the next contributor.
`sideEffects: false` on `@workflow/utils`: verified that every module in the
package only declares (no import-time work), so a bundler can now drop the
unused parts of the barrel instead of keeping all ~64 KB of it because three
packages import one 476-byte function.
---------
Signed-off-by: Pranay Prakash <pranay.gp@gmail.com>
Co-authored-by: Peter Wielander <mittgfu@gmail.com>
Co-authored-by: Kenneth <kenneth@standardforensics.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Peter Wielander <peter.wielander@vercel.com>
* Run the test suites CI was silently skipping
`turbo test` runs a package's tests only if that package declares a `test`
script, so a suite can sit in the repo for months without ever running. Four
were in that state: @workflow/world (13 files, 160 tests), @workflow/cli (5 /
51), @workflow/nitro (1 / 30), and two files under packages/core/e2e that no
workflow named.
Wire each one up, and add scripts/check-test-suites-wired.mjs plus a lint job
so the next unwired suite fails CI instead of going unnoticed.
Fixes#3731
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Drop the changesets and rename the guard job
The PR only wires up existing suites and adds a CI check, so there is nothing
to release. Rename the job to match its `no-test-overrides` sibling.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs: apply Vercel technical writing standards
Audit the complete documentation corpus, package READMEs, skills, and
source TSDoc/comments against the vercel-technical-writing skill and
style-rules.md. Normalize sentence-case headings without changing
published anchors, remove prose em dashes and filler wording, improve
active voice and self-contained phrasing, standardize product/brand
capitalization, American English, list punctuation, units, and code
fence languages, and preserve exact runtime strings/table placeholders.
All executable code is unchanged. Modified skills have their metadata
versions bumped.
* docs: extend writing audit to repository Markdown
Apply the same technical-writing rules to design documents, compiler
specifications, workbench guides, package changelogs, and the remaining
tracked Markdown outside the deployed docs corpus. Preserve historical
meaning, commands, output literals, table placeholders, and heading
anchors.
* docs: exclude generated package changelogs from audit
* Pre-claim inline steps inside the suspension batch (born-running pairs)
Restacked onto main after #3025's squash-merge; folds in the review-round
changes to the flush loop (per-write requestId attribution on createBatch,
and the seeded/advancing slot-bump expectation, now shared with the
pre-claim ceiling).
Fold each lazy-inline step's deferred writes into the batched fan-out as an
adjacent [step_created, step_started] pair: the created row carries the input,
the started row is a bare ownership-stamped claim the server folds into one
born-running create. The whole scheduling turn commits as ONE durable write,
inline bodies start straight off that commit (in parallel with the VQS
publishes for backgrounded steps), and executeStep gains a pre-claimed mode
that runs or skips the body off the batch's per-event verdict - a pair 409 is
the same skipped outcome as losing the lazy claim. The lone-inline case keeps
the optimistic lazy path (a pair-only batch buys nothing over the single
claim). Also threads per-event computeInstanceId through the World batch
request, and folds the batch's committed slot ceiling into the inline slot
snapshot so terminal writes stop being answered with reports echoing the
batch's own events.
* Parallel chunk commits, per-chunk continuation, batch span attributes
Production trace of a 67-event fan-out showed the three batch chunks
POSTing back-to-back (~230ms each) with no bodies or queue messages until
all three settled (~670ms). Three changes:
- Chunks now POST concurrently. Slot assignment is the server's, so
parallel chunks race for slot ranges exactly like the pre-fold path's
parallel single writes did; entity conditions, not commit order, carry
correctness. The foreign-interleaving diagnostic is computed once over
the whole fold (committed span vs seed) instead of per chunk.
- Per-chunk continuation: each chunk's step-execution queue messages
publish the moment ITS creates are durable (in-flush, via stepDispatch,
same message shape and idempotency key as the caller's dispatch pass -
the affected steps are pre-reported in queuedStepCorrelationIds so the
caller skips them). Only the chunk carrying the inline pairs gates
handleSuspension's return (opt-in via allowDeferredBatchWork); trailing
chunk commits + all publishes ride result.deferredBatchWork, which the
runtime joins next to the dispatch join before it can ack - the
every-create-durable-before-ack contract is unchanged, the bodies just
start off the pair chunk instead of the slowest chunk.
- OTel: batch identity attributes (workflow.batch.size, per-type
workflow.batch.shape) now live on the world.events.createBatch span
(instrumentObject) instead of the http POST span, which keeps only
wire-level facts (transport, bytes) and no longer sets
workflow.event.type - that attribute names a single event write and
tagging a batch with its first event's type misclassifies traffic.
* Address review: settle deferred fold on failure, drop pair-batch retry
Three fixes from review of the deferred/parallel-chunk fold.
1. A pair-chunk rejection escaped `handleSuspension` while the trailing
chunks' commits and publishes were still in flight. `deferredBatchWork`
never reaches the caller once the handler throws, so nothing joined that
work — exactly the state `settlePhase` exists to prevent: a sibling create
landing after the rejection commits an event from the abandoned replay's
seeded sequence and races the caller's restart reload. The failure path now
settles `trailing` before rethrowing.
2. Every pair-carrying chunk gates the return, not just the first. Pairs sort
to the front and two rows per inline step fit inside one chunk, so this is
one commit today, but `findIndex` silently degraded if either cap moved: a
pair in an unawaited chunk yields no `inlineClaims` entry, the caller falls
back to a lazy `step_started`, and that races this same fold's in-flight
pair for the same step. constants.test.ts now pins the cap relationship.
3. A batch carrying a `step_started` is no longer retried in-process. The
born-running pair does converge to a 409, but the pre-claim caller reads a
pair 409 as "a concurrent writer owns this step" and skips the body — and
on a retry that is indistinguishable from "my own first attempt committed
the pair". Skipping there stranded a running step stamped with this
invocation's own message id until the ownership lease expired (860s), where
the single-POST path deliberately fails the delivery and recovers through
owned-recovery in seconds. Same reasoning `EVENT_RETRY_ELIGIBILITY` already
applies to `step_started`.
Also asserts `lazyStepInput` / `preclaimedStart` mutual exclusivity in
executeStep instead of only documenting it, and adds the changeset.
Tests: +1 suspension-handler (pair-chunk failure settles the trailing chunk
before escaping — fails without fix 1), +1 constants (cap relationship), +1
world-vercel (a born-running pair batch is single-attempt), and the existing
batch-retry test retargeted at an entity-conditioned batch. Full
@workflow/core unit suite 2178 green, @workflow/world-vercel 514 green,
typecheck green across core / world / world-vercel.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Guard inline bodies against unhandledRejection; review follow-ups
The dispatch/deferred-batch joins now sit between the step promises'
creation and the `Promise.all` that reads them, so a body rejecting in that
window had no handler attached at the microtask checkpoint — an
unhandledRejection, fatal under Node's default --unhandled-rejections=throw.
A 412 fenced claim races exactly that window, and `deferredBatchWork` widens
it by a trailing-chunk round trip. Attach a no-op catch at creation, the same
way `dispatchesSettled` already does two lines up; the awaits below still
decide the outcome.
Review follow-ups:
- `workflow.batch.shape` is sorted by event type. Map iteration is first-seen
order, so a pre-claimed fold and a pure eager fold rendered the same
composition as different strings, which is not groupable as a dimension.
- A lost pre-claim reports StepSkipReason `running`, not `completed`. The
pair's 409 says the step already exists and its claim winner is executing;
the other skip site is a genuine terminal-state conflict, and tagging both
`completed` left the attribute unable to separate the two.
- `batchCommittedSlotCeiling`'s docstring now says the echo is only fully
suppressed for a single-chunk fold: on a multi-chunk fan-out an inline
terminal write issued before the trailing chunks land still names a
position below them and still draws a report.
- The defensive throw on a missing dehydrated input records where it lands —
the pair is already durable, so it fails with the step claimed and its body
unrun, recovered on redelivery via owned-recovery rather than failing
cleanly.
No regression test for the unhandledRejection: the existing
inlineClaimRejectionScenario runs both steps inline, so `dispatches` is empty
and the join resolves in a microtask — the window never opens and a test
there passes with or without the fix. Reproducing it needs a scenario with a
backgrounded step and a slow queue publish alongside the fenced claim.
Full @workflow/core unit suite 2178 green, @workflow/world-vercel 514 green,
typecheck and biome clean.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Pin per-event computeInstanceId on the batch wire
Batch encoding is a separate path from the single-event POST, so the frame
meta had no coverage: the only assertion was at the World-call boundary.
Adds a wire-level test that a pre-claimed pair's step_started half carries
computeInstanceId in its frame meta and the step_created half does not.
Verified it fails when the threading in createWorkflowRunEventBatch is
removed.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
* Guard the pre-claim path as inert on Worlds without createBatch
world-local and world-postgres do not implement createBatch, so the fold
never engages there — but the runtime passes ownerMessageId and
allowDeferredBatchWork unconditionally. The existing "keeps the single path
when the World lacks createBatch" test passed neither, so it never covered
the pre-claim path at all.
Assert the inertness with the params the runtime actually sends: no claims,
no deferred work, no slot ceiling, the lazy-inline step still carrying its
input, and no step_started reaching the world.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Peter Wielander <peter.wielander@vercel.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
## createBatch: the client half of the v4 batch event write (per-event
results, no fence)
> **Note:** this PR was rebuilt from scratch. The previous revision
implemented the retired "v2 suspension fence" design
(`expectedRunVersion` / `batchId` / `logicalCreatedAt`, a
grammar-validated collect mode, world-postgres migration 0016,
world-local claim machinery). The server redesigned its endpoint in
place (vercel/workflow-server#646, merged and deployed) and this branch
now targets that contract on top of current `main` (specVersion 6 slot
identity). The old head is tagged `batch-client-v2-fence-design`; prior
review threads reference deleted code.
### The server contract this targets
`POST /api/v4/runs/:runId/events/batch` (workflow-server#646): an
**ordered** list of v4 frames — byte-identical to single-event POST
frames, **no batch-level meta** — committed in one DynamoDB transaction
per attempt, answered with HTTP 200 + `{ results }`: one entry per
frame, in request order. Each event reports what its own single POST
would have returned: `200` + the materialized entity, or the single-path
status/code (e.g. `409`/`conflict` for an event an earlier delivery
already applied). A transport retry of a committed batch converges to
all-409s with nothing written twice — idempotency comes from per-entity
conditions, not batch bookkeeping. Slot-identity runs only (specVersion
≥ 6 — what `world-vercel` stamps on every new run since #3389).
### What this revision ships
1. **`@workflow/world` — the spec addition.** `Storage['events']` gains
one optional method; **method presence is the capability declaration**
(no capability flag, no stub required):
```ts
createBatch?(
runId: string,
events: BatchEventRequest[],
params?: CreateEventBatchParams
): Promise<EventBatchResult>;
interface BatchEventRequest {
event: CreateEventRequest; // same discriminated union as the single create
occurredAt?: Date; // under slot identity: the source of the durable createdAt
}
type BatchEventItemResult = // one per submitted event, in request order
| { status: 200; event: Event; run?: WorkflowRun; step?: Step; wait?: Wait }
| { status: number; error: string; message: string };
interface EventBatchResult { results: BatchEventItemResult[] }
```
Contract: **ordered** (events land in the log in request order),
**per-event outcomes** (each event reports what its own single `create`
would have returned — success discriminated by `error === undefined`),
**idempotent on retry** (per-entity conditions make a retried committed
batch converge to per-event 409s). Worlds that don't implement it keep
the single-event path. `world-local` and `world-postgres` deliberately
do NOT implement it — batching a local/in-process write buys nothing
(this deletes the old revision's riskiest surface: the hand-written
postgres migration and the world-local claim machinery).
2. **`@workflow/world-vercel`** — the wire adapter: per-event frames
concatenated in order (reusing the single-frame encoder; each frame
carries its own `occurredAt`, which under slot identity is the source of
the durable `createdAt` — this natively closes the replay-clock question
the old `logicalCreatedAt` field existed for), CBOR `{ results }`
decoded against the **same per-type zod schemas as the single POST**,
loud `SCHEMA_VALIDATION` on any malformed response (wrong length,
invalid item), and the standard typed error mapping for request-level
failures.
3. **Retry policy** — a `batchIdempotent` override in the event-retry
eligibility machinery: the whole batch POST retries transient transport
failures/5xx (and waits out 429 `Retry-After` per #3504) regardless of
the contained event types, because per-event entity conditions make the
retry converge; the per-type non-retryability matrix guards *single*
posts (where e.g. a retried bare `step_started` would increment
`attempt`) and doesn't apply inside a batch.
Tests: 7 wire tests — frame encoding/ordering + **no fence fields on the
wire**, per-event result mapping (successes typed, failures passed
through), malformed-response failures (length mismatch, invalid item
body with index), typed request-level 400s, in-process 5xx retry,
empty-batch guard — plus 9 suspension-handler tests for the runtime
fold: ordering (steps then waits), per-event 409 tolerance, non-409
failure propagation, every gate exclusion (flag off / no `createBatch` /
pre-slot run / hook writes), 32-cap chunking, and lazy-inline exclusion.
Full `world-vercel` suite: 508 passed; full `@workflow/core` suite: 2126
passed.
### The runtime integration: batched suspension fan-out (ON by default)
The suspension handler folds a **clean fan-out** — the suspension's
eager `step_created` + `wait_created` writes — into `createBatch` calls
of at most **32 events**, and uses the batch endpoint **exactly when two
or more batchable eager events exist**: a lone eager event takes the
ordinary single write (same round trip, and it keeps the slot-snapshot +
bump-and-report the single path provides) (mirroring the server's
transaction budgets: 2 items/event against the 100-item cap, 768 KB
inline-byte budget; larger fan-outs commit in successive batches). The
gate requires: World implements `createBatch` ∧ run on slot identity
(specVersion ≥ 6) ∧ no attribute writes ∧ no hook writes ∧ no resilient
step dispatch. **Everything outside the gate keeps the single-event path
byte-for-byte**, and lazy-inline steps keep deferring their
`step_created` to the lazy start exactly as before.
Per-event semantics mirror the single path: a `409` is the same
already-exists tolerance as `EntityConflictError` (the conflicted step
is not marked owned); any other per-event failure fails the suspension
write the way a single-path rejection would. Slot bumps (the batch
endpoint has no bump-and-report) are tolerated and logged — the same
accepted exposure as a dropped truncated skipped-slot report on the
single path.
**On by default**, with the `WORKFLOW_TURBO`-shaped kill switch as the
operator escape hatch: **`WORKFLOW_BATCH_TRANSITIONS=0`** (or `false`)
disables batching and restores the exact prior one-write-per-event path.
Documented in the worlds configuration reference and the changelog
entry. Burn-in watch: the `event_batch`-tagged slot-conflict metrics and
DynamoDB throttle monitors on the server side.
### Docs
- New v5 changelog entry **`changelog/batched-event-writes`**
documenting the World spec addition (full `createBatch` signature +
contract — the signature block is compile-checked against
`@workflow/world` by the docs code-sample checker), the runtime fold,
and the follow-up.
- `configuration/worlds` gains the **`WORKFLOW_BATCH_TRANSITIONS`**
reference entry: default on, `=0`/`false` as the documented escape
hatch.
### Staged follow-up: the deferred sequential transition (the STSO win)
Hold `step_completed(N)` across the replay turn and commit
`[step_completed(N), step_created(N+1), step_started(N+1)]` as one batch
at the next lazy start (the server folds the pair born-running). This
needs the synthetic-completion replay machinery rebuilt against today's
runtime (parallel inline batches, turbo's run-ready barrier, optimistic
starts, slot bookkeeping) — it stays a separate PR so the SDK's most
sensitive replay path gets its own focused review. Its acceptance
criteria are already agreed: the runtime eligibility matrix as unit
tests, and an e2e that asserts ≥1 POST to `/events/batch` and **zero**
single-event POSTs for the batched transitions.
### Compatibility
- Old servers: no `/batch` route → 404/405 → callers fall back to
single-event posts (the runtime PRs will latch this per run).
- Pre-slot runs: request-level 400 (`batch-requires-slot-identity`) →
same fallback.
- No `WORKFLOW_SERVER_URL_OVERRIDE` pin this time — the server endpoint
is merged and deployed to production.
Refs: vercel/workflow-server#646 (endpoint), vercel/workflow-server#780
(unbatchable-types design space), #3389 (slot identity), #3504 (429
retry).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Report end-to-end TTR for a hook resumption — entry into the public resume
API through to the first line of the next durable step — on that step's
`step.execute` span, decomposed into non-overlapping phases that sum
exactly to the total:
workflow.resume.total_ms
workflow.resume.phase.{producer_prep,queue_delivery,resume_setup,
replay,step_dispatch,step_claim,step_prepare}_ms
dimensioned by trigger, dispatch strategy, setup source, and whether the
step ran inline or was dispatched to another invocation.
T0 is stamped by whichever public entry point the caller used, so
`resumeWebhook` — which does its own by-token lookup and key resolution
before reaching the shared implementation — measures the same window as
`resumeHook` rather than a systematically shorter one. T7 is taken inside
`contextStorage.run`, immediately before `stepFn.apply()`, so the
`step_prepare` phase covers the step-context setup it is defined to cover.
`resumeHook()` puts the producer boundaries on an optional
`hookResumeTiming` field on the queue message (both dispatch paths); the
consuming invocation adds its own and hands them to the execution that
will actually ATTEMPT the next durable step. That decision is made against
the dispatch loop's own classification, so an owned-recovery step keeps
the measurement here instead of it riding off on a queued sibling, and a
step converted into a delayed backstop wake — which this delivery does not
attempt — never takes it. Within an inline batch the tracking is shared
and a one-shot latch picks the single step that reaches user code, so the
sample survives the batch's first step losing its create-claim. A
deployment-affinity re-route forwards the timing untouched, keeping the
wasted hop inside `queue_delivery`.
The field is optional in every direction (new producer/old consumer, new
consumer/old message, no workflow-server change) and parses with
`.catch(undefined)` so a malformed value can never fail a delivery. A
sample is emitted only when every required boundary is present, finite,
and monotonic — a skewed or incomplete set is dropped rather than
reported as a negative phase.
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
## Summary & Motivation
Adds `events.getMany` to the analytics API, letting dashboard consumers
enrich canonical event pages with ClickHouse provenance in one bounded,
deduplicated batch request instead of N point lookups. Coordinated with
a workflow-server batch endpoint.
## Test Plan
Added unit tests for the client and schema; also ran Biome checks, `git
diff --check`, and world-vercel typecheck.
Signed-off-by: Alex Langenfeld <alex.langenfeld@vercel.com>
* feat(world,world-vercel,core): resilient step dispatch (parallel step_created + queue publish)
Newly created steps are handed to the queue in parallel with their
step_created event write, with the serialized input carried on the
message (stepInput) so the queue consumer can idempotently re-ensure
the event when the direct write failed transiently — mirroring
resilient start (runInput) and resilient hook resume (hookInput).
- @workflow/world: stepInput on WorkflowInvokePayload,
CreateEventParams.viaStepDispatch, WorldCapabilities.resilientStepDispatch
- core (node:vm): suspension handler publishes eligible steps alongside
their create; the dispatch pass skips them (queuedStepCorrelationIds)
- core (quickjs): dispatchPendingOps does the same for overflow steps;
the ineligible fallback is now published in parallel too (removes the
serial per-step enqueue loop)
- consumer: on a redelivery, a stepInput-carrying message re-ensures
step_created (marked viaStepDispatch) before executing
- under an enforced precondition guard the parallel path requires
backend cooperation (capabilities.resilientStepDispatch, declared by
world-vercel): a 412-rejected step's in-flight dispatch is revoked
server-side and its re-ensure refused
- step dispatch/retry idempotency keys are step-identity-scoped
(cid + hashed step name) so a revoked message for a reassigned
correlation id cannot absorb the corrected schedule's dispatch
- kill switch: WORKFLOW_RESILIENT_STEP_DISPATCH=0
* Validate stepInput.input as Uint8Array at the schema boundary
Review feedback: producers only attach stepInput when the dehydrated
input is binary and the queue transport preserves bytes (CBOR), so a
non-binary value means the payload was mangled in transit. Enforcing
Uint8Array in StepDispatchInputSchema fails the message parse instead
of silently writing non-binary data into a step_created, and types the
consumer's re-ensure so the unchecked 'as SerializedData' cast goes
away.
* Keep sequential dispatch under an enforced precondition guard (drop the resilientStepDispatch capability lift)
Review feedback (two P1s): backend-side revocation bookkeeping cannot
carry the guard's correctness property across the queue side-channel —
- nothing orders a slow guarded create's eventual 412 (the moment the
backend learns the dispatch is poisoned and records the revocation
marker) before the consumer's redelivery re-ensure, so attempt > 1
is a probabilistic mitigation, not a happens-before; and
- a best-effort marker that fails open (Redis loss) cannot back a
capability the SDK treats as a correctness attestation.
Only sequencing the publish after the create gives the message a
happens-after edge over the create's guard verdict, so the guard gate
is now unconditional: worlds that enforce the precondition guard keep
the sequential create-then-publish dispatch. The parallel resilient
path remains for unguarded writes (the quickjs engine everywhere, and
worlds without the guard). Removes WorldCapabilities.resilientStepDispatch
and world-vercel's declaration; the viaStepDispatch flag is kept and
re-documented as advisory (server-side defense-in-depth only).
This also dissolves the reviewed dedupe hazard on the step-identity-
scoped dispatch keys: with no 410-ack path in any real SDK flow, a
message for a never-created step keeps redelivering until an entity
exists, execution always hydrates input from the committed entity
(never the message), and a name-mismatched stale start is skipped by
the server's stepName fence.
* Correct the MAX_RESILIENT_STEP_INPUT_BYTES rationale: VQS has no hard message-size cap
256 KB is the queue's inline-vs-S3 threshold, not a rejection limit
(payloads above it spill to S3-backed storage transparently). The
128 KiB bound is a cost/latency choice — keep step messages on the
inline path rather than paying an S3 double-hop for bytes that already
live in the event log.
* Recover a missing step in-band when a stepInput-carrying delivery beats its create
Durabench parallel sweeps (guard-off, node engine) caught ~4-8% of
fan-out runs stalling one branch for ~306s on the resilient dispatch
path. Root cause: the consumer's step_created re-ensure was gated on
metadata.attempt > 1, but world-vercel's failure-retry path re-enqueues
a FRESH message whose attempt resets to 1 — so when a delivery beat the
producer's parallel step_created write, every fast retry hit the same
'step not found' rejection with attempt 1, and the step only recovered
when the ORIGINAL message's ~300s visibility-timeout redelivery finally
arrived with attempt 2.
The recovery is now in-band and attempt-independent: when a
stepInput-carrying execution rejects with the step-missing signature
(WorkflowWorldError, 404 or the local worlds' message shape), the
consumer materializes the step_created from the message payload and
retries the execution once within the same delivery. The eager
attempt>1 ensure is kept as a round-trip saver on genuine redeliveries.
Sweep effect expected: the 305-306s TTLS outliers disappear while the
resilient path keeps its p50 win (1054ms vs 1425ms at 64 branches).
The lazy hook fast path (#3345) hoisted the consumer's hook_received
write above the deployment-affinity guard (#2960), so a misrouted lazy
resume wrote its event before the guard could re-route the delivery.
Stamp the run's pinned deployment on the resume message
(hookInput.deploymentId, from the producer's resume context) and, on
the consumer, compare it against the ambient deployment id immediately
before the fast path: a match continues with no run fetch, a mismatch
fetches the authoritative run and hands it to the existing guard —
which keeps sole ownership of re-route/fail policy and remains the
authoritative protection before replay and step execution. The
re-routed message preserves the complete hookInput (it may hold the
only copy of the resume payload). Older messages without the field, and
worlds without deployment affinity, are unchanged: they skip the
pre-check and rely on the authoritative guard, the pre-guard write
staying convergent per (runId, resumeId).
Fixes the misrouted-lazy-resume unit test broken by the #2960/#3345
ordering: a modern misrouted resume now re-routes with zero event
writes, asserted for both hook_received and run_started.
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* perf(core): initialize lazy hook replay from hook_received stream
On a lazy hook queue delivery, the consumer's idempotent hook_received
re-ensure is hoisted above run_started and doubles as the invocation's
setup request: it asks the World to return the current replay log with
the write (new advisory CreateEventParams.preloadEvents), so one HTTP
request yields the canonical event, the reconstructed run, and the
complete replay log — skipping both the run_started POST and the
initial events.list.
- world: optional `preloadEvents?: true` on CreateEventParams, the
hook_received dual of skipPreload; Worlds may ignore it
- world-vercel: createHookReceivedPreloadEventV4 sends the frame Accept
on eligible hook_received posts and decodes either response mode —
frames via the response decoder extracted from the LIST consumer
(GET behavior unchanged), CBOR via the shared materialized-response
mapping. The run is reconstructed from run_created/run_started (plus
attr_set folds), the canonical event found by x-wf-event-id, and
resumeId now survives frame decoding so the runtime can match it
- core: new fast path before the generic run-state setup, guarded on
hookInput.resumeId + payloadDigest; a validated COMPLETE preload
(hasMore false — this path has no cursor-continuation machinery)
initializes workflowRun/preloadedEvents/maxEventsLimit directly,
anything else falls back to the run_started setup without re-posting
the hook; error classification matches the existing re-ensure
(terminal → consume, transient → redeliver); setup source reported
via workflow.resume_setup_source (never
workflow.hook.resilient_resume_materialized, which stays a
recovery-only signal)
- producer resumeHook() is unchanged and never sets preloadEvents
Based directly on main (no dependency on #3124/#3191); pairs with
workflow-server's streamed hook_received replay-log response, which
deploys first — the SDK negotiates per request and falls back safely
against older servers.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* address review: lazy fallback, retryable resume, terminal telemetry
- world-vercel: the preload request keeps hook_received's lazy
remoteRefBehavior — a supporting server owns frame-body resolution,
while an older server now answers the CBOR fallback without resolving
an S3-backed payload the runtime would discard
- world-vercel: the atomic lazy-resume shape (resumeId + digest) opts
into withEventPostRetry via idempotentHookResume — the (runId,
resumeId) claim makes the POST idempotent-on-retry; legacy/partial
hook_received shapes stay single-attempt, definitive 4xx stays
non-retryable (unit + adapter + trace-propagation coverage)
- core: a terminal event found in the preload records
workflow.resume_setup_source=hook_received_stream and the run's
actual terminal status on the span before consuming the delivery
- core: document resilient_resume_materialized as the legacy/non-atomic
re-ensure signal (claim ownership is not observable client-side, so
the hoisted path deliberately never emits it) and resume_setup_source
as a latency signal, not proof of event creation; note the Option A
skip is now unreachable for atomic resumes
- world: spell out the full preload usability contract on preloadEvents
(complete hasMore-false log, non-null cursor, run/startedAt/maxEvents,
lifecycle events, matching resumeId, list ordering, read-after-write
consistency); bump @workflow/world to minor
- new QuickJS sourcing tests (VM mocked): an attested complete preload
is used verbatim with no events.list, a non-attested hook-containing
preload is refetched, and an attested empty preload is not trusted
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
## Summary & Motivation
A queue callback that reaches a deployment other than the one its run is pinned to derives the per-run encryption key from the wrong master key, so the delivery fails before user code runs and the run dies as a blank "exceeded max retries". The delivery is re-enqueued explicitly addressed to the run's own deployment — strictly better-targeted than the send that misrouted — and the run is failed with the new `DEPLOYMENT_MISMATCH` error code only once `WORKFLOW_DEPLOYMENT_MISMATCH_MAX_RETRIES` (default 3) is spent. Gated on the new World capability `deploymentAffinity`, so worlds with synthetic or version-tagged deployment ids are unaffected.
## Test Plan
Unit tests added for the guard and both runtime paths; local vitest and typechecks pass.
* feat(world,world-vercel,core): bulk run cancellation primitive
Add a bulk cancellation contract to @workflow/world (schemas, types, and an
optional Storage['runs'].cancelMany method), implement it in
@workflow/world-vercel via a single POST /v4/runs/cancel request, and add a
cancelRuns runtime helper to @workflow/core that uses the world fast path
when available and otherwise falls back to bounded-concurrency (max 20)
single-run cancellation.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* Update packages/world/src/interfaces.ts
Co-authored-by: Peter Wielander <mittgfu@gmail.com>
Signed-off-by: Karthik Kalyan <105607645+karthikscale3@users.noreply.github.com>
---------
Signed-off-by: Karthik Kalyan <105607645+karthikscale3@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: Peter Wielander <mittgfu@gmail.com>
Nathan Colosimo