workflow 5.0.0-beta.5 → 5.0.0-beta.50

package/docs/cookbook/advanced/publishing-libraries.mdx

@@ -2,16 +2,20 @@
 title: Publishing Libraries
 description: Structure and publish npm packages that export workflow functions for consumers to use with Workflow SDK.
 type: guide
-summary: Learn how to build, export, and test npm packages that ship workflow and step functions — including package.json exports, re-exporting for stable workflow IDs, keeping step I/O clean, and integration testing.
+summary: Learn how to build, export, and test npm packages that ship workflow and step functions, including package.json exports, re-exporting so the consumer's compiler discovers your workflows, keeping step I/O clean, and integration testing.
 ---
 
+<CopyPrompt
+  text="Package these workflow functions as a publishable npm library. Give the package a dedicated workflows entry point (for example `exports[&quot;./workflows&quot;]`) that ships the workflow and step source for the consumer's compiler to process. Keep every workflow and step input and output serializable, and read credentials from environment variables inside steps instead of accepting client instances. Document the consumer re-export requirement: consumers create a file in their `workflows/` directory containing `export * from &quot;<pkg>/workflows&quot;` so their build discovers and compiles the library's workflow and step files and replay can resolve them after cold starts. Add an integration test that runs a library workflow end to end from a consumer-style setup. Verify the build, that the library's workflows and steps show up as compiled entries, and replay safety."
+/>
+
 import { File, Folder, Files } from "fumadocs-ui/components/files";
 
 <Callout>
 This is an advanced guide for library authors who want to publish reusable workflow functions as npm packages. It assumes familiarity with `"use workflow"`, `"use step"`, and the workflow execution model.
 </Callout>
 
-## Package Structure
+## Package structure
 
 A workflow library follows a standard TypeScript package layout with a dedicated `workflows/` directory. Each workflow file exports one or more workflow functions that consumers can import and pass to `start()`.
 
@@ -40,14 +44,14 @@ A workflow library follows a standard TypeScript package layout with a dedicated
 
 Key files:
 
