workflow 5.0.0-beta.5 → 5.0.0-beta.51

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,9 +77,9 @@ export async function processPayment() {
 }
 ```
 
-## Handling Hook Conflicts in Your Workflow
+## Handling hook conflicts
 
-When a hook conflict occurs, awaiting the hook will throw a `HookConflictError`. You can catch this error to handle the conflict gracefully:
+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:
 
 ```typescript lineNumbers
 import { createHook } from "workflow";
@@ -93,26 +97,76 @@ export async function processPayment(orderId: string) {
     if (HookConflictError.is(error)) { // [!code highlight]
       // Another workflow is already processing this order
       console.log(`Conflicting token: ${error.token}`);
-      return { success: false, reason: "duplicate-processing" };
+      if (error.conflictingRunId) {
+        console.log(`Active run: ${error.conflictingRunId}`);
+      }
+      return {
+        success: false,
+        reason: "duplicate-processing",
+        token: error.token,
+        runId: error.conflictingRunId
+      };
     }
     throw error; // Re-throw other errors
   }
 }
 ```
 
-This pattern is useful when you want to detect and handle duplicate processing attempts instead of letting the workflow fail.
+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
+
+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:
+
+```typescript lineNumbers
+import { getRun, resumeHook, start } from "workflow/api";
+import { processPayment } from "@/workflows/process-payment";
+
+type ProcessPaymentResult =
+  | { success: true; payment: unknown }
+  | {
+      success: false;
+      reason: "duplicate-processing";
+      token: string;
+      runId?: string;
+    };
+
+export async function POST(request: Request) {
+  const { orderId, payment } = await request.json();
+  const run = await start(processPayment, [orderId]);
+  const result = (await run.returnValue) as ProcessPaymentResult;
+
+  if (
+    result.success === false &&
+    result.reason === "duplicate-processing" &&
+    result.runId
+  ) {
+    await resumeHook(result.token, payment); // [!code highlight]
+    const activeRun = getRun(result.runId); // [!code highlight]
+
+    return Response.json({
+      delegatedToRunId: activeRun.runId,
+      result: await activeRun.returnValue
+    });
+  }
+
+  return Response.json(result);
+}
+```
+
+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
+## 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.)
@@ -122,4 +176,6 @@ After a workflow completes, its hook tokens become available for reuse by other
 ## Related
 
 - [Hooks](/docs/foundations/hooks) - Learn more about using hooks in workflows
+- [getRun](/docs/api-reference/workflow-api/get-run) - Retrieve or control the active run
+- [resumeHook](/docs/api-reference/workflow-api/resume-hook) - Deliver data to the active hook
 - [createWebhook](/docs/api-reference/workflow/create-webhook) - Alternative for fixed webhook URLs

package/docs/errors/index.mdx

@@ -9,43 +9,9 @@ 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>
+<AutoCards />
 
-## Learn More
+## 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.

package/docs/errors/run-expired.mdx

@@ -0,0 +1,85 @@
+---
+title: run-expired
+description: A run's data passed its retention boundary, so its result can no longer be read.
+type: troubleshooting
+summary: Read a run's result before it expires, or return it through a channel you control.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability/retention
+  - /docs/api-reference/workflow-api/start
+  - /docs/foundations/hooks
+---
+
+## Error
+
+```text
+Run "wrun_..." completed, but its data expired at 2026-08-28T05:02:35.009Z
+and is no longer readable.
+```
+
+Thrown as a `RunExpiredError` from `await run.returnValue`.
+
+## Why this happens
+
+A run's payloads — its input, output and error, and those of its steps — are
+kept only for as long as the World's retention policy says. Its *metadata* —
+id, status, timestamps — usually outlives them. So a run can be readable as a
+record while its result is already gone.
+
+Rather than hand back a placeholder that is indistinguishable from a value the
+workflow genuinely returned, `returnValue` throws.
+
+Two ways to reach it:
+
+- **The run was started with `experimental_retention: 0`.** Its data is
+  deleted the moment it reaches a terminal state, and that deletion races your
+  own read of the result — and generally wins. On these runs, expect this
+  error rather than treating it as an edge case. See
+  [Data retention](/docs/observability/retention).
+- **The run simply aged out.** It finished long enough ago that the World's
+  default retention window has passed.
+
+## How to respond
+
+`RunExpiredError` is terminal. Retrying will not bring the data back. Catch it
+and use the run's metadata to decide what you want to do.
+
+```typescript lineNumbers
+import { getRun } from "workflow/api"
+import { RunExpiredError } from "workflow/errors"
+
+export async function readResult(runId: string) {
+  try {
+    return await getRun(runId).returnValue
+  } catch (error) {
+    if (RunExpiredError.is(error)) { // [!code highlight]
+      // `runStatus` is the run's terminal status when the World still has
+      // it, so you can tell a successful run whose result is gone from a
+      // failed one whose error is gone.
+      if (error.runStatus === "completed") {
+        // The run succeeded; its result is simply no longer stored.
+      }
+      return null
+    }
+    throw error
+  }
+}
+```
+
+The error carries `runId`, `runStatus` and `expiredAt` when the World reports
+them.
+
+### If you need the result of a zero-retention run
+
+Do not read it back off the run. Send it somewhere you control while the run
+is still executing — a step that writes it to your own store. That is the
+intended pattern for `experimental_retention: 0`: the point of the option is
+that the platform does not keep your data, so the platform cannot also be where
+you fetch it from afterwards.
+
+## Related
+
+If the run is gone entirely — metadata included — the World reports it as
+missing and you get a `WorkflowRunNotFoundError` instead. That means the
+record itself has been cleaned up, not just its payloads.