workflow 5.0.0-beta.9 → 5.0.0

package/docs/observability/lifecycle-hooks.mdx

@@ -0,0 +1,95 @@
+---
+title: Lifecycle Hooks
+description: Register global handlers that observe workflow runs completing or failing, for centralized reporting to services like Sentry.
+type: guide
+summary: Observe run completions and failures from a single place with registerLifecycleHooks.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability
+  - /docs/observability/tracing
+  - /docs/errors
+---
+
+Lifecycle hooks let you register global handlers that observe workflow runs completing or failing on your app's compute. They can observe even the failures that never reach a `try/catch` in workflow code, such as a replay timing out or a run exhausting its queue deliveries. Use them for best-effort centralized error reporting, such as forwarding failed runs to Sentry without wrapping each workflow body.
+
+## Registering hooks
+
+Call `registerLifecycleHooks` from `workflow/api` early in your application's lifecycle, so the handlers exist before the first run finishes. In Next.js, [`instrumentation.ts`](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation) is the natural place; in any other app, any module that loads at startup works.
+
+```typescript title="instrumentation.ts" lineNumbers
+export async function register() {
+  if (process.env.NEXT_RUNTIME === "nodejs") {
+    const { registerLifecycleHooks } = await import("workflow/api")
+
+    registerLifecycleHooks({
+      async onRunCompleted({ run, workflowName }) {
+        console.log(`Run ${run.runId} (${workflowName}) completed`)
+      },
+      async onRunFailed({ run, workflowName, error }) {
+        console.error(
+          `Run ${run.runId} (${workflowName}) failed with ${error.errorCode}:`,
+          error.cause
+        )
+      },
+    })
+  }
+}
+```
+
+Keep the dynamic `workflow/api` import inside the `NEXT_RUNTIME === "nodejs"` guard. Next.js also compiles `instrumentation.ts` for the Edge runtime. A top-level static import pulls Node.js-only dependencies into that compilation and breaks webpack Edge builds, even if the registration call is guarded.
+
+`registerLifecycleHooks` returns an unregister function. You can register multiple hook sets, and handlers run in registration order. Registrations are not deduplicated: register each hook set once per process, and call its unregister function before registering it again during hot reload or module re-evaluation. Otherwise, repeated registrations invoke the same handler multiple times for each transition.
+
+## Handler parameters
+
+Both handlers receive a `workflowName` string and the [`Run`](/docs/api-reference/workflow-api/get-run) instance for the transitioned run. `workflowName` is the machine-readable workflow identifier, such as `workflow//./src/workflows/order//processOrder`. Use this parameter to filter runs without a backend read. `run.runId` is also available without a read.
+
+The `Run` instance hydrates lazily. Accessors such as `run.workflowName`, `run.status`, and `run.returnValue` still fetch from the backend when used. In particular, `workflowName` is a string, while `run.workflowName` is a `Promise<string>`. Lazy access defers those reads; it does not make them free.
+
+`onRunFailed` additionally receives a `WorkflowRunFailedError` hydrated for reporting. Unlike `run.returnValue`, it defers readable stream I/O and uses persisted abort snapshots:
+
+- `error.errorCode`: the failure classification (`USER_ERROR`, `RUNTIME_ERROR`, `MAX_DELIVERIES_EXCEEDED`, and more). See [error codes](/docs/errors) for the full list.
+- `error.cause`: the thrown value hydrated from the persisted error data, with registered Error subclass identity, message, stack, and cause chain preserved. Readable streams load lazily when consumed, and abort signals reflect their persisted state without live subscriptions. Writable streams retain their normal forwarding pipe and lock-polling setup during hydration. If hydration fails, the cause is a generic `Error`, matching `run.returnValue`'s fallback. Any JavaScript value can be thrown, so this is typed `unknown`.
+
+In `onRunFailed`, `run.returnValue` rejects because the run failed. Use `error.cause` to inspect or report the thrown value instead of awaiting `run.returnValue`.
+
+The invocation's `waitUntil` scope includes background stream operations from the hydrated cause, even after a handler returns or throws. Close or release stream reader and writer locks when finished so that work can settle. Await other asynchronous reporting work in your handler, such as `Sentry.flush()` below, to keep it in the same lifetime scope.
+
+## Reporting failed runs to Sentry
+
+This example reports failures for workflows named `processOrder`. Remove the filter to report failures from all workflows.
+
+```typescript title="instrumentation.ts" lineNumbers
+export async function register() {
+  if (process.env.NEXT_RUNTIME === "nodejs") {
+    const { registerLifecycleHooks } = await import("workflow/api")
+    const Sentry = await import("@sentry/nextjs")
+
+    Sentry.init({ dsn: process.env.SENTRY_DSN })
+
+    registerLifecycleHooks({
+      async onRunFailed({ run, workflowName, error }) {
+        if (!workflowName.endsWith("//processOrder")) return
+
+        Sentry.captureException(error.cause ?? error, {
+          tags: {
+            workflowRunId: run.runId,
+            workflowName,
+            errorCode: error.errorCode,
+          },
+        })
+        await Sentry.flush(2000)
+      },
+    })
+  }
+}
+```
+
+## How handlers behave
+
+- **Host-only.** Handlers run with full Node.js access, never inside the workflow's sandboxed VM. Calling `registerLifecycleHooks` from workflow code throws.
+- **Fire-and-forget.** Handlers cannot delay or change the run's outcome. The runtime logs and swallows a throwing handler, and the remaining handlers still run. On Vercel, `waitUntil` keeps the invocation alive while handlers finish, subject to the invocation's duration limit. On other hosts, handlers run as detached work. If the host freezes or terminates the process after the response, handlers may not complete.
+- **Best-effort delivery.** Each registered handler is invoked at most once by the invocation that writes the terminal event. For a failure, this happens after any workflow or step retries are exhausted. Callbacks are not retried if they throw or the process dies, so a callback may never run or may stop before completing. The [event log](/docs/how-it-works/event-sourcing) is the system of record, not lifecycle callbacks.
+- **Fires where the transition is recorded.** Terminal transitions recorded outside your app's compute do **not** fire handlers. For example, when you cancel a run from the CLI or the Vercel dashboard, the backend writes that transition, so no handler runs.
+- **Register everywhere your workflows run.** The terminal write can happen in any function invocation that processes the run's queue messages, so registration must run at startup in every instance of the app (which `instrumentation.ts` guarantees).

