workflow 5.0.0-beta.3 → 5.0.0-beta.30

package/docs/deploying/world/local-world.mdx

@@ -38,7 +38,7 @@ Learn more in the [Observability](/docs/observability) documentation.
 
 ## Configuration
 
-The local world works with zero configuration, but you can customize behavior through environment variables or programmatically via `createLocalWorld()`.
+The local world works with zero configuration, but you can customize behavior through environment variables or programmatically via `createWorld()`.
 
 ### `WORKFLOW_LOCAL_DATA_DIR`
 
@@ -56,22 +56,39 @@ Port resolution priority: `baseUrl` > `port` > `PORT` > auto-detected
 
 ### `WORKFLOW_LOCAL_QUEUE_CONCURRENCY`
 
-Maximum number of concurrent queue workers. Default: `100`
+Maximum number of concurrent queue message handlers. Default: `1000`
+
+### `WORKFLOW_LOCAL_QUEUE_MAX_VISIBILITY`
+
+Maximum number of seconds a local queue message can stay hidden before the handler rechecks the run. Default: unlimited.
+
+### `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
+
+Flush interval, in milliseconds, for buffered stream writes. Default: `10`.
 
 ### Programmatic configuration
 
-{/* @skip-typecheck: incomplete code sample */}
-```typescript title="workflow.config.ts" lineNumbers
-import { createLocalWorld } from "@workflow/world-local";
+Options passed to `createWorld()` take precedence over the environment variables above. Export the configured World from a module and point `WORKFLOW_TARGET_WORLD` at that module:
 
-const world = createLocalWorld({
+```typescript title="my-world.ts" lineNumbers
+import { createWorld } from "@workflow/world-local";
+
+export default createWorld({
   dataDir: "./custom-workflow-data",
   port: 5173,
   // baseUrl overrides port if set
   baseUrl: "https://local.example.com:3000",
+  recoverActiveRuns: true,
+  streamFlushIntervalMs: 10, // overrides WORKFLOW_STREAM_FLUSH_INTERVAL_MS
 });
 ```
 
+```bash title=".env"
+WORKFLOW_TARGET_WORLD="./my-world.ts"
+```
+
+`createWorld()` also accepts `tag`, which scopes local storage files to a suffix. It is mainly used by test harnesses that share one `.workflow-data` directory.
+
 ## Limitations
 
 The local world is designed for development, not production:

package/docs/deploying/world/postgres-world.mdx

@@ -22,6 +22,15 @@ Install the Postgres World package in your workflow project:
 @workflow/world-postgres
 ```
 
+<Callout type="info">
+Use the same release channel for `workflow` and `@workflow/world-postgres`. If
+your app uses a beta or other prerelease Workflow version, install the matching
+prerelease Postgres World package, such as
+`npm install @workflow/world-postgres@beta`. Mismatched versions fail before
+starting a run with an error that says the runtime requires a World with a
+matching spec version.
+</Callout>
+
 Configure the required environment variables to use the world and point it to your PostgreSQL database:
 
 ```bash title=".env"
@@ -29,12 +38,44 @@ WORKFLOW_TARGET_WORLD="@workflow/world-postgres"
 WORKFLOW_POSTGRES_URL="postgres://user:password@host:5432/database"
 ```
 
-Run the migration script to create the necessary tables in your database. Ensure `WORKFLOW_POSTGRES_URL` is set when running this command:
+Run the migration script to create the necessary tables in your database. Ensure `WORKFLOW_POSTGRES_URL` or `DATABASE_URL` is set when running this command:
+
+<Tabs items={["npm", "pnpm", "Yarn", "Bun"]}>
+
+<Tab value="npm">
+
+```bash
+npx --package=@workflow/world-postgres bootstrap
+```
+
+</Tab>
+
+<Tab value="pnpm">
+
+```bash
+pnpm dlx --package @workflow/world-postgres bootstrap
+```
+
+</Tab>
+
+<Tab value="Yarn">
 
 ```bash
-npx workflow-postgres-setup
+yarn dlx --package @workflow/world-postgres bootstrap
 ```
 
+</Tab>
+
+<Tab value="Bun">
+
+```bash
+bunx --package @workflow/world-postgres bootstrap
+```
+
+</Tab>
+
+</Tabs>
+
 <Callout type="info">
 The migration is idempotent and can safely be run as a post-deployment lifecycle script.
 </Callout>
