workflow 5.0.0-beta.5 → 5.0.0-beta.50

package/docs/changelog/index.mdx

@@ -12,5 +12,7 @@ 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
-- [Serializable AbortController and AbortSignal](/docs/changelog/serializable-abort-controller) — March 12, 2026
+- [Durable hook resume](/docs/changelog/lazy-hook-resume) (August 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/lazy-event-creation.md

@@ -0,0 +1,127 @@
+---
+title: Lazy inline step start
+description: Defer step_created for the inline step and fold it into a single step_started, saving one world round-trip per inline step.
+---
+
+# Lazy inline step start
+
+## Motivation
+
+The owned-inline runtime path used to write two separate world events for a step it already owns and is about to run inline:
+
+1. `step_created`, written by the suspension handler (`suspension-handler.ts`)
+2. `step_started`, written by `executeStep` (`step-executor.ts`)
+3. `step_completed` / `step_failed`, written by `executeStep`
+
+On the Vercel world each `world.events.create` is a network round-trip, so for a sequential `"use step"` workflow this is pure latency between steps. Steps (1) and (2) are two round-trips for a step we already own and are about to execute in the same invocation.
+
+This change defers `step_created` for that one inline step: `executeStep` sends a single `step_started` carrying the step input, and the world creates the step on the fly. This materializes the step entity **and** a synthetic `step_created` event so replay still observes it. **Two writes per inline step instead of three.** It mirrors the existing [resilient `run_started` → `run_created`](./resilient-start) pattern.
+
+Steps that are *queued* (not run inline) keep their eager `step_created` and are unchanged. Only the single inline step per suspension is made lazy.
+
+## Design
+
+### Suspension handler
+
+- `handleSuspension` selects exactly one step to defer: the first uncreated step (`stepItems.find(item => stepsNeedingCreation.has(...))`), which matches the inline candidate the caller would have picked.
+- For that step it **skips** the `step_created` write and instead returns it as `lazyInlineStep = { correlationId, stepName, dehydratedInput }`. It is **not** added to `createdStepCorrelationIds` because ownership is no longer decided here.
+- A `lazyInlineStep` is designated only when there is no `hook.getConflict()` awaiter (`hasAwaitedHookCreation === false`). With an awaiter present nothing runs inline, so nothing is deferred.
+
+### `executeStep`
+
+- A new `lazyStepInput` parameter carries the already-dehydrated input. When present, the `step_started` event includes `input` so the world creates the step on the fly. When absent, `step_started` carries only `stepName` (the legacy contract).
+- For an **unregistered** step on the lazy path, `executeStep` sends the lazy `step_started` first to materialize the step, *then* writes `step_failed` (see [Materialize before failing](#materialize-before-failing-unregistered-steps) below).
+
+### World contract
+
+- `step_started` accepts an optional `input`. When provided for a non-existent step, the world atomically creates the step entity plus a **synthetic `step_created`** event (so the event log reads `created → started → completed`), then records `step_started`.
+- A `stepCreated` signal is added to the event result so callers can tell whether the lazy `step_started` created the step or attached to an existing one.
+- Worlds updated: `world-local`, `world-postgres`, `world-vercel`.
+
+## Interactions with inline execution
+
+### Exactly-one-owner is preserved (the race moved)
+
+The guarantee that exactly one handler runs a step's body inline is intact, but it resolves at a different event:
+
+- **Before:** ownership was won at the atomic `step_created` claim in the suspension handler; the loser caught `EntityConflictError` and queued instead.
+- **After:** two concurrent handlers may both *select* the same `lazyInlineStep` (selection is optimistic, before any race). The race is now the world's atomic create-claim inside the lazy `step_started` (lock file in world-local, `onConflictDoNothing` + unique index in world-postgres, `attribute_not_exists` on the server). The loser gets `EntityConflictError`, which `executeStep` maps to `{ type: 'skipped' }`, so it never runs the body.
+
+This is safe **because a lazy `step_started` is only ever sent for a brand-new step**. The suspension handler defers only steps with no prior `step_created` (`!hasCreatedEvent`).
+
+### Crash recovery is unchanged
+
+On crash recovery the step already has a `step_created` event in the log (`hasCreatedEvent === true`), so it is **not** a lazy candidate. It is re-queued and re-run via a normal **non-lazy** `step_started`, which re-starts a `running` step. At-least-once execution is preserved exactly as before.
+
+### Materialize before failing unregistered steps
+
+The inline path previously assumed an invariant: *by the time `executeStep` runs, the step entity already exists* (the suspension handler created it). The unregistered-step branch relied on this and writes `step_failed` directly, with no preceding `step_started`.
+
+With the `step_created` deferred, the entity no longer exists when `executeStep` bails for an unregistered step, so the `step_failed` write hits the world's "step must exist" ordering guard and is rejected, wedging the run until it times out. On the lazy path, send the lazy `step_started` first (creating the entity + synthetic `step_created`), then write `step_failed`. The lazy `step_started`'s atomic create-claim still preserves exactly-one-owner. A concurrent winner makes our create reject with `EntityConflictError` → `skipped`, so the failure is never written twice.
+
+This is the general rule the deferral introduces: **any inline path that writes a terminal step event must first ensure the deferred step has been materialized.**
+
+### Replay correctness and the inline-delta fast path
+
+The client step consumer (`step.ts`) sets `hasCreatedEvent` only when it observes a `step_created` event, and checks step-name divergence against `stepName`. The lazy path stays replay-correct only because the world writes a **synthetic `step_created`**: replay still sees `created → started → completed`. The input lives on the synthetic `step_created`; the `step_started` row drops the input but keeps `stepName` for the divergence check.
+
+This intersects with the inline-delta optimization. The delta returned on the `step_completed` write is consumed by the *next* replay in place of an `events.list`, diffed against `preInlineWriteCursor` (snapshotted before replay). Because the synthetic `step_created`, `step_started`, and `step_completed` are all written *after* that cursor, the world's "events since cursor" delta carries the full triple, so the next replay does not diverge. The delta gate (one step, no hooks/waits, the lone pending step is the inline one) is unchanged.
+
+### Pre-emption by attributes / hook conflicts
+
+When `attr_set` events force an immediate in-process replay, or a hook conflict forces a re-invocation, the handler skips the dispatch loop for that pass. The deferred step is therefore **neither created nor queued** on that pass; it is recreated and run on the following replay (where it is still a lazy candidate).
+
+This is a small behavioral improvement: previously the eager `step_created` left an orphan "created but never started" event when a step lost an attribute/hook race (e.g. `Promise.race([setAttributes(), step()])` where the attribute write wins and completes the run). With deferral, a step that loses the race is never created, reducing event-log garbage.
+
+### `hook.getConflict()` awaiter
+
+When a `hook.getConflict()` awaiter is present, no `lazyInlineStep` is designated, nothing runs inline, every step gets its eager `step_created` and is queued, and the handler re-invokes immediately so replay resolves the awaiter. This is identical to the pre-change behavior. The deferral never serializes the awaiter's parallel continuation behind an inline step.
+
+## Rollout and compatibility
+
+Server-first. The matching world-vercel backend change must deploy before this ships; the Vercel world targets a single backend whose spec version is always at least the SDK's, so the new SDK only ever talks to an already-upgraded backend. An old SDK against a new backend is safe because the lazy path is strictly additive. It triggers only when `step_started` carries both `stepName` and `input`, which old SDKs never send. For `world-local` / `world-postgres` the world ships in the same package as the runtime, so there is no version skew. Detection is by `input` presence on the event, mirroring resilient `run_started`, so no capability negotiation is needed.
+
+# Parallel inline steps + optimistic start
+
+A follow-up builds two more latency wins on top of lazy inline start. Both are client-side only; they reuse the world's lazy create-on-`step_started` support and need no further world/backend changes.
+
+## Inline up to N steps in parallel
+
+Previously the owned-inline path ran **exactly one** step inline per suspension and queued the rest. For a `Promise.all([stepA(), stepB(), stepC()])` fan-out that meant one branch ran inline while the others paid a queue round-trip each before making any progress.
+
+The suspension handler now defers `step_created` for up to **`WORKFLOW_MAX_INLINE_STEPS` (default 3)** steps and returns them as `lazyInlineSteps`. The runtime runs that batch inline **in parallel** (`Promise.all`), each via its own lazy `step_started`, and queues only the steps beyond the cap.
+
+- **Selection:** the first N uncreated steps, matching the previous single-step inline candidate. Steps beyond N keep their eager `step_created` and are queued exactly as before.
+- **Result aggregation:** `retry` steps (whose `step_started` succeeded, so the step exists) are re-queued per-step as background steps with their own delay. `throttled` steps are different: a throttle rejects the lazy `step_started` on the create-claim, so the step was *never created* and has no recoverable input. Re-queuing it as an input-less background step would make the world reject the bare `step_started` with "Step not found" and redeliver until it fails. Any throttle instead **defers redelivery of the orchestrator** (by the longest throttle backoff in the batch), which re-runs the throttled step inline *with its input* on replay. The runtime only loops back to replay in-process once every inline step has reached a terminal state.
+- **Inline-delta fast path:** still used only for the single-step sequential case (`lazyInlineSteps.length === 1`). With more than one inline step each writes its own events, so a per-write delta would be partial; multi-step batches fall back to a normal incremental `events.list`.
+- **Config:** `WORKFLOW_MAX_INLINE_STEPS` is clamped to 1..16. Setting it to `1` reproduces the previous single-inline-step behavior exactly (a useful kill-switch). Inline bodies run in parallel within one function invocation, so the cap also bounds per-handler memory/CPU fan-out.
+
+## Optimistic inline start (opt-in, off by default)
+
+Normally `executeStep` awaits `step_started` (the lazy create-claim round-trip) before running the body. Because the inline path already holds the step input locally, it doesn't actually need that round-trip to begin.
+
+When `WORKFLOW_OPTIMISTIC_INLINE_START` is enabled (set it to `1`/`true`; it is **off by default**), an inline step fires `step_started` **without awaiting it** and starts running the body immediately against locally-synthesized state. A lazy step is always brand-new, so attempt is 1, there is no prior error, and `startedAt` is now. All values are known without the server. The in-flight `step_started` is reconciled immediately before the terminal write:
+
+- **Lost the create-claim (409 / `EntityConflictError`)** → discard the body result and return `skipped`; the winning handler owns the terminal write.
+- **Run gone / throttled / too-early** → discard the body result and surface `gone` / `throttled` / `retry`.
+- **Transient (non-translatable) failure** → propagate it, so the queue redelivers exactly as the await path does today.
+- **Success** → write `step_completed` / `step_failed` / `step_retrying` as usual. Awaiting `step_started` before the terminal write keeps the event log ordered (`created → started → completed`).
+
+### Safety and the idempotency tradeoff
+
+- **Exactly-one terminal write is preserved.** Optimistic start changes only *when the body runs*, never who writes the terminal event. The terminal event is still gated by the lazy `step_started` create-claim, which is awaited before the terminal write. Losers return `skipped`.
+- **Bounded to attempt 1.** Only brand-new (`!hasCreatedEvent`) steps are lazy; a retried step already has a `step_created`, so it takes the normal await-then-run path with the real attempt counter. Synthesizing `attempt = 1` locally is therefore always correct.
+- **Why wider double-execution is off by default.** Running the body before confirming ownership means two handlers racing for the same step's create-claim can *both* run the side effects before either wins (previously the loser 409'd on `step_created` and skipped before running anything). This is unsafe for non-idempotent steps. In particular, two concurrent runs of a step that writes to the **workflow stream** (e.g. an AI agent streaming tokens) can interleave and **corrupt the stream data**. The optimization therefore ships **disabled**; enable it (`WORKFLOW_OPTIMISTIC_INLINE_START=1`) only for deployments whose inline step bodies are idempotent and stream-safe.
+
+## Queue messages: inline steps don't pay a round-trip
+
+Inline steps that **complete** never enqueue a per-step flow-route message. When every step in an inline batch reaches a terminal state with no pending background ops, the runtime continues its in-process loop and replays. A sequential chain (or a clean parallel fan-out) of inline steps therefore runs entirely within one invocation with **zero** queue messages. A workflow whose only work is three parallel inline steps issues no `queue()` calls.
+
+The only flow-route messages produced around an inline batch are:
+
+- **Pre-batch dispatch:** The steps *beyond* the inline cap (and any pending wait/sleep continuation). Inline steps are explicitly excluded from this dispatch.
+- **`retry` results:** One delayed message per retried step. A retry *is* the step becoming its own background invocation, so this is expected.
+- **`throttled` results:** A single deferral of the orchestrator message (see above).
+- **Pending background ops:** If any inline step left unflushed stream writes (e.g. output streams to blob storage), the loop breaks and enqueues **one** continuation (aggregated across the batch, not per-step) so `waitUntil` can flush before the next replay reads them.
+
+In other words: completed inline steps cost no queue round-trips; only steps that genuinely run as their own background invocations create new flow-route messages.

package/docs/changelog/lazy-hook-resume.mdx

@@ -0,0 +1,78 @@
+---
+title: Durable hook resume
+description: resumeHook() durably writes hook_received and only then publishes the workflow wake, so a resolved call can never be lost to a disposal race.
+---
+
+# Durable hook resume
+
+## Motivation
+
+The previous lazy path published the serialized hook payload on the workflow
+queue and left the queue consumer to create `hook_received`. If the hook was
+disposed after `resumeHook()` returned but before the consumer write committed,
+that write was rejected and the acknowledged queue delivery could not resume the
+workflow: the caller was told the resume succeeded, and it was lost.
+
+`resumeHook()` now resolves only after both the durable event write and the
+workflow wake have succeeded, in that order.
+
+## Design
+
+The dispatch is strictly serial:
+
+1. The hook is resolved by token. An unknown token throws `HookNotFoundError`.
+2. The producer writes `hook_received` durably into the run's event log. A
+   client-minted `resumeId` and payload digest ride the write when the backend
+   supports atomic resume claims, so transport-level retries of the same write
+   converge on exactly one committed event. A write refused because the hook
+   was disposed or the run ended throws `HookNotFoundError`.
+3. Only after the write is acknowledged does the producer publish the workflow
+   wake. The wake carries no payload — the payload lives in the event log — so
+   nothing rides on the queue message but the trigger. Publication is retried
+   a bounded number of times.
+
+Because the event is committed before the wake exists, a disposal or run
+completion racing the queue delivery cannot erase a resume the caller was told
+succeeded: the delivery replays the committed event from the log.
+
+- `ResumedHook.resilientResume` remains on the type for source compatibility
+  and is no longer set. The internal `resumeHookDurable()` entry point is
+  removed; `resumeHook()` itself now provides the durable guarantee.
+
+A resolved call proves that the event is durable and the wake was accepted.
+`HookNotFoundError` proves this invocation committed no event. Any other thrown
+error is ambiguous only in *dispatch*, never in durability: a wake failure
+after the write leaves the event committed, and any later wake of the run
+(from any source) delivers it. A fresh `resumeHook()` invocation mints a new
+`resumeId`, so blindly retrying a failed call can append a second
+`hook_received`; callers that need at-most-once behavior across separate
+invocations must deduplicate on their own request key.
+
+## Behavior change: resumes against an ended run
+
+The lazy path never observed the server's rejection — it published a message
+and resolved, so a resume against a run that had already ended reported
+success (reachable whenever the hook record outlives its run, e.g. token
+retention). The durable write restores the check: **a resume against an ended
+run now throws `HookNotFoundError`**, and a late webhook delivery to a
+finished run answers 404 where it previously answered 202. Senders that treat
+4xx as terminal will stop retrying such deliveries; that is the correct
+signal, since nothing can resume an ended run.
+
+A transient write conflict (HTTP 409, e.g. an event-slot conflict that
+escaped the server's internal retry budget under contention) is no longer
+re-keyed to `HookNotFoundError`. It surfaces as a retryable error, and its
+rejected transaction committed nothing, so retrying the resume is safe.
+
+## Compatibility
+
+Nothing about the queue message changes: the wake has the same shape the
+sequential path always published, so no consumer, backend, or server
+coordination is needed and either side can roll back independently.
+
+Consumers continue to accept legacy `hookInput` messages from older producers,
+materializing their payload before replay. This permits rolling upgrades
+without a coordinated producer and consumer deployment.
+
+`WORKFLOW_DISABLE_LAZY_HOOK_RESUME` no longer gates anything and is ignored:
+there is no lazy path left to disable.

package/docs/changelog/meta.json

@@ -1,5 +1,15 @@
 {
   "title": "Changelog",
-  "pages": ["index", "eager-processing", "resilient-start"],
+  "pages": [
+    "index",
+    "lazy-hook-resume",
+    "eager-processing",
+    "resilient-resume",
+    "resilient-start",
+    "lazy-event-creation",
+    "turbo-mode",
+    "step-message-ownership",
+    "batched-event-writes"
+  ],
   "defaultOpen": false
 }

package/docs/changelog/resilient-resume.mdx

@@ -0,0 +1,32 @@
+---
+title: Resilient hook resume
+description: resumeHook() now tolerates transient event storage failures when the queue is healthy instead of failing the resume.
+---
+
+# Resilient `resumeHook()`
+
+<Callout type="info">
+  Superseded by [durable hook resume](/docs/changelog/lazy-hook-resume):
+  `resumeHook()` now writes the `hook_received` event durably and only then
+  publishes the workflow wake, so the two-writer design, the queue-carried
+  payload, and the `resilientResume` flag described below are historical. The
+  `(runId, resumeId)` constraint remains, converging transport-level retries
+  of the producer's own write (and legacy `hookInput` redeliveries from older
+  producers).
+</Callout>
+
+## 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 retriggered, 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 or legacy runs), `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 uses the sequential path.