workflow 5.0.0-beta.5 → 5.0.0-beta.6

package/docs/ai/index.mdx

@@ -120,16 +120,17 @@ The core code that makes all of this happen is quite simple. Here's a breakdown
 
 <Tab value="API Route">
 
-Our API route makes a simple call to [AI SDK's `Agent` class](https://ai-sdk.dev/docs/agents/overview), which is a simple wrapper around [AI SDK's `streamText` function](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text#streamtext). This is also where we pass tools to the agent.
+Our API route makes a simple call to [AI SDK's `ToolLoopAgent` class](https://ai-sdk.dev/docs/agents/overview), which encapsulates the LLM call, tool execution loop, and stopping conditions on top of [AI SDK's `streamText` function](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text#streamtext). This is also where we pass tools to the agent.
 
 ```typescript title="app/api/chat/route.ts" lineNumbers
-import { Experimental_Agent as Agent } from "ai";
-import type { LanguageModel } from "ai";
+import { ToolLoopAgent } from "ai";
+import type { UIMessage } from "ai";
+import { convertToModelMessages, createUIMessageStreamResponse } from "ai";
 
 export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
-  const agent = new Agent({ // [!code highlight]
-    model: gateway("bedrock/claude-4-5-haiku-20251001-v1"),
+  const agent = new ToolLoopAgent({ // [!code highlight]
+    model: "bedrock/claude-4-5-haiku-20251001-v1",
     instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });

package/docs/api-reference/workflow-api/start.mdx

@@ -2,7 +2,7 @@
 title: start
 description: Start and enqueue a new workflow run.
 type: reference
-summary: Use start to programmatically enqueue a new workflow run from outside a workflow function.
+summary: Use start to programmatically enqueue a new workflow run.
 prerequisites:
   - /docs/foundations/starting-workflows
 ---
@@ -50,7 +50,8 @@ Learn more about [`WorkflowReadableStreamOptions`](/docs/api-reference/workflow-
 
 ## Good to Know
 
-* The `start()` function is used in runtime/non-workflow contexts to programmatically trigger workflow executions.
+* The `start()` function is used in runtime contexts to programmatically trigger workflow executions.
+* In v5, `start()` can also be called directly from a workflow function to spawn a child run or continue work in a new run. See [Workflow Composition](/cookbook/common-patterns/workflow-composition) and [Versioning](/docs/foundations/versioning).
 * This is different from calling workflow functions directly, which is the typical pattern in Next.js applications.
 * The function returns immediately after enqueuing the workflow - it doesn't wait for the workflow to complete.
 * All arguments must be [serializable](/docs/foundations/serialization).
@@ -84,7 +85,7 @@ const run = await start(myWorkflow, ["arg1", "arg2"], { // [!code highlight]
 
 ### Using `deploymentId: "latest"`
 
-Set `deploymentId` to `"latest"` to automatically resolve the most recent deployment for the current environment. This is useful when you want to ensure a workflow run targets the latest deployed version of your application rather than the deployment that initiated the call.
+Set `deploymentId` to `"latest"` to automatically resolve the most recent deployment for the current environment. This is useful when you want to ensure a workflow run targets the latest deployed version of your application rather than the deployment that initiated the call. For when to use this and how it fits with default run pinning, see [Versioning](/docs/foundations/versioning).
 
 ```typescript
 import { start } from "workflow/api";
@@ -96,7 +97,7 @@ const run = await start(myWorkflow, ["arg1", "arg2"], { // [!code highlight]
 ```
 
 <Callout type="info">
-The `deploymentId` option is currently a Vercel-specific feature. The `"latest"` value resolves to the most recent deployment matching your current environment — the same production target for production deployments, or the same git branch for preview deployments.
+The `deploymentId` option is currently a Vercel-specific feature. Other Worlds may implement this option differently to match their own deployment runtimes, and the World spec may rename it from `deploymentId` to `version` in a future SDK version. On Vercel, `"latest"` resolves to the most recent deployment matching your current environment — the same production target for production deployments, or the same git branch for preview deployments.
 </Callout>
 
 <Callout type="warn">

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

@@ -22,7 +22,7 @@ For simpler cases where steps share a single event log, use [direct await compos
 
 The core pattern has three parts:
 
-1. A **step** that calls `start()` to spawn a child workflow and returns the run ID
+1. A parent workflow that calls `start()` to spawn child workflows and records their run IDs
 2. A **polling loop** in the parent workflow that checks child status with `getRun()`
 3. A **step** that retrieves the child's return value once it completes
 
@@ -67,7 +67,11 @@ export async function processDocumentBatch(documentIds: string[]) {
   "use workflow";
 
   // Spawn a child workflow for each document
-  const runIds = await spawnChildren(documentIds);
+  const runIds: string[] = [];
+  for (const docId of documentIds) {
+    const run = await start(processDocument, [docId]); // [!code highlight]
+    runIds.push(run.runId);
+  }
 
   // Poll until all children complete
   await pollUntilComplete(runIds);
@@ -77,19 +81,6 @@ export async function processDocumentBatch(documentIds: string[]) {
 
   return { processed: results.length, results };
 }
-
-async function spawnChildren(
-  documentIds: string[]
-): Promise<string[]> {
-  "use step"; // [!code highlight]
-
-  const runIds: string[] = [];
-  for (const docId of documentIds) {
-    const run = await start(processDocument, [docId]); // [!code highlight]
-    runIds.push(run.runId);
-  }
-  return runIds;
-}
 ```
 
 ### Polling loop
@@ -163,7 +154,7 @@ async function collectResults(
 
 ## Fan-out pattern: chunked spawning
 
-When spawning hundreds of children, batch the `start()` calls to avoid overwhelming the system. Use multiple spawn steps, each launching a chunk of children.
+When spawning hundreds of children, batch the `start()` calls to avoid overwhelming the system. Start one chunk at a time from the parent workflow.
 
 ```typescript
 import { start } from "workflow/api";
@@ -179,7 +170,7 @@ export async function largeReportBatch(reportConfigs: Array<{ id: string; query:
   const allRunIds: string[] = [];
   for (let i = 0; i < reportConfigs.length; i += CHUNK_SIZE) {
     const chunk = reportConfigs.slice(i, i + CHUNK_SIZE);
-    const runIds = await spawnReportChunk(chunk); // [!code highlight]
+    const runIds = await startReportChunk(chunk); // [!code highlight]
     allRunIds.push(...runIds);
   }
 
@@ -190,14 +181,12 @@ export async function largeReportBatch(reportConfigs: Array<{ id: string; query:
   return { total: results.length, results };
 }
 
-async function spawnReportChunk(
+async function startReportChunk(
   configs: Array<{ id: string; query: string }>
 ): Promise<string[]> {
-  "use step";
-
   const runIds: string[] = [];
   for (const config of configs) {
-    const run = await start(generateReport, [config.id, config.query]);
+    const run = await start(generateReport, [config.id, config.query]); // [!code highlight]
     runIds.push(run.runId);
   }
   return runIds;
@@ -356,12 +345,12 @@ async function pollWithRetries(
 
 ## Tips
 
-- **`start()` must be called from a step**, not directly from a workflow function. Wrap it in a `"use step"` function.
+- **`start()` can be called directly from a workflow function in v5.** It records a step-backed boundary in the parent event log and returns a serializable `Run`.
 - **`getRun()` must also be called from a step.** The polling loop lives in the workflow, but the actual status check is a step.
 - **Set a max iteration count on polling loops** to prevent runaway workflows. Calculate the count from your expected max duration and poll interval.
-- **Use chunked spawning for large batches.** Spawning 500 children in a single step can time out. Break it into chunks of 10-50.
+- **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 only sees the child's final status.
-- **Use `deploymentId: "latest"`** if children should run on the most recent deployment. See the [`start()` API reference](/docs/api-reference/workflow-api/start#using-deploymentid-latest) for compatibility considerations.
+- **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
 

package/docs/cookbook/agent-patterns/durable-agent.mdx

@@ -14,6 +14,10 @@ Use this pattern to make any AI SDK agent durable. The agent becomes a workflow,
 - Long-running agent sessions where losing progress is unacceptable
 - Agents that need per-step observability in the workflow event log
 
+<Callout type="info">
+A durable agent run stays on the deployment that started it. For multi-turn agents that should pick up newer code between turns, see [Versioning](/docs/foundations/versioning) for patterns that start the next turn or next session run with `deploymentId: "latest"`.
+</Callout>
+
 ## Pattern
 
 Replace `Agent` with `DurableAgent`, wrap the function in `"use workflow"`, mark each tool with `"use step"`, and stream output through `getWritable()`.

package/docs/cookbook/common-patterns/scheduling.mdx

@@ -7,6 +7,10 @@ summary: Schedule future actions with durable sleep that survives cold starts, a
 
 Workflow's `sleep()` is durable — it survives cold starts, restarts, and deployments. Combined with `defineHook()` and `Promise.race()`, it becomes the foundation for interruptible scheduled workflows like drip campaigns, reminders, and timed sequences.
 
+<Callout type="info">
+Scheduled workflows are still pinned to the deployment that started them. If you are building recurring or indefinitely running schedules that should adopt newer code over time, see [Versioning](/docs/foundations/versioning) for the explicit `deploymentId: "latest"` continuation pattern.
+</Callout>
+
 ## When to use this
 
 - Sending emails on a schedule (drip campaigns, onboarding sequences, reminders)

package/docs/cookbook/common-patterns/workflow-composition.mdx

@@ -53,7 +53,7 @@ The parent waits for the child to finish before continuing. Both functions share
 
 ### Background spawn via `start()`
 
-To run a child workflow independently without blocking the parent, call [`start()`](/docs/api-reference/workflow-api/start) from a step. This launches the child as a separate workflow run with its own `runId`.
+To run a child workflow independently without blocking the parent, call [`start()`](/docs/api-reference/workflow-api/start) from the parent workflow. This launches the child as a separate workflow run with its own `runId`.
 
 ```typescript lineNumbers
 import { start } from "workflow/api";
@@ -62,37 +62,30 @@ 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
 
-async function triggerReportGeneration(reportId: string) {
-  "use step"; // [!code highlight]
-
-  const run = await start(generateReport, [reportId]); // [!code highlight]
-  return run.runId;
-}
-
 export async function processOrder(orderId: string) {
   "use workflow";
 
   const order = await fulfillOrder(orderId);
 
-  const reportRunId = await triggerReportGeneration(orderId); // [!code highlight]
+  const reportRun = await start(generateReport, [orderId]); // [!code highlight]
 
   await sendConfirmation(orderId);
 
-  return { orderId, reportRunId };
+  return { orderId, reportRunId: reportRun.runId };
 }
 ```
 
 The parent continues immediately after `start()` returns. The child runs independently and can be monitored separately using the returned `runId` (e.g., via [`getRun()`](/docs/api-reference/workflow-api/get-run)).
 
 <Callout type="info">
-If you want the child workflow to run on the latest deployment rather than the current one, 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.
+If you want the child workflow to run on the latest deployment rather than the current one, pass [`deploymentId: "latest"`](/docs/api-reference/workflow-api/start#using-deploymentid-latest) in the `start()` options. See [Versioning](/docs/foundations/versioning) for the full model. This is currently a Vercel-specific feature, and other Worlds may map the concept to their own deployment runtimes. 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>
 
 ## How it works
 
 1. **Direct await flattens.** When a workflow function awaits another workflow function, the child's `"use workflow"` directive is treated as inline — the child's steps emit into the parent's event log and share the parent's run ID.
 2. **`start()` mints a new run.** The child gets its own `runId`, its own event log, and its own retry boundary. The parent only sees the `runId` returned by `start()`.
-3. **`start()` must be called from a step.** Calling `start()` directly from a workflow function is not allowed — wrap it in a `"use step"` function. This keeps the spawn deterministic across replays.
+3. **`start()` can run inside workflows.** In v5, `start()` is step-backed, so it can be called directly from a workflow function and still records a deterministic step boundary in the event log.
 
 ## Choosing between the two modes
 
@@ -106,9 +99,9 @@ If you want the child workflow to run on the latest deployment rather than the c
 
 ## Adapting to your use case
 
-- **Spawn many children at once** — call `start()` in a loop inside a step. For more advanced fan-out (chunking, polling, partial-failure handling), graduate to the [Child Workflows](/cookbook/advanced/child-workflows) recipe.
+- **Spawn many children at once** — call `start()` in a loop from the workflow. For more advanced fan-out (chunking, polling, partial-failure handling), graduate to the [Child Workflows](/cookbook/advanced/child-workflows) recipe.
 - **Wait for a background child to finish** — combine `start()` with `getRun()` polling. The [Child Workflows](/cookbook/advanced/child-workflows) page covers the full polling loop.
-- **Pass results back from background children** — the spawn step returns the `runId`; later, a poll step uses `getRun(runId).returnValue` to fetch the final result.
+- **Pass results back from background children** — `start()` returns the `runId`; later, a poll step uses `getRun(runId).returnValue` to fetch the final result.
 
 ## Key APIs
 

package/docs/cookbook/integrations/ai-sdk.mdx

@@ -32,6 +32,10 @@ Use [`streamText()`](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text)
 
 One workflow run = one full conversation. The workflow suspends between turns on a hook and resumes when the next user message arrives. Conversation state, tool history, and intermediate computation all live inside the run.
 
+<Callout type="info">
+Because the conversation is one workflow run, it stays on the deployment that started it. If each turn should run on the latest deployment while preserving selected state or streams, see [Versioning](/docs/foundations/versioning) for the child-run continuation pattern.
+</Callout>
+
 <Tabs items={['Workflow', 'API Route', 'Client']}>
 
 <Tab value="Workflow">

package/docs/cookbook/integrations/chat-sdk.mdx

@@ -20,6 +20,10 @@ Workflow SDK complements it by making bot **sessions** durable. Each conversatio
 - Survives deploys, cold starts, and crashes — the session picks up from the last step on replay
 - Receives follow-up messages via hooks, so the bot stays responsive while the workflow is still running
 
+<Callout type="info">
+One thread mapped to one workflow run also means the thread stays on the deployment that started it. For channels where each message should use newer code, see [Versioning](/docs/foundations/versioning) for explicit child-run and handoff patterns using `deploymentId: "latest"`.
+</Callout>
+
 The rest of this page covers the integration pattern. For a full Slack + Next.js + Redis walkthrough, see the [Durable chat sessions guide](https://chat-sdk.dev/docs/guides/durable-chat-sessions-nextjs) on chat-sdk.dev.
 
 ## How It Fits Together

package/docs/cookbook/integrations/sandbox.mdx

@@ -21,6 +21,10 @@ A sandbox alone gets you an isolated VM. A workflow around it gets you a **durab
 - **Beyond the 5-hour hard cap.** Every Vercel Sandbox has a maximum lifetime. The workflow tracks that deadline and proactively snapshots + recreates *before* the cap, so the logical session outlives any one VM. Effectively unbounded session duration on top of time-bounded infrastructure.
 - **Automatic cleanup.** `try/finally` in the workflow guarantees the VM is stopped on failure or destroy.
 
+<Callout type="info">
+An effectively unbounded sandbox session is still one workflow run, so it stays on the deployment that started it. If the controller or agent code should upgrade over time, use an explicit version boundary and pass the serialized state or stream handles forward. See [Versioning](/docs/foundations/versioning).
+</Callout>
+
 ## Use Case: Coding Agents
 
 This is the pattern [Open Agents](https://open-agents.dev/) uses to spawn coding agents that run "infinitely in the cloud." Each agent session gets its own sandbox — full filesystem, network, and runtime access — and the durable workflow keeps the agent loop resumable across restarts, auto-hibernates when the user walks away, and reconnects instantly when they return.

package/docs/deploying/building-a-world.mdx

@@ -93,7 +93,7 @@ interface Storage {
 
 **Run Creation:** For `run_created` events, the `runId` parameter may be a client-provided string or `null`. When `null`, your World generates and returns a new `runId`.
 
-**Hook Tokens:** Hook tokens must be unique. If a `hook_created` event conflicts with an existing token, return a `hook_conflict` event instead.
+**Hook Tokens:** Hook tokens must be unique. If a `hook_created` event conflicts with an existing token, return a `hook_conflict` event instead and include the active hook owner's run ID as `eventData.conflictingRunId`.
 
 **Automatic Hook Disposal:** When a workflow reaches a terminal state (`completed`, `failed`, or `cancelled`), automatically dispose of all associated hooks to release tokens for reuse.
 

package/docs/deploying/world/vercel-world.mdx

@@ -139,6 +139,8 @@ On Vercel, workflow runs are pegged to the deployment that started them. This me
 
 This ensures long-running workflows complete reliably without being affected by subsequent deployments.
 
+For the full model, including rerunning on latest and explicit upgrade boundaries, see [Versioning](/docs/foundations/versioning).
+
 ## Security
 
 ### Consumer function security

package/docs/errors/hook-conflict.mdx

@@ -73,9 +73,9 @@ export async function processPayment() {
 }
 ```
 
-## Handling Hook Conflicts in Your Workflow
+## Handling Hook Conflicts
 
-When a hook conflict occurs, awaiting the hook will throw a `HookConflictError`. You can catch this error to handle the conflict gracefully:
+When a hook conflict occurs, awaiting the hook will throw a `HookConflictError`. The error exposes the token that conflicted and, for current worlds, the run ID that currently owns it. `conflictingRunId` remains optional for compatibility with older persisted events and world implementations, so guard it before delegating:
 
 ```typescript lineNumbers
 import { createHook } from "workflow";
@@ -93,14 +93,64 @@ export async function processPayment(orderId: string) {
     if (HookConflictError.is(error)) { // [!code highlight]
       // Another workflow is already processing this order
       console.log(`Conflicting token: ${error.token}`);
-      return { success: false, reason: "duplicate-processing" };
+      if (error.conflictingRunId) {
+        console.log(`Active run: ${error.conflictingRunId}`);
+      }
+      return {
+        success: false,
+        reason: "duplicate-processing",
+        token: error.token,
+        runId: error.conflictingRunId
+      };
     }
     throw error; // Re-throw other errors
   }
 }
 ```
 
-This pattern is useful when you want to detect and handle duplicate processing attempts instead of letting the workflow fail.
+This pattern is useful when you want to detect duplicate processing inside the workflow. Runtime APIs such as `resumeHook()` and `getRun()` must be called outside workflow functions, for example from an API route or in a step.
+
+### Delegate to the Active Run
+
+In idempotency flows, a conflict means another active run already owns the hook token. You can return the duplicate-processing payload from the workflow, resume the active hook to deliver the payload to the existing run, then use `getRun(result.runId)` to wait for, stream, or cancel the active run:
+
+```typescript lineNumbers
+import { getRun, resumeHook, start } from "workflow/api";
+import { processPayment } from "@/workflows/process-payment";
+
+type ProcessPaymentResult =
+  | { success: true; payment: unknown }
+  | {
+      success: false;
+      reason: "duplicate-processing";
+      token: string;
+      runId?: string;
+    };
+
+export async function POST(request: Request) {
+  const { orderId, payment } = await request.json();
+  const run = await start(processPayment, [orderId]);
+  const result = (await run.returnValue) as ProcessPaymentResult;
+
+  if (
+    result.success === false &&
+    result.reason === "duplicate-processing" &&
+    result.runId
+  ) {
+    await resumeHook(result.token, payment); // [!code highlight]
+    const activeRun = getRun(result.runId); // [!code highlight]
+
+    return Response.json({
+      delegatedToRunId: activeRun.runId,
+      result: await activeRun.returnValue
+    });
+  }
+
+  return Response.json(result);
+}
+```
+
+If the caller needs live output instead of the final result, return `activeRun.getReadable()` from the same branch. If the duplicate request should replace the active work, call `await activeRun.cancel()` after inspecting the run.
 
 ## When Hook Tokens Are Released
 
@@ -122,4 +172,6 @@ After a workflow completes, its hook tokens become available for reuse by other
 ## Related
 
 - [Hooks](/docs/foundations/hooks) - Learn more about using hooks in workflows
+- [getRun](/docs/api-reference/workflow-api/get-run) - Retrieve or control the active run
+- [resumeHook](/docs/api-reference/workflow-api/resume-hook) - Deliver data to the active hook
 - [createWebhook](/docs/api-reference/workflow/create-webhook) - Alternative for fixed webhook URLs

package/docs/foundations/index.mdx

@@ -32,4 +32,7 @@ Workflow programming can be a slight shift from how you traditionally write real
     <Card href="/docs/foundations/idempotency" title="Idempotency">
         Prevent duplicate side effects when retrying operations.
     </Card>
+    <Card href="/docs/foundations/versioning" title="Versioning">
+        Understand how runs stay pinned to deployments and when to opt in to newer code.
+    </Card>
 </Cards>

package/docs/foundations/meta.json

@@ -8,7 +8,8 @@
     "streaming",
     "cancellation",
     "serialization",
-    "idempotency"
+    "idempotency",
+    "versioning"
   ],
   "defaultOpen": true
 }

package/docs/foundations/starting-workflows.mdx

@@ -13,7 +13,7 @@ Once you've defined your workflow functions, you need to trigger them to begin e
 
 ## The `start()` Function
 
-The [`start()`](/docs/api-reference/workflow-api/start) function is used to programmatically trigger workflow executions from runtime contexts like API routes, Server Actions, or any server-side code.
+The [`start()`](/docs/api-reference/workflow-api/start) function is used to programmatically trigger workflow executions from runtime contexts like API routes, Server Actions, or any server-side code. In v5, you can also call `start()` from inside a workflow function when you want to spawn a child run or continue work in a new run.
 
 ```typescript lineNumbers
 import { start } from "workflow/api";
@@ -41,6 +41,10 @@ export async function POST(request: Request) {
 
 **Learn more**: [`start()` API Reference](/docs/api-reference/workflow-api/start)
 
+<Callout type="info">
+For parent-child workflow patterns, see [Workflow Composition](/cookbook/common-patterns/workflow-composition). For long-lived workflows that intentionally hand off to newer deployments with `deploymentId: "latest"`, see [Versioning](/docs/foundations/versioning).
+</Callout>
+
 ## The `Run` Object
 
 When you call `start()`, it returns a [`Run`](/docs/api-reference/workflow-api/start#returns) object that provides access to the workflow's status and results.

package/docs/foundations/versioning.mdx

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

package/docs/getting-started/next.mdx

@@ -75,9 +75,9 @@ To enable helpful hints in your IDE, setup the workflow plugin in `tsconfig.json
 </Accordion>
 
 <Accordion type="single" collapsible>
-  <AccordionItem value="typescript-intellisense" className="[&_h3]:my-0">
+  <AccordionItem value="configure-proxy-handler" className="[&_h3]:my-0">
     <AccordionTrigger className="text-sm">
-      ### Configure Proxy Handler (if applicable)
+      <h3 id="configure-proxy-handler">Configure Proxy Handler (if applicable)</h3>
     </AccordionTrigger>
     <AccordionContent className="[&_p]:my-2">
 
@@ -85,7 +85,9 @@ If your Next.js app has a [proxy handler](https://nextjs.org/docs/app/api-refere
 (formerly known as "middleware"), you'll need to update the matcher pattern to exclude Workflow's
 internal paths to prevent the proxy handler from running on them.
 
-Add `.well-known/workflow/*` to your middleware's exclusion list:
+If you see `[local world] Queue operation failed` with `Cannot perform ArrayBuffer.prototype.slice on a detached ArrayBuffer`, your proxy matcher is still intercepting Workflow's internal `POST /.well-known/workflow/v1/flow` request. This is especially easy to miss in Next.js 16, where `proxy.ts` replaced `middleware.ts`.
+
+Add `.well-known/workflow/*` to your matcher exclusion list:
 
 ```typescript title="proxy.ts" lineNumbers
 import { NextResponse } from "next/server";

package/docs/how-it-works/code-transform.mdx

@@ -193,7 +193,7 @@ handleUserSignup.workflowId = "workflow//workflows/user.js//handleUserSignup"; /
 - The `workflowId` property is added (same as workflow mode)
 - Step functions are not transformed in client mode
 
-**Why this transformation?** Workflow functions cannot be called directly—they must be started using [`start()`](/docs/api-reference/workflow-api/start). The error prevents accidental direct execution while the `workflowId` property allows the `start()` function to identify which workflow to launch.
+**Why this transformation?** Workflow functions cannot be called directly from application code—they must be started using [`start()`](/docs/api-reference/workflow-api/start). The error prevents accidental direct execution while the `workflowId` property allows the `start()` function to identify which workflow to launch.
 
 The IDs are generated exactly like in workflow mode to ensure they can be directly referenced at runtime.
 
@@ -321,7 +321,7 @@ The compiler generates stable IDs for workflows and steps based on file paths an
 - **Portable**: Works across different runtimes and deployments
 
 <Callout type="info">
-  Although IDs can change when files are moved or functions are renamed, Workflow SDK function assume atomic versioning in the World. This means changing IDs won't break old workflows from running, but will prevent run from being upgraded and will cause your workflow/step names to change in the observability across deployments.
+  Although IDs can change when files are moved or functions are renamed, Workflow SDK functions assume [atomic versioning](/docs/foundations/versioning) in the World. This means changing IDs won't break old workflows from running, but will prevent runs from being upgraded and will cause your workflow/step names to change in observability across deployments.
 </Callout>
 
 ## Framework Integration

package/docs/how-it-works/event-sourcing.mdx

@@ -127,7 +127,7 @@ flowchart TD
 
 Unlike other entities, hooks don't have a `status` field—the states above are conceptual. An "active" hook is one that exists in storage, while "disposed" means the hook has been deleted. When a `hook_disposed` event is created, the hook record is removed rather than updated.
 
-While a hook is active, its token is reserved and cannot be used by other workflows. If a workflow attempts to create a hook with a token that is already in use by another active hook, a `hook_conflict` event is recorded instead of `hook_created`. This causes the hook's promise to reject with a `HookConflictError`, which you can detect with `HookConflictError.is(error)`. See the [hook-conflict error](/docs/errors/hook-conflict) documentation for more details.
+While a hook is active, its token is reserved and cannot be used by other workflows. If a workflow attempts to create a hook with a token that is already in use by another active hook, a `hook_conflict` event is recorded instead of `hook_created`. Current worlds include the token and the run ID that currently owns it, though older persisted events or world implementations may only include the token. This causes the hook's promise to reject with a `HookConflictError`, which you can detect with `HookConflictError.is(error)`. See the [hook-conflict error](/docs/errors/hook-conflict) documentation for more details.
 
 When a hook is disposed (either explicitly or when its workflow completes), the token is released and can be claimed by future workflows. Hooks are automatically disposed when a workflow reaches a terminal state (`completed`, `failed`, or `cancelled`). The `hook_disposed` event is only needed for explicit disposal before workflow completion.
 
@@ -188,7 +188,7 @@ Events are categorized by the entity type they affect. Each event contains metad
 | Event | Description |
 |-------|-------------|
 | `hook_created` | Creates a new hook in `active` state. Contains the hook token and optional metadata. |
-| `hook_conflict` | Records that hook creation failed because the token is already in use by another active hook. The hook is not created, and awaiting the hook will reject with a `HookConflictError`. |
+| `hook_conflict` | Records that hook creation failed because the token is already in use by another active hook. Contains the token and, for current worlds, the active hook owner's run ID. The hook is not created, and awaiting the hook will reject with a `HookConflictError`. |
 | `hook_received` | Records that a payload was delivered to the hook. The hook remains `active` and can receive more payloads. |
 | `hook_disposed` | Deletes the hook from storage (conceptually transitioning to `disposed` state). The token is released for reuse by future workflows. |
 

package/docs/migration-guides/migrating-from-aws-step-functions.mdx

@@ -54,11 +54,11 @@ The migration replaces declarative configuration with idiomatic TypeScript and c
 | Choice state | `if` / `else` / `switch` | Native TypeScript control flow. |
 | Wait state | `sleep()` | Import `sleep` from `workflow`. |
 | Parallel state | `Promise.all()` | Standard concurrency primitives. |
-| Map state | Inline sequential → `for` loop; bounded parallel (`MaxConcurrency: N`) → batched `Promise.all` or a concurrency limiter like `p-limit`; Distributed Map / large fan-out → step-wrapped `start()` per item, then step-wrapped `getRun()` to collect. | Match the concurrency mode of the original Map. |
+| Map state | Inline sequential → `for` loop; bounded parallel (`MaxConcurrency: N`) → batched `Promise.all` or a concurrency limiter like `p-limit`; Distributed Map / large fan-out → `start()` per item, then step-wrapped `getRun()` to collect. | Match the concurrency mode of the original Map. |
 | Retry / Catch | Step retries, `RetryableError`, `FatalError` | Retry logic moves to step boundaries. |
 | `Catch` to a compensation state | `try`/`catch` in the workflow function, calling compensation steps in reverse order (push/pop a rollback stack) | See [`/docs/foundations/errors-and-retries`](/docs/foundations/errors-and-retries) for the SAGA pattern. |
 | `.waitForTaskToken` | `createHook()` or `createWebhook()` | Hooks for typed signals; webhooks for HTTP. |
-| Child state machine (`StartExecution`) | `"use step"` around `start()` / `getRun()` | Return the `Run` object, await its result from another step. |
+| Child state machine (`StartExecution`) | `start()` plus a `"use step"` wrapper around `getRun()` | Return the `Run` object, await its result from another step. |
 | Execution event history | Workflow event log | Same durable replay model. |
 | Progress via DynamoDB / SNS for client polling | `getWritable()` + named streams | Stream durable updates; clients read from the stream. |
 
@@ -213,21 +213,16 @@ return { refundId, status: 'rejected' };
 
 ## Spawn a child workflow
 
-In ASL, a parent machine calls `StartExecution` (usually via `.sync` or `.waitForTaskToken`) to launch a child. In the Workflow SDK, `start()` and `getRun()` are runtime APIs, so wrap them in `"use step"` functions. Returning the `Run` object from the spawn step lets workflow observability deep-link to the child run.
+In ASL, a parent machine calls `StartExecution` (usually via `.sync` or `.waitForTaskToken`) to launch a child. In v5, call `start()` directly from the workflow to launch a child. Wrap `getRun()` and `returnValue` access in a `"use step"` function when you need to await the child result.
 
 ### Parent starts a child
 
 ```typescript title="workflow/workflows/parent.ts"
 import { start } from 'workflow/api';
 
-async function spawnChild(item: string) {
-  'use step'; // [!code highlight]
-  return await start(childWorkflow, [item]);
-}
-
 export async function parentWorkflow(item: string) {
   'use workflow';
-  const run = await spawnChild(item);
+  const run = await start(childWorkflow, [item]); // [!code highlight]
   return { childRunId: run.runId };
 }
 ```
@@ -338,7 +333,7 @@ Delete the ASL JSON, per-task Lambda deployments, IAM roles, and callback queues
 ## Features without a 1:1 equivalent
 
 - **Express workflows.** At-least-once semantics and 5-minute duration make them a poor fit for the SDK's durable replay model. Consider keeping them on Step Functions or migrating to a queue consumer.
-- **Distributed Map state.** Up to 10,000 concurrent child executions with S3 item sources has no 1:1 analog; fan out with step-wrapped `start()` per item, then `Promise.all` with `p-limit` to bound concurrency.
+- **Distributed Map state.** Up to 10,000 concurrent child executions with S3 item sources has no 1:1 analog; fan out with `start()` per item, then `Promise.all` with `p-limit` to bound concurrency.
 - **Optimized AWS service integrations (`arn:aws:states:::dynamodb:*`, `eventbridge:*`, `bedrock:*`, `ecs:runTask.sync`, etc.).** These become regular SDK calls inside `'use step'` functions — credentials, retries, and polling move into the step.
 - **Per-state IAM roles.** ASL lets each state run under its own IAM role. In the SDK, all steps share the deployment's credentials; scope secrets and roles at deployment time.
 - **CloudWatch alarms / X-Ray cross-service traces / CloudWatch Logs retention.** The SDK event log + observability UI replaces orchestrator state transitions, not AWS-wide observability. Keep alarms and traces for other resources.
@@ -351,8 +346,8 @@ Delete the ASL JSON, per-task Lambda deployments, IAM roles, and callback queues
 - Replace Choice states with `if`/`else`/`switch`.
 - Replace Wait states with `sleep()` from `workflow`.
 - Replace Parallel states with `Promise.all()`.
-- Replace Map states based on their concurrency mode: inline sequential → `for` loop; bounded parallel (`MaxConcurrency: N`) → batched `Promise.all` or a concurrency limiter like `p-limit`; Distributed Map / large fan-out → step-wrapped `start()` per item, then step-wrapped `getRun()` to collect.
-- Replace `StartExecution` child machines with `"use step"` wrappers around `start()` and `getRun()`.
+- Replace Map states based on their concurrency mode: inline sequential → `for` loop; bounded parallel (`MaxConcurrency: N`) → batched `Promise.all` or a concurrency limiter like `p-limit`; Distributed Map / large fan-out → `start()` per item, then step-wrapped `getRun()` to collect.
+- Replace `StartExecution` child machines with direct `start()` calls and a `"use step"` wrapper around `getRun()` when collecting results.
 - Replace `.waitForTaskToken` with `createHook()` (internal callers) or `createWebhook()` (HTTP callers).
 - Move Retry/Catch to step boundaries using `maxRetries`, `RetryableError`, and `FatalError`.
 - Use `getStepMetadata().stepId` as the idempotency key for external side effects.

package/docs/migration-guides/migrating-from-inngest.mdx

@@ -51,10 +51,10 @@ Inngest's event-bus model is loosely coupled — publishers don't know consumers
 | `step.run()` | `"use step"` function | Standalone async function with Node.js access. |
 | `step.sleep()` / `step.sleepUntil()` | `sleep()` | `sleep('5m')` for a duration; `sleep(date)` for sleep-until. |
 | `step.waitForEvent()` | `createHook()` or `createWebhook()` | Hooks for typed signals, webhooks for HTTP. |
-| `step.invoke()` | `"use step"` wrappers around `start()` / `getRun()` | Spawn a child run, pass `runId` forward. |
+| `step.invoke()` | `start()` plus a `"use step"` wrapper around `getRun()` | Spawn a child run, pass `runId` forward, and collect from a step when needed. |
 | `inngest.send()` / event triggers | `start()` from your app boundary | Start workflows directly. |
 | Retry configuration (`retries`) | `RetryableError`, `FatalError`, `maxRetries` | Retry logic lives at the step level. |
-| `step.sendEvent()` | `"use step"` wrapper around `start()` | Fan out via `start()`, not an event bus. |
+| `step.sendEvent()` | `start()` from the workflow or app boundary | Fan out explicitly, not through an event bus. |
 | Realtime / `step.realtime.publish()` | `getWritable()` / `getWritable({ namespace })` | Named streams are the canonical way for clients to read workflow status. No database or `getRun()` polling required. |
 
 ## Translate your first workflow
@@ -169,20 +169,10 @@ Event matching disappears. A hook's token encodes the routing (for example, `ref
 
 ## Spawn a child workflow
 
-`step.invoke()` splits into two steps: spawn and collect. `start()` and `getRun()` are runtime APIs, so wrap them in `"use step"` functions. Return the `Run` object from the spawn step so observability can deep-link into the child run.
+`step.invoke()` splits into spawn and collect. In v5, call `start()` directly from the workflow to spawn the child. Wrap `getRun()` and `returnValue` access in a `"use step"` function when you need to collect the result. Returning the `Run` object from `start()` lets observability deep-link into the child run.
 
 You can return either the full `Run` object (enables deep-linking) or just `run.runId` (simpler).
 
-{/* @skip-typecheck: snippet without imports */}
-```typescript title="workflow/workflows/parent.ts"
-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:
-
 {/* @skip-typecheck: snippet without imports */}
 ```typescript title="workflow/workflows/parent.ts"
 async function collectResult(runId: string) {
@@ -193,7 +183,7 @@ async function collectResult(runId: string) {
 
 export async function parentWorkflow(item: string) {
   'use workflow';
-  const child = await spawnChild(item);
+  const child = await start(childWorkflow, [item]); // [!code highlight]
   return await collectResult(child.runId);
 }
 ```
@@ -266,7 +256,7 @@ See [Errors and retries](/docs/foundations/errors-and-retries) for full retry do
 
 - `step.waitForEvent(...)` → `createHook({ token })` + `await hook`. Resume it from an API route with `resumeHook(token, payload)`.
 - `step.sleep(...)` → `sleep("5m")` from `workflow`.
-- `step.invoke(child, { data })` → wrap `start(child, [data])` in a `"use step"` function that returns the `Run`, and optionally read its return value with `getRun(run.runId).returnValue`.
+- `step.invoke(child, { data })` → call `start(child, [data])` from the workflow, and optionally read its return value from a step with `getRun(run.runId).returnValue`.
 
 ### Step 5: Start runs from the app
 
@@ -301,8 +291,8 @@ Remove the `inngest` client, the `serve()` route, event schemas, and the Inngest
 - Swap `step.sleep()` / `step.sleepUntil()` for `sleep()` from `workflow`.
 - Swap `step.waitForEvent()` for `createHook()` (internal) or `createWebhook()` (HTTP).
 - Model `waitForEvent` timeouts as `Promise.race()` between the hook and `sleep()`.
-- Replace `step.invoke()` with `"use step"` wrappers around `start()` and `getRun()`.
-- Replace `step.sendEvent()` fan-out with `start()` called from a `"use step"` function.
+- Replace `step.invoke()` with direct `start()` calls and a `"use step"` wrapper around `getRun()` when collecting results.
+- Replace `step.sendEvent()` fan-out with explicit `start()` calls.
 - Remove the Inngest client, `serve()` handler, and event definitions.
 - Push retry configuration down to step boundaries via `maxRetries`, `RetryableError`, and `FatalError`.
 - Use `getStepMetadata().stepId` as the idempotency key for external side effects.

package/docs/migration-guides/migrating-from-temporal.mdx

@@ -50,7 +50,7 @@ Migration removes infrastructure and collapses indirection. Business logic stays
 | Signal | `createHook()` or `createWebhook()` | Use hooks for typed resume signals; webhooks for HTTP callbacks. |
 | Query | `getWritable({ namespace: 'status' })` stream | Durably stream status updates from the workflow. Clients read from the stream instead of polling a database. |
 | Update | `createHook()` + `resumeHook()` (one-way) | Temporal Updates return a value to the caller; hooks do not. If the Update returns data, either write the result to a named stream via `getWritable()` and have the caller read from it, or keep an HTTP read route that fetches the workflow's current state. |
-| Child Workflow | `"use step"` wrappers around `start()` / `getRun()` | Spawn from a step and return the `Run` object so observability can deep-link into child runs. |
+| Child Workflow | `start()` plus a `"use step"` wrapper around `getRun()` | Spawn a child run and return the `Run` object so observability can deep-link into child runs. |
 | Activity retry policy | Step retries, `RetryableError`, `FatalError`, `maxRetries` | Retries live at the step boundary. |
 | Event History | Workflow event log / run timeline | Same durable replay; built-in observability UI replaces Temporal Web. Search attributes and visibility APIs have no direct equivalent — filter by run status and timestamps instead. |
 
@@ -173,19 +173,14 @@ Temporal Queries expose in-memory workflow state on demand. In the Workflow SDK,
 
 ### Minimal translation
 
-`start()` and `getRun()` are runtime APIs, so wrap them in `"use step"` functions. Return the `Run` object (not a plain `runId` string) so workflow observability can deep-link into child runs.
+In v5, call `start()` directly from the workflow to spawn a child run. Wrap `getRun()` and `returnValue` access in a `"use step"` function when you need to await the child result. Return the `Run` object (not a plain `runId` string) so workflow observability can deep-link into child runs.
 
 ```typescript title="workflow/workflows/parent.ts"
 import { start } from 'workflow/api';
 
-async function spawnChild(item: string) {
-  'use step'; // [!code highlight]
-  return start(childWorkflow, [item]); // [!code highlight]
-}
-
 export async function parentWorkflow(item: string) {
   'use workflow';
-  const child = await spawnChild(item); // [!code highlight]
+  const child = await start(childWorkflow, [item]); // [!code highlight]
   return { childRunId: child.runId };
 }
 ```
@@ -204,7 +199,7 @@ async function collectResult(runId: string) {
 }
 ```
 
-Call both steps from the parent in sequence: `const result = await collectResult(child.runId)`. To fan out, call `spawnChild` inside a loop, then `Promise.all` the `collectResult` calls.
+Call `start()` and then `collectResult()` from the parent in sequence: `const result = await collectResult(child.runId)`. To fan out, call `start()` inside a loop, then `Promise.all` the `collectResult` calls.
 
 <Callout type="warn">
 Activity retry policy moves to the step boundary. Use `maxRetries`, `RetryableError`, and `FatalError` on each step instead of a single workflow-wide retry block.
@@ -308,7 +303,7 @@ Remove the Worker process, `@temporalio/*` dependencies, and the Temporal Server
 - Convert each Activity into a `"use step"` function.
 - Remove Worker and Task Queue code. Start workflows from the app with `start()`.
 - Replace Signals with `createHook()` or `createWebhook()` for HTTP callers.
-- Wrap `start()` and `getRun()` in `"use step"` functions for child workflows. Return the `Run` object from `start()` so observability can deep-link into child runs.
+- Use `start()` directly for child workflows, and wrap `getRun()` in a `"use step"` function when collecting results. Return the `Run` object from `start()` so observability can deep-link into child runs.
 - Set retry policy per step with `maxRetries`, `RetryableError`, and `FatalError`.
 - Use `getStepMetadata().stepId` as the idempotency key for external side effects.
 - Stream status and progress from steps with `getWritable({ namespace: 'status' })`, and have clients read from the stream instead of polling.

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

@@ -48,7 +48,7 @@ Migration collapses the task abstraction into plain async functions. Business lo
 | `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. |
+| `tasks.trigger()` / `triggerAndWait()` | `start()` and `getRun(runId).returnValue` | Call `start()` directly; wrap `getRun()` collection in a `"use step"` function. |
 | `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. |
@@ -180,23 +180,14 @@ A hook is an inbound write channel. The caller that knows the token resumes the
 
 ## 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.
+`triggerAndWait()` splits into spawn and collect. In v5, call `start()` directly from the workflow to spawn the child. Wrap `getRun()` and `returnValue` access in a `"use step"` function when you need to collect the result.
 
 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:
+Await the result in a step, then orchestrate both from the parent:
 
 ```typescript title="workflow/workflows/parent.ts"
-import { getRun } from 'workflow/api';
+import { getRun, start } from 'workflow/api';
 
 async function collectResult(runId: string) {
   'use step';
@@ -206,12 +197,12 @@ async function collectResult(runId: string) {
 
 export async function parentWorkflow(item: string) {
   'use workflow';
-  const child = await spawnChild(item);
+  const child = await start(childWorkflow, [item]); // [!code highlight]
   return await collectResult(child.runId);
 }
 ```
 
-To fan out, call `spawnChild` inside a loop, then `Promise.all` the `collectResult` calls. That replaces `batch.triggerAndWait()`.
+To fan out, call `start()` 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.
 
@@ -273,7 +264,7 @@ async function loadOrder(id: string) {
 - `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`.
+- `triggerAndWait(payload)` → call `start(child, [payload])` from the workflow and return the `Run` object, then read the result with a step that calls `getRun(runId).returnValue`.
 
 ### Step 5: Start runs from the app
 
@@ -324,7 +315,7 @@ Throw `new RetryableError(msg, { retryAfter: '5s' })` to control delay between a
 - 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 `triggerAndWait()` with direct `start()` calls and a `"use step"` wrapper around `getRun()` when collecting results.
 - 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`.

package/package.json

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