workflow 5.0.0-beta.1 → 5.0.0-beta.11

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
 

package/docs/foundations/cancellation.mdx

@@ -0,0 +1,460 @@
+---
+title: Cancellation
+description: Cancel long-running steps cooperatively using AbortSignal, or cancel entire workflow runs.
+type: conceptual
+summary: Cancel in-flight work with AbortSignal or stop entire workflow runs.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/foundations/common-patterns
+  - /docs/foundations/hooks
+  - /docs/how-it-works/cancellation
+---
+
+Workflow DevKit supports two cancellation mechanisms: **AbortSignal** for fine-grained, cooperative cancellation of individual operations, and **run cancellation** for stopping an entire workflow. This guide covers both.
+
+## AbortSignal
+
+`AbortController` and `AbortSignal` work across workflow and step boundaries. Create an `AbortController` with `new AbortController()` in a workflow function, pass its signal to steps, and call `abort()` — using the standard [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) API you already know.
+
+```typescript lineNumbers
+import { sleep } from "workflow";
+
+export async function cancellableWorkflow() {
+  "use workflow";
+
+  const controller = new AbortController(); // [!code highlight]
+
+  const result = await Promise.race([
+    longRunningStep(controller.signal), // [!code highlight]
+    sleep("30s").then(() => "timeout" as const),
+  ]);
+
+  if (result === "timeout") {
+    controller.abort(); // [!code highlight]
+    return { status: "timed out" };
+  }
+
+  return { status: "completed", result };
+}
+
+async function longRunningStep(signal: AbortSignal) {
+  "use step";
+
+  const response = await fetch("https://api.example.com/slow-operation", {
+    signal, // [!code highlight]
+  });
+
+  return response.json();
+}
+```
+
+No special imports, no wrapper functions — just the standard `AbortController` API.
+
+<Callout type="info">
+Cancellation is **cooperative**. Aborting a signal doesn't forcefully kill a step — it's up to the step's code to check `signal.aborted` or pass the signal to APIs like `fetch` that respect it. If a step ignores the signal, it runs to completion.
+</Callout>
+
+<Callout type="info">
+To learn how `AbortController` works durably across workflow suspensions, replays, and step boundaries, see [How Cancellation Works](/docs/how-it-works/cancellation).
+</Callout>
+
+### Timeout with Cancellation
+
+Race a step against a timeout, and cancel the step if the timeout wins:
+
+```typescript lineNumbers
+import { sleep } from "workflow";
+
+export async function fetchWithTimeout(url: string) {
+  "use workflow";
+
+  const controller = new AbortController();
+
+  const result = await Promise.race([
+    fetchUrl(url, controller.signal),
+    sleep("10s").then(() => null),
+  ]);
+
+  if (result === null) {
+    controller.abort(); // [!code highlight]
+    throw new Error(`Request to ${url} timed out after 10s`);
+  }
+
+  return result;
+}
+
+async function fetchUrl(url: string, signal: AbortSignal) {
+  "use step";
+  const response = await fetch(url, { signal });
+  return response.json();
+}
+```
+
+### Cancelling Parallel Work
+
+When racing multiple steps, cancel the losers:
+
+```typescript lineNumbers
+export async function firstResponder(urls: string[]) {
+  "use workflow";
+
+  const controller = new AbortController();
+
+  const result = await Promise.race( // [!code highlight]
+    urls.map((url) => fetchUrl(url, controller.signal)) // [!code highlight]
+  ); // [!code highlight]
+
+  controller.abort(); // Cancel remaining fetches // [!code highlight]
+
+  return result;
+}
+
+async function fetchUrl(url: string, signal: AbortSignal) {
+  "use step";
+  const response = await fetch(url, { signal });
+  return { url, data: await response.json() };
+}
+```
+
+### Passing Signal Through a Pipeline
+
+Pass the same signal to a chain of steps. Aborting cancels whichever step is currently running:
+
+```typescript lineNumbers
+declare function splitIntoChunks(data: ArrayBuffer): ArrayBuffer[]; // @setup
+declare function processChunk(chunk: ArrayBuffer): Promise<Uint8Array>; // @setup
+
+export async function pipelineWorkflow(dataUrl: string) {
+  "use workflow";
+
+  const controller = new AbortController();
+
+  try {
+    const raw = await downloadData(dataUrl, controller.signal);
+    const transformed = await transformData(raw, controller.signal);
+    const result = await uploadData(transformed, controller.signal);
+    return result;
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      return { status: "cancelled" };
+    }
+    throw err;
+  }
+}
+
+async function downloadData(url: string, signal: AbortSignal) {
+  "use step";
+  const response = await fetch(url, { signal });
+  return response.arrayBuffer();
+}
+
+async function transformData(data: ArrayBuffer, signal: AbortSignal) {
+  "use step";
+
+  signal.throwIfAborted(); // [!code highlight]
+
+  const chunks = splitIntoChunks(data);
+  const results = [];
+
+  for (const chunk of chunks) {
+    signal.throwIfAborted(); // [!code highlight]
+    results.push(await processChunk(chunk));
+  }
+
+  return Buffer.concat(results);
+}
+
+async function uploadData(data: ArrayBuffer, signal: AbortSignal) {
+  "use step";
+  await fetch("https://storage.example.com/upload", {
+    method: "POST",
+    body: data,
+    signal,
+  });
+  return { status: "uploaded" };
+}
+```
+
+### Step-Initiated Abort
+
+A step can receive the full `AbortController` and call `abort()` to cancel parallel work. This is useful for watchdog/monitor patterns where one step observes an external condition and cancels other in-flight steps:
+
+```typescript lineNumbers
+export async function processWithQuotaCheck(userId: string, dataUrl: string) {
+  "use workflow";
+
+  const controller = new AbortController();
+
+  // Run the work and a quota monitor in parallel
+  const [result] = await Promise.all([ // [!code highlight]
+    processData(dataUrl, controller.signal), // [!code highlight]
+    monitorQuota(userId, controller), // [!code highlight]
+  ]); // [!code highlight]
+
+  return result;
+}
+
+async function processData(url: string, signal: AbortSignal) {
+  "use step";
+  const response = await fetch(url, { signal });
+  const data = await response.arrayBuffer();
+  // ... expensive processing ...
+  return { processed: true };
+}
+
+async function monitorQuota(userId: string, controller: AbortController) {
+  "use step";
+
+  // Poll quota status while the other step is running
+  while (!controller.signal.aborted) {
+    const quota = await fetch(`https://api.example.com/quota/${userId}`);
+    const { exceeded } = await quota.json();
+
+    if (exceeded) {
+      controller.abort("Quota exceeded"); // Cancels processData // [!code highlight]
+      return;
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 5000));
+  }
+}
+```
+
+### User-Triggered Cancellation with Hooks
+
+Combine hooks with abort controllers to let users cancel in-flight work from an external API:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+export async function userCancellableWorkflow(jobId: string) {
+  "use workflow";
+
+  using cancelHook = createHook<{ reason: string }>({
+    token: `cancel:${jobId}`,
+  });
+
+  const controller = new AbortController();
+  const workPromise = doExpensiveWork(controller.signal);
+
+  const result = await Promise.race([ // [!code highlight]
+    workPromise.then((data) => ({ status: "completed", data })),
+    cancelHook.then((payload) => { // [!code highlight]
+      controller.abort(); // [!code highlight]
+      return { status: "cancelled", reason: payload.reason };
+    }),
+  ]);
+
+  return result;
+}
+
+async function doExpensiveWork(signal: AbortSignal) {
+  "use step";
+  const response = await fetch("https://api.example.com/expensive", { signal });
+  return response.json();
+}
+```
+
+```typescript title="app/api/cancel/route.ts" lineNumbers
+import { resumeHook } from "workflow/api";
+
+export async function POST(request: Request) {
+  const { jobId, reason } = await request.json();
+
+  await resumeHook(`cancel:${jobId}`, { reason });
+  return Response.json({ cancelled: true });
+}
+```
+
+### How Steps Handle Abort
+
+When an `AbortSignal` is aborted, the behavior depends on how the step uses it:
+
+| Usage | Behavior on Abort |
+|-------|-------------------|
+| `fetch(url, { signal })` | Request is cancelled, throws `AbortError` |
+| `signal.throwIfAborted()` | Throws the abort reason |
+| `signal.aborted` check | Returns `true`, step can exit gracefully |
+| `signal.addEventListener('abort', fn)` | Callback fires, step can clean up |
+| Ignored | Step runs to completion (abort is cooperative) |
+
+### Abort Errors Skip Retries
+
+When a step throws due to an abort (e.g., `fetch` throws `AbortError`, or `signal.throwIfAborted()` throws), the error is automatically wrapped in a `FatalError`. This means the step **skips retries** and the error bubbles up to the workflow immediately.
+
+This is the correct behavior because an abort is an intentional cancellation — retrying the step would just result in another abort. You don't need to manually wrap abort errors in `FatalError`.
+
+```typescript lineNumbers
+import { sleep } from "workflow";
+
+export async function workflow() {
+  "use workflow";
+  const controller = new AbortController();
+
+  try {
+    const result = await Promise.race([
+      cancellableStep(controller.signal),
+      sleep("5s").then(() => null),
+    ]);
+    if (result === null) controller.abort();
+    return result;
+  } catch (err) {
+    // AbortError arrives as FatalError — no retries attempted // [!code highlight]
+    return { status: "cancelled" };
+  }
+}
+
+async function cancellableStep(signal: AbortSignal) {
+  "use step";
+  // If this throws AbortError, it's automatically wrapped in FatalError
+  const response = await fetch("https://api.example.com/slow", { signal });
+  return response.json();
+}
+```
+
+### Passing AbortSignal as Workflow Input
+
+You can pass an `AbortSignal` from external code into a workflow via `start()`:
+
+{/* @skip-typecheck: myWorkflow is not declared, this is a conceptual snippet */}
+```typescript lineNumbers
+import { start } from "workflow/api";
+
+export async function POST(request: Request) {
+  const controller = new AbortController();
+  const run = await start(myWorkflow, [controller.signal]); // [!code highlight]
+
+  // Later, cancel from external code
+  controller.abort(); // [!code highlight]
+}
+```
+
+When the signal is serialized at the `start()` boundary, an event listener is attached to the external signal that writes the cancellation packet to the backing stream. This means the external `abort()` propagates into the workflow — but only while the originating process is still alive (same constraint as passing a `ReadableStream` as input).
+
+<Callout type="info">
+For reliable external cancellation that works regardless of process lifetime, prefer the [User-Triggered Cancellation with Hooks](#user-triggered-cancellation-with-hooks) pattern. Hooks are durable and don't depend on the caller's process staying alive.
+</Callout>
+
+## Run Cancellation
+
+Run cancellation stops an entire workflow at the next suspension point. Unlike `AbortSignal`, it is not cooperative — the workflow does not continue executing after cancellation.
+
+```typescript title="app/api/cancel-run/route.ts" lineNumbers
+import { getRun } from "workflow/api";
+
+export async function POST(request: Request) {
+  const { runId } = await request.json();
+
+  const run = getRun(runId);
+  await run.cancel(); // [!code highlight]
+
+  return Response.json({ cancelled: true });
+}
+```
+
+<Callout type="info">
+Calling `run.cancel()` is the same action as clicking the **Cancel** button on a run in the observability UI — both produce identical `run_cancelled` events in the event log.
+</Callout>
+
+When a run is cancelled:
+- The workflow stops at its next suspension point (step call, hook await, or sleep)
+- A `run_cancelled` event is recorded in the [event log](/docs/how-it-works/event-sourcing)
+- All associated hooks are disposed and their tokens released
+- Streams are closed
+
+<Callout type="info">
+Run cancellation does **not** automatically abort any outstanding `AbortSignal`s. Steps that are currently executing will run to completion. If you need in-flight cancellation of specific operations, use `AbortSignal`.
+</Callout>
+
+## AbortSignal vs. Run Cancellation
+
+| | AbortSignal | Run Cancellation |
+|---|---|---|
+| **Scope** | Individual operations within a step | Entire workflow run |
+| **Triggered by** | Your code (`controller.abort()`) | External API (`run.cancel()`) |
+| **Cooperative** | Yes — steps must check the signal | No — workflow stops at the next suspension point |
+| **Granularity** | Can target specific steps or operations | All-or-nothing |
+| **In-flight steps** | Aborted immediately if using the signal | Run to completion |
+
+Use `AbortSignal` when you need fine-grained, in-flight cancellation of specific operations. Use run cancellation when you want to stop the entire workflow.
+
+## Best Practices
+
+**Use `throwIfAborted()` before expensive work.** This throws the signal's abort reason if the signal is already aborted, preventing wasted compute:
+
+```typescript lineNumbers
+async function expensiveStep(signal: AbortSignal) {
+  "use step";
+  signal.throwIfAborted(); // [!code highlight]
+  // ... expensive work ...
+}
+```
+
+**Handle abort errors in the workflow.** Abort errors arrive as `FatalError` (no retries) and can be caught with a standard try/catch:
+
+```typescript lineNumbers
+declare function cancellableStep(signal: AbortSignal): Promise<void>; // @setup
+import { FatalError } from "workflow";
+
+export async function workflow() {
+  "use workflow";
+  const controller = new AbortController();
+
+  try {
+    await cancellableStep(controller.signal);
+  } catch (err) {
+    if (FatalError.is(err)) { // [!code highlight]
+      return { status: "cancelled" };
+    }
+    throw err;
+  }
+}
+```
+
+**Use `AbortSignal.any()` to combine signals:**
+
+```typescript lineNumbers
+async function stepWithMultipleSignals(
+  userSignal: AbortSignal,
+  timeoutSignal: AbortSignal
+) {
+  "use step";
+
+  const combined = AbortSignal.any([userSignal, timeoutSignal]); // [!code highlight]
+  const response = await fetch("https://api.example.com/data", {
+    signal: combined,
+  });
+  return response.json();
+}
+```
+
+**Abort after a race:**
+
+```typescript lineNumbers
+declare function stepA(signal: AbortSignal): Promise<string>; // @setup
+declare function stepB(signal: AbortSignal): Promise<string>; // @setup
+
+export async function workflow() {
+  "use workflow";
+  const controller = new AbortController();
+
+  const winner = await Promise.race([
+    stepA(controller.signal),
+    stepB(controller.signal),
+  ]);
+
+  controller.abort(); // Clean up whichever step is still running // [!code highlight]
+  return winner;
+}
+```
+
+This is safe even if both steps have already completed — aborting a finished operation is a no-op.
+
+## Related Documentation
+
+- [How Cancellation Works](/docs/how-it-works/cancellation) — Hook and stream backing, serialization internals
+- [Serialization](/docs/foundations/serialization) — Understanding serializable types
+- [Common Patterns](/docs/foundations/common-patterns) — Timeout and race patterns
+- [Hooks](/docs/foundations/hooks) — Pausing workflows for external events
+- [Errors and Retries](/docs/foundations/errors-and-retries) — Handling step failures

package/docs/foundations/errors-and-retries.mdx

@@ -141,7 +141,7 @@ callApi.maxRetries = 5; // Retry up to 5 times on failure (6 total attempts)
 
 ## Error Codes
 
-When a workflow run fails, the error may include a `code` that classifies the failure. You can access it programmatically via the `Run` class:
+When a workflow run fails, the error includes an `errorCode` that classifies the failure, alongside the original thrown value (preserved as `cause`):
 
 ```typescript lineNumbers
 import { WorkflowRunFailedError } from "@workflow/errors";
@@ -153,8 +153,12 @@ try {
   const result = await run.returnValue;
 } catch (err) {
   if (WorkflowRunFailedError.is(err)) {
-    console.log(err.cause.code); // "USER_ERROR", "RUNTIME_ERROR", or undefined
-    console.log(err.cause.message); // The error message
+    console.log(err.errorCode); // "USER_ERROR", "RUNTIME_ERROR", or undefined
+    // `cause` is the original thrown value, hydrated through the workflow
+    // serialization pipeline. It can be any thrown value, so check shape.
+    if (err.cause instanceof Error) {
+      console.log(err.cause.message); // The error message
+    }
   }
 }
 ```

package/docs/foundations/index.mdx

@@ -17,9 +17,6 @@ Workflow programming can be a slight shift from how you traditionally write real
     <Card href="/docs/foundations/starting-workflows" title="Starting Workflows">
         Trigger workflows and track their execution using the `start()` function.
     </Card>
-    <Card href="/docs/foundations/common-patterns" title="Common Patterns">
-        Common patterns useful in workflows.
-    </Card>
     <Card href="/docs/foundations/errors-and-retries" title="Errors & Retrying">
         Types of errors and how retrying work in workflows.
     </Card>
@@ -35,4 +32,7 @@ Workflow programming can be a slight shift from how you traditionally write real
     <Card href="/docs/foundations/idempotency" title="Idempotency">
         Prevent duplicate side effects when retrying operations.
     </Card>
+    <Card href="/docs/foundations/versioning" title="Versioning">
+        Understand how runs stay pinned to deployments and when to opt in to newer code.
+    </Card>
 </Cards>