@workflow/core 5.0.0-beta.5 → 5.0.0-beta.50

package/docs/foundations/versioning.mdx

@@ -0,0 +1,263 @@
+---
+title: Versioning
+description: Understand how workflow runs are pinned to deployments, how to recover runs after a fix, and how to opt in to newer code explicitly.
+type: guide
+summary: Keep in-flight runs stable by default, then choose explicit upgrade boundaries when you need them.
+prerequisites:
+  - /docs/foundations/starting-workflows
+related:
+  - /docs/api-reference/workflow-api/start
+  - /docs/foundations/cancellation
+  - /cookbook/common-patterns/workflow-composition
+---
+
+Workflow runs are pinned to the deployment that starts them. When a run begins, Workflow SDK records the deployment for that run and continues executing the run on that same copy of your code.
+
+That default is intentional. Durable workflows can pause for minutes, days, or months. If the code underneath a paused run changed every time you deployed, an in-flight run could resume into a different function body, different step names, or different input types than the ones it started with. That can make type safety fragile and can break long-running work in hard-to-debug ways.
+
+With Workflow SDK, you can keep shipping. New runs use new deployments, while existing runs keep the version they already understand.
+
+## Default behavior
+
+Start a workflow normally:
+
+```typescript title="app/api/orders/route.ts" lineNumbers
+import { start } from "workflow/api";
+import { fulfillOrder } from "@/workflows/fulfill-order";
+
+export async function POST(request: Request) {
+  const { orderId } = await request.json();
+
+  const run = await start(fulfillOrder, [orderId]); // [!code highlight]
+
+  return Response.json({ runId: run.runId });
+}
+```
+
+The run is tied to the deployment that handled this request. If you deploy a new version while the workflow is [sleeping](/docs/api-reference/workflow/sleep), [waiting on a hook](/docs/foundations/hooks), [retrying a step](/docs/foundations/errors-and-retries), or processing later queue messages, that existing run still resumes on the original deployment.
+
+```typescript title="workflows/fulfill-order.ts" lineNumbers
+import { sleep } from "workflow";
+
+export async function fulfillOrder(orderId: string) {
+  "use workflow";
+
+  await reserveInventory(orderId);
+  await sleep("2d");
+  await chargeCustomer(orderId);
+  await shipOrder(orderId);
+}
+
+async function reserveInventory(orderId: string) {
+  "use step";
+  // ...
+}
+
+async function chargeCustomer(orderId: string) {
+  "use step";
+  // ...
+}
+
+async function shipOrder(orderId: string) {
+  "use step";
+  // ...
+}
+```
+
+If you deploy a change to `chargeCustomer()` while a run is in the two-day sleep, the existing run does not suddenly resume into the new implementation. It continues on the deployment it started on. The next order starts on the latest deployment and uses the new code from the beginning.
+
+## Fixing in-flight runs
+
+Sometimes you deploy because the old code had a bug. The safest fix is usually explicit:
+
+1. Deploy the fixed code.
+2. Find the affected runs in [observability](/docs/observability) or with the CLI.
+3. Cancel the old runs if they are still running.
+4. Rerun them on the latest deployment with the same inputs.
+
+This keeps the version boundary visible. The old run ends as canceled or failed, and the replacement run starts fresh on the fixed deployment. This is a good fit for one-off, ad-hoc upgrades where you explicitly opt in to moving affected runs onto a new version.
+
+```bash
+# Inspect affected runs and copy the exact workflowName value.
+npx workflow inspect runs \
+  --backend vercel \
+  --status running
+
+# Cancel one run.
+npx workflow cancel <run-id> \
+  --backend vercel
+
+# Or bulk-cancel matching running runs.
+npx workflow cancel \
+  --status running \
+  --workflowName "workflow//./workflows/fulfill-order//fulfillOrder" \
+  --backend vercel
+```
+
+The `--workflowName` filter expects the generated workflow ID, not only the exported function's short name. Use the `workflowName` value from `workflow inspect runs`, and use [`parseWorkflowName()`](/docs/api-reference/workflow-observability/parse-workflow-name) when you need display-friendly names.
+
+In the [observability UI](/docs/observability), use **Rerun on latest** to enqueue the workflow again with the same inputs against the latest deployment.
+
+If you are writing your own recovery route, call `start()` with the same arguments and `deploymentId: "latest"`:
+
+```typescript title="app/api/orders/rerun/route.ts" lineNumbers
+import { start } from "workflow/api";
+import { fulfillOrder } from "@/workflows/fulfill-order";
+
+export async function POST(request: Request) {
+  const { orderId } = await request.json();
+
+  const run = await start(fulfillOrder, [orderId], {
+    deploymentId: "latest", // [!code highlight]
+  });
+
+  return Response.json({ runId: run.runId });
+}
+```
+
+<Callout type="warn">
+`deploymentId: "latest"` is currently a Vercel-specific feature. Other Worlds may implement this option differently to match their own deployment runtimes, and the World spec may rename it from `deploymentId` to `version` in a future SDK version. On Vercel, `"latest"` resolves to the most recent deployment matching your current environment. Because the caller and target deployment can be different, keep the [workflow function name and file path](/docs/errors/workflow-not-registered), arguments, and return value backward-compatible across the deployments you plan to bridge.
+</Callout>
+
+## Self upgrading workflows
+
+Some workflows are expected to run for long periods. Scheduled loops, recurring jobs, agents, and chat sessions often should not stay on one deployment forever.
+
+Model those as a sequence of runs. Each run does a bounded piece of work, then starts the next run on the latest deployment and exits. This is similar to `continueAsNew` in other durable execution systems, but Workflow SDK uses [explicit recursion through `start()`](/cookbook/common-patterns/workflow-composition).
+
+```typescript title="workflows/daily-digest.ts" lineNumbers
+import { sleep } from "workflow";
+import { start } from "workflow/api";
+
+type DigestState = {
+  userId: string;
+  lastSentAt?: string;
+};
+
+export async function dailyDigest(state: DigestState) {
+  "use workflow";
+
+  const sentAt = await sendDigest(state.userId);
+  await sleep("1d");
+
+  const run = await start(
+    dailyDigest,
+    [{ ...state, lastSentAt: sentAt }],
+    {
+      deploymentId: "latest", // [!code highlight]
+    }
+  );
+
+  return { continuedAs: run.runId };
+}
+
+async function sendDigest(userId: string) {
+  "use step";
+  // ...
+  return new Date().toISOString();
+}
+```
+
+This pattern gives every run a clear lifecycle:
+
+- The current run stays on its original deployment.
+- The next run starts on the latest deployment.
+- The [serialized `state`](/docs/foundations/serialization) is the migration boundary between versions.
+- Observability can link parent and child runs when a workflow starts another run.
+
+## Carrying context forward
+
+Anything that is [serializable by Workflow SDK](/docs/foundations/serialization) can be passed from one run to the next as an argument. That includes plain state objects, `ReadableStream`, `WritableStream`, `AbortSignal`, and other supported serialized values.
+
+For example, a long export can register its [output stream](/docs/foundations/streaming) once, write progress from each run, and pass the same stream plus updated state into the next run:
+
+```typescript title="workflows/export-report.ts" lineNumbers
+import { getWritable } from "workflow";
+import { start } from "workflow/api";
+
+type ExportState = {
+  exportId: string;
+  page: number;
+};
+
+export async function exportReport(
+  state: ExportState,
+  progress?: WritableStream<string>
+) {
+  "use workflow";
+
+  // Register the stream once. Continuation runs receive this same stream
+  // as an argument and keep writing to it.
+  const stream =
+    progress !== undefined ? progress : getWritable<string>();
+
+  const hasMore = await exportPage(state, stream);
+
+  if (!hasMore) {
+    await writeProgress(stream, { type: "done", totalPages: state.page });
+    return { totalPages: state.page };
+  }
+
+  const run = await start(exportReport, [
+    { ...state, page: state.page + 1 },
+    stream,
+  ], {
+    deploymentId: "latest", // [!code highlight]
+  });
+
+  return { continuedAs: run.runId };
+}
+
+async function exportPage(
+  state: ExportState,
+  stream: WritableStream<string>
+) {
+  "use step";
+
+  // Do work for this version boundary.
+  const hasMore = state.page < 10;
+  const writer = stream.getWriter();
+
+  try {
+    await writer.write(
+      JSON.stringify({ type: "page", page: state.page }) + "\n"
+    );
+    return hasMore;
+  } finally {
+    writer.releaseLock();
+  }
+}
+
+async function writeProgress(
+  stream: WritableStream<string>,
+  event: { type: "done"; totalPages: number }
+) {
+  "use step";
+
+  const writer = stream.getWriter();
+  try {
+    await writer.write(JSON.stringify(event) + "\n");
+  } finally {
+    writer.releaseLock();
+  }
+}
+```
+
+```typescript title="app/api/export/route.ts" lineNumbers
+import { start } from "workflow/api";
+import { exportReport } from "@/workflows/export-report";
+
+export async function POST(request: Request) {
+  const { exportId } = await request.json();
+
+  const run = await start(exportReport, [{ exportId, page: 1 }]);
+
+  // Linked continuation runs keep writing to the stream registered by
+  // the parent run, because that stream is passed forward as an argument.
+  return new Response(run.readable, {
+    headers: { "Content-Type": "application/jsonl" },
+  });
+}
+```
+
+Each run still has one clear version boundary: the current run stays on its original deployment, the next run starts on the latest deployment, and only the explicit state and stream handle are carried forward.

