workflow 5.0.0-beta.2 → 5.0.0-beta.21

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

@@ -0,0 +1,315 @@
+---
+title: Child Workflows
+description: Spawn child workflows from a parent and wait for completion via hook resume.
+type: guide
+summary: Orchestrate independent child workflows from a parent using start(), defineHook(), and startAndWait() — the child resumes the parent's hook when done instead of polling getRun().status.
+related:
+  - /docs/api-reference/workflow-api/start
+---
+
+Use child workflows when a single workflow needs to orchestrate many independent units of work. Each child runs as its own workflow with a separate event log, retry boundary, and failure scope -- if one child fails, it doesn't take down the parent or siblings.
+
+## When to use child workflows
+
+Child workflows are the right choice when:
+
+- **Work units are independent.** Each child can run without knowing about the others (e.g., processing individual documents, generating separate reports).
+- **You need isolated failure boundaries.** A failing child should not abort unrelated work. The parent decides how to handle failures.
+- **You want massive fan-out.** Spawning 50 or 500 children is practical because each runs on its own infrastructure.
+- **You need per-item observability.** Each child workflow has its own run ID, status, and event log for monitoring.
+
+For simpler cases where steps share a single event log, use [direct await composition](/cookbook/common-patterns/workflow-composition#direct-await-flattening) instead.
+
+## Basic pattern: spawn and wait via hook
+
+The recommended pattern has four parts:
+
+1. A **completion hook** the parent creates and awaits — zero compute while waiting
+2. A **wrapped child export** that runs the real child in try/catch/finally and resumes the parent's hook from a step in `finally`
+3. A **`start()` call** that spawns the wrapped child with the hook token (directly from the workflow in v5)
+4. A **`startAndWait()` helper** that ties the hook, spawn, and typed result together
+
+```typescript
+import { defineHook, getWorkflowMetadata } from "workflow";
+import { start } from "workflow/api";
+import { z } from "zod";
+
+declare function fetchDocument(documentId: string): Promise<string>; // @setup
+declare function analyzeContent(content: string): Promise<string>; // @setup
+declare function generateSummary(analysis: string): Promise<string>; // @setup
+
+const childCompletionHook = defineHook({
+  schema: z.discriminatedUnion("status", [
+    z.object({ status: z.literal("completed"), value: z.unknown() }),
+    z.object({ status: z.literal("failed"), error: z.string() }),
+  ]),
+});
+
+function completionToken(parentRunId: string, key: string) {
+  return `child-completion:${parentRunId}:${key}`;
+}
+
+async function resumeParentCompletion(
+  token: string,
+  result:
+    | { status: "completed"; value: unknown }
+    | { status: "failed"; error: string }
+) {
+  "use step";
+  await childCompletionHook.resume(token, result);
+}
+
+async function withChildCompletionHook<TResult>(
+  runChild: () => Promise<TResult>,
+  completionTokenArg: string
+) {
+  let result:
+    | { status: "completed"; value: TResult }
+    | { status: "failed"; error: string }
+    | undefined;
+
+  try {
+    const value = await runChild();
+    result = { status: "completed", value };
+  } catch (error) {
+    result = {
+      status: "failed",
+      error: error instanceof Error ? error.message : String(error),
+    };
+  } finally {
+    if (result) {
+      await resumeParentCompletion(completionTokenArg, result);
+    }
+  }
+}
+
+// Child workflow -- processes a single document
+export async function processDocument(documentId: string) {
+  "use workflow";
+
+  const content = await fetchDocument(documentId);
+  const analysis = await analyzeContent(content);
+  const summary = await generateSummary(analysis);
+
+  return { documentId, summary };
+}
+
+// Spawnable wrapper -- explicit export so `start()` can register it
+export async function processDocumentWithCompletion(
+  documentId: string,
+  completionTokenArg: string
+) {
+  "use workflow";
+
+  await withChildCompletionHook(
+    () => processDocument(documentId),
+    completionTokenArg
+  );
+}
+
+async function startAndWait<TResult>(
+  key: string,
+  startChild: (completionTokenArg: string) => Promise<void>
+): Promise<TResult> {
+  const { workflowRunId } = getWorkflowMetadata();
+  const token = completionToken(workflowRunId, key);
+  const hook = childCompletionHook.create({ token }); // [!code highlight]
+
+  await startChild(token);
+
+  const completion = await hook; // [!code highlight]
+  if (completion.status === "failed") {
+    throw new Error(completion.error);
+  }
+  return completion.value as TResult;
+}
+
+// Parent workflow -- orchestrates document processing
+export async function processDocumentBatch(documentIds: string[]) {
+  "use workflow";
+
+  const results = await Promise.all(
+    documentIds.map((documentId) =>
+      startAndWait<{ documentId: string; summary: string }>(documentId, (token) =>
+        start(processDocumentWithCompletion, [documentId, token]).then(() => undefined) // [!code highlight]
+      )
+    )
+  );
+
+  return { processed: results.length, results };
+}
+```
+
+### Why hooks instead of polling?
+
+Polling with `getRun().status` in a `sleep()` loop works, but hook resume is preferable because:
+
+- **Zero compute while waiting** — the parent suspends on the hook instead of waking every poll interval
+- **Immediate wake-up** — the parent resumes as soon as the child finishes, not on the next poll tick
+- **Typed payloads** — the child sends `{ status, value | error }` directly; no separate `returnValue` fetch step
+- **No worker-pool pressure** — `Run#returnValue` polling inside steps can hold worker slots while waiting for children (see [Eager Processing](/docs/changelog/eager-processing))
+
+When a parent calls a child workflow inline with `await` (flattened into the same run), the same wrapper and hook handshake still works — pass the token and `await processDocumentWithCompletion(...)` inside `startAndWait()` instead of calling `start()`.
+
+## Fan-out pattern: chunked spawning
+
+When spawning hundreds of children, batch the `start()` calls to avoid overwhelming the system. Each child still gets its own completion hook keyed by a stable identifier (document ID, report ID, index).
+
+```typescript
+import { start } from "workflow/api";
+
+declare function startAndWait<TResult>(
+  key: string,
+  startChild: (completionTokenArg: string) => Promise<void>
+): Promise<TResult>; // @setup
+
+const CHUNK_SIZE = 10;
+
+export async function largeReportBatch(
+  reportConfigs: Array<{ id: string; query: string }>
+) {
+  "use workflow";
+
+  const results = [];
+  for (let i = 0; i < reportConfigs.length; i += CHUNK_SIZE) {
+    const chunk = reportConfigs.slice(i, i + CHUNK_SIZE);
+    const chunkResults = await Promise.all(
+      chunk.map((config) =>
+        startAndWait<{ reportId: string; formatted: string }>(config.id, (token) =>
+          start(generateReportWithCompletion, [
+            config.id,
+            config.query,
+            token,
+          ]).then(() => undefined)
+        )
+      )
+    );
+    results.push(...chunkResults);
+  }
+
+  return { total: results.length, results };
+}
+
+async function generateReportWithCompletion(
+  reportId: string,
+  query: string,
+  completionTokenArg: string
+) {
+  "use workflow";
+
+  await withChildCompletionHook(
+    () => generateReport(reportId, query),
+    completionTokenArg
+  );
+}
+
+async function generateReport(reportId: string, query: string) {
+  "use workflow";
+
+  const data = await queryDatabase(reportId, query);
+  const formatted = await formatReport(reportId, data);
+  return { reportId, formatted };
+}
+
+declare function queryDatabase(reportId: string, query: string): Promise<string>; // @setup
+declare function formatReport(reportId: string, data: string): Promise<string>; // @setup
+declare function withChildCompletionHook<TResult>(
+  runChild: () => Promise<TResult>,
+  completionTokenArg: string
+): Promise<void>; // @setup
+```
+
+## Error handling
+
+### Tolerating partial failures
+
+Use `Promise.allSettled` with `startAndWait()` so one failing child doesn't abort siblings. The hook payload already carries `{ status: "failed", error }` — no status polling required.
+
+```typescript
+import { start } from "workflow/api";
+
+declare function startAndWait<TResult>(
+  key: string,
+  startChild: (completionTokenArg: string) => Promise<void>
+): Promise<TResult>; // @setup
+declare function processDocumentWithCompletion(
+  documentId: string,
+  completionTokenArg: string
+): Promise<void>; // @setup
+
+export async function processDocumentBatchTolerant(documentIds: string[]) {
+  "use workflow";
+
+  const settled = await Promise.allSettled(
+    documentIds.map((documentId) =>
+      startAndWait<{ documentId: string; summary: string }>(documentId, (token) =>
+        start(processDocumentWithCompletion, [documentId, token]).then(
+          () => undefined
+        )
+      )
+    )
+  );
+
+  const results = settled
+    .filter(
+      (entry): entry is PromiseFulfilledResult<{ documentId: string; summary: string }> =>
+        entry.status === "fulfilled"
+    )
+    .map((entry) => entry.value);
+
+  const failed = settled.filter((entry) => entry.status === "rejected").length;
+
+  return { processed: results.length, failed, results };
+}
+```
+
+### Retrying failed children
+
+When a child fails, spawn a replacement with a fresh hook token. Track restart counts to prevent infinite retry loops.
+
+```typescript
+declare function startAndWait<TResult>(
+  key: string,
+  startChild: (completionTokenArg: string) => Promise<void>
+): Promise<TResult>; // @setup
+declare function spawnProcessDocument(
+  documentId: string,
+  completionTokenArg: string
+): Promise<void>; // @setup
+
+async function startAndWaitWithRetries(
+  documentId: string,
+  maxRestarts: number
+): Promise<{ documentId: string; summary: string }> {
+  for (let attempt = 0; attempt <= maxRestarts; attempt++) {
+    try {
+      return await startAndWait<{ documentId: string; summary: string }>(
+        `${documentId}:${attempt}`,
+        (token) => spawnProcessDocument(documentId, token)
+      );
+    } catch (error) {
+      if (attempt === maxRestarts) throw error;
+    }
+  }
+
+  throw new Error("unreachable");
+}
+```
+
+## Tips
+
+- **`defineHook().resume()` must be called from a step.** The wrapped child's `finally` block calls a step that resumes the parent hook.
+- **Export wrapped children at module scope.** The SDK registers `"use workflow"` functions statically — a runtime higher-order function returned from `withChildCompletionHook()` cannot be passed to `start()`.
+- **Use stable hook keys** — document ID, job ID, or index — so parallel children inside one parent run don't collide on tokens.
+- **Use chunked spawning for large batches.** Starting 500 children at once can create a large burst of work. Break it into chunks of 10-50.
+- **Each child has its own retry semantics.** Steps inside child workflows retry independently. The parent sees the final `{ status, value | error }` payload from the hook.
+- **Use `deploymentId: "latest"`** if children should run on the most recent deployment. See [Versioning](/docs/foundations/versioning) for the full model and the [`start()` API reference](/docs/api-reference/workflow-api/start#using-deploymentid-latest) for compatibility considerations.
+
+## Key APIs
+
+- [`start()`](/docs/api-reference/workflow-api/start) -- spawn a new workflow run and get its run ID
+- [`defineHook()`](/docs/api-reference/workflow/define-hook) -- typed hook for parent/child completion handshakes
+- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) -- resume a waiting parent from a step (called by the child wrapper)
+- [`getWorkflowMetadata()`](/docs/api-reference/workflow/get-workflow-metadata) -- read the parent run ID for deterministic hook tokens
+- [`"use workflow"`](/docs/foundations/workflows-and-steps) -- marks the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps) -- marks functions with full Node.js access