-- **`src/index.ts`** — Package entry point. Exports the public API.
-- **`src/types.ts`** — Shared TypeScript types.
-- **`src/workflows/index.ts`** — Re-exports every workflow so consumers can pull them in under one specifier (see [Entry Points and Exports](#entry-points-and-exports)).
-- **`src/workflows/*.ts`** — One file per workflow function (e.g. `transcode.ts`, `generate-thumbnails.ts`).
-- **`src/lib/`** — Internal helpers. Plain async code, *not* marked with `"use workflow"` or `"use step"`.
-- **`test-server/workflows.ts`** — Re-export file used by integration tests (see [Testing Workflow Libraries](#testing-workflow-libraries)).
+- **`src/index.ts`**: Package entry point that exports the public API.
+- **`src/types.ts`**: Shared TypeScript types.
+- **`src/workflows/index.ts`**: Re-exports every workflow so consumers can pull them in under one specifier (see [Entry points and exports](#entry-points-and-exports)).
+- **`src/workflows/*.ts`**: One file per workflow function (for example, `transcode.ts` or `generate-thumbnails.ts`).
+- **`src/lib/`**: Internal helpers with plain async code that is not marked with `"use workflow"` or `"use step"`.
+- **`test-server/workflows.ts`**: Re-export file used by integration tests (see [Test workflow libraries](#test-workflow-libraries)).
 
-### Entry Points and Exports
+### Entry points and exports
 
 Use the `exports` field in `package.json` to expose separate entry points for the main API and the raw workflow functions:
 
@@ -71,7 +75,7 @@ Use the `exports` field in `package.json` to expose separate entry points for th
 
 The main entry point (`@acme/media`) exports types, utilities, and convenience wrappers. The `./workflows` entry point (`@acme/media/workflows`) exports the raw workflow functions that consumers need for the build system.
 
-### Source Files
+### Source files
 
 The package entry re-exports workflows alongside any utilities:
 
@@ -89,7 +93,7 @@ export * from "./transcode";
 export * from "./generate-thumbnails";
 ```
 
-### Build Configuration
+### Build configuration
 
 Use a bundler like `tsup` with separate entry points for each export. Mark `workflow` as external so it's resolved from the consumer's project:
 
@@ -110,39 +114,43 @@ export default defineConfig({
 });
 ```
 
-## Re-Exporting for Workflow ID Stability
+## Re-exporting for compiler discovery
 
-Workflow SDK's compiler assigns each workflow function a stable ID based on its position in the source file that the build system processes. When a consumer imports a pre-built workflow from an npm package, the compiler never sees the original source — it only sees the compiled output. This means workflow IDs won't match between the library's development environment and the consumer's app.
+The workflow compiler only transforms files it discovers, and discovery starts from the consumer's `workflows/` directory and follows imports out from there. A library's workflow functions are not on that graph by default, so nothing compiles them and the runtime has no definition to run.
 
-The fix is a **re-export file**. The consumer creates a file in their `workflows/` directory that re-exports the library's workflows. The build system then processes this file and assigns stable IDs.
+The fix is a **re-export file**. The consumer creates a file in their `workflows/` directory that re-exports the library's workflows, which pulls the library's source onto the discovery graph and gives its entry point an address the runtime can resolve.
 
-### Consumer Setup
+### Consumer setup
 
 ```typescript lineNumbers
 // workflows/media.ts (in the consumer's project)
-// Re-export library workflows so the build system assigns stable IDs
+// Re-export library workflows so the compiler discovers and transforms them
 export * from "@acme/media/workflows"; // [!code highlight]
 ```
 
-This one-line file is all that's needed. The workflow compiler transforms this file, discovers the workflow and step functions from the library, and assigns IDs that are stable across deployments.
+This one-line file is all that's needed. The compiler follows the re-export into the package, transforms the workflow and step functions it finds, and registers them under IDs the runtime can resolve.
+
+### Why this is necessary
+
+Without re-exporting, the workflow runtime cannot match a running workflow to its function definition. When a run is replayed after a cold start, the runtime looks up functions by their compiler-assigned IDs. If those functions were never compiled, the IDs don't exist and replay fails.
 
-### Why This Is Necessary
+Point the re-export at the package's dedicated workflows entry point rather than a deep path into `dist/`. Files reachable through the package's `exports` map get an ID of the form `name/subpath@version`; a deep, non-exported file falls back to a path-based ID instead.
 
-Without re-exporting, the workflow runtime cannot match a running workflow to its function definition. When a workflow run is replayed after a cold start, the runtime looks up functions by their compiler-assigned IDs. If the IDs don't exist (because the compiler never processed the library's source), replay fails.
+<Callout type="info">
+**IDs for code you ship embed your package version.** A step in `@acme/media` version `1.4.0` gets the ID `step//@acme/media/workflows@1.4.0//transcode`, so publishing `1.5.0` renames every workflow and step the package ships.
 
-The re-export pattern ensures:
+That is safe on worlds with deployment pinning, such as Vercel, because runs are pinned to the deployment that started them. A run records its deployment ID and every resume targets that same deployment, so after a consumer upgrades, new runs execute the new version while runs already in flight keep replaying against the old one. Consumers do not need to drain anything before upgrading.
 
-1. **Stable IDs** — the compiler assigns IDs based on the consumer's source tree
-2. **Replay safety** — IDs persist across deployments and cold starts
-3. **Version upgrades** — re-exported IDs remain stable as long as the consumer's file doesn't change
+The re-export file does not change any of this. An ID is derived from where the file lives, not from how it was imported, so a package file keeps its `name@version` ID whether or not a consumer re-exports it.
+</Callout>
 
-## Keeping Step I/O Clean
+## Keeping step I/O clean
 
 When you publish a workflow library, every step function's inputs and outputs are recorded in the event log. This has two implications:
 
-### 1. Everything Must Be Serializable
+### 1. Everything must be serializable
 
-Step inputs and outputs must be serializable. The workflow runtime supports a rich set of types beyond plain JSON — including `Date`, `RegExp`, `Map`, `Set`, `BigInt`, `Uint8Array`, `URL`, `Error`, and class instances that implement [custom class serialization](/docs/foundations/serialization#custom-class-serialization). See the [serialization reference](/docs/foundations/serialization) for the full list of supported types. Do not pass or return:
+Step inputs and outputs must be serializable. The workflow runtime supports a rich set of types beyond plain JSON, including `Date`, `RegExp`, `Map`, `Set`, `BigInt`, `Uint8Array`, `URL`, `Error`, and class instances that implement [custom class serialization](/docs/foundations/serialization#custom-class-serialization). See the [serialization reference](/docs/foundations/serialization) for the full list of supported types. Do not pass or return:
 
 - Functions or closures
 - `WeakRef`, `WeakMap`, or `WeakSet`
@@ -161,7 +169,7 @@ async function callExternalApi(endpoint: string, params: Record<string, string>)
 // Bad: pass a pre-constructed client object
 async function callExternalApi(client: ApiClient, params: Record<string, string>) {
   "use step";
-  // ApiClient is not serializable — this will fail on replay
+  // ApiClient is not serializable, so this will fail on replay
   return await client.request(params);
 }
 ```
@@ -191,13 +199,13 @@ async function fetchData(apiKey: string, query: string) {
 
 The choice is a matter of library API design preference. Resolving from environment variables keeps the step signature simpler, while passing credentials explicitly makes dependencies visible and can be easier to test.
 
-## Testing Workflow Libraries
+## Testing workflow libraries
 
-Library authors need integration tests that exercise workflows through the full Workflow SDK runtime — not just unit tests of individual functions.
+Library authors need integration tests that exercise workflows through the full Workflow SDK runtime, rather than only unit tests of individual functions.
 
-### Test Server Pattern
+### Test server pattern
 
-Create a minimal test server that re-exports your library's workflows, just like a consumer would:
+Create a minimal test server that re-exports your library's workflows, like a consumer would:
 
 ```typescript lineNumbers
 // test-server/workflows.ts
@@ -206,7 +214,7 @@ export * from "@acme/media/workflows"; // [!code highlight]
 
 This test server acts as a stand-in consumer app. Point your test runner at it to exercise the full workflow lifecycle: start, replay, and completion.
 
-### Vitest Configuration
+### Vitest configuration
 
 Use a dedicated Vitest config for integration tests that run against the Workflow SDK runtime:
 
@@ -233,22 +241,22 @@ pnpm vitest run tests/unit
 pnpm vitest run --config vitest.workflowsdk.config.ts
 ```
 
-### What to Test
+### What to test
 
-- **Happy path**: workflow starts, all steps execute, and the final result is correct
-- **Serialization round-trip**: inputs and outputs survive the event log
-- **Replay**: kill and restart a workflow mid-execution to verify deterministic replay
-- **Error handling**: verify that step failures produce the expected errors
+- **Happy path**: The workflow starts, all steps execute, and the final result is correct.
+- **Serialization round-trip**: Inputs and outputs survive the event log.
+- **Replay**: Stop and restart a workflow during execution to verify deterministic replay.
+- **Error handling**: Step failures produce the expected errors.
 
-## Working With and Without Workflow Installed
+## Working with and without Workflow installed
 
-Some libraries want to be useful to consumers who *aren't* using Workflow SDK at all — the library picks up durable behavior when a workflow runtime is present and falls back to plain async execution otherwise.
+Some libraries need to support consumers who *aren't* using Workflow SDK. The library gains durable behavior when a workflow runtime is present and falls back to plain async execution otherwise.
 
 <Callout type="info">
 Two rules for isomorphic packages:
 
-1. **Any runtime reference to the `workflow` package must be loaded via dynamic `import("workflow")` inside a try/catch.** A static top-level import makes the module fail to load for consumers who haven't installed workflow.
-2. **The `"use workflow"` and `"use step"` directives are safe to keep in your library source.** When a consumer compiles your code with the Workflow SDK toolchain (via the [re-export pattern](#re-exporting-for-workflow-id-stability) above), the SWC plugin transforms them into durable-execution glue. When they're not compiled — plain Node, plain tests, a consumer without the runtime — they are just string expression statements and run as no-ops.
+1. **Load any runtime reference to the `workflow` package through dynamic `import("workflow")` inside a try/catch.** A static top-level import makes the module fail to load for consumers who haven't installed Workflow.
+2. **Keep the `"use workflow"` and `"use step"` directives in your library source.** When a consumer compiles your code with the Workflow SDK toolchain (via the [re-export pattern](#re-export-for-compiler-discovery) above), the SWC plugin transforms the directives into durable-execution glue. When the directives aren't compiled (plain Node.js, plain tests, or a consumer without the runtime), they are string expression statements and run as no-ops.
 </Callout>
 
 ### Optional peer dependency
@@ -270,14 +278,14 @@ Declare `workflow` as an **optional** peer so consumers without the runtime aren
 
 ### Runtime detection
 
-Wrap a dynamic `import("workflow")` in try/catch. If either the module isn't installed *or* `getWorkflowMetadata()` throws (call site isn't inside a workflow run), fall through to the standalone path.
+Wrap a dynamic `import("workflow")` in try/catch. If either the module isn't installed *or* `getStepMetadata()` throws (call site isn't inside a workflow step), fall through to the standalone path.
 
 ```typescript lineNumbers
-async function getWorkflowRunId(): Promise<string | null> { // [!code highlight]
+async function getWorkflowStepId(): Promise<string | null> { // [!code highlight]
   try {
     const wf = await import("workflow");
-    const { workflowRunId } = wf.getWorkflowMetadata();
-    return workflowRunId;
+    const { stepId } = wf.getStepMetadata();
+    return stepId;
   } catch {
     return null;
   }
@@ -286,13 +294,14 @@ async function getWorkflowRunId(): Promise<string | null> { // [!code highlight]
 
 ### A concrete use case: replay-safe idempotency keys
 
-A payments utility that uses the workflow run ID as a Stripe idempotency key when available, and a fresh UUID otherwise:
+A payments utility can use the current workflow step ID as a Stripe idempotency key when available and a fresh universally unique identifier (UUID) otherwise:
 
-{/* @skip-typecheck - depends on getWorkflowRunId defined in the previous block */}
 ```typescript lineNumbers
+declare function getWorkflowStepId(): Promise<string | null>; // @setup (defined in the previous block)
+
 export async function processPayment(amount: number, currency: string) {
-  const runId = await getWorkflowRunId();
-  const idempotencyKey = runId ?? crypto.randomUUID(); // [!code highlight]
+  const stepId = await getWorkflowStepId();
+  const idempotencyKey = stepId ? `payment:${stepId}` : crypto.randomUUID(); // [!code highlight]
 
   const res = await fetch("https://api.stripe.com/v1/charges", {
     method: "POST",
@@ -306,14 +315,14 @@ export async function processPayment(amount: number, currency: string) {
 }
 ```
 
-When called from inside a workflow run, the step wrapping this utility gets a stable idempotency key across replays — Stripe dedupes retries for free. When called from a plain Node.js process, it behaves like any other function and a fresh UUID is generated.
+When called from inside a workflow step, the utility gets a stable idempotency key for that step across retries, so Stripe deduplicates retries. When called from a plain Node.js process, it behaves like any other function and generates a fresh UUID. For more patterns, see [Idempotency](/docs/foundations/idempotency).
 
 ### In production
 
 Packages in the wild built on Workflow SDK:
 
-- **[`@mux/ai`](https://github.com/muxinc/ai)** — Reusable video AI workflows (summaries, chapters, content moderation, translation, embeddings) exported with `"use workflow"` / `"use step"` directives. In a standard Node environment the directives are no-ops and the SDK runs as a plain async library; in a Workflow SDK environment the consumer's compiler transforms them into durable, resumable steps with automatic retries and observability. Written up in detail in [*How Mux shipped durable video workflows with their @mux/ai SDK*](https://vercel.com/blog/how-mux-shipped-durable-video-workflows-with-their-mux-ai-sdk) on the Vercel blog.
-- **World ID** — Human-in-the-loop "proof of human" primitive for agent workflows. Developers drop a World ID step into any workflow to require a zero-knowledge cryptographic proof that a real, unique human authorized a specific action (deploy approvals, large payments, sensitive data access, etc.). Because it runs as a workflow step, every verification is durable, replay-safe, and viewable inside the run's execution timeline — giving you a provable audit record of which human approved what. Available on npm and announced in [*World ID for agents: Browserbase, Exa, Okta, and Vercel*](https://world.org/blog/announcements/browserbase-exa-okta-world-id-for-agentic-web) on the World blog.
+- **[`@mux/ai`](https://github.com/muxinc/ai)**: Reusable video AI workflows (summaries, chapters, content moderation, translation, embeddings) exported with `"use workflow"` / `"use step"` directives. In a standard Node environment the directives are no-ops and the SDK runs as a plain async library; in a Workflow SDK environment the consumer's compiler transforms them into durable, resumable steps with automatic retries and observability. Written up in detail in [*How Mux shipped durable video workflows with their @mux/ai SDK*](https://vercel.com/blog/how-mux-shipped-durable-video-workflows-with-their-mux-ai-sdk) on the Vercel blog.
+- **World ID**: Human-in-the-loop "proof of human" primitive for agent workflows. Developers drop a World ID step into any workflow to require a zero-knowledge cryptographic proof that a real, unique human authorized a specific action (deploy approvals, large payments, sensitive data access, etc.). Because it runs as a workflow step, every verification is durable, replay-safe, and viewable inside the run's execution timeline, giving you a provable audit record of which human approved what. Available on npm and announced in [*World ID for agents: Browserbase, Exa, Okta, and Vercel*](https://world.org/blog/announcements/browserbase-exa-okta-world-id-for-agentic-web) on the World blog.
 
 ## Checklist
 
@@ -330,7 +339,7 @@ Before publishing a workflow library:
 
 ## Key APIs
 
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
-- [`"use step"`](/docs/api-reference/workflow/use-step) — marks functions for durable execution
-- [`start`](/docs/api-reference/workflow/start) — starts a workflow run
-- [`getWorkflowMetadata`](/docs/api-reference/workflow/get-workflow-metadata) — runtime detection and run ID access
+- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions): Declares the orchestrator function.
+- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions): Marks functions for durable execution.
+- [`start`](/docs/api-reference/workflow-api/start): Starts a workflow run.
+- [`getWorkflowMetadata`](/docs/api-reference/workflow/get-workflow-metadata): Provides runtime detection and run ID access.

package/docs/cookbook/advanced/serializable-steps.mdx

@@ -6,9 +6,13 @@ summary: Return a callback from a step to defer construction of a non-owned clas
 related:
   - /docs/foundations/serialization
   - /docs/foundations/serialization#custom-class-serialization
-  - /docs/api-reference/workflow/use-step
+  - /docs/foundations/workflows-and-steps#step-functions
 ---
 
+<CopyPrompt
+  text="Make this non-serializable dependency usable inside a durable workflow with the step-as-factory pattern. Instead of passing the object (AI SDK model, cloud SDK client) into the workflow, export a factory that returns an async callback marked with &quot;use step&quot; which constructs and returns the object at execution time, for example `export function openai(...args) { return async () => { &quot;use step&quot;; return openaiProvider(...args); }; }`. Pass the factory across the workflow boundary (the compiler serializes the function reference, not the instance) and invoke it inside steps where full Node.js access is available. Keep the factory's constructor arguments serializable. Verify the workflow builds, replays deterministically, and the dependency is only instantiated during step execution."
+/>
+
 <Callout>
 This is an advanced guide. It dives into workflow internals and is not required reading to use workflow.
 </Callout>
@@ -17,12 +21,12 @@ This is an advanced guide. It dives into workflow internals and is not required
 
 Workflow functions run inside a sandboxed VM where every value that crosses a function boundary must be serializable. There are two ways to get a non-serializable object across that boundary, depending on whether you own the class:
 
-- **You own the class** — implement the [`WORKFLOW_SERIALIZE` / `WORKFLOW_DESERIALIZE` protocol](/docs/foundations/serialization#custom-class-serialization). The instance becomes a first-class serializable value: you can pass it as a workflow input, return it from a step, and call `"use step"` instance methods on it directly. This is the right tool when the class is yours to modify.
-- **You don't own the class** — you can't add methods to `openai("gpt-4o")` from `@ai-sdk/openai` or `new S3Client({...})` from `@aws-sdk/client-s3`. Instead, wrap construction in a `"use step"` factory function and pass the factory across the boundary. That's what this page covers.
+- **You own the class**: implement the [`WORKFLOW_SERIALIZE` / `WORKFLOW_DESERIALIZE` protocol](/docs/foundations/serialization#custom-class-serialization). The instance becomes a first-class serializable value: you can pass it as a workflow input, return it from a step, and call `"use step"` instance methods on it directly. This is the right tool when the class is yours to modify.
+- **You don't own the class**: you can't add methods to `openai("gpt-4o")` from `@ai-sdk/openai` or `new S3Client({...})` from `@aws-sdk/client-s3`. Instead, wrap construction in a `"use step"` factory function and pass the factory across the boundary. That's what this page covers.
 
-## The Problem
+## The problem
 
-AI SDK model providers — `openai("gpt-4o")`, `anthropic("claude-sonnet-4-20250514")`, etc. — return complex objects with methods, closures, and internal state. Passing one directly into a step causes a serialization error, and you can't bolt `WORKFLOW_SERIALIZE` onto a third-party class.
+AI SDK model providers (`openai("gpt-4o")`, `anthropic("claude-sonnet-4-20250514")`, etc.) return complex objects with methods, closures, and internal state. Passing one directly into a step causes a serialization error, and you can't bolt `WORKFLOW_SERIALIZE` onto a third-party class.
 
 ```typescript lineNumbers
 import { openai } from "@ai-sdk/openai";
@@ -35,7 +39,7 @@ export async function brokenAgent(prompt: string) {
 
   const writable = getWritable<UIMessageChunk>();
   const agent = new DurableAgent({
-    // This fails — the model object is not serializable
+    // This fails: the model object is not serializable
     model: openai("gpt-4o"),
   });
 
@@ -43,9 +47,9 @@ export async function brokenAgent(prompt: string) {
 }
 ```
 
-## The Solution: Step-as-Factory
+## The solution: step-as-factory
 
-Instead of passing the model object, pass a **callback function** that returns the model. Marking that callback with `"use step"` tells the compiler to serialize the *function reference* (which is just a string identifier) rather than its return value. The provider is only instantiated at execution time, inside the step's full Node.js runtime.
+Instead of passing the model object, pass a **callback function** that returns the model. Marking that callback with `"use step"` tells the compiler to serialize the *function reference* (which is a string identifier) rather than its return value. The provider is only instantiated at execution time, inside the step's full Node.js runtime.
 
 ```typescript lineNumbers
 import { openai as openaiProvider } from "@ai-sdk/openai";
@@ -59,9 +63,13 @@ export function openai(...args: Parameters<typeof openaiProvider>) {
 }
 ```
 
-The `DurableAgent` receives a function (`() => Promise<LanguageModel>`) instead of a model object. When the agent needs to call the LLM, it invokes the factory inside a step where the real provider can be constructed with full Node.js access.
+The `DurableAgent` receives a function (`() => Promise<LanguageModel>`) instead of a model object. When the agent needs to call the large language model (LLM), it invokes the factory inside a step where the real provider can be constructed with full Node.js access.
+
+## How `@workflow/ai` uses this
 
-## How `@workflow/ai` Uses This
+<Callout type="warn">
+`@workflow/ai`'s pre-wrapped providers and `DurableAgent` are deprecated. AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) resolves models from AI Gateway model strings (for example, `"openai/gpt-4o"`), which usually removes the need for a model factory; see the [migration guide](https://ai-sdk.dev/v7/docs/agents/workflow-agent#migrating-from-durableagent). The serialization pattern on this page still applies to any non-serializable dependency you own (for example, cloud SDK clients).
+</Callout>
 
 The `@workflow/ai` package ships pre-wrapped providers for all major AI SDK backends. Each one follows the same pattern:
 
@@ -97,14 +105,14 @@ export async function chatAgent(prompt: string) {
 }
 ```
 
-## Writing Your Own Serializable Wrapper
+## Writing your own serializable wrapper
 
 Apply the same pattern to any non-serializable dependency. The key rule: **the outer function captures serializable arguments, and the inner `"use step"` function constructs the real object at runtime**.
 
 ```typescript lineNumbers
 import type { S3Client as S3ClientType } from "@aws-sdk/client-s3";
 
-// The arguments (region, bucket) are plain strings — serializable
+// The arguments (region, bucket) are plain strings, which are serializable
 export function createS3Client(region: string) {
   return async (): Promise<S3ClientType> => {
     "use step";
@@ -133,15 +141,15 @@ async function uploadFile(
 }
 ```
 
-## Why This Works
+## Why this works
 
-1. **Compiler transformation**: `"use step"` tells the SWC plugin to extract the function into a separate bundle. The workflow VM only sees a serializable reference (function ID + captured arguments).
-2. **Closure tracking**: The compiler tracks which variables the step function closes over. Only serializable values (strings, numbers, plain objects) can be captured.
-3. **Deferred construction**: The actual provider/client is only constructed when the step executes in the Node.js runtime — never in the sandboxed workflow VM.
+1. **Compiler transformation**: `"use step"` tells the SWC plugin to extract the function into a separate bundle. The workflow VM only sees a serializable reference (function ID and captured arguments).
+2. **Closure tracking**: The compiler tracks which variables the step function closes over. The function can capture only serializable values, such as strings, numbers, and plain objects.
+3. **Deferred construction**: The step constructs the provider or client only when it executes in the Node.js runtime, never in the sandboxed workflow VM.
 
 ## Key APIs
 
-- [`"use step"`](/docs/api-reference/workflow/use-step) — marks a function for extraction and serialization
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
-- [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — accepts a model factory for durable AI agent streaming
-- [Custom class serialization](/docs/foundations/serialization#custom-class-serialization) — the companion pattern for classes you own (`WORKFLOW_SERIALIZE` / `WORKFLOW_DESERIALIZE`)
+- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions): Marks a function for extraction and serialization.
+- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions): Declares the orchestrator function.
+- [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent): Provides AI SDK's durable agent, resolves models through AI Gateway strings, and replaces `DurableAgent`.
+- [Custom class serialization](/docs/foundations/serialization#custom-class-serialization): Provides the companion pattern for classes you own (`WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE`).

package/docs/cookbook/advanced/upgrading-workflows.mdx

@@ -0,0 +1,199 @@
+---
+title: Upgrading Workflows
+description: Identify a clean upgrade point in a long-running workflow and spawn a fresh run on the latest deployment carrying state forward.
+type: guide
+summary: 'Identify a clean upgrade point and hand off to a fresh run via `start(self, [state], { deploymentId: "latest" })`, either automatically on every iteration, or on demand via a dedicated upgrade hook.'
+related:
+  - /docs/foundations/versioning
+  - /cookbook/common-patterns/workflow-composition
+  - /docs/api-reference/workflow-api/start
+  - /docs/foundations/hooks
+---
+
+<CopyPrompt
+  text="Add a safe self-upgrade point to this long-running workflow. Identify the loop boundary where no step is mid-side-effect. Define a serializable state object that contains all progress needed to continue. At the boundary, call `start(self, [state], { deploymentId: &quot;latest&quot; })` or the documented replacement workflow with the carried state, then return from the old run. If upgrades should be manual, add a `defineHook()` upgrade signal and resume it from an API route with `resumeHook()` from `workflow/api`. Make the handoff idempotent so retries do not start duplicate successor runs, and verify old-to-new handoff plus duplicate prevention."
+/>
+
+Workflows that block on external events for days, weeks, or months can outlive many deployments. **The key is to identify a clean upgrade point in the workflow** (a moment where it's safe to checkpoint state and start fresh) and then call [`start()`](/docs/api-reference/workflow-api/start) with `deploymentId: "latest"` to spawn a new run carrying that state forward. The current run ends; the next run begins on whatever deployment is live at that moment, so shipped fixes apply immediately without ever migrating an in-flight run.
+
+<Callout type="info">
+For the underlying model (why runs pin to a deployment by default, how cancel-and-rerun works, and how state crosses the version boundary), see [Versioning](/docs/foundations/versioning). This recipe focuses on event-driven workflows that need to keep advancing across deployments.
+</Callout>
+
+A clean upgrade point is any spot in the workflow where:
+
+- All in-progress side effects have completed or aren't needed by the next iteration.
+- The relevant state can be serialized into the workflow's input arguments.
+- The workflow can create a checkpoint after handling an external event, completing a batch, or finishing a logical phase.
+
+There are two ways to apply this:
+
+1. **Upgrade on every iteration** ([Method 1](#method-1-upgrade-on-every-iteration)): Each run handles a single event and unconditionally hands off to a fresh run on the latest deployment before exiting. This method needs no extra triggers, but every event incurs the respawn cost.
+2. **Upgrade on demand through a dedicated hook** ([Method 2](#method-2-upgrade-on-demand-via-a-dedicated-hook)): A single long-lived run handles many events in a loop and respawns only when an `upgradeHook` fires. A separate endpoint resumes that hook from your control plane, for example, after a deployment. This method provides more control and fewer respawns at the cost of an explicit trigger.
+
+### When to use each
+
+- **Use Method 1** when iterations are short and frequent, the work is inexpensive to checkpoint, and you want shipped fixes to apply on the next event. Long-lived session workflows, such as subscriptions, queues, and finite-state machines (FSMs), that already process events one at a time fit this method.
+- **Use Method 2** when iterations are infrequent or expensive, or when you need to roll out a fix to a fleet of in-flight runs after a deployment by fanning out to a control-plane endpoint. This method also fits when an upgrade should be an explicit operation rather than a side effect of handling each event.
+
+## Method 1: Upgrade on every iteration
+
+Each run inherits state via its argument, blocks on a hook, processes the resume, then unconditionally hands off to its successor by calling `start()` directly from the workflow body with `deploymentId: "latest"`.
+
+```typescript lineNumbers
+import { defineHook, getWorkflowMetadata } from "workflow";
+import { start } from "workflow/api";
+
+declare function processItem(itemId: string): Promise<void>; // @setup
+
+interface QueueState {
+  processed: number;
+  cursor: string | null;
+}
+
+export const nextItemHook = defineHook<{ itemId: string }>();
+
+export async function longRunningQueue(
+  state: QueueState = { processed: 0, cursor: null },
+): Promise<void> {
+  "use workflow";
+
+  const { workflowRunId } = getWorkflowMetadata();
+
+  // Block until something fires the hook. Could be hours, days, or longer.
+  // Per-run hook tokens (workflowRunId) keep concurrent chains isolated.
+  const { itemId } = await nextItemHook.create({ token: workflowRunId }); // [!code highlight]
+
+  await processItem(itemId);
+
+  // Hand off to a fresh run on the latest deployment. THIS run ends here.
+  // `deploymentId: "latest"` resolves to whichever deployment is current
+  // when this spawn lands, NOT the deployment running this code.
+  await start( // [!code highlight]
+    longRunningQueue, // [!code highlight]
+    [{ processed: state.processed + 1, cursor: itemId }], // [!code highlight]
+    { deploymentId: "latest" }, // [!code highlight]
+  );
+}
+```
+
+### Resuming the hook
+
+Any server-side code can resume the currently-active iteration by calling `.resume()` with the run ID:
+
+```typescript
+import { nextItemHook } from "@/workflows/long-running-queue";
+
+export async function POST(req: Request) {
+  const { runId, itemId } = await req.json();
+
+  await nextItemHook.resume(runId, { itemId }); // [!code highlight]
+
+  return Response.json({ success: true });
+}
+```
+
+The caller tracks the active `runId`, such as in a database or returned from the previous iteration, and updates it whenever the chain advances.
+
+## Method 2: Upgrade on demand via a dedicated hook
+
+Use a single long-running workflow that handles events in a loop. Define a second hook, `upgradeHook`, alongside the work hook, and race them. While only the work hook fires, the run keeps handling events on its current deployment. When `upgradeHook` resumes, the workflow captures current state and respawns on the latest deployment, then exits.
+
+```typescript lineNumbers
+import { defineHook, getWorkflowMetadata } from "workflow";
+import { start } from "workflow/api";
+
+declare function processItem(itemId: string): Promise<void>; // @setup
+
+interface QueueState {
+  processed: number;
+  cursor: string | null;
+}
+
+export const nextItemHook = defineHook<{ itemId: string }>();
+export const upgradeHook = defineHook<{ reason?: string }>(); // [!code highlight]
+
+export async function longRunningQueue(
+  state: QueueState = { processed: 0, cursor: null },
+): Promise<void> {
+  "use workflow";
+
+  const { workflowRunId } = getWorkflowMetadata();
+
+  while (true) {
+    // Race a normal work event against the upgrade signal.
+    const event = await Promise.race([ // [!code highlight]
+      nextItemHook
+        .create({ token: workflowRunId })
+        .then((payload) => ({ kind: "work" as const, payload })),
+      upgradeHook // [!code highlight]
+        .create({ token: workflowRunId }) // [!code highlight]
+        .then(() => ({ kind: "upgrade" as const })), // [!code highlight]
+    ]);
+
+    if (event.kind === "upgrade") { // [!code highlight]
+      // Checkpoint current state and hand off to a fresh run
+      // on whatever deployment is live now. THIS run ends here.
+      await start(longRunningQueue, [state], { // [!code highlight]
+        deploymentId: "latest", // [!code highlight]
+      }); // [!code highlight]
+      return; // [!code highlight]
+    }
+
+    await processItem(event.payload.itemId);
+    state = {
+      processed: state.processed + 1,
+      cursor: event.payload.itemId,
+    };
+  }
+}
+```
+
+### Triggering the upgrade
+
+Expose a separate endpoint that resumes `upgradeHook` for a given run. Call it from your deployment pipeline, an admin UI, or a fan-out script that iterates over every active run after shipping a fix.
+
+```typescript
+import { upgradeHook } from "@/workflows/long-running-queue";
+
+export async function POST(req: Request) {
+  const { runId, reason } = await req.json();
+
+  // The workflow exits its loop, captures state, and respawns
+  // on the latest deployment.
+  await upgradeHook.resume(runId, { reason }); // [!code highlight]
+
+  return Response.json({ success: true });
+}
+```
+
+To upgrade a fleet of runs after a deployment, list active runs from a tracking store and call this endpoint for each run.
+
+## How it works
+
+1. **`deploymentId: "latest"` is the upgrade knob.** Without it, the spawn pins to the current deployment. With it, the new run resolves to whatever deployment is current when the runtime picks it up, so any shipped fix applies starting from that respawn. Both methods rely on this.
+2. **`start()` runs directly from the workflow body.** In v5, [`start()`](/docs/api-reference/workflow-api/start) is step-backed, so it can be called from a workflow function and still records a deterministic step boundary in the event log, so no manual `"use step"` wrapper is required.
+3. **State carries through the function argument.** The accumulating context flows from run N to run N+1 as a serialized argument. No external store is required for the state itself.
+4. **Per-run hook tokens.** Using `workflowRunId` as the hook token scopes each iteration's wait to its own run, so multiple chains can run concurrently without interfering.
+5. **Method 1 vs Method 2 is only where the spawn happens.** In Method 1 every run spawns its successor unconditionally before exiting; there is no long-lived process to migrate. In Method 2 the spawn happens only when the upgrade hook fires; otherwise the loop keeps handling events on the same run.
+
+## Adapting to your use case
+
+- **Combine with a sleep**: Race the hook against `sleep()` so iterations also tick on a timer. `Promise.race([hook, sleep("1d")])` lets the workflow advance even if no external event arrives.
+- **Use stateless successors**: If the next iteration doesn't need the previous state, such as for a pure event router, call `start(longRunningQueue, [], { deploymentId: "latest" })` and skip the argument plumbing.
+- **Persist state externally**: If state needs to be readable from outside the workflow for dashboards, debugging, or recovery, write it to a database in a step before spawning the next run.
+- **Track the active `runId` externally**: The system that resumes the hook needs to know the current run. Capture the `runId` returned by `start()` and write it to a database keyed by a stable session identifier in a step, so resumers always look up the latest run.
+
+## Caveats
+
+- **Maintain backward compatibility**: Because the next run executes on a different deployment, the workflow's input arguments and return type must remain compatible across deployments. Adding required fields, removing fields, or changing types can cause serialization failures. See the [`deploymentId: "latest"` callout](/docs/api-reference/workflow-api/start#using-deploymentid-latest).
+- **Keep the workflow identity stable**: The function name and file path form the workflow identity. Renaming the function or moving the file across a deployment changes the workflow ID, so the next iteration will fail to resolve.
+- **Account for the gap between iterations**: The current run ends as soon as `start()` returns, and the next run starts asynchronously. A resume that arrives in that window can fail with "hook not found." Make resumers retry, or have the API persist pending payloads and apply them once the next iteration is ready.
+- **Track active Method 2 runs externally**: Because Method 2's runs are long-lived, the set of in-flight runs changes only when one starts, completes, or upgrades. Persist run IDs and clean them up on completion or upgrade so a rollout script can fan out reliably. After resuming `upgradeHook`, update the tracked run ID once the new run reports back, as you would in Method 1.
+
+## Key APIs
+
+- [`"use workflow"`](/docs/foundations/workflows-and-steps): Marks the orchestrator function.
+- [`start()`](/docs/api-reference/workflow-api/start) with [`deploymentId: "latest"`](/docs/api-reference/workflow-api/start#using-deploymentid-latest): Spawns the successor on the newest deployment.
+- [`defineHook()`](/docs/api-reference/workflow/define-hook): Suspends the workflow until an external event resumes it.
+- [`getWorkflowMetadata()`](/docs/api-reference/workflow/get-workflow-metadata): Exposes `workflowRunId` for per-run hook tokens.