workflow 5.0.0-beta.9 → 5.0.0

package/docs/errors/corrupted-event-log.mdx

@@ -1,39 +1,60 @@
 ---
 title: corrupted-event-log
-description: The workflow's event log contains an event that no consumer can process, indicating corruption or invalid state.
+description: The workflow's event log contains an event that cannot be processed or a stored payload that cannot be read.
 type: troubleshooting
-summary: Resolve corrupted event log errors caused by duplicate or orphaned events.
+summary: Resolve corrupted event log errors caused by invalid events or unreadable stored payloads.
 prerequisites:
   - /docs/foundations/workflows-and-steps
 related:
   - /docs/foundations/errors-and-retries
 ---
 
-This error occurs when the Workflow runtime encounters an event in the event log that no registered consumer can process. This means the event log is in an invalid state — typically due to duplicate or orphaned events.
+This error occurs when the Workflow runtime cannot safely replay the event log. The log may be in an invalid state, such as an orphaned event or one no consumer can attribute to anything the workflow did, or it may reference a stored payload that the World can no longer read.
 
-This is a **workflow-level fatal error**. It cannot be caught or handled inside your workflow code. A corrupted event log immediately fails the entire run without executing any more user code. The run must be retried from outside the workflow.
+This is a **workflow-level fatal error**. It cannot be caught or handled inside your workflow code. The runtime retries transient replay divergence automatically, but an unreadable stored payload is terminal immediately because replaying cannot restore it.
 
-## Error Message
+## Error message
 
+For replay divergence:
+
+```text
+Workflow replay diverged <divergenceCount> times after <maxRecoveryReplays> recovery replays; latest divergent event was <eventId>; divergent event ids: <eventId>, <eventId>, ... Last divergence: <details>
 ```
-Unconsumed event in event log: eventType=<type>, correlationId=<id>, eventId=<id>. This indicates a corrupted or invalid event log.
+
+The `divergent event ids` list has one entry per divergence in the recovery chain, oldest first. Every recovery replay diverging at the same event points at a fixed disagreement between the log and the code; ids that wander point at a race with another writer.
+
+`<details>` is the last divergence's own message. When the replay could not place an event, it names the invocation that was pending under that event's position at the time, and where the replay's walk over the log stood:
+
+```text
+Replay could not consume event: eventType=wait_created, correlationId=wait_<id>, eventId=<eventId>. pending at this id: step <stepName> (step_<id>). consumer: index=<n>, length=<n>, parked=<n>, lastConsumed=<eventId>
 ```
 
-## Why This Happens
+Steps, sleeps and hooks draw their ids from one sequence, so `pending at this id` reports the entity the replay put at that position, whatever its kind. In the example, the log recorded a sleep where this replay reached a step named `<stepName>`.
+
+For an unreadable stored payload:
+
+```text
+the event log references a payload that no longer exists in storage: <details>
+```
+
+## Why this happens
+
+Workflows persist their progress as an ordered event log. During replay, the runtime processes each event in sequence. Every event must be consumed by a matching callback, such as a step or sleep waiting for its result. An event no callback ever claims is one the runtime would have to drop to finish the run, so it fails the run instead of returning a result that silently ignored it.
 
-Workflows persist their progress as an ordered event log. During replay, the runtime processes each event in sequence — every event must be consumed by a matching callback (e.g., a step or sleep waiting for its result). When an event has no matching consumer, the runtime cannot advance past it, which would block all subsequent events and hang the workflow indefinitely.
+A delivery written from outside the replay, such as a hook firing or a step completing on another invocation, can land ahead of the events the replay is writing itself. That is ordinary concurrency rather than corruption, so the runtime holds such an event and offers it to each consumer the replay registers afterwards. The failure comes only when the workflow function returns while an event is still held, at which point no consumer can ever appear. A replay that suspends still holding one reports it on the span (`workflow.events.parked.count`, `.event_id`, `.event_type`) and leaves the decision to the replay that follows.
 
-Instead of silently hanging, the runtime raises a `WorkflowRuntimeError` to fail the workflow fast and surface the problem.
+Before failing on divergence, the runtime retries the replay and surfaces this terminal error only if replay still cannot recover. It does not retry a payload that the World reports as permanently missing.
 
 Common scenarios that produce this error:
 