package/docs/observability/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "Observability",
-  "pages": ["attributes"]
+  "pages": ["tracing", "attributes", "retention", "lifecycle-hooks"]
 }

package/docs/observability/retention.mdx

@@ -0,0 +1,95 @@
+---
+title: Data retention
+description: Control how long a run's data is kept after it finishes.
+type: reference
+summary: Control how long a run's data is kept after the run ends.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability
+  - /docs/api-reference/workflow-api/start
+---
+
+A finished run leaves data behind: the inputs and outputs of the workflow and
+each of its steps, the payloads on its event log, and anything written to its
+streams. How long that data is kept is decided by the World you are running
+on, not by the SDK.
+
+`experimental_retention` on [`start()`](/docs/api-reference/workflow-api/start)
+lets a run ask for a specific retention period, rather than the World's default.
+
+## Deleting a run's data as soon as it ends
+
+{/* @skip-typecheck: abbreviated usage; processDocumentWorkflow is the reader's own workflow */}
+```typescript lineNumbers
+const run = await start(processDocumentWorkflow, [documentId], {
+  experimental_retention: 0, // [!code highlight]
+})
+```
+
+`0` asks the World to delete the run's **user data** the moment the run
+completes or fails, rather than keeping it for the World's default window.
+
+Two values are accepted today:
+
+| Value | Meaning |
+| --- | --- |
+| `0` | Delete user data as soon as the run reaches a terminal state. |
+| `'default'` | Use the World's default. Identical to omitting the option. |
+
+<Callout type="warn">
+  The option is prefixed `experimental_` because both its name and the set of
+  values it accepts are expected to change.
+</Callout>
+
+## What is deleted, and what is not
+
+**Deleted:** the run's input, output and error; every step's input, output and
+error; the payloads on the event log; and stream contents.
+
+**Kept:** the run, step and event records themselves — their ids, timestamps,
+status, step names, and any [attributes](/docs/observability/attributes) you
+set. They are kept for the World's default period so the run stays visible in
+the CLI and web UI. A purged run is still listed and still traceable; its
+payloads simply read back as expired.
+
+Inspecting a purged run shows it as expired rather than failing. The Workflow
+CLI renders the run's own input, output and error as `<data expired>`:
+
+```bash
+workflow inspect runs wrun_...
+```
+
+Step, hook and event payloads read back empty. On the Vercel World they also
+render as `<data expired>`; on Worlds that clear the stored value outright
+they simply show as empty. Either way the data is gone — the difference is
+only in how the absence is labelled.
+
+<Callout type="warn">
+  **You cannot read the return value of a run started with
+  `experimental_retention: 0`.** The deletion races your own read of the
+  result and generally wins, so `await run.returnValue` throws
+  [`RunExpiredError`](/docs/errors/run-expired) instead of resolving.
+
+  This is a known limitation. If you need the result, send it somewhere you
+  control, e.g. a step that writes it to your own store, rather than reading
+  it back off the run.
+</Callout>
+
+`RunExpiredError` is not specific to `experimental_retention: 0`. Any run read
+after its retention window has passed throws it, and the error carries
+`runId`, `runStatus` and `expiredAt` when the World still has them — so a
+caller can tell a successful run whose result is gone from a failed one whose
+error is gone. If the run's metadata is gone too, the World reports the run as
+missing and you get `WorkflowRunNotFoundError` instead.
+
+## Retention is implemented by the World
+
+The SDK records your preference; it does not enforce it. `start()` writes the
+value onto the run as the reserved `$retention` attribute, and the World
+decides what to do when the run ends. Attributes are a spec version 4 feature,
+so `experimental_retention: 0` throws against an older World rather than being
+recorded and ignored. A World that does implement spec version 4 but not
+retention **keeps the data**. If you need certainty that a specific World
+deletes your data, confirm it against that World's own documentation rather
+than the presence of this option.

