workflow 5.0.0-beta.37 → 5.0.0-beta.39

package/README.md

@@ -28,22 +28,6 @@ The Workflow SDK community can be found on [GitHub Discussions](https://github.c
 
 Contributions to Workflow SDK are welcome and highly appreciated. Please use GitHub [issues](https://github.com/vercel/workflow/issues) and [discussions](https://github.com/vercel/workflow/discussions) to collaborate with the team and wider community.
 
-## Author list
-
-Workflow SDK was built by engineers at [Vercel](https://vercel.com) and the [Open Source Community](https://github.com/vercel/workflow/graphs/contributors).
-
-The initial core contributing engineers are:
-
-- Adrian Lam ([@adriandlam](https://github.com/adriandlam))
-- Dillon Mulroy ([@dmmulroy](https://github.com/dmmulroy))
-- Gal Schlezinger ([@Schniz](https://github.com/Schniz))
-- JJ Kasper ([@ijjk](https://github.com/ijjk))
-- Nathan Rajlich ([@TooTallNate](https://github.com/TooTallNate))
-- Peter Wielander ([@VaguelySerious](https://github.com/VaguelySerious))
-- Pranay Prakash ([@pranaygp](https://github.com/pranaygp))
-
-The Workflow SDK logo was designed by Cecilio Ruiz [@ceciliorz](https://x.com/ceciliorz)
-
 ---
 
 ## Security

package/dist/api.d.ts

@@ -1,6 +1,6 @@
 import '@workflow/core/runtime/world-init';
 export type { CancelRunOptions, Event, StopSleepOptions, StopSleepResult, WorkflowRun, } from '@workflow/core/runtime';
-export { getHookByToken, resumeHook, resumeWebhook, } from '@workflow/core/runtime/resume-hook';
+export { getHookByToken, type ResumedHook, resumeHook, resumeWebhook, } from '@workflow/core/runtime/resume-hook';
 export { getRun, Run, type WorkflowReadableStream, type WorkflowReadableStreamOptions, } from '@workflow/core/runtime/run';
 export { type StartOptions, start, } from '@workflow/core/runtime/start';
 //# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAOA,OAAO,mCAAmC,CAAC;AAE3C,YAAY,EACV,gBAAgB,EAChB,KAAK,EACL,gBAAgB,EAChB,eAAe,EACf,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,cAAc,EACd,UAAU,EACV,aAAa,GACd,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,MAAM,EACN,GAAG,EACH,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,GACnC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,GACN,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAOA,OAAO,mCAAmC,CAAC;AAE3C,YAAY,EACV,gBAAgB,EAChB,KAAK,EACL,gBAAgB,EAChB,eAAe,EACf,WAAW,GACZ,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,cAAc,EACd,KAAK,WAAW,EAChB,UAAU,EACV,aAAa,GACd,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,MAAM,EACN,GAAG,EACH,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,GACnC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,GACN,MAAM,8BAA8B,CAAC"}

package/dist/api.js

@@ -9,4 +9,4 @@ import '@workflow/core/runtime/world-init';
 export { getHookByToken, resumeHook, resumeWebhook, } from '@workflow/core/runtime/resume-hook';
 export { getRun, Run, } from '@workflow/core/runtime/run';
 export { start, } from '@workflow/core/runtime/start';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBpLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2FwaS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxxRUFBcUU7QUFDckUseUVBQXlFO0FBQ3pFLDJFQUEyRTtBQUMzRSw0RUFBNEU7QUFDNUUsNkVBQTZFO0FBQzdFLG1CQUFtQjtBQUNuQix5RUFBeUU7QUFDekUsT0FBTyxtQ0FBbUMsQ0FBQztBQVMzQyxPQUFPLEVBQ0wsY0FBYyxFQUNkLFVBQVUsRUFDVixhQUFhLEdBQ2QsTUFBTSxvQ0FBb0MsQ0FBQztBQUM1QyxPQUFPLEVBQ0wsTUFBTSxFQUNOLEdBQUcsR0FHSixNQUFNLDRCQUE0QixDQUFDO0FBQ3BDLE9BQU8sRUFFTCxLQUFLLEdBQ04sTUFBTSw4QkFBOEIsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIFNpZGUtZWZmZWN0IGltcG9ydDogZW5zdXJlIGB3b3JsZC50c2AgaXMgbG9hZGVkIHNvIGl0cyBtb2R1bGUtbG9hZFxuLy8gYGdsb2JhbFRoaXNbR2V0V29ybGRGbktleV0gPz89IGdldFdvcmxkYCByZWdpc3RyYXRpb24gZmlyZXMgYmVmb3JlIGFueVxuLy8gaG9zdCByb3V0ZSByZWFjaGVzIGBnZXRXb3JsZExhenkoKWAuIFdpdGhvdXQgdGhpcywgd2VicGFjay90dXJib3BhY2sgY2FuXG4vLyB0cmVlLXNoYWtlIGB3b3JsZC50c2Agb3V0IG9mIHJvdXRlcyB0aGF0IG9ubHkgdXNlIGBzdGFydGAuIFJlc29sdmVkIHRvIGFuXG4vLyBlbXB0eSBzdHViIHZpYSB0aGUgYHdvcmtmbG93YCBleHBvcnQgY29uZGl0aW9uIGluIFZNL3N0ZXAgYnVuZGxlcywgc28gdGhpc1xuLy8gc3RheXMgaG9zdC1vbmx5LlxuLy8gU2VlIGBAd29ya2Zsb3cvY29yZS9zcmMvcnVudGltZS93b3JsZC1pbml0LnRzYCBmb3IgdGhlIGZ1bGwgcmF0aW9uYWxlLlxuaW1wb3J0ICdAd29ya2Zsb3cvY29yZS9ydW50aW1lL3dvcmxkLWluaXQnO1xuXG5leHBvcnQgdHlwZSB7XG4gIENhbmNlbFJ1bk9wdGlvbnMsXG4gIEV2ZW50LFxuICBTdG9wU2xlZXBPcHRpb25zLFxuICBTdG9wU2xlZXBSZXN1bHQsXG4gIFdvcmtmbG93UnVuLFxufSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lJztcbmV4cG9ydCB7XG4gIGdldEhvb2tCeVRva2VuLFxuICByZXN1bWVIb29rLFxuICByZXN1bWVXZWJob29rLFxufSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lL3Jlc3VtZS1ob29rJztcbmV4cG9ydCB7XG4gIGdldFJ1bixcbiAgUnVuLFxuICB0eXBlIFdvcmtmbG93UmVhZGFibGVTdHJlYW0sXG4gIHR5cGUgV29ya2Zsb3dSZWFkYWJsZVN0cmVhbU9wdGlvbnMsXG59IGZyb20gJ0B3b3JrZmxvdy9jb3JlL3J1bnRpbWUvcnVuJztcbmV4cG9ydCB7XG4gIHR5cGUgU3RhcnRPcHRpb25zLFxuICBzdGFydCxcbn0gZnJvbSAnQHdvcmtmbG93L2NvcmUvcnVudGltZS9zdGFydCc7XG4iXX0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYXBpLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2FwaS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxxRUFBcUU7QUFDckUseUVBQXlFO0FBQ3pFLDJFQUEyRTtBQUMzRSw0RUFBNEU7QUFDNUUsNkVBQTZFO0FBQzdFLG1CQUFtQjtBQUNuQix5RUFBeUU7QUFDekUsT0FBTyxtQ0FBbUMsQ0FBQztBQVMzQyxPQUFPLEVBQ0wsY0FBYyxFQUVkLFVBQVUsRUFDVixhQUFhLEdBQ2QsTUFBTSxvQ0FBb0MsQ0FBQztBQUM1QyxPQUFPLEVBQ0wsTUFBTSxFQUNOLEdBQUcsR0FHSixNQUFNLDRCQUE0QixDQUFDO0FBQ3BDLE9BQU8sRUFFTCxLQUFLLEdBQ04sTUFBTSw4QkFBOEIsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIFNpZGUtZWZmZWN0IGltcG9ydDogZW5zdXJlIGB3b3JsZC50c2AgaXMgbG9hZGVkIHNvIGl0cyBtb2R1bGUtbG9hZFxuLy8gYGdsb2JhbFRoaXNbR2V0V29ybGRGbktleV0gPz89IGdldFdvcmxkYCByZWdpc3RyYXRpb24gZmlyZXMgYmVmb3JlIGFueVxuLy8gaG9zdCByb3V0ZSByZWFjaGVzIGBnZXRXb3JsZExhenkoKWAuIFdpdGhvdXQgdGhpcywgd2VicGFjay90dXJib3BhY2sgY2FuXG4vLyB0cmVlLXNoYWtlIGB3b3JsZC50c2Agb3V0IG9mIHJvdXRlcyB0aGF0IG9ubHkgdXNlIGBzdGFydGAuIFJlc29sdmVkIHRvIGFuXG4vLyBlbXB0eSBzdHViIHZpYSB0aGUgYHdvcmtmbG93YCBleHBvcnQgY29uZGl0aW9uIGluIFZNL3N0ZXAgYnVuZGxlcywgc28gdGhpc1xuLy8gc3RheXMgaG9zdC1vbmx5LlxuLy8gU2VlIGBAd29ya2Zsb3cvY29yZS9zcmMvcnVudGltZS93b3JsZC1pbml0LnRzYCBmb3IgdGhlIGZ1bGwgcmF0aW9uYWxlLlxuaW1wb3J0ICdAd29ya2Zsb3cvY29yZS9ydW50aW1lL3dvcmxkLWluaXQnO1xuXG5leHBvcnQgdHlwZSB7XG4gIENhbmNlbFJ1bk9wdGlvbnMsXG4gIEV2ZW50LFxuICBTdG9wU2xlZXBPcHRpb25zLFxuICBTdG9wU2xlZXBSZXN1bHQsXG4gIFdvcmtmbG93UnVuLFxufSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lJztcbmV4cG9ydCB7XG4gIGdldEhvb2tCeVRva2VuLFxuICB0eXBlIFJlc3VtZWRIb29rLFxuICByZXN1bWVIb29rLFxuICByZXN1bWVXZWJob29rLFxufSBmcm9tICdAd29ya2Zsb3cvY29yZS9ydW50aW1lL3Jlc3VtZS1ob29rJztcbmV4cG9ydCB7XG4gIGdldFJ1bixcbiAgUnVuLFxuICB0eXBlIFdvcmtmbG93UmVhZGFibGVTdHJlYW0sXG4gIHR5cGUgV29ya2Zsb3dSZWFkYWJsZVN0cmVhbU9wdGlvbnMsXG59IGZyb20gJ0B3b3JrZmxvdy9jb3JlL3J1bnRpbWUvcnVuJztcbmV4cG9ydCB7XG4gIHR5cGUgU3RhcnRPcHRpb25zLFxuICBzdGFydCxcbn0gZnJvbSAnQHdvcmtmbG93L2NvcmUvcnVudGltZS9zdGFydCc7XG4iXX0=

package/docs/api-reference/workflow-api/resume-hook.mdx

@@ -50,7 +50,7 @@ showSections={["parameters"]}
 
 ### Returns
 
-Returns a `Promise<Hook>` that resolves to:
+Returns a `Promise<ResumedHook>` — a `Hook` extended with an optional `resilientResume` flag. Resolving means the resume was accepted and the workflow will continue, whether the `hook_received` event was written directly or, on the parallel fast path, delivered through the workflow queue for the runtime to materialize (see the [lazy hook resume changelog](/docs/changelog/resilient-resume)). `resilientResume` is `true` only when the direct event write failed transiently and the resume was recovered through the queue; on the happy path it is absent. The resolved hook:
 
 <TSDoc
 definition={`

package/docs/api-reference/workflow-errors/precondition-failed-error.mdx

@@ -8,14 +8,18 @@ related:
   - /docs/api-reference/workflow-errors/entity-conflict-error
 ---
 
-`PreconditionFailedError` is thrown by world implementations when an event creation is rejected because the client's event-log snapshot is stale — a newer out-of-band event (such as a received hook or a completed step) was recorded after the snapshot the client replayed from. It corresponds to HTTP 412 Precondition Failed semantics.
+`PreconditionFailedError` is thrown by world implementations when an event creation is rejected because the client's event-log snapshot is stale — either a newer out-of-band event (such as a received hook or a completed step) was recorded after the snapshot the client replayed from, or the snapshot is missing an event recorded at or before it. It corresponds to HTTP 412 Precondition Failed semantics.
 
-This only occurs when the optimistic-concurrency guard is enabled via `WORKFLOW_PRECONDITION_GUARD=1` (see [Runtime Tuning](/docs/configuration/runtime-tuning)); event creations that carry no snapshot are never rejected with this error.
+This only occurs while the optimistic-concurrency guard is enabled (`WORKFLOW_PRECONDITION_GUARD`, on by default — see [Runtime Tuning](/docs/configuration/runtime-tuning)); event creations that carry no snapshot are never rejected with this error.
+
+A world rejects only on evidence and accepts the creation whenever it cannot decide, so this error always means the snapshot really was stale — but not receiving it does not prove the snapshot was current.
 
 <Callout>
-The Workflow runtime handles this error automatically: it reloads the event log and retries, ultimately re-enqueueing the run for a fresh replay if it cannot catch up. You will only encounter it when interacting with world storage APIs directly.
+The Workflow runtime handles this error automatically: it restarts the replay in the same invocation from a corrected event log, and re-invokes the run for a fresh replay only once its in-process restart budget is spent. It never retries the rejected creation as-is, because a replay working from a corrected log derives different events. You will only encounter it when interacting with world storage APIs directly.
 </Callout>
 
+A world may attach the events the client was missing to the rejection as `details`, which lets the runtime restart without re-reading the event log. Doing so is optional, and the runtime falls back to a full reload when the details are absent or unusable.
+
 ```typescript lineNumbers
 import { PreconditionFailedError } from "workflow/errors"
 declare const world: { events: { create(...args: any[]): Promise<any> } }; // @setup
@@ -40,6 +44,8 @@ definition={`
 interface PreconditionFailedError {
   /** Delay in seconds before the operation should be retried. Present when the server sends a Retry-After header. */
   retryAfter?: number;
+  /** Optional rejection payload. A world may put the events the client was missing here, as \`{ events, cursor }\`, so the runtime can restart its replay without re-reading the event log. */
+  details?: unknown;
   /** The error message. */
   message: string;
 }

package/docs/changelog/index.mdx

@@ -12,5 +12,6 @@ Stay up to date with the latest changes to Workflow SDK.
 
 ## 2026
 
-- [Eager processing of steps and incremental event replay](/docs/changelog/eager-processing) - March 2026
+- [Resilient hook resume](/docs/changelog/resilient-resume) — July 2026
+- [Eager processing of steps and incremental event replay](/docs/changelog/eager-processing) — March 2026
 - Serializable AbortController and AbortSignal — March 12, 2026

package/docs/changelog/meta.json

@@ -3,6 +3,7 @@
   "pages": [
     "index",
     "eager-processing",
+    "resilient-resume",
     "resilient-start",
     "lazy-event-creation",
     "turbo-mode",

package/docs/changelog/resilient-resume.mdx

@@ -0,0 +1,22 @@
+---
+title: Resilient hook resume
+description: resumeHook() now tolerates transient event storage failures, as long as the queue is healthy, instead of failing the resume.
+---
+
+# Resilient `resumeHook()`
+
+## Motivation
+
+`resumeHook()` used to write the `hook_received` event and dispatch the workflow queue message strictly one after the other, so every resume paid two sequential round trips and a transient event-storage failure failed the whole resume even when the queue was healthy. This change runs both writes **concurrently** — cutting a round trip off resume latency — and, on the same path, brings `resumeHook()` to parity with [resilient `start()`](/docs/changelog/resilient-start): a transient event-write failure no longer fails the resume when the payload can still be delivered through the queue.
+
+## Design
+
+- On the fast path, `resumeHook()` writes the `hook_received` event and dispatches the workflow queue message **concurrently** (`Promise.allSettled`). The queue message carries a `hookInput` payload — the dehydrated hook payload plus a client-minted `resumeId` idempotency key, the hook token, and a payload digest.
+- A `(runId, resumeId)` dedup constraint keeps the two writers converging on **exactly one** `hook_received` event: whichever lands first wins, and the other is resolved server-side as success rather than a duplicate. The queue consumer idempotently re-ensures the event from `hookInput` before replay, so the resume is guaranteed even if the direct write never commits.
+- Replay also deduplicates: `hook_received` events sharing a `resumeId` belong to the same resume attempt, and only the first in the event log is delivered to workflow code. Even if a redelivery materializes the event twice, the payload reaches the workflow exactly once.
+- **Queue dispatch failure is fatal** — the run was not re-triggered, so no consumer will re-ensure the event, and `resumeHook()` throws. A transient event-write failure (429/5xx, a transport error, or an expected `(runId, resumeId)` conflict with the consumer's own re-ensure) is swallowed because the queue delivery still guarantees the resume; a terminal run surfaces as `HookNotFoundError`, and any other event-write error is rethrown.
+- `resumeHook()` returns `ResumedHook` (exported from `workflow/api`), which extends `Hook` with an optional `resilientResume` flag. The flag is `true` only when the direct write failed transiently and the resume was recovered through the queue; on the happy path and the sequential fallback it is absent.
+
+## Compatibility
+
+The parallel fast path is gated per resume: it activates only when both the target run's queue consumer and the live backend independently attest dedup support (re-checked on every resume, so rollout and rollback both degrade safely). Otherwise — for oversized payloads, legacy runs, or with `WORKFLOW_DISABLE_LAZY_HOOK_RESUME=1` — `resumeHook()` falls back to the original sequential write-then-dispatch path. Because runs keep executing on the deployment they were created on, a resume targeting a run from an older deployment simply uses the sequential path.

package/docs/configuration/runtime-tuning.mdx

@@ -38,16 +38,43 @@ For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPL
 - Default: `3`
 - Recovery replays before replay divergence is recorded as corruption.
 
+### `WORKFLOW_DISABLE_LAZY_HOOK_RESUME`
+
+- Default: enabled (lazy hook resume on)
+- Resuming a hook persists the `hook_received` event and publishes the workflow invocation concurrently, cutting a round trip off resume latency. On this parallel path the queue message also carries the payload, so a transient event-write failure still resumes the run — the queue consumer re-ensures the `hook_received` event before replay. A backend `(runId, resumeId)` constraint keeps the two writers converging on exactly one event.
+- The runtime falls back to the sequential path automatically when the consumer or backend does not attest dedup support (or the payload is too large to inline on the queue message). On the sequential path the event is written *before* dispatch and its failure fails the resume — the fallback trades that resilience away to stay safe when dedup is not enforced, it does not preserve it.
+- Set `1` to force the sequential path as a kill switch. The chosen strategy is reported on the resume span as `workflow.hook.resume_strategy`.
+
 ### `WORKFLOW_PRECONDITION_GUARD`
 
 - Default: enabled
-- An optimistic-concurrency guard for event creation: replay-context event creations send a `stateUpdatedAt` snapshot timestamp, and a backend that supports the guard rejects a creation with 412 ([`PreconditionFailedError`](/docs/api-reference/workflow-errors/precondition-failed-error)) when a newer out-of-band event (a received hook or a completed step) was recorded after that snapshot.
-- On rejection the runtime reloads the event log and retries, falling back to a queue re-invocation with a fresh replay if it cannot catch up.
+- An optimistic-concurrency guard for event creation: replay-context event creations describe the snapshot they replayed from — its latest event timestamp (`stateUpdatedAt`), the number of events it contains (`stateEventCount`), and its event-log cursor (`stateCursor`) — and a backend that supports the guard rejects a creation with 412 ([`PreconditionFailedError`](/docs/api-reference/workflow-errors/precondition-failed-error)) when a newer out-of-band event (a received hook or a completed step) was recorded after that snapshot, or when the snapshot is missing an event recorded at or before it.
+- On rejection the runtime restarts the replay in the same invocation from a corrected event log, and falls back to a re-invocation with a fresh replay once the restart budget is spent. The rejected write is never retried as-is: a replay working from a corrected log derives different events, so only a fresh replay may write again.
 - When enabled — and the World declares that it enforces the guard (`capabilities.preconditionGuard`; the Vercel World does) — the runtime also keeps the per-step event-log delta optimization (consuming the delta returned by a step's terminal write instead of issuing an extra `events.list` per step) active while the run has an open hook. Without an enforced guard, an open hook disables it.
 - While a hook is open on a guard-enforcing deployment, inline steps take the await-then-run path even when optimistic inline start is enabled: the step's `step_started` claim carries the snapshot and is awaited before the body runs, so a claim the backend rejects as stale never executes user code.
 - Backends that do not support the guard ignore the snapshot; they must not declare the capability, so guard-dependent optimizations stay off against them even when the flag is set.
+- The guard only ever rejects on evidence, and it fails open in every other case: a backend that cannot decide — because its record of recent events is incomplete, has expired, or covers only part of the run's history — must accept the write. A rejection therefore always means the snapshot really was incomplete, but the absence of one does not prove it was complete. Busy runs (wide step fan-outs, high hook volume) are the most likely to skip the check.
+- As a result, 412 volume describes a workload rather than the health of a deployment, and a run that never sees one is not evidence the guard is inactive.
 - Set `0` to disable.
 
+### `WORKFLOW_PRECONDITION_MAX_INPROCESS_RESTARTS`
+
+- Default: `3`
+- How many times a single invocation restarts its replay in-process after a rejected event creation before it falls back to a re-invocation.
+- A restart reloads the event log and rebuilds the workflow from scratch, so it costs a replay but no queue round trip. A World may attach the missing events to its rejection, in which case the first restart needs no event-log request at all.
+
+### `WORKFLOW_PRECONDITION_MAX_REINVOCATIONS`
+
+- Default: `5`
+- How many re-invocations one run may spend on rejected event creations before it is failed with `RUNTIME_ERROR`.
+- Counted on the run's queue messages rather than per invocation, because a re-invocation enqueues a fresh message and so restarts the ordinary delivery count. Without this budget a run whose event log keeps growing faster than it can be read would cycle indefinitely.
+
+### `WORKFLOW_PRECONDITION_REINVOKE_DELAY_SECONDS`
+
+- Default: `2`
+- Delay before a re-invocation caused by a rejected event creation.
+- Unlike an in-process restart, which re-reads immediately, a re-invocation only happens once the in-process budget failed to catch up — so the delay gives the other writers a moment to quiesce.
+
 ## Inline execution
 
 ### `WORKFLOW_V2_TIMEOUT_MS`
@@ -115,6 +142,14 @@ For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPL
 - Debug log filter with wildcards and negation.
 - Examples: `workflow:*`, `workflow:*,-workflow:telemetry:*`.
 
+## Transport
+
+### `WORKFLOW_H2_MULTIPLEX`
+
+- Default: enabled
+- On the Vercel World, lets concurrent event-log requests share one HTTP/2 connection instead of one connection per in-flight request.
+- Set `0` to send one event request per connection.
+
 ## Queue namespace
 
 ### `WORKFLOW_QUEUE_NAMESPACE`

package/docs/configuration/worlds.mdx

@@ -21,11 +21,11 @@ A [World](/docs/deploying) stores workflow state and delivers queue messages.
 
 Outside Vercel, Workflow defaults to the Local World. On Vercel, leave `WORKFLOW_TARGET_WORLD` unset for the normal case; Workflow detects the Vercel deployment and selects the Vercel World automatically.
 
-The World is selected when your app is **built**, not when it runs, and compiled into the server bundles. Detection therefore reads the build environment: `VERCEL_DEPLOYMENT_ID` when it is available, otherwise `VERCEL=1` for builds where no deployment exists yet. A dev server is never affected, because `VERCEL_ENV=development` and `NODE_ENV=development` both keep the Local World selected — including when `vercel env pull` has written `VERCEL=1` into `.env.local`.
+The World is selected when your app **runs**, from the environment of the process serving it, so changing `WORKFLOW_TARGET_WORLD` takes effect on the next start without a rebuild. Detection keys off `VERCEL_DEPLOYMENT_ID`, which Vercel sets in every deployed function and nothing else sets: with it, the Vercel World; without it, the Local World.
 
-If your build environment does not expose Vercel's system environment variables — for example a build that runs in a container of your own before uploading, or one where [system environment variables](https://vercel.com/docs/environment-variables/system-environment-variables) are disabled for the project — set `WORKFLOW_TARGET_WORLD=vercel` in the build environment. Without it, the deployment is built against the Local World and every run fails writing to a read-only filesystem. Switching this value requires a rebuild; changing it at runtime has no effect.
+Broader signals are deliberately ignored. `vercel env pull` writes `VERCEL=1` into `.env.local`, so a dev server or a production server started on your own machine sees it while running against a writable filesystem — where the Local World is the right choice. Set `WORKFLOW_TARGET_WORLD=vercel` explicitly if you want such a process to talk to the Vercel World; starting a run then fails with an error naming the missing `VERCEL_DEPLOYMENT_ID`.
 
-The mirror image applies when a build that looks like Vercel is served somewhere else: a production server started locally or in CI with an env file from `vercel env pull` has `VERCEL=1`, so it is built against the Vercel World and then has no `VERCEL_DEPLOYMENT_ID` at runtime. Starting a run in that server fails with an error saying so. To run the same code against your filesystem, set `WORKFLOW_TARGET_WORLD=local` and rebuild.
+A deployment that pins `WORKFLOW_TARGET_WORLD=local` warns at startup and fails on its first write, because a Vercel deployment's filesystem is read-only.
 
 Set `WORKFLOW_TARGET_WORLD` only when you want to use a custom or self-hosted World:
 
@@ -86,6 +86,18 @@ The Local World is the default outside Vercel and is intended for development.
 - Default: unlimited
 - Maximum seconds a local queue message stays hidden before the handler rechecks the run.
 
+### `WORKFLOW_LOCAL_HEADERS_TIMEOUT_MS`
+
+- Factory option: none
+- Default: `30000`
+- Maximum milliseconds to wait for a local queue handler to begin responding before the durable message is redelivered. Set to `0` to disable.
+
+### `WORKFLOW_LOCAL_BODY_TIMEOUT_MS`
+
+- Factory option: none
+- Default: `30000`
+- Maximum gap in milliseconds between response body chunks from a local queue handler before the durable message is redelivered. Set to `0` to disable.
+
 ### `recoverActiveRuns`
 
 - Environment variable: `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.37",
+  "version": "5.0.0-beta.39",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -59,18 +59,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "5.0.0-beta.37",
-    "@workflow/cli": "5.0.0-beta.37",
-    "@workflow/core": "5.0.0-beta.37",
-    "@workflow/errors": "5.0.0-beta.13",
+    "@workflow/astro": "5.0.0-beta.39",
+    "@workflow/cli": "5.0.0-beta.39",
+    "@workflow/core": "5.0.0-beta.39",
+    "@workflow/errors": "5.0.0-beta.15",
     "@workflow/typescript-plugin": "5.0.0-beta.5",
-    "@workflow/utils": "5.0.0-beta.7",
-    "@workflow/next": "5.0.0-beta.37",
-    "@workflow/nest": "5.0.0-beta.37",
-    "@workflow/nitro": "5.0.0-beta.37",
-    "@workflow/nuxt": "5.0.0-beta.37",
-    "@workflow/sveltekit": "5.0.0-beta.37",
-    "@workflow/rollup": "5.0.0-beta.37"
+    "@workflow/utils": "5.0.0-beta.8",
+    "@workflow/next": "5.0.0-beta.39",
+    "@workflow/nest": "5.0.0-beta.39",
+    "@workflow/nitro": "5.0.0-beta.39",
+    "@workflow/nuxt": "5.0.0-beta.39",
+    "@workflow/sveltekit": "5.0.0-beta.39",
+    "@workflow/rollup": "5.0.0-beta.39"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",