-1. **Duplicate completion events** — Two `wait_completed` events for a single `wait_created`, or two `step_completed` events for the same step. The first is consumed normally, but the second has no consumer.
-2. **Orphaned events** — A `step_completed` or `wait_completed` event whose `correlationId` doesn't match any step or sleep in the workflow code.
-3. **Events after terminal state** — An event that arrives after its corresponding step or wait has already reached a terminal state (e.g., `step_retrying` after `step_completed`).
+- **An unclaimed event that repeats nothing**: A duplicate of a kind the log already records for that entity is read past rather than failing the run, so a second `step_completed` or `wait_completed` is not this error (see [Duplicate Events](/docs/how-it-works/event-sourcing#duplicate-events)). What fails is an unclaimed event with no earlier counterpart to defer to: a `step_started` behind a `step_completed` on a log that never recorded a `step_started`, for instance. No consumer remains for the step, and there is no earlier event of that kind the replay could be reading instead.
+- **Orphaned events**: A `step_completed` or `wait_completed` event whose `correlationId` doesn't match any step or sleep in the workflow code, so the replay reaches its end still holding it.
+- **A hole in the log**: Events are numbered by their position in the run's log, and those positions are dense, so a position below the log's highest that holds no event means the log the replay loaded is incomplete. The runtime cannot tell a position no write ever occupied from one whose event it failed to read, so it refuses to replay rather than produce a result that may be silently wrong. See [`WORKFLOW_SLOT_GAP_CHECK`](/docs/configuration/runtime-tuning#workflow_slot_gap_check).
+- **An unreadable stored payload**: An event row still references a payload object, but the World reports that the object no longer exists in its storage. The same log would fail on every replay, so the run fails immediately instead of retrying forever.
 
-## What To Do
+## What to do
 
-This error indicates a bug in the Workflow SDK or Workflow server — not in your workflow code. Your workflow code does not need to change. Follow these steps to resolve the issue:
+This error indicates a bug in the Workflow SDK or Workflow server, not in your workflow code. Your workflow code does not need to change. Follow these steps to resolve the issue:
 
 ### 1. Upgrade to the latest `workflow` package
 
@@ -45,18 +66,18 @@ npm install workflow@latest
 
 ### 2. Retry the failed run
 
-Since this is a fatal error, the run is automatically marked as `failed`. You can re-run it using the **Re-run** button in the Workflow Dashboard.
+If this error reports replay divergence, automatic replay recovery has already been exhausted. If it reports an unreadable payload, recovery cannot recreate that payload. In either case, the run has been marked as `failed`. You can re-run the workflow using the **Re-run** button in the Workflow Dashboard; a re-run starts a new run with a new event log.
 
 ### 3. Report the issue
 
-If the error persists after upgrading, please [open an issue on GitHub](https://github.com/vercel/workflow/issues/new) so we can investigate and fix the underlying bug. Include the following details to help us diagnose the problem:
+If the error persists after upgrading, [open an issue on GitHub](https://github.com/vercel/workflow/issues/new) so we can investigate and fix the underlying bug. Include the following details to help us diagnose the problem:
 
 - The version of the `workflow` package you are using
 - The run ID(s) of the affected workflow run(s)
-- The error message (including `eventType`, `correlationId`, and `eventId`)
+- The complete error message, including any `eventType`, `correlationId`, `eventId`, or payload details
 - Any details about the event log or the workflow that triggered the error
 
-## This Error Cannot Be Caught
+## This error cannot be caught
 
 Unlike other workflow errors, a corrupted event log error is **not catchable** inside your workflow function. Because the event log itself is invalid, the runtime cannot safely continue executing any user code. The entire run fails immediately and is marked as `failed`.
 

package/docs/errors/deployment-mismatch.mdx

@@ -0,0 +1,71 @@
+---
+title: deployment-mismatch
+description: A workflow run was delivered to a deployment other than the one it is pinned to.
+type: troubleshooting
+summary: Understand how Workflow recovers from a misrouted delivery, and why a run eventually fails with DEPLOYMENT_MISMATCH.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/foundations/versioning
+  - /docs/errors/runtime-decryption-failed
+  - /docs/foundations/errors-and-retries
+---
+
+Every run is pinned to a single deployment when it starts. When a queued workflow or step callback is delivered to a **different** deployment, Workflow does not execute it there. Instead it re-routes the message to the deployment the run is pinned to, and only if the run keeps arriving elsewhere does it fail with the `DEPLOYMENT_MISMATCH` classification.
+
+This is an SDK/runtime signal, not an error thrown by your workflow code, and it is not catchable inside a workflow function.
+
+## Error message
+
+```text
+Workflow run "wrun_..." is pinned to deployment "dpl_A", but was received by deployment "dpl_B". The runtime re-routed the message to "dpl_A" 3 times and it kept arriving elsewhere, so the run was stopped to protect against code-skew errors. Verify that the run's deployment is still available and that queue callbacks are routed to it.
+```
+
+When the queue definitively reports that the run's deployment cannot be reached (it was deleted, or aged out of its retention window), no re-route is possible and the message omits the re-routing clause. Transient or unknown publishing failures leave the current delivery unacknowledged so the queue can redeliver it; they do not fail the run or consume this recovery budget.
+
+## Why a run is pinned
+
+A run's deployment is chosen once, at [`start()`](/docs/api-reference/workflow-api/start):
+
+- By default it is the deployment that called `start()`. See [Versioning](/docs/foundations/versioning) for why runs are pinned this way.
+- With `start(workflow, args, { deploymentId })` it is the id you pass, so a run can deliberately target a deployment other than the one that created it.
+- With `deploymentId: "latest"` it is the most recent deployment for the current environment, resolved at start time.
+
+Whichever it is, that `deploymentId` is recorded on the run, and every subsequent workflow replay and step execution must happen on that deployment. Continuing on a different one is unsafe:
+
+1. **Code skew.** The workflow and step bundles on the receiving deployment may not match the code that produced the run's recorded history, so replay could diverge or produce incorrect results.
+2. **Encryption.** Step inputs and other event-log payloads are encrypted with a per-run key derived from the pinned deployment's key material. A different deployment derives the wrong key and cannot decrypt them, previously the source of a confusing [runtime-decryption-failed](/docs/errors/runtime-decryption-failed) that exhausted retries with no clear cause.
+
+So the runtime checks the pinned deployment before it executes anything, and `DEPLOYMENT_MISMATCH` names the result, instead of the mismatch surfacing later as an unrelated decryption failure.
+
+## Automatic recovery
+
+A deployment that receives a run it does not own first tries to fix the delivery rather than fail the run:
+
+1. It re-enqueues the message **explicitly addressed** to the run's own deployment. This is strictly better-addressed than the send that misrouted, which inherited the producing deployment's ambient id.
+2. Delivery is delayed with a short exponential backoff (1s, 2s, 4s).
+3. If the run keeps arriving at the wrong deployment, the run is failed with `DEPLOYMENT_MISMATCH` after `WORKFLOW_DEPLOYMENT_MISMATCH_MAX_RETRIES` attempts (default `3`). Set it to `0` to fail on the first misrouted delivery instead.
+
+Nothing is executed on the wrong deployment during recovery: no workflow code, no step body, no `step_started`, and no hook resume. Whatever the delivery was carrying travels with it, so a pending step keeps its identity and a hook resume keeps its payload: they run on the deployment that can actually decrypt them.
+
+Recovery attempts do not create events on the run, so a run that self-heals looks completely normal. They are reported on the invocation's trace span (`workflow.deployment.pinned_id`, `workflow.deployment_mismatch.retry_count`, `workflow.deployment_mismatch.recovered`) and as a runtime warning in your function logs.
+
+## What to do
+
+- **Re-run from the current deployment.** Trigger the workflow again from your latest deployment (or use the **Re-run** button in the Workflow Dashboard). The new run is pinned to the current deployment.
+- **Keep a run's deployment available** for the lifetime of that run. A run whose deployment has been deleted or has aged out cannot be resumed and must be re-run: recovery cannot help, so these fail on the first misrouted delivery. This applies to runs started with an explicit `deploymentId` too: pinning a run to an older deployment keeps it dependent on that deployment for its whole lifetime.
+- **Report it** if the pinned deployment was still available. Include both deployment IDs and the run ID from the error message, plus the trace span attributes above. A run that failed this way despite a reachable target is a routing fault worth investigating rather than something to work around.
+
+## This error cannot be caught
+
+Like other runtime signals, `DEPLOYMENT_MISMATCH` is **not catchable** inside your workflow function: the run is failed before any workflow or step code executes on the receiving deployment. Check the run status from outside instead:
+
+```typescript lineNumbers
+import { getRun } from "workflow/api";
+
+const run = getRun("wrun_abc123");
+const status = await run.status;
+if (status === "failed") {
+  console.error("Run failed");
+}
+```

package/docs/errors/fetch-in-workflow.mdx

@@ -9,21 +9,25 @@ related:
   - /docs/api-reference/workflow/fetch
 ---
 
+<CopyPrompt
+  text="Fix `fetch` usage inside workflow functions. Search workflow files for direct global `fetch(...)` calls and libraries such as AI SDK calls that use fetch. For basic HTTP calls inside a `&quot;use workflow&quot;` function, import `{ fetch }` from `workflow` and replace the global call. For SDK/client calls that need normal Node.js or provider behavior, move the call into a helper function with `&quot;use step&quot;` and call that step from the workflow. Keep all step inputs and outputs serializable. Verify the workflow starts and replays without the fetch-in-workflow error."
+/>
+
 This error occurs when you try to use `fetch()` directly in a workflow function, or when a library (like the AI SDK) tries to call `fetch()` under the hood.
 
-## Error Message
+## Error message
 
-```
+```text
 Global "fetch" is unavailable in workflow functions. Use the "fetch" step function from "workflow" to make HTTP requests.
 ```
 
-## Why This Happens
+## Why this happens
 
 Workflow functions run in a sandboxed environment without direct access to `fetch()`.
 
 Many libraries make HTTP requests under the hood. For example, the AI SDK's `generateText()` function calls `fetch()` to make HTTP requests to AI providers. When these libraries run inside a workflow function, they fail because the global `fetch` is not available.
 
-## Quick Fix
+## Quick fix
 
 Import the `fetch` step function from the `workflow` package and assign it to `globalThis.fetch` inside your workflow function. This version of `fetch` is a step function that wraps the standard `fetch` API, automatically handling serialization and providing retry capabilities. This will also make `fetch()` available to all functions and libraries in the current workflow function.
 
@@ -31,14 +35,13 @@ Import the `fetch` step function from the `workflow` package and assign it to `g
 
 ```typescript lineNumbers title="workflows/ai.ts"
 import { generateText } from "ai";
-import { openai } from "@ai-sdk/openai";
 
 export async function chatWorkflow(prompt: string) {
   "use workflow";
 
   // Error - generateText() calls fetch() under the hood
   const result = await generateText({ // [!code highlight]
-    model: openai("gpt-4"), // [!code highlight]
+    model: "spacexai/grok-4.6", // [!code highlight]
     prompt, // [!code highlight]
   }); // [!code highlight]
 
@@ -50,7 +53,6 @@ export async function chatWorkflow(prompt: string) {
 
 ```typescript lineNumbers title="workflows/ai.ts"
 import { generateText } from "ai";
-import { openai } from "@ai-sdk/openai";
 import { fetch } from "workflow"; // [!code highlight]
 
 export async function chatWorkflow(prompt: string) {
@@ -60,7 +62,7 @@ export async function chatWorkflow(prompt: string) {
 
   // Now generateText() can make HTTP requests via the fetch step
   const result = await generateText({
-    model: openai("gpt-4"),
+    model: "spacexai/grok-4.6",
     prompt,
   });
 
@@ -68,15 +70,14 @@ export async function chatWorkflow(prompt: string) {
 }
 ```
 
-## Common Scenarios
+## Common scenarios
 
-### AI SDK Integration
+### AI SDK integration
 
 This is the most common scenario - using AI SDK functions that make HTTP requests:
 
 ```typescript lineNumbers
 import { generateText, streamText } from "ai";
-import { openai } from "@ai-sdk/openai";
 import { fetch } from "workflow"; // [!code highlight]
 
 export async function aiWorkflow(userMessage: string) {
@@ -84,9 +85,9 @@ export async function aiWorkflow(userMessage: string) {
 
   globalThis.fetch = fetch; // [!code highlight]
 
-  // generateText makes HTTP requests to OpenAI
+  // generateText makes an HTTP request under the hood
   const response = await generateText({
-    model: openai("gpt-4"),
+    model: "spacexai/grok-4.6",
     prompt: userMessage,
   });
 
@@ -94,7 +95,7 @@ export async function aiWorkflow(userMessage: string) {
 }
 ```
 
-### Direct API Calls
+### Direct API calls
 
 You can also use the fetch step function directly for your own HTTP requests:
 

package/docs/errors/hook-conflict.mdx

@@ -10,15 +10,19 @@ related:
   - /docs/api-reference/workflow/define-hook
 ---
 
+<CopyPrompt
+  text="Fix hook token conflicts. Find every `createHook({ token })` or typed hook creation site. If multiple waits can exist at the same time, include a unique stable discriminator in the token such as `${workflowRunId}:approval:${itemId}` or `${orderId}:${attempt}` instead of reusing one global token. If duplicate work should join an existing run, catch `HookConflictError` from `@workflow/errors`, read the conflicting run ID from the error/result if available, and use `getRun(runId)` plus `resumeHook()` from `workflow/api` to deliver the payload to the active run. Keep token generation deterministic across retries so replay does not create new hook identities. Verify two concurrent runs and a duplicate request no longer throw hook-conflict unexpectedly."
+/>
+
 This error occurs when you try to create a hook with a token that is already in use by another active workflow run. Hook tokens must be unique across all running workflows in your project.
 
-## Error Message
+## Error message
 
-```
+```text
 Hook token "<token>" is already in use by another workflow
 ```
 
-## Why This Happens
+## Why this happens
 
 Hooks use tokens to identify incoming webhook payloads. When you create a hook with `createHook({ token: "my-token" })`, the Workflow runtime reserves that token for your workflow run. If another workflow run is already using that token, a conflict occurs.
 
@@ -27,9 +31,9 @@ This typically happens when:
 1. **Two workflows start simultaneously** with the same hardcoded token
 2. **A previous workflow run is still waiting** for a hook when a new run tries to use the same token
 
-## Common Causes
+## Common causes
 
-### Hardcoded Token Values
+### Hardcoded token values
 
 {/* @skip-typecheck: incomplete code sample */}
 ```typescript lineNumbers
@@ -57,7 +61,7 @@ export async function processPayment(orderId: string) {
 }
 ```
 
-### Omitting the Token (Auto-generated)
+### Omitting the token (auto-generated)
 
 The safest approach is to let the Workflow runtime generate a unique token automatically:
 
@@ -73,7 +77,7 @@ export async function processPayment() {
 }
 ```
 
-## Handling Hook Conflicts
+## Handling hook conflicts
 
 When a hook conflict occurs, awaiting the hook will throw a `HookConflictError`. The error exposes the token that conflicted and, for current worlds, the run ID that currently owns it. `conflictingRunId` remains optional for compatibility with older persisted events and world implementations, so guard it before delegating:
 
@@ -110,7 +114,7 @@ export async function processPayment(orderId: string) {
 
 This pattern is useful when you want to detect duplicate processing inside the workflow. Runtime APIs such as `resumeHook()` and `getRun()` must be called outside workflow functions, for example from an API route or in a step.
 
-### Delegate to the Active Run
+### Delegate to the active Run
 
 In idempotency flows, a conflict means another active run already owns the hook token. You can return the duplicate-processing payload from the workflow, resume the active hook to deliver the payload to the existing run, then use `getRun(result.runId)` to wait for, stream, or cancel the active run:
 
@@ -152,22 +156,45 @@ export async function POST(request: Request) {
 
 If the caller needs live output instead of the final result, return `activeRun.getReadable()` from the same branch. If the duplicate request should replace the active work, call `await activeRun.cancel()` after inspecting the run.
 
-## When Hook Tokens Are Released
+### Take the token over
+
+If the newest run should always own the token, create the hook with [`experimental_force: true`](/docs/api-reference/workflow/create-hook#take-over-a-token-another-run-holds). The new run takes the token instead of getting `HookConflictError`, and the previous owner's `await hook` rejects with [`HookForceClaimedError`](/docs/errors/hook-force-claimed).
+
+This enables zero-downtime transfers for hooks so one run can hand off a hook to another without dropping messages.
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+export async function processPayment(orderId: string) {
+  "use workflow";
+
+  const hook = createHook({
+    token: `payment-${orderId}`,
+    experimental_force: true, // [!code highlight]
+  });
+  const payment = await hook;
+}
+```
+
+A run started at a Workflow spec version below 8, including runs started by older SDK releases, can't be taken from, so the forced hook still gets `HookConflictError` in that case.
+
+## When hook tokens are released
 
 Hook tokens are automatically released when:
 
 - The workflow run **completes** (successfully or with an error)
-- The workflow run is **cancelled**
+- The workflow run is **canceled**
 - The hook is explicitly **disposed**
 
 After a workflow completes, its hook tokens become available for reuse by other workflows.
 
-## Best Practices
+## Best practices
 
 1. **Use auto-generated tokens** when possible - they are guaranteed to be unique
 2. **Include unique identifiers** if you need custom tokens (order ID, user ID, etc.)
 3. **Avoid reusing the same token** across multiple concurrent workflow runs
 4. **Consider using webhooks** (`createWebhook`) if you need a fixed, predictable URL that can receive multiple payloads
+5. **Use `experimental_force`** when a newer run should replace the run holding the token
 
 ## Related
 

package/docs/errors/hook-force-claimed.mdx

@@ -0,0 +1,96 @@
+---
+title: hook-force-claimed
+description: Another workflow run took this hook's token over with experimental_force.
+type: troubleshooting
+summary: Handle HookForceClaimedError by letting the replaced run wrap up while the new owner receives the token's payloads.
+prerequisites:
+  - /docs/foundations/hooks
+related:
+  - /docs/api-reference/workflow/create-hook
+  - /docs/api-reference/workflow-errors/hook-force-claimed-error
+---
+
+<CopyPrompt
+  text="Handle hook-force-claimed. Find every `createHook({ token })` whose token can be taken over by another run created with `experimental_force: true`. Wrap the `await hook` / `for await...of` in a try/catch, check `HookForceClaimedError.is(error)` from `workflow/errors`, and make the replaced run finish cleanly: persist or return anything it still owes (using `error.claimedByRunId` if the new owner should be told), then exit instead of retrying the await. If the run itself should be the one taking over, add `experimental_force: true` to its `createHook()` call and make sure the token is explicit. Verify that starting a second run with the same token wakes the first, that its await rejects with HookForceClaimedError, and that resumeHook() payloads sent after the takeover reach the second run."
+/>
+
+This error is thrown to a workflow run that was waiting on a hook when another run created a hook with the same token and [`experimental_force: true`](/docs/api-reference/workflow/create-hook#take-over-a-token-another-run-holds). The token moved to that run; this run's hook is disposed and will not receive anything further.
+
+## Error message
+
+```text
+Hook token "<token>" was force-claimed by another workflow (run "<runId>")
+```
+
+## Why this happens
+
+A hook token is owned by one active run at a time. Normally a second run asking for a held token gets [`HookConflictError`](/docs/errors/hook-conflict). With `experimental_force`, the second run takes the token instead:
+
+1. The holder's hook is disposed, and a `hook_disposed` event naming the new owner is written to the holder's event log.
+2. The holder is woken. If it was awaiting the hook, that promise rejects with `HookForceClaimedError`. Payloads that arrived before the takeover are still delivered first; a `for await...of` loop drains them and then throws.
+3. Every `resumeHook()` for the token from then on reaches the new owner, including a delivery that was already in flight. Senders are never told the token moved. The one exception is a `resumeWebhook()` request caught inside the handoff window: its body can be sent only once, so it fails with a retryable error instead of being redirected, and the sender's retry reaches the new owner.
+
+This is expected behavior, not a failure of the replaced run. It usually means a newer run for the same subject (a channel, a conversation, a device) has started and is meant to take over.
+
+## Handling the takeover
+
+Catch the error where the hook is awaited and let the run finish. The error tells you which run replaced this one:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+import { HookForceClaimedError } from "workflow/errors";
+
+declare function processMessage(message: { text: string }): Promise<void>; // @setup
+declare function flushDraft(channelId: string): Promise<void>; // @setup
+
+export async function channelWorkflow(channelId: string) {
+  "use workflow";
+
+  const hook = createHook<{ text: string }>({
+    token: `channel:${channelId}`,
+    experimental_force: true,
+  });
+
+  try {
+    for await (const message of hook) {
+      await processMessage(message);
+    }
+  } catch (error) {
+    if (HookForceClaimedError.is(error)) { // [!code highlight]
+      // A newer run owns the channel now. Hand off and stop.
+      await flushDraft(channelId);
+      return { replacedBy: error.claimedByRunId };
+    }
+    throw error;
+  }
+}
+```
+
+Anything the replaced run still needs to publish should happen in this branch. Do not create another hook with the same token here unless this run really should take the token back: runs forcing the same token converge on whichever registered last, and every other one receives this error again.
+
+## Several runs forcing the same token
+
+Any number of runs can force the same token at once without leaving the token or the runs in a bad state. The takeovers chain: each run that loses the token receives `HookForceClaimedError` naming the run that took it, exactly one run ends up owning the token, and a run that crashes halfway through its own takeover is completed by the next request for the token. Which of several simultaneous claimers wins is not defined, so start them in order if the order matters. If a run should fall back rather than keep fighting for the token, catch `HookForceClaimedError` and exit instead of forcing again.
+
+## Runs that cannot be taken from
+
+A run that was started at a Workflow spec version below 8 (an older SDK release, a Python SDK run, or a deployment with `WORKFLOW_SEALED_LOG=0`) would never learn that its hook was disposed. The World declines to take its token: the forced hook rejects with the ordinary [`HookConflictError`](/docs/errors/hook-conflict), whose `conflictingRunId` names that run, and the run keeps receiving its payloads. Handle it like any other conflict, for example by [delegating to the active run](/docs/errors/hook-conflict#delegate-to-the-active-run). A finished run holding a retained token is taken over at any version.
+
+## Deciding who takes over
+
+- **The newest run should win.** Create the hook with `experimental_force: true` in the workflow that starts on each new deployment, restart, or session. Older runs get `HookForceClaimedError` and exit.
+- **The first run should win.** Do not use `experimental_force`. Later runs get `HookConflictError` and can [delegate to the active run](/docs/errors/hook-conflict#delegate-to-the-active-run).
+- **Both runs should keep working.** Give them different tokens.
+
+## When it is thrown
+
+- To `await hook` and to `for await...of` once buffered payloads are drained.
+- On every later `await` of the same hook. `hook.getConflict()` resolves with `null`: the hook was registered, it just no longer holds the token.
+- Never to a run that has already finished. A token retained after the run ended with `experimental_minRetention` is taken over silently.
+
+## Related
+
+- [Hooks](/docs/foundations/hooks) - Taking over a token from another run
+- [createHook](/docs/api-reference/workflow/create-hook#take-over-a-token-another-run-holds) - The `experimental_force` option
+- [HookForceClaimedError](/docs/api-reference/workflow-errors/hook-force-claimed-error) - Error reference
+- [hook-conflict](/docs/errors/hook-conflict) - The default behavior without `experimental_force`

package/docs/errors/index.mdx

@@ -9,43 +9,30 @@ related:
 
 Fix common mistakes when creating and executing workflows in the **Workflow SDK**.
 
-<Cards>
-    <Card href="/docs/errors/fetch-in-workflow" title="fetch-in-workflow">
-        Learn how to use fetch in workflow functions.
-    </Card>
-    <Card href="/docs/errors/hook-conflict" title="hook-conflict">
-        Learn how to handle hook token conflicts between workflows.
-    </Card>
-    <Card href="/docs/errors/node-js-module-in-workflow" title="node-js-module-in-workflow">
-        Learn how to use Node.js modules in workflows.
-    </Card>
-    <Card href="/docs/errors/serialization-failed" title="serialization-failed">
-        Learn how to handle serialization failures in workflows.
-    </Card>
-    <Card href="/docs/errors/start-invalid-workflow-function" title="start-invalid-workflow-function">
-        Learn how to start an invalid workflow function.
-    </Card>
-    <Card href="/docs/errors/timeout-in-workflow" title="timeout-in-workflow">
-        Learn how to handle timing delays in workflow functions.
-    </Card>
-    <Card href="/docs/errors/webhook-invalid-respond-with-value" title="webhook-invalid-respond-with-value">
-        Learn how to use the correct `respondWith` values for webhooks.
-    </Card>
-    <Card href="/docs/errors/webhook-response-not-sent" title="webhook-response-not-sent">
-        Learn how to send responses when using manual webhook response mode.
-    </Card>
-    <Card href="/docs/errors/corrupted-event-log" title="corrupted-event-log">
-        Learn how to handle corrupted or invalid event logs.
-    </Card>
-    <Card href="/docs/errors/step-not-registered" title="step-not-registered">
-        Resolve step not registered errors caused by deployment mismatches.
-    </Card>
-    <Card href="/docs/errors/workflow-not-registered" title="workflow-not-registered">
-        Resolve workflow not registered errors caused by deployment mismatches.
-    </Card>
-</Cards>
-
-## Learn More
+## Error codes
+
+When a workflow run fails, its `errorCode` identifies the failure category. You can read it from [`WorkflowRunFailedError`](/docs/api-reference/workflow-errors/workflow-run-failed-error), the Workflow CLI's `error.code` field, or the `workflow.error.code` OpenTelemetry span attribute.
+
+| Code | Description |
+| --- | --- |
+| `USER_ERROR` | An error thrown by workflow or step code, including an unhandled step failure or `FatalError`. |
+| `RUNTIME_ERROR` | The Workflow runtime encountered an internal error, such as missing runtime data or an invariant failure. Persistent occurrences should be [reported](https://github.com/vercel/workflow/issues). |
+| [`CORRUPTED_EVENT_LOG`](/docs/errors/corrupted-event-log) | The run's event log cannot be replayed because it contains orphaned or mismatched events, a gap, or an unreadable stored payload. |
+| [`REPLAY_DIVERGENCE`](/docs/errors/replay-divergence) | One replay could not consume the event log deterministically. The runtime automatically retries before treating repeated divergence as a corrupted event log. |
+| `MAX_DELIVERIES_EXCEEDED` | The run exceeded the maximum number of queue deliveries, usually because a persistent failure kept causing redelivery. |
+| `MAX_EVENTS_EXCEEDED` | The run reached the World's per-run event limit. Split unbounded work into child workflows before reaching the limit. |
+| `REPLAY_TIMEOUT` | Workflow replay exceeded the configured duration limit. This measures workflow execution and event-log replay between step boundaries, not time spent inside step functions. |
+| `STREAM_ERROR` | Workflow stream infrastructure failed while reading or writing data. This is an SDK or backend failure rather than an error in workflow code. |
+| `WORLD_CONTRACT_ERROR` | A World returned data that violated the SDK contract and could not be retried safely. This usually indicates a World implementation bug. |
+| [`DEPLOYMENT_MISMATCH`](/docs/errors/deployment-mismatch) | A run was delivered to a deployment other than the one it is pinned to, and automatic re-routing did not recover it. |
+
+For guidance on catching failures, retry behavior, and inspecting `WorkflowRunFailedError`, see [Errors and retries](/docs/foundations/errors-and-retries).
+
+## Troubleshooting guides
+
+<AutoCards />
+
+## Learn more
 
 * [API Reference](/docs/api-reference) - Complete API documentation
 * [Foundations](/docs/foundations) - Architecture and core concepts

package/docs/errors/node-js-module-in-workflow.mdx

@@ -9,21 +9,25 @@ related:
   - /docs/how-it-works/understanding-directives
 ---
 
+<CopyPrompt
+  text="Fix Node.js module usage inside workflow functions. Search workflow files for imports or direct usage of Node-only APIs such as `fs`, `path`, `crypto`, `process`, `http`, or SDK clients. Remove those imports from files/functions that execute under `&quot;use workflow&quot;`. Create helper functions with `&quot;use step&quot;` for filesystem, crypto, environment, network, database, or SDK work, and call those helpers from the workflow. Keep the workflow function limited to deterministic orchestration, serializable values, `sleep`, hooks, and step calls. Verify the workflow starts without node-js-module-in-workflow errors."
+/>
+
 This error occurs when you try to import or use Node.js core modules (like `fs`, `http`, `crypto`, `path`, etc.) directly inside a workflow function.
 
-## Error Message
+## Error message
 
-```
+```text
 Cannot use Node.js module "fs" in workflow functions. Move this module to a step function.
 ```
 
-## Why This Happens
+## Why this happens
 
 Workflow functions run in a sandboxed environment without full Node.js runtime access. This restriction is important for maintaining **determinism** - the ability to replay workflows exactly and resume from where they left off after suspensions or failures.
 
 Node.js modules have side effects and non-deterministic behavior that could break workflow replay guarantees.
 
-## Quick Fix
+## Quick fix
 
 Move any code using Node.js modules to a step function. Step functions have full Node.js runtime access.
 
@@ -64,7 +68,7 @@ async function read(filePath: string) {
 }
 ```
 
-## Common Node.js Modules
+## Common Node.js modules
 
 These common Node.js core modules cannot be used in workflow functions:
 

package/docs/errors/replay-divergence.mdx

@@ -0,0 +1,27 @@
+---
+title: replay-divergence
+description: A workflow replay temporarily followed a path that did not match its recorded events.
+type: troubleshooting
+summary: Understand automatic recovery when a workflow replay diverges from its event history.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/errors/corrupted-event-log
+  - /docs/foundations/errors-and-retries
+---
+
+A replay divergence occurs when one invocation of a workflow cannot consume the durable event history using the promises, hooks, sleeps, or steps it created during replay.
+
+This is an SDK/runtime signal, not an error thrown by your workflow code. It is not catchable inside a workflow function.
+
+## Automatic recovery
+
+A single divergent replay does not prove that persisted history is corrupted. For example, asynchronous delivery ordering may cause one invocation to follow the wrong side of a race while another replay can follow the recorded history correctly.
+
+The runtime automatically queues another replay when an invocation reports `REPLAY_DIVERGENCE`. No terminal `run_failed` event is written during these recovery attempts.
+
+If recovery replays continue to diverge after the recovery budget is exhausted, the runtime marks the run as failed with `CORRUPTED_EVENT_LOG` and records the latest divergent event for diagnosis.
+
+## What to do
+
+Most replay divergence signals recover without action. If a run ultimately fails with `CORRUPTED_EVENT_LOG`, update to the latest `workflow` package and report the run ID and error details if the failure persists.