package/docs/observability/tracing.mdx

@@ -0,0 +1,124 @@
+---
+title: Tracing
+description: Distributed tracing with OpenTelemetry for workflow runs, steps, and queue deliveries.
+type: guide
+summary: Trace workflow execution end to end with OpenTelemetry.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability
+  - /docs/observability/attributes
+  - /docs/how-it-works/event-sourcing
+---
+
+The Workflow SDK includes [OpenTelemetry](https://opentelemetry.io) instrumentation. It emits spans for workflow starts, every workflow and step invocation, and the HTTP calls it makes to the workflow backend, and it propagates trace context across queue deliveries so a run remains traceable end to end.
+
+The SDK only depends on the OpenTelemetry **API**, never on an SDK or exporter. If your application does not register an OpenTelemetry SDK, all tracing code is a silent no-op with no overhead and no behavior change.
+
+## Enabling tracing
+
+Register any OpenTelemetry Node SDK in your application. On Vercel with Next.js, the simplest setup is [`@vercel/otel`](https://vercel.com/docs/tracing/instrumentation) in `instrumentation.ts`:
+
+```typescript title="instrumentation.ts" lineNumbers
+import { registerOTel } from "@vercel/otel"
+
+export function register() {
+  registerOTel({ serviceName: "my-app" })
+}
+```
+
+No workflow-specific configuration is required. As soon as a tracer provider and propagator are registered, the SDK's spans, context propagation, and span links activate automatically.
+
+<Callout>
+`@opentelemetry/api` is an **optional peer dependency**. An OpenTelemetry SDK such as `@vercel/otel` normally pulls it in transitively, but installing it directly (`npm i @opentelemetry/api`) guarantees it is present in your build, particularly for bundled or serverless targets where the SDK's tracing is inlined at build time. If it can't be resolved, tracing is a silent no-op.
+</Callout>
+
+## Spans
+
+| Span name | Kind | Emitted when |
+| --- | --- | --- |
+| `workflow.start <name>` | internal | `start()` is called in your application code |
+| `workflow.execute <name>` | consumer (root) | a queue delivery invokes the workflow; replay, orchestration, and inline steps run under it |
+| `step.execute <name>` | internal (inline) / consumer + root (queue-delivered) | a step function executes |
+| `http <method>` | client | the SDK calls the workflow backend (event reads/writes) |
+| `workflow.stream.write` | client | a stream chunk (or the stream close) is flushed to the backend |
+| `workflow.stream.flush` | client | a buffered batch of stream writes settles; back-dated to the batch's first `write()`, so its duration is the app-perceived batch latency (buffer dwell + RPC) |
+| `workflow.stream.close` | client | the stream-close RPC; its duration is the close round trip |
+| `workflow.stream.read.complete` | client | a stream read drains; back-dated to the read dispatch, so its duration is the total read (`workflow.stream.read.chunks` / `.bytes` carry throughput counts) |
+| `workflow.stream.read.connect` | client | a live stream read opens; the span covers dispatch → response headers (network connect) |
+| `workflow.stream.read` | client | a live stream read receives its first chunk; the span's duration is the end-to-end time-to-first-chunk (see `workflow.stream.read.ttfc_ms`) |
+
+`<name>` is the short function name (for example `processOrder`); the full machine name, including the source module, is available in the `workflow.name` / `step.name` attributes.
+
+Stream spans are emitted by the SDK's world backend on the client that writes or reads the stream, and (like all SDK spans) are no-ops when no OpenTelemetry SDK is registered. The `workflow.stream.read` span only appears once the first non-empty chunk arrives.
+
+## Key attributes
+
+| Attribute | Description |
+| --- | --- |
+| `workflow.run.id` | The run ID (`wrun_...`). Present on every workflow and step span; the primary key for finding all spans of a run. |
+| `workflow.name` | The workflow function name. |
+| `workflow.trace.mode` | The active trace mode (`linked` or `continuous`). |
+| `workflow.trace.propagated` | Whether the invocation received trace context from the queue message. |
+| `workflow.queue.overhead_ms` | Time between the message being enqueued and the handler starting: queue dwell plus any cold start. |
+| `workflow.stream.name` | The stream name, on stream write/read spans. |
+| `workflow.stream.operation` | The stream operation: `write`, `write_multi`, `close`, `read`, or `flush`. |
+| `workflow.stream.write.chunk_rtt` | Time between emission of a chunk to the wire, and receiving the `ack` message for that chunk. Also stamped on `workflow.stream.flush` (the batch's write RPC duration, network included). |
+| `workflow.stream.flush.buffer_dwell_ms` | On `workflow.stream.flush`: time the batch's first chunk waited in the client-side write buffer (flush timer, run-ready barrier) before the request was dispatched. `workflow.stream.flush.chunks` / `.bytes` carry the batch shape. |
+| `workflow.stream.read.ttfc_ms` | Time between opening a read connection and observing and receiving the first chunk back. |
+| `workflow.stream.read.connect_ms` | On `workflow.stream.read`: the connect portion (read dispatch → stream handle/response headers), network included. |
+
+## Trace shape: one trace per invocation
+
+A single workflow run can span hours or days across many separate function invocations: every `sleep()` wake-up, hook resume, retry, and queued step continuation is a new queue delivery. Stitching all of that into one trace produces giant, slow-loading traces that most tracing backends truncate.
+
+Instead, the SDK creates **one bounded trace per invocation**. Each `workflow.execute` (or background `step.execute`) span starts a new trace root and attaches two **span links**:
+
+- a link to the **enqueue site**, the span that queued the message which triggered this invocation, and
+- a link to the **run origin**, the trace in which `start()` was originally called.
+
+A span link is OpenTelemetry's relationship for "causally related, but in a different trace." It is the standard pattern for asynchronous messaging, where producing and consuming a message can be separated by arbitrary time.
+
+```mermaid
+flowchart LR
+    O["start() request trace"]
+    A["invocation 1"]
+    B["invocation 2"]
+    C["invocation 3 ..."]
+    A -. "link" .-> O
+    B -. "link" .-> O
+    C -. "link" .-> O
+    B -. "link" .-> A
+    C -. "link" .-> B
+
+    style O fill:#a78bfa,stroke:#8b5cf6,color:#000
+```
+
+Each invocation links back to the trace that enqueued it and to the run origin.
+
+To see a whole run, query by attribute rather than by trace ID (for example `workflow.run.id = wrun_...` in your tracing backend), or follow the span links between invocation traces.
+
+## Trace modes
+
+The `WORKFLOW_TRACE_MODE` environment variable controls the shape:
+
+| Mode | Behavior |
+| --- | --- |
+| `linked` (default) | Each invocation is its own trace root with span links to the enqueue site and the run origin. Traces stay small; sampling is decided per invocation. |
+| `continuous` | The run-origin context becomes the **parent** of every invocation, so the entire run shares one trace ID. |
+
+<Callout type="warn">
+This is a behavior change from v4, which always used `continuous`-style tracing. If you have dashboards or queries that assume one trace ID per run, either update them to use `workflow.run.id` and span links, or set `WORKFLOW_TRACE_MODE=continuous` to restore the previous shape. In `linked` mode, each invocation root makes its own sampling decision, and the number of root spans increases to one per invocation.
+</Callout>
+
+## Context propagation
+
+When tracing is enabled, the SDK propagates [W3C Trace Context](https://www.w3.org/TR/trace-context/) on its outbound calls:
+
+- **Backend requests** carry `traceparent`, `tracestate`, and `baggage` headers, so backend spans can join your trace.
+- **Queue messages** carry the run-origin trace context in the message payload, and the queue re-delivers the producer's context to the workflow handler, where it becomes the enqueue-site span link.
+- **Baggage** carries `workflow.run_id` and `workflow.name` entries during workflow execution, allowing downstream services you call from steps to tag their own telemetry with the run ID.
+
+<Callout>
+Baggage entries set by your application are propagated as a `baggage` HTTP header on the SDK's backend requests, like any other OpenTelemetry-instrumented HTTP call. Avoid placing sensitive values in baggage.
+</Callout>

package/docs/testing/index.mdx

@@ -3,18 +3,18 @@ title: Testing
 description: Unit test individual steps and integration test entire workflows using Vitest.
 ---
 
-Testing is a critical part of building reliable workflows. Because steps are just functions annotated with directives, they can be unit tested like any other JavaScript function. Workflow SDK also provides a Vitest plugin that runs full workflows in-process — no running server required.
+Test steps like any other JavaScript function, or use the Workflow SDK Vitest plugin to run complete workflows in-process without a server.
 
 This guide covers two approaches:
 
-1. **Unit testing** - Test individual steps as plain functions, without the workflow runtime.
-2. **Integration testing** - Test entire workflows in-process using the `workflow()` Vitest plugin. Required when you want to test workflow specific code paths, like those using [hooks](/docs/foundations/hooks), webhooks, [`sleep()`](/docs/api-reference/workflow/sleep), retries, etc.
+1. **Unit testing**: Test individual steps as plain functions without the workflow runtime.
+2. **Integration testing**: Test entire workflows in-process using the `workflow()` Vitest plugin. Use integration tests for workflow-specific code paths that use [hooks](/docs/foundations/hooks), webhooks, [`sleep()`](/docs/api-reference/workflow/sleep), or retries.
 
-## Unit Testing Steps
+## Unit testing steps
 
-Without the workflow compiler, the `"use step"` directive is a no-op. Your step functions run as regular JavaScript functions, making them straightforward to unit test with no special configuration.
+Without the workflow compiler, the `"use step"` directive is a no-op. Your step functions run as regular JavaScript functions, so you can unit test them without special configuration.
 
-### Example Steps
+### Example steps
 
 Given a workflow file with step functions like this:
 
@@ -49,7 +49,7 @@ export async function sendOnboardingEmail(user: { id: string; email: string }) {
 }
 ```
 
-### Writing Unit Tests for Steps
+### Writing unit tests for steps
 
 You can import and test step functions directly with Vitest. No special configuration or workflow plugin is needed:
 
@@ -77,18 +77,30 @@ describe("sendWelcomeEmail step", () => {
 This approach is ideal for verifying the business logic inside individual steps in isolation.
 
 <Callout type="info">
-Unit testing works well for individual steps. A simple workflow that only calls steps can also be unit tested this way, since `"use workflow"` is similarly a no-op without the compiler. However, any workflow that uses runtime features like [`sleep()`](/docs/api-reference/workflow/sleep), [hooks](/docs/foundations/hooks), or [webhooks](/docs/foundations/hooks#understanding-webhooks) cannot be unit tested directly because those APIs require the workflow runtime. Use [integration testing](#integration-testing-with-the-vitest-plugin) for testing entire workflows, especially those that depend on workflow-only features.
+Unit testing works well for individual steps. A workflow that only calls steps can also be unit tested this way, since `"use workflow"` is similarly a no-op without the compiler. However, any workflow that uses runtime features like [`sleep()`](/docs/api-reference/workflow/sleep), [hooks](/docs/foundations/hooks), or [webhooks](/docs/foundations/hooks#understanding-webhooks) cannot be unit tested directly because those APIs require the workflow runtime. Use [integration testing](#integration-testing-with-the-vitest-plugin) for testing entire workflows, especially those that depend on workflow-only features.
 </Callout>
 
-## Integration Testing with the Vitest Plugin
+## Integration testing with the Vitest plugin
 
-For workflows that rely on runtime features like [hooks](/docs/foundations/hooks), [webhooks](/docs/foundations/hooks#understanding-webhooks), [`sleep()`](/docs/api-reference/workflow/sleep), or error retries, you need to test against a real workflow setup. The `@workflow/vitest` plugin handles everything automatically — it compiles your workflow directives, builds the runtime bundles, and executes workflows entirely in-process. No server required.
+For workflows that rely on runtime features like [hooks](/docs/foundations/hooks), [webhooks](/docs/foundations/hooks#understanding-webhooks), [`sleep()`](/docs/api-reference/workflow/sleep), or error retries, you need to test against a real workflow setup. The `@workflow/vitest` plugin handles everything automatically: it compiles your workflow directives, builds the runtime bundles, and executes workflows entirely in-process. No server required.
 
 <Callout type="warn">
-`vi.mock()` and related calls do _not_ work inside workflow functions, only step functions. Your workflow functions cannot import third party code that needs to be mocked. Mocking works for npm packages imported in step functions. If something needs to be mocked, it likely belongs inside a step function either way.
+`vi.mock()` cannot reach code inside workflow functions at all, and reaches step code only under specific conditions. Read [Mocking](#mocking) before reaching for it.
 </Callout>
 
-### Vitest Configuration
+### Installation
+
+```package-install
+npm i -D @workflow/vitest@beta
+```
+
+<Callout type="warn">
+**Workflow 5 needs the `beta` tag.** `@workflow/vitest@latest` is still the 4.x line, so a plain `npm i -D @workflow/vitest` installs a v4 plugin next to a v5 app. Install `@workflow/vitest@beta`, or pin the beta your app is on (for example `@workflow/vitest@5.0.0-beta.53`), and upgrade it together with `workflow`.
+
+The plugin builds and runs your workflows against the copy of `@workflow/core` it was installed with, so it checks this for you. At the start of each run it compares that copy with the one your app resolves: a different major fails the run with the install command that fixes it, and any other difference logs a warning. Set [`WORKFLOW_VITEST_VERSION_CHECK=off`](/docs/configuration/build-and-diagnostics#workflow_vitest_version_check) to skip the check.
+</Callout>
+
+### Vitest configuration
 
 Create a separate Vitest config for integration tests that includes the `workflow()` plugin:
 
@@ -109,15 +121,15 @@ That's it. The plugin automatically:
 
 1. Transforms `"use workflow"` and `"use step"` directives via SWC
 2. Builds workflow and step bundles before tests run
-3. Sets up an in-process workflow runtime using a fresh [Local World](/docs/worlds/local) instance in each test worker — all workflow data is cleared automatically between test files for full isolation
+3. Sets up an in-process workflow runtime using a fresh [Local World](/worlds/local) instance in each test worker; all workflow data is cleared automatically between test files for full isolation
 
 <Callout type="info">
 Use a separate Vitest configuration and a distinct file naming convention (e.g. `*.integration.test.ts`) to keep unit tests and integration tests separate. Unit tests run with a standard Vitest config without the workflow plugin, while integration tests use the config above.
 </Callout>
 
-### Writing Integration Tests
+### Writing integration tests
 
-Use [`start()`](/docs/api-reference/workflow-api/start) to trigger a workflow and [`run.returnValue`](/docs/api-reference/workflow-api/start#returnvalue) to get the result. `returnValue` is a promise that blocks until the workflow completes (or throws if it fails):
+Use [`start()`](/docs/api-reference/workflow-api/start) to trigger a workflow and [`run.returnValue`](/docs/api-reference/workflow-api/start#returns) to get the result. `returnValue` is a promise that blocks until the workflow completes (or throws if it fails):
 
 ```typescript title="workflows/calculate.integration.test.ts" lineNumbers
 import { describe, it, expect } from "vitest";
@@ -144,9 +156,9 @@ describe("calculateWorkflow", () => {
 });
 ```
 
-### Testing Hooks and Waits
+### Testing hooks and waits
 
-The real power of integration testing comes when testing workflow-only features. Hooks and waits can be resumed programmatically using the [`workflow/api`](/docs/api-reference/workflow-api) functions, making it straightforward to simulate external events in your tests.
+Integration testing is most useful for workflow-only features. You can resume hooks and waits programmatically using the [`workflow/api`](/docs/api-reference/workflow-api) functions to simulate external events in your tests.
 
 Given a workflow that waits for approval via a hook, then sleeps before publishing:
 
@@ -228,7 +240,7 @@ describe("approvalWorkflow", () => {
       reviewer: "bob",
     });
 
-    // No wakeUp() needed here — the rejected path has no sleep
+    // No wakeUp() needed here; the rejected path has no sleep
     const result = await run.returnValue;
     expect(result).toEqual({
       status: "rejected",
@@ -243,12 +255,12 @@ describe("approvalWorkflow", () => {
 </Callout>
 
 <Callout type="info">
-`waitForSleep()` returns the first **pending** sleep — one that has a `wait_created` event but no corresponding `wait_completed` event. If your workflow has multiple parallel sleeps, `waitForSleep()` returns whichever is found first. After waking one, call `waitForSleep()` again to get the next pending one. For sequential sleeps, `waitForSleep()` naturally returns each one as the workflow reaches it.
+`waitForSleep()` returns the first **pending** sleep, one that has a `wait_created` event but no corresponding `wait_completed` event. If your workflow has multiple parallel sleeps, `waitForSleep()` returns whichever is found first. After waking one, call `waitForSleep()` again to get the next pending one. For sequential sleeps, `waitForSleep()` naturally returns each one as the workflow reaches it.
 </Callout>
 
-### Testing Webhooks
+### Testing webhooks
 
-Webhooks are hooks that receive HTTP `Request` objects. In tests, resume them using [`resumeWebhook()`](/docs/api-reference/workflow-api/resume-webhook) with a `Request` payload — no HTTP server needed:
+Webhooks are hooks that receive HTTP `Request` objects. In tests, resume them using [`resumeWebhook()`](/docs/api-reference/workflow-api/resume-webhook) with a `Request` payload, with no HTTP server needed:
 
 ```typescript title="workflows/ingest.ts" lineNumbers
 import { createWebhook } from "workflow";
@@ -256,7 +268,7 @@ import { createWebhook } from "workflow";
 export async function ingestWorkflow(endpointId: string) {
   "use workflow";
 
-  // Webhook tokens are always randomly generated
+  // Webhook tokens are always generated for you
   using webhook = createWebhook(); // [!code highlight]
 
   const request = await webhook; // [!code highlight]
@@ -282,7 +294,7 @@ describe("ingestWorkflow", () => {
   it("should process webhook data", async () => {
     const run = await start(ingestWorkflow, ["ep-1"]);
 
-    // Discover the randomly generated webhook token
+    // Discover the generated webhook token
     const hook = await waitForHook(run); // [!code highlight]
 
     // Resume the webhook with a Request object
@@ -303,7 +315,73 @@ describe("ingestWorkflow", () => {
 });
 ```
 
-### Manual Setup
+### Referencing workflows by name
+
+Importing the workflow function is the best way to start it: [`start()`](/docs/api-reference/workflow-api/start) keeps its argument and return types. When a test cannot import it, because the workflow lives in a module the test does not pull in or because the test drives runs by name, look it up with [`getWorkflowRef()`](/docs/api-reference/vitest#getworkflowref) instead of hand-writing the generated `workflow//...` id:
+
+```typescript title="workflows/approval.integration.test.ts" lineNumbers
+import { describe, it, expect } from "vitest";
+import { start } from "workflow/api";
+import { getWorkflowRef, listWorkflowRefs } from "@workflow/vitest"; // [!code highlight]
+
+describe("approvalWorkflow", () => {
+  it("is part of the test build", () => {
+    expect(listWorkflowRefs().map((ref) => ref.name)).toContain( // [!code highlight]
+      "approvalWorkflow"
+    );
+  });
+
+  it("can be started by name", async () => {
+    const run = await start(getWorkflowRef("approvalWorkflow"), ["doc-1"]); // [!code highlight]
+    expect(run.runId).toMatch(/^wrun_/);
+  });
+});
+```
+
+The names come from the manifest the test build writes next to its bundles, so they follow your code when files move. When one exported name appears in several files, qualify it with the file, `getWorkflowRef("workflows/approval.ts#approvalWorkflow")`, which also matches by path suffix. An unknown or ambiguous name throws with the workflows the build does contain.
+
+<Callout type="info">
+A reference is matched by name, so the run is typed as `Run<unknown>`. Import the workflow function when you want the argument and return types checked.
+</Callout>
+
+### Mocking
+
+Steps do not run from your test file's module graph. They run from the bundles the plugin builds, and workflow bodies run from a code string inside the sandboxed VM, so `vi.mock()` reaches less here than in an ordinary Vitest test:
+
+| What you mock | Step code sees it | Workflow body sees it |
+| --- | --- | --- |
+| An npm package a step file imports | Only when the generated bundles load through Vitest's module runner (see below) | No |
+| An npm package imported by a local module that a step file imports | Same as above | No |
+| A project-local module a step file imports | No: it is bundled into the step bundle, so there is no module left to replace | No |
+| A step function imported and called directly, with no `workflow()` plugin | Yes, ordinary Vitest rules | n/a |
+
+Workflow bodies execute in a VM that has no module registry, so nothing can intercept their imports. That is the same reason side effects belong in steps: if a dependency needs mocking, it belongs on the step side.
+
+Whether step code sees an npm mock depends on how Vitest loaded the plugin. In a normal install `@workflow/vitest` is external to Vitest, Node loads the generated bundle directly, and steps get the real package. Ask for the other behavior explicitly:
+
+```typescript title="vitest.integration.config.ts" lineNumbers
+import { defineConfig } from "vitest/config";
+import { workflow } from "@workflow/vitest";
+
+export default defineConfig({
+  plugins: [workflow()],
+  test: {
+    // Route the generated bundles through Vitest's module runner, so vi.mock()
+    // applies to the npm packages your steps import.
+    server: { deps: { inline: [/@workflow\/vitest/] } }, // [!code highlight]
+  },
+});
+```
+
+The cost is that the generated bundle goes through Vite's transform pipeline in every test worker.
+
+Three approaches work regardless of how the plugin was loaded:
+
+- **Unit test the step directly.** Without the plugin, `"use step"` is a no-op and the function is an ordinary async function, so `vi.mock()` behaves normally.
+- **Pass the dependency in.** A step that takes its collaborator as an argument is controlled by the caller, with no module interception involved.
+- **Feed values through hooks.** Resume a [hook](/docs/foundations/hooks) with the data you want instead of mocking whatever would have produced it.
+
+### Manual setup
 
 If you need more control over the test lifecycle, the plugin also exports the individual setup functions:
 
@@ -354,11 +432,11 @@ afterAll(async () => {
 For advanced setups that require a running server (e.g. testing against your actual framework's HTTP layer), see [Server-based integration testing](/docs/testing/server-based).
 </Callout>
 
-## Debugging Test Runs
+## Debugging test runs
 
-When integration tests fail, the [Workflow SDK CLI and Web UI](/docs/observability) can help you inspect what happened. Because integration tests persist workflow state locally, you can use the same observability tools you would use in development.
+When integration tests fail, the [Workflow SDK CLI and web UI](/docs/observability) can help you inspect what happened. Because integration tests persist workflow state locally, you can use the same observability tools you use in development.
 
-Launch the Web UI to visually explore your test workflow runs:
+Launch the web UI to explore your test workflow runs:
 
 ```bash
 npx workflow web
@@ -374,7 +452,7 @@ npx workflow inspect runs
 npx workflow inspect run <run-id>
 ```
 
-The Web UI shows each step, its inputs and outputs, retry attempts, hook state, and timing. This is especially useful for diagnosing issues with hooks that were not resumed, steps that failed unexpectedly, or workflows that timed out.
+The web UI shows each step, its inputs and outputs, retry attempts, hook state, and timing. Use it to diagnose hooks that were not resumed, steps that failed unexpectedly, or workflows that timed out.
 
 ![Workflow SDK Web UI](/o11y-ui.png)
 
@@ -382,35 +460,39 @@ The Web UI shows each step, its inputs and outputs, retry attempts, hook state,
 See the [Observability](/docs/observability) docs for the full set of CLI commands and Web UI features.
 </Callout>
 
-## Best Practices
+## Best practices
 
-### Separate Unit and Integration Tests
+### Separate unit and integration tests
 
 Keep two test configurations:
 
-- **Unit tests** - Standard Vitest config, no workflow plugin. Fast, no infrastructure required.
-- **Integration tests** - Vitest config with `workflow()` plugin. Tests the full workflow lifecycle including hooks, sleeps, and retries.
+- **Unit tests**: Standard Vitest config with no workflow plugin. These tests require no infrastructure.
+- **Integration tests**: Vitest config with the `workflow()` plugin. These tests cover the full workflow lifecycle, including hooks, sleeps, and retries.
 
-### Use Custom Hook Tokens for Deterministic Testing
+### Use custom hook tokens for deterministic testing
 
-When testing workflows with hooks, use [custom tokens](/docs/foundations/hooks#custom-tokens-for-deterministic-hooks) based on predictable values (like document IDs or test identifiers). This makes it easy to resume the correct hook in your test code.
+When testing workflows with hooks, use [custom tokens](/docs/foundations/hooks#custom-tokens-for-deterministic-hooks) based on predictable values (like document IDs or test identifiers). This lets you resume the correct hook in your test code.
 
-### Set Appropriate Timeouts
+### Set appropriate timeouts
 
 Workflows may take longer to execute than typical unit tests, especially when they involve multiple steps or retries. Set a generous `testTimeout` in your integration test config.
 
-### Test Error and Retry Scenarios
+### Test error and retry scenarios
 
 Integration tests are the right place to verify that your workflows handle errors correctly, including retryable errors, fatal errors, and timeout scenarios.
 
-## Further Reading
+### Upgrade `@workflow/vitest` with the SDK
+
+`@workflow/vitest` carries its own copy of the Workflow runtime, so treat it as part of the same upgrade as `workflow`. While Workflow 5 is in beta, that means the `beta` tag on both. See [Installation](#installation).
+
+## Further reading
 
 - [Hooks & Webhooks](/docs/foundations/hooks) - Pausing and resuming workflows with external data
 - [`start()` API Reference](/docs/api-reference/workflow-api/start) - Start workflows programmatically
 - [`resumeHook()` API Reference](/docs/api-reference/workflow-api/resume-hook) - Resume hooks with data
 - [`resumeWebhook()` API Reference](/docs/api-reference/workflow-api/resume-webhook) - Resume webhooks with Request objects
 - [`getRun()` API Reference](/docs/api-reference/workflow-api/get-run) - Check workflow run status and wake up sleeping runs
-- [`@workflow/vitest` API Reference](/docs/api-reference/vitest) - Test helpers: `waitForSleep()`, `waitForHook()`, and plugin setup
+- [`@workflow/vitest` API Reference](/docs/api-reference/vitest) - Test helpers: `waitForSleep()`, `waitForHook()`, `getWorkflowRef()`, and plugin setup
 - [Vite Integration](/docs/getting-started/vite) - Set up the Vite plugin
 - [Observability](/docs/observability) - Inspect and debug workflow runs with the CLI and Web UI
 - [Server-based testing](/docs/testing/server-based) - Integration testing with a running server