workflow 5.0.0-beta.1 → 5.0.0-beta.3

package/docs/migration-guides/migrating-from-trigger-dev.mdx

@@ -0,0 +1,337 @@
+---
+title: Migrating from trigger.dev
+description: Move a trigger.dev v3 TypeScript app to the Workflow SDK by replacing task(), schemaTask(), wait.for / wait.forToken, triggerAndWait, and metadata streams with Workflows, Steps, Hooks, and start() / getRun().
+type: guide
+summary: Translate a trigger.dev v3 app into the Workflow SDK with side-by-side code examples.
+prerequisites:
+  - /docs/getting-started/next
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/foundations/starting-workflows
+  - /docs/foundations/errors-and-retries
+  - /docs/foundations/hooks
+  - /docs/foundations/streaming
+  - /docs/deploying/world/vercel-world
+---
+
+<Callout type="info">
+Install the Workflow SDK migration skill:
+
+```bash
+npx skills add https://github.com/vercel/workflow --skill migrating-to-workflow-sdk
+```
+</Callout>
+
+## Why migrate to the Workflow SDK?
+
+- Streaming is built in via named streams (`getWritable()` and `getWritable({ namespace })`). Durable status writes replace `metadata.stream()` and `metadata.set()`, and clients read from the end of the stream for current status.
+- Orchestration and infrastructure live in a single deployment. There is no separate trigger.dev cloud or self-hosted worker fleet to operate.
+- TypeScript-first DX: plain async/await control flow, no `task()` factory, no `schemaTask()` wrapper for payloads you already type with TypeScript.
+- Agent-first tooling: the `npx workflow` CLI, `@workflow/ai` for durable AI agents, and a Claude skill for generating workflows.
+- Retry policy is per step. Throw `RetryableError` to retry with a delay, or `FatalError` to stop. There is no central task-level retry config.
+
+## What changes when you leave trigger.dev?
+
+trigger.dev v3 defines durable work with `task()` or `schemaTask()` from `@trigger.dev/sdk` (trigger.dev v3), deploys tasks to the trigger.dev cloud or a self-hosted instance, and triggers runs via `tasks.trigger()`. A separate worker fleet picks up runs, applies retry policies, and routes `wait.for`, `wait.forToken`, and `metadata.stream` calls through the platform.
+
+The Workflow SDK replaces that with `"use workflow"` functions that orchestrate `"use step"` functions in plain TypeScript. There is no task registry, separate deploy target, or SDK client. Durable replay, retries, and event history ship with the runtime.
+
+Migration collapses the task abstraction into plain async functions. Business logic stays the same.
+
+## Concept mapping
+
+| trigger.dev | Workflow SDK | Migration note |
+| --- | --- | --- |
+| `task({ id, run })` | `"use workflow"` function started with `start()` | No factory or id registry. |
+| `schemaTask({ schema, run })` | Typed function + `"use workflow"` | Validate inputs at the call site. |
+| Inline `run` body | `"use step"` function | Side effects move into named steps. |
+| `logger` / `metadata.set` | `console` + `getWritable({ namespace: 'status' })` | Logs flow through the run timeline. Status writes go on a named stream. |
+| `wait.for({ seconds \| minutes \| hours \| days })` / `wait.until({ date })` | `sleep()` | Import from `workflow`. |
+| `wait.forToken({ timeout })` | `createHook()` + `Promise.race` with `sleep()` | Hooks carry a typed token. |
+| `tasks.trigger()` / `triggerAndWait()` | `start()` and `getRun(runId).returnValue` | Wrap both in `"use step"` functions. |
+| `batch.triggerAndWait()` | `Promise.all(runIds.map(collectResult))` | Fan out via standard concurrency. |
+| `AbortTaskRunError` | `FatalError` | Stops retries immediately. |
+| `retry.onThrow` / `retry.fetch` | `RetryableError`, `FatalError`, `maxRetries` | Retry count lives on the step via `myStep.maxRetries = N` (default 3). Control delay between attempts by throwing `new RetryableError(msg, { retryAfter: '5s' })` — there is no built-in exponential helper; compute the delay yourself based on `getStepMetadata().attempt` if you need one. |
+| `metadata.stream()` / Realtime | `getWritable()` / `getWritable({ namespace })` | For granular business status (progress updates, current-stage messages), prefer writing to `getWritable({ namespace: 'status' })` from a step and reading from the end of the named stream on the client. Use `getRun(runId).status` for terminal/lifecycle state only. |
+| Self-hosted worker + dashboard | Managed execution + built-in UI | No worker fleet to operate. |
+
+## Translate your first workflow
+
+<Callout type="warn">
+trigger.dev's `task.run` body has full Node.js access. The SDK's `'use workflow'` body runs in a sandboxed VM — side effects (I/O, `Date.now()`, `Math.random()`, DB, fetch) must live inside `'use step'` functions. Orchestration stays in the workflow body.
+</Callout>
+
+Start with the shell. trigger.dev wraps the handler in `task()`; the Workflow SDK marks the function with a directive.
+
+```typescript title="trigger/order.ts (trigger.dev)"
+import { task } from '@trigger.dev/sdk';
+
+export const processOrder = task({
+  id: 'process-order',
+  run: async (payload: { orderId: string }) => {
+    return { orderId: payload.orderId, status: 'completed' };
+  },
+});
+```
+
+```typescript title="trigger/order.ts (Workflow SDK)"
+export async function processOrder(orderId: string) {
+  'use workflow'; // [!code highlight]
+  return { orderId, status: 'completed' };
+}
+```
+
+**What changed:** the `task()` factory and its `id` field disappear. The function is a plain export tagged with `"use workflow"`.
+
+### Add a step
+
+The body of `run` becomes one or more `"use step"` functions.
+
+```typescript title="workflow/workflows/order.ts"
+async function loadOrder(orderId: string) {
+  'use step'; // [!code highlight]
+  const res = await fetch(`https://example.com/api/orders/${orderId}`);
+  return res.json() as Promise<{ id: string }>;
+}
+```
+
+Call it from the workflow with a plain `await`. Each additional side effect (`reserveInventory`, `chargePayment`) follows the same shape.
+
+### Start the run
+
+trigger.dev dispatches with `tasks.trigger<typeof processOrder>('process-order', { orderId })`. The Workflow SDK calls `start()` directly:
+
+```typescript title="app/api/orders/route.ts"
+import { start } from 'workflow/api';
+import { processOrder } from '@/workflows/order';
+
+export async function POST(request: Request) {
+  const { orderId } = (await request.json()) as { orderId: string };
+  const run = await start(processOrder, [orderId]); // [!code highlight]
+  return Response.json({ runId: run.runId });
+}
+```
+
+No id lookup, no API key, no separate worker. `start()` returns a handle immediately.
+
+## Wait for an external signal
+
+`wait.forToken()` becomes `createHook()` plus `await`.
+
+{/* @skip-typecheck: trigger.dev SDK types not available */}
+```typescript title="workflow/workflows/refund.ts (trigger.dev, abbreviated)"
+// import { wait } from '@trigger.dev/sdk';
+const token = await wait.createToken({ timeout: '7d' });
+const approval = await wait.forToken<{ approved: boolean }>(token.id).unwrap();
+// External system resumes with: await wait.completeToken(token.id, { approved: true });
+```
+
+{/* @skip-typecheck: snippet without imports */}
+```typescript title="workflow/workflows/refund.ts (Workflow SDK)"
+using approval = createHook<{ approved: boolean }>({ // [!code highlight]
+  token: `refund:${refundId}:approval`,
+});
+const payload = await approval;
+```
+
+**What changed:** the platform-issued opaque token becomes an app-owned string. The caller that resumes the run supplies that same string, so there is no token lookup. (trigger.dev also exposes `token.url` for external callers; the SDK analog is `createWebhook().url`).
+
+### Resume from an API route
+
+There are two shapes of resume, and `wait.forToken` can map to either:
+
+- **Server-side resume (known token):** `createHook<T>({ token: 'business-token' })` + `resumeHook(token, payload)` from an API route. Use this when your app knows the token shape and controls the resume call.
+- **Third-party callback URL (generated token):** `createWebhook({ respondWith: 'default' })` + pass `webhook.url` to the external system. The external system hits the URL to resume.
+
+See [`/docs/foundations/hooks`](/docs/foundations/hooks) for both surfaces.
+
+trigger.dev completes a token with `wait.completeToken(tokenId, { approved })`. The SDK equivalent is `resumeHook`:
+
+```typescript title="app/api/refunds/[refundId]/approve/route.ts"
+import { resumeHook } from 'workflow/api';
+
+export async function POST(request: Request, { params }: { params: Promise<{ refundId: string }> }) {
+  const { refundId } = await params;
+  const { approved } = (await request.json()) as { approved: boolean };
+  await resumeHook(`refund:${refundId}:approval`, { approved }); // [!code highlight]
+  return Response.json({ ok: true });
+}
+```
+
+### Add a timeout and branch on the payload
+
+trigger.dev's `timeout: '7d'` option maps to a `Promise.race()` with `sleep()`:
+
+{/* @skip-typecheck: continuation snippet */}
+```typescript title="workflow/workflows/refund.ts"
+const result = await Promise.race([
+  approval.then((p) => ({ type: 'decision' as const, approved: p.approved })),
+  sleep('7d').then(() => ({ type: 'timeout' as const })), // [!code highlight]
+]);
+
+if (result.type === 'timeout') return { refundId, status: 'timed-out' };
+if (!result.approved) return { refundId, status: 'rejected' };
+return { refundId, status: 'approved' };
+```
+
+<Callout type="info">
+A hook is an inbound write channel. The caller that knows the token resumes the run with a typed payload. For granular business status (progress updates, current-stage messages), prefer writing to `getWritable({ namespace: 'status' })` from a step and reading from the end of the named stream on the client. Use `getRun(runId).status` for terminal/lifecycle state only.
+</Callout>
+
+## Spawn a child workflow
+
+`triggerAndWait()` splits into two steps: spawn and collect. `start()` and `getRun()` are runtime APIs, so wrap them in `"use step"` functions. Return the full `Run` object from `spawnChild` so observability tooling can deep-link to the child run.
+
+You can return either the full `Run` object (enables deep-linking) or just `run.runId` (simpler). The runtime serializes `Run` to its `runId` in the event log either way.
+
+```typescript title="workflow/workflows/parent.ts"
+import { start } from 'workflow/api';
+
+async function spawnChild(item: string) {
+  'use step';
+  return start(childWorkflow, [item]); // [!code highlight]
+}
+```
+
+Await the result in a second step, then orchestrate both from the parent:
+
+```typescript title="workflow/workflows/parent.ts"
+import { getRun } from 'workflow/api';
+
+async function collectResult(runId: string) {
+  'use step';
+  const run = getRun(runId);
+  return (await run.returnValue) as { item: string; result: string }; // [!code highlight]
+}
+
+export async function parentWorkflow(item: string) {
+  'use workflow';
+  const child = await spawnChild(item);
+  return await collectResult(child.runId);
+}
+```
+
+To fan out, call `spawnChild` inside a loop, then `Promise.all` the `collectResult` calls. That replaces `batch.triggerAndWait()`.
+
+`Promise.all` rejects on first failure; use `Promise.allSettled` if you need batch-mode error tolerance similar to trigger.dev's `{ ok, output, error }` per-run result.
+
+## What you stop operating
+
+Dropping the trigger.dev SDK removes several moving parts:
+
+- **No task registry or `id` strings.** Workflow files carry directive annotations and export plain functions.
+- **No `@trigger.dev/sdk` client or API key.** `start()` launches runs directly from API routes or server actions.
+- **No worker fleet or self-hosted instance.** The runtime schedules execution inside the app's deploy target.
+- **No separate Realtime channel.** `getWritable()` streams updates from steps over the run's durable stream.
+- **No dashboard account.** The built-in observability UI (`npx workflow web`) reads the same event log the runtime writes.
+
+Workflows suspended on `sleep()` or a hook consume no compute until resumed.
+
+## Step-by-step first migration
+
+Pick one trigger.dev task and migrate it end-to-end before touching the rest. The steps below describe the smallest viable path.
+
+### Step 1: Install the Workflow SDK
+
+Add the runtime. Framework integrations (Next.js, Nitro, Nuxt, SvelteKit, Astro, Nest) are subpath exports of the same `workflow` package, e.g. `workflow/next` — no additional install needed.
+
+```bash
+pnpm add workflow
+```
+
+### Step 2: Convert `task()` to a `"use workflow"` export
+
+Drop the factory call and the `id`. Move the handler body up and replace the payload object with typed function arguments.
+
+```ts title="workflows/order.ts"
+// Before (trigger.dev)
+// export const processOrder = task({
+//   id: "process-order",
+//   run: async ({ orderId }: { orderId: string }) => { ... },
+// });
+
+// After (Workflow SDK)
+export async function processOrder(orderId: string) {
+  "use workflow"; // [!code highlight]
+  // ...
+}
+```
+
+### Step 3: Convert the task body into `"use step"` named functions
+
+Each side effect becomes a named function with `"use step"` on the first line. The workflow calls them with a plain `await`. `schemaTask()` validation moves to the call site: validate with zod before calling `start()`.
+
+```ts
+async function loadOrder(id: string) {
+  "use step"; // [!code highlight]
+  return fetch(`/api/orders/${id}`).then((r) => r.json());
+}
+```
+
+### Step 4: Replace `wait.*` with hooks and `sleep`
+
+- `wait.for({ seconds | minutes | hours | days })` / `wait.until({ date })` → `sleep('5m')` or `sleep(date)` from `workflow`.
+- `wait.forToken(token)` → `createHook({ token })` + `await`. Complete it with `resumeHook(token, payload)` from an API route.
+- `wait.forToken({ timeout })` → `Promise.race([hook, sleep(timeout)])`.
+- `triggerAndWait(payload)` → wrap `start(child, [payload])` in a `"use step"` function and return the `Run` object, then read the result with a second step that calls `getRun(runId).returnValue`.
+
+### Step 5: Start runs from the app
+
+Delete the trigger.dev client setup. Launch runs directly from an API route or server action:
+
+```ts title="app/api/orders/route.ts"
+import { start } from "workflow/api";
+import { processOrder } from "@/workflows/order";
+
+export async function POST(req: Request) {
+  const { orderId } = await req.json();
+  const run = await start(processOrder, [orderId]);
+  return Response.json({ runId: run.runId });
+}
+```
+
+### Step 6: Retire trigger.dev infrastructure
+
+Remove the `@trigger.dev/sdk` dependency, the `trigger.config.ts` file, the `trigger/` directory, and any self-hosted worker deployment. Delete dashboard API keys from the environment. Verify the run in `npx workflow web` before shipping.
+
+## Retries on steps
+
+Retry count lives on the step function itself. Set it as a property on the step:
+
+```typescript
+async function chargePayment(orderId: string) {
+  "use step";
+  // ...
+}
+chargePayment.maxRetries = 5;
+```
+
+Throw `new RetryableError(msg, { retryAfter: '5s' })` to control delay between attempts, or `FatalError` to stop retries immediately. See [`/docs/foundations/errors-and-retries`](/docs/foundations/errors-and-retries).
+
+## Features without a 1:1 equivalent
+
+- **`schedules.task()` / cron triggers.** The SDK has no built-in scheduler. Trigger runs from Vercel Cron or a system cron calling `start()`.
+- **Concurrency keys / queue concurrency limits.** No direct analog. Enforce limits inside steps (semaphores, external coordinator) or debounce at the publisher.
+- **`machine` presets / custom images.** Machine specs are per-task in trigger.dev; in the SDK, function resources are per-deployment (configure via your hosting platform).
+- **Realtime / `subscribeToRun`.** Use `getRun(runId).getReadable()` plus named `getWritable()` streams for live progress.
+- **`onFailure` lifecycle hook.** No equivalent. Handle cleanup in the workflow body with a try/catch + compensation-stack pattern.
+- **Trigger.dev dashboard.** Workflow SDK ships `npx workflow web` for local inspection and the Vercel Observability tab for deployed runs.
+
+## Quick-start checklist
+
+- Replace `task({ id, run })` with a `"use workflow"` function; launch it with `start()`.
+- Convert each task body into named `"use step"` functions.
+- Swap `wait.for` / `wait.until` for `sleep()` from `workflow`.
+- Swap `wait.forToken` for `createHook()` (internal) or `createWebhook()` (HTTP).
+- Model `wait.forToken` timeouts as `Promise.race()` between the hook and `sleep()`.
+- Replace `triggerAndWait()` with `"use step"` wrappers around `start()` and `getRun()`.
+- Replace `batch.triggerAndWait()` with `Promise.all` over the collected child `Run` handles.
+- Move `schemaTask` validation to the call site; pass typed arguments into the workflow.
+- Replace `AbortTaskRunError` with `FatalError`; model retries per step with `RetryableError` and `maxRetries`.
+- Use `getStepMetadata().stepId` as the idempotency key for external side effects.
+- Replace `metadata.stream()` and Realtime with `getWritable()`.
+- Remove the `@trigger.dev/sdk` dependency, `trigger.config.ts`, and any self-hosted worker.
+- Deploy and verify runs end-to-end with the built-in observability UI.
+
+---
+*Verified against `workflow@5.0.0-beta.1` and `@trigger.dev/sdk` v3 on 2026-04-16.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.1",
+  "version": "5.0.0-beta.3",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -56,18 +56,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "5.0.0-beta.1",
-    "@workflow/cli": "5.0.0-beta.1",
-    "@workflow/core": "5.0.0-beta.1",
-    "@workflow/errors": "5.0.0-beta.0",
-    "@workflow/typescript-plugin": "5.0.0-beta.1",
-    "@workflow/utils": "5.0.0-beta.0",
-    "@workflow/next": "5.0.0-beta.1",
-    "@workflow/nest": "5.0.0-beta.1",
-    "@workflow/nitro": "5.0.0-beta.1",
-    "@workflow/nuxt": "5.0.0-beta.1",
-    "@workflow/sveltekit": "5.0.0-beta.1",
-    "@workflow/rollup": "5.0.0-beta.1"
+    "@workflow/astro": "5.0.0-beta.3",
+    "@workflow/cli": "5.0.0-beta.3",
+    "@workflow/errors": "5.0.0-beta.1",
+    "@workflow/typescript-plugin": "5.0.0-beta.3",
+    "@workflow/core": "5.0.0-beta.3",
+    "@workflow/next": "5.0.0-beta.3",
+    "@workflow/utils": "5.0.0-beta.1",
+    "@workflow/nest": "5.0.0-beta.3",
+    "@workflow/nitro": "5.0.0-beta.3",
+    "@workflow/nuxt": "5.0.0-beta.3",
+    "@workflow/sveltekit": "5.0.0-beta.3",
+    "@workflow/rollup": "5.0.0-beta.3"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",

package/docs/foundations/common-patterns.mdx

@@ -1,265 +0,0 @@
----
-title: Common Patterns
-description: Implement distributed patterns using familiar async/await syntax with no new APIs to learn.
-type: guide
-summary: Apply sequential, parallel, timeout, and composition patterns in workflows.
-prerequisites:
-  - /docs/foundations/workflows-and-steps
-related:
-  - /docs/foundations/errors-and-retries
-  - /docs/foundations/hooks
----
-
-Common distributed patterns are simple to implement in workflows and require learning no new syntax. You can just use familiar async/await patterns.
-
-## Sequential Execution
-
-The simplest way to orchestrate steps is to execute them one after another, where each step can be dependent on the previous step.
-
-```typescript lineNumbers
-declare function validateData(data: unknown): Promise<string>; // @setup
-declare function processData(data: string): Promise<string>; // @setup
-declare function storeData(data: string): Promise<string>; // @setup
-
-export async function dataPipelineWorkflow(data: unknown) {
-  "use workflow";
-
-  const validated = await validateData(data);
-  const processed = await processData(validated);
-  const stored = await storeData(processed);
-
-  return stored;
-}
-```
-
-## Parallel Execution
-
-When you need to execute multiple steps in parallel, you can use `Promise.all` to run them all at the same time.
-
-```typescript lineNumbers
-declare function fetchUser(userId: string): Promise<{ name: string }>; // @setup
-declare function fetchOrders(userId: string): Promise<{ items: string[] }>; // @setup
-declare function fetchPreferences(userId: string): Promise<{ theme: string }>; // @setup
-
-export async function fetchUserData(userId: string) {
-  "use workflow";
-
-  const [user, orders, preferences] = await Promise.all([ // [!code highlight]
-    fetchUser(userId), // [!code highlight]
-    fetchOrders(userId), // [!code highlight]
-    fetchPreferences(userId) // [!code highlight]
-  ]); // [!code highlight]
-
-  return { user, orders, preferences };
-}
-```
-
-This not only applies to steps - since [`sleep()`](/docs/api-reference/workflow/sleep) and [`webhook`](/docs/api-reference/workflow/create-webhook) are also just promises, we can await those in parallel too.
-We can also use `Promise.race` instead of `Promise.all` to stop executing promises after the first one completes.
-
-```typescript lineNumbers
-import { sleep, createWebhook } from "workflow";
-declare function executeExternalTask(webhookUrl: string): Promise<void>; // @setup
-
-export async function runExternalTask(userId: string) {
-  "use workflow";
-
-  const webhook = createWebhook();
-  await executeExternalTask(webhook.url); // Send the webhook somewhere
-
-  // Wait for the external webhook to be hit, with a timeout of 1 day,
-  // whichever comes first
-  await Promise.race([ // [!code highlight]
-    webhook, // [!code highlight]
-    sleep("1 day"), // [!code highlight]
-  ]); // [!code highlight]
-
-  console.log("Done")
-}
-```
-
-## A Full Example
-
-Here's a simplified example taken from the [birthday card generator demo](https://github.com/vercel/workflow-examples/tree/main/birthday-card-generator), to illustrate how sequential and parallel execution can be combined.
-
-```typescript lineNumbers
-import { createWebhook, sleep, type Webhook } from "workflow"
-declare function makeCardText(prompt: string): Promise<string>; // @setup
-declare function makeCardImage(text: string): Promise<string>; // @setup
-declare function sendRSVPEmail(friend: string, webhook: Webhook): Promise<void>; // @setup
-declare function sendBirthdayCard(text: string, image: string, rsvps: unknown[], email: string): Promise<void>; // @setup
-
-async function birthdayWorkflow(
-    prompt: string,
-    email: string,
-    friends: string[],
-    birthday: Date
-) {
-    "use workflow";
-
-    // Generate a birthday card with sequential steps
-    const text = await makeCardText(prompt)
-    const image = await makeCardImage(text)
-
-    // Create webhooks for each friend who's invited to the birthday party
-    const webhooks = friends.map(_ => createWebhook())
-
-    // Send out all the RSVP invites in parallel steps
-    await Promise.all(
-        friends.map(
-            (friend, i) => sendRSVPEmail(friend, webhooks[i])
-        )
-    )
-
-    // Collect RSVPs as they are made without blocking the workflow
-    let rsvps = []
-    webhooks.map(
-        webhook => webhook
-            .then(req => req.json())
-            .then(( { rsvp } ) => rsvps.push(rsvp))
-    )
-
-    // Wait until the birthday
-    await sleep(birthday)
-
-    // Send birthday card with as many rsvps were collected
-    await sendBirthdayCard(text, image, rsvps, email)
-
-    return { text, image, status: "Sent" }
-}
-```
-
-## Timeout Pattern
-
-A common requirement is adding timeouts to operations that might take too long. Use `Promise.race` with `sleep()` to implement this pattern.
-
-```typescript lineNumbers
-import { sleep } from "workflow";
-declare function processData(data: string): Promise<string>; // @setup
-
-export async function processWithTimeout(data: string) {
-  "use workflow";
-
-  const result = await Promise.race([ // [!code highlight]
-    processData(data), // [!code highlight]
-    sleep("30s").then(() => "timeout" as const), // [!code highlight]
-  ]); // [!code highlight]
-
-  if (result === "timeout") {
-    // In workflows, any thrown error exits the workflow (FatalError is for steps)
-    throw new Error("Processing timed out after 30 seconds");
-  }
-
-  return result;
-}
-```
-
-This pattern works with any promise-returning operation including steps, hooks, and webhooks. For example, you can add a timeout to a webhook that waits for external input:
-
-```typescript lineNumbers
-import { sleep, createWebhook } from "workflow";
-declare function sendApprovalRequest(requestId: string, webhookUrl: string): Promise<void>; // @setup
-
-export async function waitForApproval(requestId: string) {
-  "use workflow";
-
-  const webhook = createWebhook<{ approved: boolean }>();
-  await sendApprovalRequest(requestId, webhook.url);
-
-  const result = await Promise.race([ // [!code highlight]
-    webhook.then((req) => req.json()), // [!code highlight]
-    sleep("7 days").then(() => ({ timedOut: true }) as const), // [!code highlight]
-  ]); // [!code highlight]
-
-  if ("timedOut" in result) {
-    throw new Error("Approval request expired after 7 days");
-  }
-
-  return result.approved;
-}
-```
-
-## Workflow Composition
-
-Workflows can call other workflows, enabling you to break complex processes into reusable building blocks. There are two approaches depending on your needs.
-
-### Direct Await (Flattening)
-
-Call a child workflow directly using `await`. This "flattens" the child workflow into the parent - the child's steps execute inline within the parent workflow's context.
-
-```typescript lineNumbers
-declare function sendEmail(userId: string): Promise<void>; // @setup
-declare function sendPushNotification(userId: string): Promise<void>; // @setup
-declare function createAccount(userId: string): Promise<void>; // @setup
-declare function setupPreferences(userId: string): Promise<void>; // @setup
-
-// Child workflow
-export async function sendNotifications(userId: string) {
-  "use workflow";
-
-  await sendEmail(userId);
-  await sendPushNotification(userId);
-  return { notified: true };
-}
-
-// Parent workflow calls child directly
-export async function onboardUser(userId: string) {
-  "use workflow";
-
-  await createAccount(userId);
-  await sendNotifications(userId); // [!code highlight]
-  await setupPreferences(userId);
-
-  return { userId, status: "onboarded" };
-}
-```
-
-With direct await, the parent workflow waits for the child to complete before continuing. The child's steps appear in the parent's event log as if they were called directly from the parent.
-
-### Background Execution via Step
-
-To run a child workflow independently without blocking the parent, use a step that calls [`start()`](/docs/api-reference/workflow-api/start). This launches the child workflow in the background.
-
-```typescript lineNumbers
-import { start } from "workflow/api";
-declare function generateReport(reportId: string): Promise<void>; // @setup
-declare function fulfillOrder(orderId: string): Promise<{ id: string }>; // @setup
-declare function sendConfirmation(orderId: string): Promise<void>; // @setup
-
-// Step that starts a workflow in the background
-async function triggerReportGeneration(reportId: string) {
-  "use step";
-
-  const run = await start(generateReport, [reportId]); // [!code highlight]
-  return run.runId;
-}
-
-// Parent workflow
-export async function processOrder(orderId: string) {
-  "use workflow";
-
-  const order = await fulfillOrder(orderId);
-
-  // Fire off report generation without waiting
-  const reportRunId = await triggerReportGeneration(orderId); // [!code highlight]
-
-  // Continue immediately - report generates in background
-  await sendConfirmation(orderId);
-
-  return { orderId, reportRunId };
-}
-```
-
-With background execution, the parent workflow continues immediately after starting the child. The child workflow runs independently with its own event log and can be monitored separately using the returned `runId`.
-
-<Callout type="info">
-If you want the child workflow to run on the latest deployment rather than the current one, you can pass [`deploymentId: "latest"`](/docs/api-reference/workflow-api/start#using-deploymentid-latest) in the `start()` options. This is currently a Vercel-specific feature. Be aware that the child workflow's function name, file path, argument types, and return type must remain compatible across deployments — renaming the function or changing its location will change the workflow ID, and modifying expected inputs or outputs can cause serialization failures.
-</Callout>
-
-**Choose direct await when:**
-- The parent needs the child's result before continuing
-- You want a single, unified event log
-
-**Choose background execution when:**
-- The parent doesn't need to wait for the result
-- You want separate workflow runs for observability