workflow 5.0.0-beta.0 → 5.0.0-beta.10

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

@@ -53,7 +53,8 @@ Create an `instrumentation.ts` file in your project root:
 export async function register() {
   if (process.env.NEXT_RUNTIME !== "edge") {
     const { getWorld } = await import("workflow/runtime");
-    await getWorld().start?.();
+    const world = await getWorld();
+    await world.start?.();
   }
 }
 ```
@@ -73,7 +74,8 @@ import type { ServerInit } from "@sveltejs/kit";
 
 export const init: ServerInit = async () => {
   const { getWorld } = await import("workflow/runtime");
-  await getWorld().start?.();
+  const world = await getWorld();
+  await world.start?.();
 };
 ```
 
@@ -92,7 +94,8 @@ import { defineNitroPlugin } from "nitro/~internal/runtime/plugin";
 
 export default defineNitroPlugin(async () => {
   const { getWorld } = await import("workflow/runtime");
-  await getWorld().start?.();
+  const world = await getWorld();
+  await world.start?.();
 });
 ```
 
@@ -138,7 +141,7 @@ If `WORKFLOW_POSTGRES_URL` is not set, the CLI defaults to `postgres://world:wor
 
 Learn more in the [Observability](/docs/observability) documentation.
 
-## Testing & Performance
+## Testing & Compatibility
 
 <WorldTestingPerformance />
 
@@ -158,7 +161,9 @@ Prefix for graphile-worker queue job names. Useful when sharing a database betwe
 
 ### `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`
 
@@ -168,15 +173,16 @@ For higher worker concurrency, Graphile Worker recommends setting `maxPoolSize`
 
 ### Programmatic configuration
 
-{/* @skip-typecheck: incomplete code sample */}
+{/*@skip-typecheck: incomplete code sample*/}
+
 ```typescript title="workflow.config.ts" lineNumbers
 import { createWorld } from "@workflow/world-postgres";
 
 const world = createWorld({
   connectionString: "postgres://user:password@host:5432/database",
   jobPrefix: "myapp_",
-  queueConcurrency: 20,
-  maxPoolSize: 20, // overrides WORKFLOW_POSTGRES_MAX_POOL_SIZE
+  queueConcurrency: 50,
+  maxPoolSize: 52, // overrides WORKFLOW_POSTGRES_MAX_POOL_SIZE
 });
 ```
 
@@ -200,6 +206,7 @@ Deploy your application to any cloud that supports long-running servers:
 - Platform-as-a-Service providers (Railway, Render, Fly.io, etc.)
 
 Ensure your deployment has:
+
 1. Network access to your PostgreSQL database
 2. Environment variables configured correctly
 3. The `start()` function called on server initialization

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

@@ -83,7 +83,7 @@ npx workflow inspect runs \
 
 Learn more in the [Observability](/docs/observability) documentation.
 
-## Testing & Performance
+## Testing & Compatibility
 
 <WorldTestingPerformance />
 
@@ -139,6 +139,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/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

@@ -43,6 +43,9 @@ Fix common mistakes when creating and executing workflows in the **Workflow SDK*
     <Card href="/docs/errors/workflow-not-registered" title="workflow-not-registered">
         Resolve workflow not registered errors caused by deployment mismatches.
     </Card>
+    <Card href="/docs/errors/runtime-decryption-failed" title="runtime-decryption-failed">
+        Resolve runtime decryption failures from the SDK's encryption layer.
+    </Card>
 </Cards>
 
 ## Learn More

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");
+}
+```

package/docs/errors/start-invalid-workflow-function.mdx

@@ -123,7 +123,7 @@ Before calling `start()`:
 1. Confirm the function includes `"use workflow"` as its first statement.
 2. Confirm your framework integration is enabled (for Next.js, wrap `next.config.ts` with [`withWorkflow()`](/docs/api-reference/workflow-next/with-workflow)).
 3. Pass the imported workflow function directly to `start()`, not a wrapper callback.
-4. Keep the function in a file that goes through Workflow DevKit's transform step.
+4. Keep the function in a file that goes through Workflow SDK's transform step.
 
 ## Related