package/docs/cookbook/advanced/meta.json

@@ -1,10 +1,9 @@
 {
   "title": "Advanced",
   "pages": [
+    "child-workflows",
+    "upgrading-workflows",
     "serializable-steps",
-    "durable-objects",
-    "isomorphic-packages",
-    "custom-serialization",
     "publishing-libraries"
   ]
 }

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

@@ -5,6 +5,8 @@ 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.
 ---
 
+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>
@@ -13,23 +15,37 @@ This is an advanced guide for library authors who want to publish reusable workf
 
 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()`.
 
-```
-my-media-lib/
-├── src/
-│   ├── index.ts              # Package entry point
-│   ├── types.ts              # Shared types
-│   ├── workflows/
-│   │   ├── index.ts          # Re-exports all workflows
-│   │   ├── transcode.ts      # Workflow: transcode a video
-│   │   └── generate-thumbnails.ts
-│   └── lib/
-│       └── api-client.ts     # Internal helpers (NOT steps)
-├── test-server/
-│   └── workflows.ts          # Re-export for integration tests
-├── tsup.config.ts
-├── package.json
-└── tsconfig.json
-```
+<Files>
+  <Folder name="my-media-lib" defaultOpen>
+    <Folder name="src" defaultOpen>
+      <File name="index.ts" />
+      <File name="types.ts" />
+      <Folder name="workflows" defaultOpen>
+        <File name="index.ts" />
+        <File name="transcode.ts" />
+        <File name="generate-thumbnails.ts" />
+      </Folder>
+      <Folder name="lib" defaultOpen>
+        <File name="api-client.ts" />
+      </Folder>
+    </Folder>
+    <Folder name="test-server" defaultOpen>
+      <File name="workflows.ts" />
+    </Folder>
+    <File name="tsup.config.ts" />
+    <File name="package.json" />
+    <File name="tsconfig.json" />
+  </Folder>
+</Files>
+
+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)).
 
 ### Entry Points and Exports
 
@@ -126,7 +142,7 @@ When you publish a workflow library, every step function's inputs and outputs ar
 
 ### 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/cookbook/advanced/custom-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`