package/docs/foundations/workflows-and-steps.mdx

@@ -14,18 +14,18 @@ import { File, Folder, Files } from "fumadocs-ui/components/files";
 
 Workflows (a.k.a. *durable functions*) are a programming model for building long-running, stateful application logic that can maintain its execution state across restarts, failures, or user events. Unlike traditional serverless functions that lose all state when they terminate, workflows persist their progress and can resume exactly where they left off.
 
-Moreover, workflows let you easily model complex multi-step processes in simple, elegant code. To do this, we introduce two fundamental entities:
+Workflows let you model complex multi-step processes in code. To do this, we introduce two fundamental entities:
 
 1. **Workflow Functions**: Functions that orchestrate/organize steps
 2. **Step Functions**: Functions that carry out the actual work
 
-## Workflow Functions
+## Workflow functions
 
 *Directive: `"use workflow"`*
 
 Workflow functions define the entrypoint of a workflow and organize how step functions are called. This type of function does not have access to the Node.js runtime, and usable `npm` packages are limited.
 
-Although this may seem limiting initially, this feature is important in order to suspend and accurately resume execution of workflows.
+Although this may seem limiting initially, this feature is required to suspend and accurately resume workflow execution.
 
 It helps to think of the workflow function less like a full JavaScript runtime and more like "stitching together" various steps using conditionals, loops, try/catch handlers, `Promise.all`, and other language primitives.
 