@@ -149,41 +190,66 @@ Learn more in the [Observability](/docs/observability) documentation.
 
 All configuration options can be set via environment variables or programmatically via `createWorld()`.
 
-### `WORKFLOW_POSTGRES_URL` (required)
+### `WORKFLOW_POSTGRES_URL`
+
+PostgreSQL connection string used by the runtime World.
 
-PostgreSQL connection string. Falls back to `DATABASE_URL` if not set.
+Precedence: `WORKFLOW_POSTGRES_URL` > `DATABASE_URL` > `postgres://world:world@localhost:5432/world`
 
-Default: `postgres://world:world@localhost:5432/world`
+The `bootstrap` migration command uses the same precedence.
 
 ### `WORKFLOW_POSTGRES_JOB_PREFIX`
 
-Prefix for graphile-worker queue job names. Useful when sharing a database between multiple applications.
+Prefix for graphile-worker queue job names. Useful when sharing a database between multiple applications. Default: `workflow_`
 
 ### `WORKFLOW_POSTGRES_WORKER_CONCURRENCY`
 
-Number of concurrent workers polling for jobs. Default: `10`
+Number of concurrent workers polling for jobs. Default: `50`.
+
+This value also bounds how many parent→child workflow polls can be in flight simultaneously. Every `await childRun.returnValue` inside a workflow holds a worker slot until the child run terminates — if you expect recursive or highly-fanned-out parent/child workflows, raise this ceiling above the peak number of concurrent polls. With the default of 50, the included `fibonacciWorkflow` e2e test (fib(6), ~24 concurrent polls at peak) passes; deeper recursion or larger fanouts need a correspondingly larger setting.
 
 ### `WORKFLOW_POSTGRES_MAX_POOL_SIZE`
 
-Maximum size of the internal `pg.Pool` used when `createWorld()` constructs the pool. Default: `10`
+Maximum size of the internal `pg.Pool` used when `createWorld()` constructs the pool. Default: the `pg` default (`10`).
 
 For higher worker concurrency, Graphile Worker recommends setting `maxPoolSize` to `10` or `queueConcurrency + 2`, whichever is larger.
 
+### `WORKFLOW_QUEUE_NAMESPACE`
+
+Queue topic namespace shared by build output and the Postgres World. Default: unset.
+
+For example, `custom` changes the queue topic prefixes from `__wkf_workflow_` and `__wkf_step_` to `__custom_wkf_workflow_` and `__custom_wkf_step_`. The value must be lowercase alphanumeric and start with a letter.
+
+### `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
+
+Flush interval, in milliseconds, for buffered stream writes. Default: `10`.
+
 ### Programmatic configuration
 
 {/*@skip-typecheck: incomplete code sample*/}
 
-```typescript title="workflow.config.ts" lineNumbers
+```typescript title="my-world.ts" lineNumbers
 import { createWorld } from "@workflow/world-postgres";
 