@@ -226,7 +242,18 @@ pnpm vitest run --config vitest.workflowsdk.config.ts
 
 ## Working With and Without Workflow Installed
 
-If your library should work both as a standalone package and inside Workflow SDK, declare `workflow` as an optional peer dependency:
+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.
+
+<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.
+</Callout>
+
+### Optional peer dependency
+
+Declare `workflow` as an **optional** peer so consumers without the runtime aren't forced to install it:
 
 ```json
 {
@@ -241,22 +268,53 @@ If your library should work both as a standalone package and inside Workflow SDK
 }
 ```
 
-Use dynamic imports and runtime detection so your library gracefully degrades when workflow is not installed:
+### Runtime detection
+
+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 isWorkflowRuntime(): Promise<boolean> {
+async function getWorkflowStepId(): Promise<string | null> { // [!code highlight]
   try {
     const wf = await import("workflow");
-    if (typeof wf.getWorkflowMetadata !== "function") return false;
-    wf.getWorkflowMetadata(); // [!code highlight]
-    return true;
+    const { stepId } = wf.getStepMetadata();
+    return stepId;
   } catch {
-    return false;
+    return null;
   }
 }
 ```
 
-See [Isomorphic Packages](/docs/cookbook/advanced/isomorphic-packages) for the full pattern including feature detection, dynamic imports, and dual-path execution.
+### A concrete use case: replay-safe idempotency keys
+
+A payments utility that uses the current workflow step ID as a Stripe idempotency key when available, and a fresh UUID otherwise:
+
+```typescript lineNumbers
+declare function getWorkflowStepId(): Promise<string | null>; // @setup (defined in the previous block)
+
+export async function processPayment(amount: number, currency: string) {
+  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",
+    headers: {
+      Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}`,
+      "Idempotency-Key": idempotencyKey, // [!code highlight]
+    },
+    body: new URLSearchParams({ amount: String(amount), currency }),
+  });
+  return res.json();
+}
+```
+
+When called from inside a workflow step, the utility gets a stable idempotency key for that step across retries — 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. 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.
 
 ## Checklist
 
@@ -273,7 +331,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
+- [`"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) — runtime detection and run ID access

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

@@ -1,17 +1,28 @@
 ---
 title: Serializable Steps
-description: Wrap non-serializable objects (like AI model providers) inside step functions so they can cross the workflow boundary.
+description: Wrap non-serializable third-party objects (like AI model providers) inside step factory functions so they can cross the workflow boundary.
 type: guide
-summary: Return a callback from a step to defer provider initialization, making non-serializable AI SDK models work inside durable workflows.
+summary: Return a callback from a step to defer construction of a non-owned class (AI SDK models, cloud SDK clients) until execution time, making them usable inside durable workflows.
+related:
+  - /docs/foundations/serialization
+  - /docs/foundations/serialization#custom-class-serialization
+  - /docs/foundations/workflows-and-steps#step-functions
 ---
 
 <Callout>
 This is an advanced guide. It dives into workflow internals and is not required reading to use workflow.
 </Callout>
 
+## When to use this pattern
+
+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.
+
 ## The Problem
 
-Workflow functions run inside a sandboxed VM where every value that crosses a function boundary must be serializable (JSON-safe). 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.
+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";
@@ -130,6 +141,7 @@ async function uploadFile(
 
 ## 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
+- [`"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
 - [`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`)