@@ -51,7 +51,7 @@ Determinism in the workflow is required to resume the workflow from a suspension
 
 The sandboxed environment that workflows run in already ensures determinism. For instance, `Math.random` and `Date` constructors are fixed in workflow runs, so you are safe to use them, and the framework ensures that the values don't change across replays.
 
-## Step Functions
+## Step functions
 
 *Directive: `"use step"`*
 
@@ -115,10 +115,10 @@ export async function POST() {
 ```
 
 <Callout type="info">
-Keep in mind that calling a step function outside of a workflow function will not have retry semantics, nor will it be observable. Additionally, certain workflow-specific functions like [`getStepMetadata()`](/docs/api-reference/workflow/get-step-metadata) will throw an error when used inside a step that's called outside a workflow.
+Calling a step function outside a workflow function provides neither retry semantics nor observability. Additionally, certain workflow-specific functions like [`getStepMetadata()`](/docs/api-reference/workflow/get-step-metadata) will throw an error when used inside a step that's called outside a workflow.
 </Callout>
 
-### Suspension and Resumption
+### Suspension and resumption
 
 Workflow functions have the ability to automatically suspend while they wait on asynchronous work. While suspended, the workflow's state is stored via the [event log](/docs/how-it-works/event-sourcing) and no compute resources are used until the workflow resumes execution.
 
@@ -126,7 +126,7 @@ Workflow functions have the ability to automatically suspend while they wait on
 
 There are multiple ways a workflow can suspend:
 
-- Waiting on a step function: the workflow yields while the step runs in the step runtime.
+- Waiting on a step function: the workflow yields while the step body runs. The step usually executes inline in the same invocation; when the invocation's inline budget is exhausted or its timeout approaches, the step is handed to the queue and the workflow resumes in a later invocation.
 - Using `sleep()` to pause for some fixed duration.
 - Awaiting on a promise returned by [`createWebhook()`](/docs/api-reference/workflow/create-webhook), which resumes the workflow when an external system passes data into the workflow.
 
@@ -150,9 +150,9 @@ export async function documentReviewProcess(userId: string) {
 }
 ```
 
-## Writing Workflows
+## Writing workflows
 
-### Basic Structure
+### Basic structure
 
 The simplest workflow consists of a workflow function and one or more step functions.
 

package/docs/how-it-works/cancellation.mdx

@@ -18,30 +18,30 @@ This guide explains how cancellation works internally. Understanding these detai
 
 When you write `new AbortController()` in a workflow function, Workflow DevKit creates a durable controller backed by two existing primitives: a [hook](/docs/foundations/hooks) and a [stream](/docs/foundations/streaming). This page explains why both are needed and how they work together.
 
-## The Problem
+## The problem
 
-`AbortController` and `AbortSignal` are inherently stateful — an abort happens once and is permanent. In a durable workflow, this state must:
+`AbortController` and `AbortSignal` are inherently stateful: an abort happens once and is permanent. In a durable workflow, this state must:
 
-1. **Survive replay** — If `abort()` was called, `signal.aborted` must return `true` on every subsequent replay of the workflow.
-2. **Propagate in real-time** — A running step on a different compute instance must receive the abort immediately, not on the next replay.
+1. **Survive replay**: If `abort()` was called, `signal.aborted` must return `true` on every subsequent replay of the workflow.
+2. **Propagate in real-time**: A running step on a different compute instance must receive the abort immediately, not on the next replay.
 
 No single primitive solves both. Hooks provide durable event log state but can't reach into a running step. Streams provide real-time cross-process communication but aren't part of the event log. The solution is to use both.
 
-## Dual Backing: Hook + Stream
+## Dual backing: hook + stream
 
 Every `AbortController` in the workflow context is backed by:
 
-### Hook (Durable State)
+### Hook (durable state)
 
-When `new AbortController()` is called in a workflow, an internal hook is created — similar to calling `createHook()`. This hook is registered in the workflow's invocations queue and produces events in the [event log](/docs/how-it-works/event-sourcing):
+When `new AbortController()` is called in a workflow, an internal hook is created, similar to calling `createHook()`. This hook is registered in the workflow's invocations queue and produces events in the [event log](/docs/how-it-works/event-sourcing):
 
 - **On creation**: A `hook_created` event records that the controller exists
 - **On abort**: The hook is resumed (producing a `hook_received` event), recording the abort permanently
 - **On replay**: The event consumer processes the `hook_received` event and updates `signal.aborted` to `true` at the same point in the replay as the original abort
 
-This gives the workflow deterministic access to the abort state — `controller.signal.aborted` always returns the correct value, even after cold starts.
+This gives the workflow deterministic access to the abort state: `controller.signal.aborted` always returns the correct value, even after cold starts.
 
-### Stream (Real-Time Propagation)
+### Stream (real-time propagation)
 
 When `controller.signal` is serialized as a step argument, a stream name is included in the serialized form. Inside the step, the deserialized `AbortSignal` listens on this stream:
 
@@ -50,7 +50,7 @@ When `controller.signal` is serialized as a step argument, a stream name is incl
 
 This gives steps real-time cancellation without waiting for the workflow to replay.
 
-### Why Both?
+### Why both?
 
 | Mechanism | Solves | Doesn't Solve |
 |---|---|---|
@@ -60,18 +60,18 @@ This gives steps real-time cancellation without waiting for the workflow to repl
 
 ## Lifecycle
 
-### 1. Controller Created in Workflow
+### 1. Controller created in workflow
 
-```
+```text
 new AbortController()
         │
         ├─→ Internal hook created (registered in invocations queue)
         └─→ Stream name generated (deterministic ULID)
 ```
 
-### 2. Signal Passed to Step
+### 2. Signal passed to step
 
-```
+```text
 stepFunction(controller.signal)
         │
         ├─→ Signal serialized as { streamName, hookToken, aborted }
@@ -80,9 +80,9 @@ stepFunction(controller.signal)
                 └─→ Background reader listens on stream for abort packet
 ```
 
-### 3. abort() Called in Workflow
+### 3. abort() called in workflow
 
-```
+```text
 controller.abort()
         │
         ├─→ signal.aborted set to true (synchronous, local state)
@@ -92,13 +92,13 @@ controller.abort()
                 ├─→ Suspension handler creates hook_received event
                 ├─→ Suspension handler writes cancellation packet to stream
                 │       │
-                │       └─→ Step receives packet → local signal fires → fetch cancelled
+                │       └─→ Step receives packet → local signal fires → fetch canceled
                 └─→ Workflow re-enqueued for replay
 ```
 
-### 4. Workflow Replays After Abort
+### 4. Workflow replays after abort
 
-```
+```text
 Replay starts → events loaded
         │
         ├─→ new AbortController() → hook created → event consumer subscribes
@@ -107,34 +107,34 @@ Replay starts → events loaded
         └─→ Workflow code sees signal.aborted === true at the correct point in replay
 ```
 
-On replay, the events consumer re-applies the abort by calling `_setAborted` when it encounters the `hook_received` event in the log — at the same point in execution where the original `abort()` happened. This is what makes the abort deterministic across replays.
+On replay, the events consumer re-applies the abort by calling `_setAborted` when it encounters the `hook_received` event in the log, at the same point in execution where the original `abort()` happened. This is what makes the abort deterministic across replays.
 
-## Where the Hook Is Created
+## Where the hook is created
 
 The backing hook is set up whenever an `AbortController` or `AbortSignal` enters the workflow context:
 
-**`new AbortController()` in a workflow function** — The workflow VM provides a durable `AbortController` implementation (similar to how it provides deterministic `Date` and serializable `Request`/`Response`). The hook is created in the constructor using the orchestrator context injected via VM globals.
+**`new AbortController()` in a workflow function**: The workflow VM provides a durable `AbortController` implementation (similar to how it provides deterministic `Date` and serializable `Request`/`Response`). The hook is created in the constructor using the orchestrator context injected via VM globals.
 
-**Returned from a step** — A step can create a plain `new AbortController()` and return it. The step-side serializer generates a stream name and hook token (using a random ULID) and includes them in the serialized payload. When the return value is deserialized into the workflow via `hydrateStepReturnValue`, the workflow reviver reads the token from the payload and sets up the hook with that token. Since the serialized payload is stored in the event log (as part of the `step_completed` event), the same token is used on every replay — no deterministic generation needed in the workflow.
+**Returned from a step**: A step can create a plain `new AbortController()` and return it. The step-side serializer generates a stream name and hook token (using a random ULID) and includes them in the serialized payload. When the return value is deserialized into the workflow via `hydrateStepReturnValue`, the workflow reviver reads the token from the payload and sets up the hook with that token. Since the serialized payload is stored in the event log (as part of the `step_completed` event), the same token is used on every replay, so no deterministic generation is needed in the workflow.
 
-**Passed as workflow input** — Conceptually the same as "returned from a step". The **external reducer** handles it at serialization time:
+**Passed as workflow input**: Conceptually the same as "returned from a step". The **external reducer** handles it at serialization time:
 
 1. Generates a stream name and hook token (random ULID)
 2. Attaches an `abort` event listener on the source signal: when the external code calls `controller.abort()`, the listener writes the cancellation packet to the stream
 3. Pushes the listener's async work into `ops` (awaited via `waitUntil`)
 4. Serializes the reference as `{ streamName, hookToken, aborted }`
 
-The serialized payload (including the generated token) is stored in the event log as part of the workflow's input. When the workflow deserializes the input, the reviver reads the token from the payload and creates the hook — identical to the "returned from a step" case. On replay, the same token is read from the event log, so the hook matches the same events.
+The serialized payload (including the generated token) is stored in the event log as part of the workflow's input. When the workflow deserializes the input, the reviver reads the token from the payload and creates the hook, identical to the "returned from a step" case. On replay, the same token is read from the event log, so the hook matches the same events.
 
 If the external code calls `abort()` while the process is still alive (within the `waitUntil` window), the stream packet arrives in the workflow, and the workflow can resume the hook to record it in the event log.
 
 <Callout type="info">
-Since the external `AbortController` is a plain JavaScript object (not the workflow VM's durable version), the stream write depends on the originating process still being alive. This is the same constraint that applies to passing a `ReadableStream` as a workflow argument — the stream pipe runs via `waitUntil` and requires the process to remain active until the data is written.
+Since the external `AbortController` is a plain JavaScript object (not the workflow VM's durable version), the stream write depends on the originating process still being alive. This is the same constraint that applies to passing a `ReadableStream` as a workflow argument: the stream pipe runs via `waitUntil` and requires the process to remain active until the data is written.
 </Callout>
 
-## Serialization & Deserialization
+## Serialization & deserialization
 
-### Serialized Form
+### Serialized form
 
 An `AbortController` or `AbortSignal` is serialized as:
 
@@ -148,23 +148,23 @@ An `AbortController` or `AbortSignal` is serialized as:
 }
 ```
 
-The `streamName` and `hookToken` are generated once at serialization time (in the step or external context) and stored in the event log as part of the serialized payload. On replay, the workflow reviver reads them from the payload — it never generates them itself. This is the same pattern used by `ReadableStream` and `WritableStream` serialization.
+The `streamName` and `hookToken` are generated once at serialization time (in the step or external context) and stored in the event log as part of the serialized payload. On replay, the workflow reviver reads them from the payload; it never generates them itself. This is the same pattern used by `ReadableStream` and `WritableStream` serialization.
 
-### Reducers (Serialization)
+### Reducers (serialization)
 
 **In step context** (`getStepReducers`): When a step returns an `AbortController`, the reducer captures the stream name. If `abort()` was called in the step, `aborted: true` is recorded.
 
-**In workflow context** (`getWorkflowReducers`): The reducer captures the stream name and hook token. These are handles — no I/O happens during serialization in the workflow.
+**In workflow context** (`getWorkflowReducers`): The reducer captures the stream name and hook token. These are handles; no I/O happens during serialization in the workflow.
 
 **In external context** (`getExternalReducers`): When an `AbortController` is passed as a workflow argument from outside, the reducer creates the backing stream and serializes the reference.
 
-### Revivers (Deserialization)
+### Revivers (deserialization)
 
 **Into step context** (`getStepRevivers`): Creates a real `AbortController`. If `aborted: true`, calls `abort()` immediately. Otherwise, pushes a stream reader into the step's `ops` array that listens for the cancellation packet and calls `abort()` when received.
 
 **Into workflow context** (`getWorkflowRevivers`): Creates the durable AbortController with hook backing. Subscribes to the events consumer for the hook's correlation ID. If the event log contains a `hook_received` event, `signal.aborted` is `true`.
 
-### abort() in a Step
+### abort() in a step
 
 When `abort()` is called on a deserialized `AbortController` inside a step:
 
@@ -172,18 +172,18 @@ When `abort()` is called on a deserialized `AbortController` inside a step:
 2. The stream write (cancellation packet) is pushed into `ctx.ops`
 3. The hook resume (`resumeHook`) is pushed into `ctx.ops`
 
-The step's `ops` array is awaited via `waitUntil(Promise.all(ops))` after the step function returns — the same mechanism used by [`getWritable()`](/docs/api-reference/workflow/get-writable). This keeps `abort()` synchronous from the caller's perspective while ensuring the async work completes.
+The step's `ops` array is awaited via `waitUntil(Promise.all(ops))` after the step function returns, the same mechanism used by [`getWritable()`](/docs/api-reference/workflow/get-writable). This keeps `abort()` synchronous from the caller's perspective while ensuring the async work completes.
 
-### Abort Errors Are Wrapped in FatalError
+### Abort errors are wrapped in FatalError
 
-When a step throws due to an abort — whether from `fetch` throwing `AbortError`, `signal.throwIfAborted()`, or any other abort-induced error — the step handler wraps the error in `FatalError` before recording it in the event log. This ensures:
+When a step throws due to an abort (whether from `fetch` throwing `AbortError`, `signal.throwIfAborted()`, or any other abort-induced error), the step executor wraps the error in `FatalError` before recording it in the event log. This ensures:
 
-- **No retries**: An abort is intentional cancellation, not a transient failure. Retrying would just abort again.
+- **No retries**: An abort is intentional cancellation, not a transient failure. Retrying would abort again.
 - **Immediate propagation**: The error bubbles up to the workflow as a `FatalError`, which the workflow can catch with `FatalError.is(err)`.
 
-The wrapping happens at the step handler level (`runtime/step-handler.ts`), during error hydration. When the step's thrown error is an `AbortError` (checked via `err.name === 'AbortError'`), it is treated as fatal regardless of the step's `maxRetries` configuration.
+The wrapping happens in `runtime/step-executor.ts` during error hydration. When the step's thrown error is an `AbortError` (checked via `err.name === 'AbortError'`), it is treated as fatal regardless of the step's `maxRetries` configuration.
 
-### abort() in the Workflow
+### abort() in the workflow
 
 When `abort()` is called in the workflow context:
 
@@ -194,7 +194,7 @@ When `abort()` is called in the workflow context:
    - Creates a `hook_received` event in the event log
    - Writes the cancellation packet to the stream (for real-time step propagation)
    - Re-enqueues the workflow for replay
-4. On replay, the event consumer processes the `hook_received` event, updating `signal.aborted` to `true` at the deterministically correct point
+5. On replay, the event consumer processes the `hook_received` event, updating `signal.aborted` to `true` at the deterministically correct point
 
 `signal.aborted` is updated synchronously so that the workflow can immediately check the state and serialization captures `aborted: true` when passing the signal to steps. On replay, the event consumer also processes the `hook_received` event, ensuring the state is consistent.
 
@@ -203,55 +203,55 @@ For abort specifically, this ensures that:
 - The abort's `hook_received` event is created in the event log
 - The cancellation stream packet is written to propagate to running steps
 
-## Race Conditions
+## Race conditions
 
-### Abort Before Hook Exists
+### Abort before hook exists
 
 When an `AbortSignal` is passed as a workflow argument via `start()`, the external reducer attaches a listener at serialization time. If the external code calls `abort()` before the workflow has started and created the internal hook, the stream packet is written but the hook doesn't exist yet.
 
 This is resolved through eventual consistency:
 
-1. The stream packet is durable — it persists in storage
+1. The stream packet is durable; it persists in storage
 2. When the workflow runs and passes the signal to a step, the step's reviver reads from the stream starting at index 0
 3. The step sees the existing packet, aborts locally, and resumes the hook (via `ops`)
 4. On the next workflow replay, the hook event is in the log and `signal.aborted` is `true`
 
-**Important:** There is a window where the workflow's `signal.aborted` returns `false` even though the external code has already called `abort()`. This lasts until a step processes the stream packet and resumes the hook. This is analogous to hooks — `resumeHook()` doesn't take effect until the workflow replays.
+**Important:** There is a window where the workflow's `signal.aborted` returns `false` even though the external code has already called `abort()`. This lasts until a step processes the stream packet and resumes the hook. This is analogous to hooks: `resumeHook()` doesn't take effect until the workflow replays.
 
-### Abort at Serialization Time
+### Abort at serialization time
 
 To prevent a micro-window where `abort()` is called between checking `signal.aborted` and attaching the listener, the external reducer uses this order:
 
 1. Attach the `abort` event listener first
-2. Then check `signal.aborted` — if already `true`, the listener won't fire, so handle immediately
+2. Then check `signal.aborted`; if already `true`, the listener won't fire, so handle immediately
 
 This ensures no abort events are missed regardless of timing.
 
-## Stream/Hook Consistency
+## Stream/hook consistency
 
 Since abort involves two operations (stream write + hook resume), partial failure is possible:
 
-### Stream Succeeds, Hook Fails
+### Stream succeeds, hook fails
 
 - Steps see the abort and throw `AbortError` (stream worked)
 - Workflow doesn't see `signal.aborted === true` on the next replay (hook not resumed)
 - The workflow sees the step failure as an error, which it can handle with try/catch
-- **Recovery:** The step-side `resumeHook` call is best-effort — if it throws, the failure is swallowed. Convergence comes from the next replay: when the step's reviver re-reads the stream, it sees the abort packet and calls `resumeHook` again. There's no in-process retry loop; the dual-mechanism design relies on either the stream or the hook eventually landing.
+- **Recovery:** The step-side `resumeHook` call is best-effort: if it throws, the failure is swallowed. Convergence comes from the next replay: when the step's reviver re-reads the stream, it sees the abort packet and calls `resumeHook` again. There's no in-process retry loop; the dual-mechanism design relies on either the stream or the hook eventually landing.
 
-### Hook Succeeds, Stream Fails
+### Hook succeeds, stream fails
 
 - Workflow sees `signal.aborted === true` on replay (hook worked)
-- Steps don't receive real-time cancellation (stream failed) — they run to completion
+- Steps don't receive real-time cancellation (stream failed), so they run to completion
 - On the next suspension, the workflow knows the abort happened and can stop calling more steps
-- **Recovery:** Natural convergence — no active harm, just missed real-time cancellation for in-flight steps.
+- **Recovery:** Natural convergence. No active harm, only missed real-time cancellation for in-flight steps.
 
-### Both Fail
+### Both fail
 
-- Abort is lost — no propagation
-- No crash or corruption — the system continues as if abort was never called
+- Abort is lost; no propagation
+- No crash or corruption; the system continues as if abort was never called
 - **Recovery:** The caller can retry the abort. If using a hook for external cancellation, the hook's retry semantics apply.
 
-The dual mechanism provides natural resilience — if either one succeeds, the system converges on the correct state.
+The dual mechanism provides natural resilience: if either one succeeds, the system converges on the correct state.
 
 ## `AbortSignal.timeout()` in Workflow VM
 
@@ -264,7 +264,7 @@ The dual mechanism provides natural resilience — if either one succeeds, the s
 A `Request`'s `.signal` is forwarded by the `Request` reducer in two cases:
 
 1. **The signal is already aborted.** The serialized payload preserves `aborted: true` and the abort `reason`, so the deserialized step sees the cancellation that happened before the boundary.
-2. **The signal is workflow-managed** (i.e., it has the `ABORT_STREAM_NAME` symbol — produced by a workflow-context `AbortController`). Its hook + stream backing carries through, and the deserialized step listens on the stream as usual.
+2. **The signal is workflow-managed** (i.e., it has the `ABORT_STREAM_NAME` symbol, produced by a workflow-context `AbortController`). Its hook + stream backing carries through, and the deserialized step listens on the stream as usual.
 
 Plain non-aborted native signals are intentionally dropped, including the auto-generated signal that `new Request(url)` synthesizes when no `signal` is passed. Forwarding every Request signal would mint stream infrastructure for the throwaway auto-signals on every Request, even ones the caller never intended to use for cancellation.
 
@@ -278,10 +278,10 @@ await fetchStep(req); // signal carries through
 controller.abort();   // step-side fetch sees the abort
 ```
 
-## Related Documentation
+## Related documentation
 
-- [Cancellation](/docs/foundations/cancellation) — Usage patterns and API
-- [Event Sourcing](/docs/how-it-works/event-sourcing) — How the event log works
-- [Hooks](/docs/foundations/hooks) — The hook primitive
-- [Streaming](/docs/foundations/streaming) — The stream primitive
-- [Serialization](/docs/foundations/serialization) — Serializable types
+- [Cancellation](/docs/foundations/cancellation): Usage patterns and API
+- [Event Sourcing](/docs/how-it-works/event-sourcing): How the event log works
+- [Hooks](/docs/foundations/hooks): The hook primitive
+- [Streaming](/docs/foundations/streaming): The stream primitive
+- [Serialization](/docs/foundations/serialization): Serializable types