-const world = createWorld({
-  connectionString: "postgres://user:password@host:5432/database",
+export default createWorld({
+  connectionString:
+    process.env.WORKFLOW_POSTGRES_URL ?? process.env.DATABASE_URL!,
   jobPrefix: "myapp_",
-  queueConcurrency: 20,
-  maxPoolSize: 20, // overrides WORKFLOW_POSTGRES_MAX_POOL_SIZE
+  namespace: "myapp",
+  queueConcurrency: 50,
+  maxPoolSize: 52, // overrides WORKFLOW_POSTGRES_MAX_POOL_SIZE
+  streamFlushIntervalMs: 10,
 });
 ```
 
+Options passed to `createWorld()` take precedence over the environment variables above. Export the World from a module and point `WORKFLOW_TARGET_WORLD` at that module:
+
+You can also pass an existing `pg.Pool` as `pool` instead of a connection string.
+
+```bash title=".env"
+WORKFLOW_TARGET_WORLD="./my-world.ts"
+```
+
 ## How It Works
 
 The Postgres World uses PostgreSQL as a durable backend:

package/docs/deploying/world/vercel-world.mdx

@@ -89,46 +89,79 @@ Learn more in the [Observability](/docs/observability) documentation.
 
 ## Configuration
 
-The Vercel World requires no configuration when deployed to Vercel. For advanced use cases, you can override settings programmatically via `createVercelWorld()`.
+In a Vercel deployment, you do not configure the Vercel World yourself. The platform injects everything the runtime needs, including `VERCEL_DEPLOYMENT_ID`, `VERCEL_PROJECT_ID`, per-request OIDC tokens, and `VERCEL_DEPLOYMENT_KEY` for encryption.
+
+Do not set those platform-provided values yourself.
+
+Most users never need to set the `WORKFLOW_VERCEL_*` variables below. They are only overrides for tools running outside Vercel, such as your laptop or CI, when those tools need to inspect or test a remote Vercel Workflow project and cannot infer the project, team, token, or target environment automatically.
+
+For example, you might set them when running `workflow inspect runs --backend vercel` from CI without an interactive `vercel login`, or when running tests against a specific preview deployment. In normal local development, the CLI infers these values from your `.vercel` directory and Vercel CLI login. In a deployed Vercel function, these variables have no effect on runtime configuration, and the runtime warns if they are set there.
 
 ### `WORKFLOW_VERCEL_ENV`
 
-The Vercel environment to use. Options: `production`, `preview`, `development`. Automatically detected.
+The Vercel environment to target. Options: `production`, `preview`. Default: `production`.
 
 ### `WORKFLOW_VERCEL_AUTH_TOKEN`
 
-Authentication token for API requests. Automatically detected.
+Vercel API authentication token (secret — keep it in your environment, not in code). Falls back to `VERCEL_TOKEN`, then to your Vercel CLI login.
 
 ### `WORKFLOW_VERCEL_PROJECT`
 
-Vercel project ID for API requests. Automatically detected.
+Vercel project ID (`prj_...`).
+
+### `WORKFLOW_VERCEL_PROJECT_NAME`
+
+Vercel project name/slug, used for dashboard links.
 
 ### `WORKFLOW_VERCEL_TEAM`
 
-Vercel team ID for API requests. Automatically detected.
+Vercel team ID.
 
 ### `WORKFLOW_VERCEL_BACKEND_URL`
 
-Custom base URL for the Vercel workflow API. Automatically detected.
+Custom base URL for the Vercel workflow API proxy. Default: `https://api.vercel.com/v1/workflow`.
+
+### `VERCEL_WORKFLOW_SERVER_URL`
+
+Custom workflow-server URL for direct runtime requests, or for the proxy to forward to via `WORKFLOW_VERCEL_BACKEND_URL`. Default: unset; normal deployments should not need this.
+
+### `VERCEL_QUEUE_MAX_DELAY_SECONDS`
+
+Maximum delay, in seconds, that Workflow uses for one Vercel Queues continuation message when implementing `sleep()`. If a workflow sleeps longer than this, the runtime schedules another continuation message when the first one fires, repeating until the sleep's target time is reached. Default: `82800` (23 hours).
+
+Vercel Queues can delay messages for up to 7 days, capped by the message TTL. Because the default TTL is 24 hours, Workflow uses a 23-hour continuation hop to stay safely inside that default.
+
+### `WORKFLOW_REQUEST_TIMEOUT_MS`
+
+Per-request timeout, in milliseconds, for Vercel World HTTP calls to workflow-server. Default: `60000`. Minimum: `1`.
+
+### `WORKFLOW_MAX_CHUNKS_PER_REQUEST`
+
+Maximum stream chunks written in one Vercel World request. Larger batches are split across multiple requests. Default: `1000`. Minimum: `1`.
 
 ### Programmatic configuration
 
+`createWorld()` accepts explicit API configuration. It does not read `WORKFLOW_VERCEL_*` automatically, so pass the environment values yourself when you want a configured World module:
+
 {/*@skip-typecheck: incomplete code sample*/}
 
-```typescript title="workflow.config.ts" lineNumbers
-import { createVercelWorld } from "@workflow/world-vercel";
+```typescript title="my-world.ts" lineNumbers
+import { createWorld } from "@workflow/world-vercel";
 
-const world = createVercelWorld({
+export default createWorld({
   token: process.env.WORKFLOW_VERCEL_AUTH_TOKEN,
-  baseUrl: "https://api.vercel.com/v1/workflow",
   projectConfig: {
-    projectId: "my-project",
-    teamId: "my-team",
+    projectId: "prj_...",
+    teamId: "team_...",
     environment: "production",
   },
 });
 ```
 
+```bash title=".env"
+WORKFLOW_TARGET_WORLD="./my-world.ts"
+```
+
 ## Versioning
 
 On Vercel, workflow runs are pegged to the deployment that started them. This means:
@@ -139,6 +172,8 @@ On Vercel, workflow runs are pegged to the deployment that started them. This me
 
 This ensures long-running workflows complete reliably without being affected by subsequent deployments.
 
+For the full model, including rerunning on latest and explicit upgrade boundaries, see [Versioning](/docs/foundations/versioning).
+
 ## Security
 
 ### Consumer function security

package/docs/errors/abort-signal-timeout-in-workflow.mdx

@@ -0,0 +1,80 @@
+---
+title: abort-signal-timeout-in-workflow
+description: AbortSignal.timeout() cannot be used inside workflow functions because it relies on real timers which break deterministic replay.
+type: troubleshooting
+summary: Use sleep() with AbortController instead of AbortSignal.timeout() in workflow functions.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/foundations/cancellation
+  - /docs/api-reference/workflow/sleep
+  - /docs/errors/timeout-in-workflow
+---
+
+## Error
+
+```
+AbortSignal.timeout() is not supported in workflow functions.
+Use sleep() with an AbortController instead.
+```
+
+## Why This Happens
+
+`AbortSignal.timeout()` creates a signal that aborts after a real-time delay using an internal timer. Workflow functions must be [deterministic](/docs/foundations/workflows-and-steps) to support replay — they run the same code multiple times during the workflow's lifecycle, using the [event log](/docs/how-it-works/event-sourcing) to resume execution to the correct point.
+
+Real-time timers break this determinism because:
+- On the first execution, the timer might fire after 10 seconds
+- On replay, the timer would fire again, but the event log may have already advanced past that point
+- The timer's behavior depends on wall-clock time, which varies between executions
+
+## How to Fix
+
+Use [`sleep()`](/docs/api-reference/workflow/sleep) with an `AbortController` to create a deterministic timeout that cancels in-flight work:
+
+**Before (incorrect):**
+
+{/* @skip-typecheck: intentionally incorrect example */}
+```typescript lineNumbers
+export async function workflow() {
+  "use workflow";
+
+  // This will throw an error
+  const signal = AbortSignal.timeout(10_000); // [!code highlight]
+  const result = await fetchData(signal);
+  return result;
+}
+```
+
+**After (correct):**
+
+```typescript lineNumbers
+import { sleep } from "workflow";
+
+export async function workflow() {
+  "use workflow";
+
+  const controller = new AbortController(); // [!code highlight]
+  void sleep("10s").then(() => controller.abort()); // [!code highlight]
+
+  return await fetchData(controller.signal);
+}
+
+async function fetchData(signal: AbortSignal) {
+  "use step";
+  const response = await fetch("https://api.example.com/data", { signal });
+  return response.json();
+}
+```
+
+The `sleep()` + `AbortController` pattern is the durable equivalent of `AbortSignal.timeout()`. The sleep is recorded in the event log, so it replays deterministically. If `fetchData` finishes within 10 seconds you get the response; if not, the timer fires `controller.abort()`, `fetch` rejects with an `AbortError`, and the step's failure propagates to the workflow as a `FatalError` (no retries — abort is intentional cancellation).
+
+<Callout type="info">
+`AbortSignal.timeout()` works normally inside step functions, since steps have full Node.js runtime access and are not replayed.
+</Callout>
+
+## Related
+
+- [Cancellation](/docs/foundations/cancellation) — Patterns for cancelling in-flight work
+- [`sleep()` API Reference](/docs/api-reference/workflow/sleep) — Durable sleep primitive
+- [Workflows and Steps](/docs/foundations/workflows-and-steps) — Why workflow functions must be deterministic
+- [`setTimeout` in Workflow](/docs/errors/timeout-in-workflow) — Similar restriction on `setTimeout`

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

@@ -9,21 +9,21 @@ 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 repeatedly cannot replay events in the event log. This usually means the event log is in an invalid state, such as duplicate or orphaned events, or that a runtime determinism bug persists across retry attempts.
 
-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 first retries transient replay divergence automatically; it marks the run as failed with this error only after replay still cannot recover.
 
 ## Error Message
 
 ```
-Unconsumed event in event log: eventType=<type>, correlationId=<id>, eventId=<id>. This indicates a corrupted or invalid event log.
+Workflow replay diverged <divergenceCount> times after <maxRecoveryReplays> recovery replays; latest divergent event was <eventId>. Last divergence: <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 (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.
 
-Instead of silently hanging, the runtime raises a `WorkflowRuntimeError` to fail the workflow fast and surface the problem.
+Instead of silently hanging, the runtime retries a divergent replay before failing the workflow and surfacing this terminal error.
 
 Common scenarios that produce this error:
 
@@ -45,7 +45,7 @@ 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 is displayed, automatic replay recovery has already been exhausted and the run has been marked as `failed`. You can re-run it using the **Re-run** button in the Workflow Dashboard.
 
 ### 3. Report the issue
 

package/docs/errors/hook-conflict.mdx

@@ -73,9 +73,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,14 +93,64 @@ 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
 
@@ -122,4 +172,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,41 +9,7 @@ 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
 

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 retry 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/runtime-decryption-failed.mdx

@@ -0,0 +1,77 @@
+---
+title: runtime-decryption-failed
+description: The SDK's built-in AES-GCM encryption layer failed to encrypt or decrypt a workflow payload.
+type: troubleshooting
+summary: Resolve runtime decryption failures caused by ciphertext corruption, key mismatch, or malformed envelopes.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/foundations/errors-and-retries
+---
+
+This error occurs when the Workflow SDK's built-in AES-GCM encryption layer fails while encrypting or decrypting a workflow payload. The SDK encrypts step inputs, step outputs, hook payloads, and other event-log data with a per-run AES-256 key whenever encryption is configured for the deployment.
+
+This is an **internal SDK failure** — your workflow code never invokes the encryption primitives directly. When this surfaces, it means the ciphertext, nonce, or auth tag the SDK tried to verify is not the bytes that were originally produced. The run is failed with the `RUNTIME_ERROR` classification.
+
+## Error Message
+
+```
+AES-256-GCM decryption failed: The operation failed for an operation-specific reason
+```
+
+The underlying cause is a native Web Crypto [`OperationError`](https://developer.mozilla.org/en-US/docs/Web/API/DOMException#operationerror) — most commonly raised by `AESCipherJob.onDone` in Node's `node:internal/crypto/util` module when the GCM authentication tag does not verify.
+
+The thrown `RuntimeDecryptionError` carries a small `context` object with diagnostic fields to help triangulate the source:
+
+- `operation` — `'encrypt'` or `'decrypt'`
+- `byteLength` — total byte length of the payload at the failure site
+- `formatPrefix` — the first 4 bytes of the input (`'encr'` for a well-formed encrypted envelope, otherwise a hex dump)
+
+## Why This Happens
+
+Common causes, in rough order of likelihood:
+
+1. **Ciphertext mutation or truncation in transit.** The encrypted payload reached the SDK with bytes that differ from what storage holds. Possible sources include a truncated HTTP response from a workflow-server ref endpoint, an edge-cache miss returning a partial 200, or a proxy drop during streaming. A truncated body whose first 4 bytes happen to still spell `encr` produces the exact "auth tag mismatch" symptom.
+2. **Key resolution mismatch.** The key used to decrypt is not the key that was used to encrypt — e.g. the run's `deploymentId` was not threaded through key resolution and the SDK fell back to the wrong deployment's key material.
+3. **Malformed encrypted envelope.** The envelope is too short to contain the GCM nonce (12 bytes) and auth tag (16 bytes), so decryption is rejected before it begins.
+
+## What To Do
+
+This error indicates an SDK or infrastructure problem — not a bug in your workflow code. Your workflow code does not need to change.
+
+### 1. Upgrade to the latest `workflow` package
+
+The underlying issue may have already been identified and fixed:
+
+```bash
+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.
+
+### 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. Include:
+
+- The version of the `workflow` package you are using
+- The run ID(s) of the affected workflow run(s)
+- The full error message, including the `context` fields (`operation`, `byteLength`, `formatPrefix`)
+- Whether the affected workflows make heavy use of large step inputs/outputs (which may indicate the failure is on the lazy-loaded ref read path)
+
+## This Error Cannot Be Caught
+
+Like other `WorkflowRuntimeError` subclasses, a runtime decryption failure is **not catchable** inside your workflow function. The runtime cannot safely continue executing user code when an event-log payload can't be verified, so the entire run fails immediately and is marked as `failed`.
+
+To handle this programmatically from outside the workflow, check the run status:
+
+```typescript lineNumbers
+import { getRun } from "workflow/api";
+
+const run = getRun("wrun_abc123");
+const status = await run.status;
+if (status === "failed") {
+  console.error("Run failed");
+}
+```