workflow 5.0.0-beta.15 → 5.0.0-beta.17

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

@@ -5,6 +5,7 @@ type: guide
 summary: Compose workflows two ways — direct await flattens the child into the parent's event log, while background spawn via start() runs the child as an independent run.
 related:
   - /cookbook/advanced/child-workflows
+  - /cookbook/common-patterns/idempotency
   - /docs/api-reference/workflow-api/start
   - /docs/api-reference/workflow-api/get-run
 ---
@@ -77,6 +78,10 @@ export async function processOrder(orderId: string) {
 
 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">
+Each background spawn creates a separate run. If duplicate requests must route to one active child workflow, have the child create a deterministic hook token from the business key and use that hook as the idempotency point. If concurrent starts race, the losing child can detect the conflict early with `await hook.getConflict()`, which resolves with the active owner so the child can point callers at it. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
+
 <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. 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>
@@ -109,3 +114,4 @@ If you want the child workflow to run on the latest deployment rather than the c
 - [`"use step"`](/docs/foundations/workflows-and-steps) — marks functions with full Node.js access
 - [`start()`](/docs/api-reference/workflow-api/start) — spawn a child workflow as a separate run
 - [`getRun()`](/docs/api-reference/workflow-api/get-run) — retrieve a workflow run's status and return value
+- [Idempotency](/docs/foundations/idempotency) — deduplicate step side effects and workflow starts

package/docs/cookbook/index.mdx

@@ -21,7 +21,7 @@ A curated collection of workflow patterns with clean, copy-paste code examples f
 - [**Rate Limiting**](/cookbook/common-patterns/rate-limiting) — Handle 429 responses and transient failures with RetryableError and backoff
 - [**Scheduling**](/cookbook/common-patterns/scheduling) — Use durable sleep to schedule actions minutes, hours, or weeks ahead
 - [**Timeouts**](/cookbook/common-patterns/timeouts) — Add deadlines to slow steps, hooks, and webhooks by racing them against a durable sleep
-- [**Idempotency**](/cookbook/common-patterns/idempotency) — Ensure side effects happen exactly once, even when steps retry
+- [**Idempotency**](/cookbook/common-patterns/idempotency) — Ensure side effects and duplicate starts are safe to retry
 - [**Webhooks**](/cookbook/common-patterns/webhooks) — Receive HTTP callbacks from external services and process them durably
 
 ## Integrations

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

@@ -130,6 +130,10 @@ export async function supportWorkflow(initialMessages: ModelMessage[]) {
 
 One endpoint handles first turn, follow-ups, and the `/done` exit. The client sends `runId` in the body to distinguish first vs follow-up.
 
+<Callout type="info">
+The first turn calls `start()` and then returns the `runId`. If your client or platform can retry that first request before it receives and stores the `runId`, use an atomic conversation or request key before starting the workflow. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
+
 ```typescript title="app/api/support/route.ts" lineNumbers
 import type { UIMessage, UIMessageChunk } from "ai";
 import { convertToModelMessages, createUIMessageStreamResponse } from "ai";
@@ -350,6 +354,10 @@ In `sliceUntilFinish`, use `reader.releaseLock()` in the `finally` block rather
 
 Clients can send a `runId` from a long-gone workflow (localStorage, back button, server restart). Wrap the follow-up path in a try/catch for `not found` / `expired` and fall through to the first-turn code path to start a fresh workflow.
 
+### Make the first turn idempotent when needed
+
+This example stores the `runId` after the first response. For strict one-session-per-thread behavior, use a deterministic hook token derived from the thread ID or conversation ID and route retries through the active hook. See [Idempotency](/docs/foundations/idempotency).
+
 ## streamText vs DurableAgent
 
 | | `streamText()` (this pattern) | `DurableAgent` |
@@ -376,8 +384,9 @@ Use `DurableAgent` for most agent use cases. Use `streamText` when you need the
 
 **Workflow SDK**
 
-* [`"use step"`](/docs/api-reference/workflow/use-step) — applied to `runTurn` to make each turn a durable, retryable unit
+* [`"use step"`](/docs/foundations/workflows-and-steps#step-functions) — applied to `runTurn` to make each turn a durable, retryable unit
 * [`defineHook()`](/docs/api-reference/workflow/define-hook) — suspension point for follow-up messages
 * [`getWritable()`](/docs/api-reference/workflow/get-writable) — resumable stream output
 * [`getRun()`](/docs/api-reference/workflow-api/get-run) — `run.getReadable({ startIndex })` for slicing per-turn streams
 * [`WorkflowChatTransport`](/docs/api-reference/workflow-ai/workflow-chat-transport) — passes `runId` between turns
+* [Idempotency](/docs/foundations/idempotency) — protect duplicate-sensitive first turns and side effects

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

@@ -176,6 +176,10 @@ export type ChatTurnPayload = {
 
 Handlers live outside the workflow file so adapter dependencies don't leak in. They decide whether to start a new workflow or resume an existing one, then store the `runId` in thread state:
 
+<Callout type="info">
+If the platform can deliver the same first message concurrently, use a deterministic hook token derived from the thread ID so duplicate handlers route to the active chat session hook. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
+
 ```typescript title="lib/chat-session-handlers.ts" lineNumbers
 import type { Message, Thread } from "chat";
 import { getRun, resumeHook, start } from "workflow/api";
@@ -289,6 +293,10 @@ Adapter packages (`@chat-adapter/slack`, `@chat-adapter/telegram`, etc.) depend
 
 A workflow run ends but its `runId` is still cached in thread state. The next message calls `resumeHook` on a dead run and throws `not found` / `expired`. Gate on `getRun(runId).exists` before resuming, or catch the error and fall through to `startSession`. Either way the user's message must not be dropped.
 
+### Make first-message routing atomic
+
+Thread state is also the idempotency boundary for starting sessions. Back it with a state adapter or database operation that can atomically claim the thread before `startSession()` runs when duplicate sessions would be harmful.
+
 ### Keep the hook outside the loop
 
 One `chatTurnHook.create({ token: workflowRunId })` per workflow run, reused every iteration. Creating a new hook with the same token throws `HookConflictError`. This is the same rule as the [AI SDK](/docs/cookbook/integrations/ai-sdk) and [Sandbox](/docs/cookbook/integrations/sandbox) session patterns.
@@ -305,3 +313,4 @@ Slack wants a 200 within 3 seconds. The webhook handler returns immediately afte
 - [`getRun()`](/docs/api-reference/workflow-api/get-run) — `run.exists` before resuming, to detect stale `runId`s.
 - [`defineHook()`](/docs/api-reference/workflow/define-hook) — per-turn suspension point inside the workflow.
 - [`registerSingleton()`](https://chat-sdk.dev/docs/api/chat) — makes the bot resolvable from inside step functions.
+- [Idempotency](/docs/foundations/idempotency) — protect duplicate-sensitive first messages and side effects.

package/docs/cookbook/integrations/sandbox.mdx

@@ -300,6 +300,10 @@ export async function sandboxSessionWorkflow() {
 
 Two endpoints. `/start` accepts an optional `{ runId }` — if the run still exists, it replays the event log from index 0 so a returning client fully rehydrates. `/command` resumes the hook and returns immediately; command output lands on the `/start` stream.
 
+<Callout type="info">
+This example starts a fresh sandbox session when no `runId` is provided. If your product needs one sandbox session per user, project, or task, use a deterministic hook token derived from that session key and route retries through the active hook. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
+
 ```typescript title="app/api/sandbox/start/route.ts" lineNumbers
 import { start, getRun } from "workflow/api";
 import { sandboxSessionWorkflow } from "@/workflows/sandbox-session";
@@ -505,6 +509,10 @@ Stream closure must happen inside a `"use step"` function. Calling `writable.clo
 
 Clients can hold `runId`s from long-gone workflow runs (localStorage, back button, server restart). Gate the reconnect path on `run.exists` and fall through to starting fresh. On `hook.resume`, catch `not found` / `expired` and return 410 so the client clears its state.
 
+### Decide whether `/start` should be idempotent
+
+The sample treats a missing or stale `runId` as a request for a new session. For one-session-per-resource behavior, use a durable resource key, such as `projectId` or `taskId`, to claim or retrieve the run before starting a new one.
+
 ### Keep the hook outside the loop
 
 Each iteration's `hook.then(...)` attaches a listener to the same hook instance. Creating a new hook per iteration with the same token throws `HookConflictError`. One hook, one token (`workflowRunId`), reused every iteration.
@@ -518,3 +526,4 @@ Each iteration's `hook.then(...)` attaches a listener to the same hook instance.
 - [`sleep()`](/docs/api-reference/workflow/sleep) — durable timer that powers both idle hibernation and proactive refresh
 - [`getRun()`](/docs/api-reference/workflow-api/get-run) — look up a run and replay its event log for reconnection
 - [`getWritable()`](/docs/api-reference/workflow/get-writable) — resumable NDJSON event stream
+- [Idempotency](/docs/foundations/idempotency) — choose when `/start` should reuse an existing run

package/docs/errors/step-not-registered.mdx

@@ -4,7 +4,7 @@ description: A step function is not registered in the current deployment.
 type: troubleshooting
 summary: Resolve step not registered errors caused by build issues.
 prerequisites:
-  - /docs/foundations/steps
+  - /docs/foundations/workflows-and-steps
 related:
   - /docs/errors/workflow-not-registered
   - /docs/api-reference/workflow-errors/step-not-registered-error

package/docs/foundations/cancellation.mdx

@@ -6,7 +6,6 @@ summary: Cancel in-flight work with AbortSignal or stop entire workflow runs.
 prerequisites:
   - /docs/foundations/workflows-and-steps
 related:
-  - /docs/foundations/common-patterns
   - /docs/foundations/hooks
   - /docs/how-it-works/cancellation
 ---
@@ -455,6 +454,6 @@ This is safe even if both steps have already completed — aborting a finished o
 
 - [How Cancellation Works](/docs/how-it-works/cancellation) — Hook and stream backing, serialization internals
 - [Serialization](/docs/foundations/serialization) — Understanding serializable types
-- [Common Patterns](/docs/foundations/common-patterns) — Timeout and race patterns
+- [Cookbook](/v5/cookbook) — Timeout, race, and other reliability patterns
 - [Hooks](/docs/foundations/hooks) — Pausing workflows for external events
 - [Errors and Retries](/docs/foundations/errors-and-retries) — Handling step failures

package/docs/foundations/hooks.mdx

@@ -112,7 +112,7 @@ export async function orderWorkflow(orderId: string) {
 }
 ```
 
-Calling `createHook()` on its own does not register the hook — registration is only committed when the workflow suspends. Awaiting `hook.getConflict()` suspends the workflow to commit the hook registration, then resolves with `null` once the hook is registered and ready to receive payloads, or with a `Run` handle for the run that owns the token if another active hook already claimed it (see [`HookConflictError`](/docs/errors/hook-conflict)). For `hook_conflict` events persisted by older worlds that did not record the owning run's ID, `getConflict()` rejects with `HookConflictError` instead of resolving with an incomplete handle. The conflicting run's accessors are durable steps, so the workflow can inspect `await conflict.status`, wait on `await conflict.returnValue`, or cancel the owner with `await conflict.cancel()` — see [Idempotency](/docs/foundations/idempotency) for these strategies.
+Calling `createHook()` on its own does not register the hook — registration is only committed when the workflow suspends. Awaiting `hook.getConflict()` suspends the workflow to commit the hook registration, then resolves with `null` once the hook is registered and ready to receive payloads, or with a `Run` handle for the run that owns the token if another active hook already claimed it (see [`HookConflictError`](/docs/errors/hook-conflict)). For `hook_conflict` events persisted by older worlds that did not record the owning run's ID, `getConflict()` rejects with `HookConflictError` instead of resolving with an incomplete handle. The conflicting run's accessors are durable steps, so the workflow can inspect `await conflict.status`, wait on `await conflict.returnValue`, or cancel the owner with `await conflict.cancel()` — see [Run idempotency](/docs/foundations/idempotency#run-idempotency) for these strategies.
 
 ### Custom Tokens for Deterministic Hooks
 

package/docs/foundations/idempotency.mdx

@@ -1,23 +1,27 @@
 ---
 title: Idempotency
-description: Ensure operations can be safely retried without producing duplicate side effects.
+description: Make step retries safe and coordinate duplicate workflow starts with hook tokens.
 type: conceptual
-summary: Prevent duplicate side effects when retrying operations in steps.
+summary: Use step IDs for retry-safe external calls, and route duplicate workflow-start requests through deterministic hook tokens.
 prerequisites:
   - /docs/foundations/workflows-and-steps
 related:
   - /docs/foundations/errors-and-retries
+  - /docs/foundations/starting-workflows
+  - /docs/foundations/hooks
 ---
 
-Idempotency is a property of an operation that ensures it can be safely retried without producing duplicate side effects.
+Idempotency is a property of an operation that ensures repeated attempts have the same effect as a single attempt.
+
+In Workflow, idempotency shows up in two related places: step idempotency makes external calls safe when a step retries, and run idempotency coordinates duplicate requests that try to start the same workflow.
+
+## Step Idempotency
 
 In distributed systems (calling external APIs), it is not always possible to ensure an operation has only been performed once just by seeing if it succeeds.
 Consider a payment API that charges the user $10, but due to network failures, the confirmation response is lost. When the step retries (because the previous attempt was considered a failure), it will charge the user again.
 
 To prevent this, many external APIs support idempotency keys. An idempotency key is a unique identifier for an operation that can be used to deduplicate requests.
 
-## The core pattern: use the step ID as your idempotency key
-
 Every step invocation has a stable `stepId` that stays the same across retries.
 Use it as the idempotency key when calling third-party APIs.
 
@@ -27,7 +31,7 @@ import { getStepMetadata } from "workflow";
 async function chargeUser(userId: string, amount: number) {
   "use step";
 
-  const { stepId } = getStepMetadata();
+  const { stepId } = getStepMetadata(); // [!code highlight]
 
   // Example: Stripe-style idempotency key
   // This guarantees only one charge is created even if the step retries
@@ -49,14 +53,235 @@ Why this works:
 - **Stable across retries**: `stepId` does not change between attempts.
 - **Globally unique per step**: Fulfills the uniqueness requirement for an idempotency key.
 
-## Best practices
+## Run idempotency
+
+Step idempotency protects side effects **inside** a workflow run. Run idempotency answers a different question: if the same API request is sent twice, should it create one workflow run or two?
+
+Because [hooks](/docs/foundations/hooks) already ensure globally unique active tokens, Workflow can use the same mechanism to coordinate duplicate requests while a run is active.
+
+Use a hook token as the idempotency key for an active workflow run. Hook tokens are globally unique while they are active: if another run tries to create a hook with the same token, the runtime records a conflict, `hook.getConflict()` resolves with a `Run` handle for the run that owns the token, and the hook rejects with [`HookConflictError`](/docs/errors/hook-conflict) when the workflow awaits or iterates its payload.
+
+The token should come from your domain, such as an order ID, invoice ID, import ID, or request ID. Create the hook near the beginning of the workflow and check `await hook.getConflict()` before doing duplicate-sensitive work that depends on owning the active token. Calling `createHook()` alone does not register the hook — awaiting `getConflict()` suspends the workflow to commit the registration.
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+type OrderRequest = { confirmed: boolean };
+type OrderResult =
+  | { status: "processed" | "cancelled" }
+  | { status: "duplicate"; runId: string };
+declare function chargeOrder(orderId: string): Promise<void>; // @setup
+
+export async function processOrder(orderId: string): Promise<OrderResult> {
+  "use workflow";
+
+  using request = createHook<OrderRequest>({ // [!code highlight]
+    token: `order:${orderId}`, // [!code highlight]
+  }); // [!code highlight]
+
+  const conflict = await request.getConflict(); // [!code highlight]
+  if (conflict) { // [!code highlight]
+    // Another active run already owns this order's token. // [!code highlight]
+    return { status: "duplicate" as const, runId: conflict.runId }; // [!code highlight]
+  } // [!code highlight]
+
+  const { confirmed } = await request;
+
+  if (!confirmed) {
+    return { status: "cancelled" as const };
+  }
+
+  await chargeOrder(orderId);
+  return { status: "processed" as const };
+}
+```
+
+The runtime creates the hook atomically. At most one active hook can own `order:${orderId}`, so duplicate workflow runs converge on one active owner. A duplicate run observes `getConflict()` resolving with the owner's `Run` and returns before it reaches `chargeOrder()`. The conflicting run's accessors (`status`, `returnValue`, `cancel()`, …) are durable steps, so the duplicate run can do more than report the owner — see [conflict-handling strategies](#conflict-handling-strategies) below.
+
+Outside the workflow, try to resume the hook first. If the hook is not registered yet, start the workflow and retry the resume until the new run creates the hook:
+
+```typescript lineNumbers
+import { resumeHook, start } from "workflow/api";
+import { HookNotFoundError } from "workflow/errors";
+import { processOrder } from "./workflows/process-order";
+
+type OrderRequest = { confirmed: boolean };
+
+async function resumeOrder(token: string, payload: OrderRequest) {
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
+      return await resumeHook(token, payload); // [!code highlight]
+    } catch (error) {
+      if (!HookNotFoundError.is(error)) throw error;
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+
+  throw new Error("Order workflow did not register its hook in time");
+}
+
+export async function POST(request: Request) {
+  const { orderId, confirmed } = await request.json();
+  const token = `order:${orderId}`;
+  const payload = { confirmed };
+
+  try {
+    const hook = await resumeHook(token, payload); // [!code highlight]
+    return Response.json({ runId: hook.runId, reused: true });
+  } catch (error) {
+    if (!HookNotFoundError.is(error)) throw error;
+  }
+
+  const run = await start(processOrder, [orderId]); // [!code highlight]
+  const resumed = await resumeOrder(token, payload);
+
+  // A concurrent request's run may have won the race between `start()` // [!code highlight]
+  // and hook registration. The resume always reaches the actual active // [!code highlight]
+  // owner, so compare run IDs instead of waiting for this run to finish. // [!code highlight]
+  return Response.json({ // [!code highlight]
+    runId: resumed.runId, // [!code highlight]
+    reused: resumed.runId !== run.runId, // [!code highlight]
+  }); // [!code highlight]
+}
+```
+
+<Callout type="warn">
+This avoids creating a new run only after the first run has registered its hook. Because `start()` returns before the run body executes and calls `createHook()`, two concurrent requests can both observe "no hook yet" and each call `start()`. The race is resolved inside the workflow body, where the losing run observes `getConflict()` resolving with the active owner and returns without doing duplicate-sensitive work — and the route detects it by comparing the resumed hook's `runId` against the run it just started, without waiting for either run to finish. A native API for atomically starting a run and registering a hook is in the works. Until then, model recovery inside the workflow by checking `hook.getConflict()`.
+</Callout>
+
+This is active-run coordination. When the workflow completes and disposes the hook, the token can be used again. If a duplicate request after completion must return the original result instead of starting fresh work, persist that completed result under the same domain key.
+
+### Conflict-handling strategies
+
+Some workflow systems resolve duplicate IDs with a fixed, pre-declared policy — typically a static choice between rejecting the new execution, deferring to the existing one, or terminating it. Workflow has no policy enum. `hook.getConflict()` hands the duplicate run the conflicting `Run` itself, and the policy is ordinary code — including policies that inspect state before deciding, which static configuration can't express.
+
+The example above implements **reject the duplicate**: return the owner's `runId` and let the caller decide. Other common strategies:
+
+**Adopt the owner's result.** Wait for the active run to finish and return its result, so callers cannot tell which run did the work:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+type OrderRequest = { confirmed: boolean };
+declare function processOwnedOrder(orderId: string): Promise<{ status: string }>; // @setup
+
+export async function processOrder(orderId: string) {
+  "use workflow";
+
+  using request = createHook<OrderRequest>({
+    token: `order:${orderId}`,
+  });
+
+  const conflict = await request.getConflict();
+  if (conflict) {
+    // Callers get the same result regardless of which run did the work.
+    return await conflict.returnValue; // [!code highlight]
+  }
+
+  return await processOwnedOrder(orderId);
+}
+```
+
+**Inspect the owner before deciding.** Branch on the owner's live state:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+type OrderRequest = { confirmed: boolean };
+declare function processOwnedOrder(orderId: string): Promise<{ status: string }>; // @setup
+
+export async function processOrder(orderId: string) {
+  "use workflow";
+
+  using request = createHook<OrderRequest>({
+    token: `order:${orderId}`,
+  });
+
+  const conflict = await request.getConflict();
+  if (conflict) {
+    const status = await conflict.status; // [!code highlight]
+    if (status === "running") {
+      return { status: "duplicate" as const, runId: conflict.runId };
+    }
+    // Owner already reached a terminal state; its hook will be released.
+  }
+
+  return await processOwnedOrder(orderId);
+}
+```
+
+**Signal the owner instead of doing the work.** The duplicate run knows the token, so it can deliver this run's input to the owner's hook from a step:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+import { resumeHook } from "workflow/api";
+
+type OrderRequest = { confirmed: boolean };
+
+async function forwardToOwner(token: string, payload: OrderRequest) {
+  "use step";
+  await resumeHook(token, payload); // [!code highlight]
+}
+
+export async function processOrder(orderId: string, confirmed: boolean) {
+  "use workflow";
+
+  const token = `order:${orderId}`;
+  using request = createHook<OrderRequest>({ token });
+
+  const conflict = await request.getConflict();
+  if (conflict) {
+    await forwardToOwner(token, { confirmed }); // [!code highlight]
+    return { status: "forwarded" as const, runId: conflict.runId };
+  }
+
+  // ... own the token and do the work
+}
+```
+
+**Supersede the owner.** Newest-wins: cancel the active run, then claim the released token. Cancellation disposes the owner's hooks; the retry loop covers the window where that disposal has not propagated yet:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+type OrderRequest = { confirmed: boolean };
+declare function chargeOrder(orderId: string): Promise<void>; // @setup
+
+export async function processOrderNewestWins(orderId: string) {
+  "use workflow";
+
+  const token = `order:${orderId}`;
+
+  for (let attempt = 0; attempt < 3; attempt++) {
+    using request = createHook<OrderRequest>({ token });
+
+    const conflict = await request.getConflict();
+    if (!conflict) {
+      // Token claimed — this run is now the owner.
+      const { confirmed } = await request;
+      if (confirmed) {
+        await chargeOrder(orderId);
+      }
+      return { status: "processed" as const };
+    }
+
+    await conflict.cancel(); // [!code highlight]
+  }
+
+  throw new Error(`Could not claim ${token} after cancelling the owner`);
+}
+```
+
+If duplicate requests should only reuse the active run without sending data, use [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) as an advisory pre-check before calling `start()`. The workflow should still check `hook.getConflict()`, because the lookup and `start()` are not atomic.
 
-- **Always provide idempotency keys to external side effects that are not idempotent** inside steps (payments, emails, SMS, queues).
-- **Prefer `stepId` as your key**; it is stable across retries and unique per step.
-- **Keep keys deterministic**; avoid including timestamps or attempt counters.
-- **Handle 409/conflict responses** gracefully; treat them as success if the prior attempt completed.
+Because this pattern uses hooks for idempotency, duplicate requests can also inject additional data and steer the existing run. The route example above uses `resumeHook()` for that: if the hook already exists, the duplicate request resumes the active workflow; if the hook is not registered yet, the route starts the workflow and retries `resumeHook()` so the payload is not dropped.
 
 ## Related docs
 
 - Learn about retries in [Errors & Retrying](/docs/foundations/errors-and-retries)
 - API reference: [`getStepMetadata`](/docs/api-reference/workflow/get-step-metadata)
+- API reference: [`createHook()`](/docs/api-reference/workflow/create-hook)
+- API reference: [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token)
+- API reference: [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook)
+- API reference: [`start()`](/docs/api-reference/workflow-api/start)
+- Learn about deterministic hook tokens in [Hooks](/docs/foundations/hooks)

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

@@ -295,7 +295,7 @@ Remove the Worker process, `@temporalio/*` dependencies, and the Temporal Server
 - **Event history archival.** Temporal archives histories to S3/GCS for long-term retention. Workflow SDK event logs are durable, but retention depends on the integration you are using. For example, see [Vercel Workflow Storage Retention](https://vercel.com/docs/workflows/pricing#storage-retention) for Vercel.
 - **Per-activity timeouts (`startToCloseTimeout`, `scheduleToCloseTimeout`, `heartbeatTimeout`).** Implement deadlines inside the step with `AbortSignal.timeout(ms)`, or wrap the call in `Promise.race(step(), sleep(...))` from the workflow.
 - **Rich retry policy (`initialInterval`, `backoffCoefficient`, `maximumInterval`, `nonRetryableErrorTypes`).** Only `maxRetries` is configurable. Classify retryability with `RetryableError`/`FatalError`; control delay between attempts via `new RetryableError(msg, { retryAfter: '5s' })`.
-- **Workers + task queues.** Managed deployments replace workers; self-hosted deployments still need a `World` implementation (see [/docs/deploying/world](/docs/deploying/world)).
+- **Workers + task queues.** Managed deployments replace workers; self-hosted deployments still need a `World` implementation (see [/docs/deploying/building-a-world](/docs/deploying/building-a-world)).
 
 ## Quick-start checklist
 

package/docs/observability/attributes.mdx

@@ -62,6 +62,20 @@ export async function cleanupAttributes() {
 
 Attribute keys must be 1-256 characters, values must be strings up to 256 bytes, and each run can have up to 64 attributes. Keys that start with `$` are reserved for framework and library code.
 
+## Viewing attributes
+
+The run details panel in the observability UI shows the run's current attributes as key-value rows. Reserved `$`-prefixed keys are marked with a badge and sorted after user keys:
+
+![Run details panel showing the Attributes card with reserved keys badged](/screenshots/attributes/run-details-attributes.png)
+
+Each `experimental_setAttributes` call appears on the trace timeline as a diamond marker at the moment the attributes were written:
+
+![Trace timeline with attr_set diamond markers on the run row](/screenshots/attributes/trace-timeline.png)
+
+Expanding an `attr_set` event — in the run sidebar or the Events tab — shows the changed keys, removed keys, and whether the write came from the workflow body or a step (with the attempt number):
+
+![Expanded attr_set events showing changes and the writer](/screenshots/attributes/run-details-attr-set-events.png)
+
 ## Experimental Behavior
 
 While attributes are experimental:

package/docs/observability/index.mdx

@@ -67,6 +67,9 @@ When deployed to Vercel, workflow data is [encrypted end-to-end](/docs/how-it-wo
 ## More Observability Features
 
 <Cards>
+    <Card href="/docs/observability/tracing" title="Tracing">
+        Distributed tracing with OpenTelemetry for workflow runs, steps, and queue deliveries.
+    </Card>
     <Card href="/docs/observability/attributes" title="Attributes">
         Attach experimental metadata to workflow runs for observability.
     </Card>

package/docs/observability/meta.json

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

package/docs/observability/tracing.mdx

@@ -0,0 +1,106 @@
+---
+title: Tracing
+description: Distributed tracing with OpenTelemetry for workflow runs, steps, and queue deliveries.
+type: guide
+summary: Trace workflow execution end to end with OpenTelemetry.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability
+  - /docs/observability/attributes
+  - /docs/how-it-works/event-sourcing
+---
+
+The Workflow SDK is instrumented with [OpenTelemetry](https://opentelemetry.io) out of the box. It emits spans for workflow starts, every workflow and step invocation, and the HTTP calls it makes to the workflow backend — and it propagates trace context across queue deliveries so a run remains traceable end to end.
+
+The SDK only depends on the OpenTelemetry **API**, never on an SDK or exporter. If your application does not register an OpenTelemetry SDK, all tracing code is a silent no-op with no overhead and no behavior change.
+
+## Enabling tracing
+
+Register any OpenTelemetry Node SDK in your application. On Vercel with Next.js, the simplest setup is [`@vercel/otel`](https://vercel.com/docs/observability/otel-overview) in `instrumentation.ts`:
+
+```typescript title="instrumentation.ts" lineNumbers
+import { registerOTel } from "@vercel/otel"
+
+export function register() {
+  registerOTel({ serviceName: "my-app" })
+}
+```
+
+No workflow-specific configuration is required. As soon as a tracer provider and propagator are registered, the SDK's spans, context propagation, and span links activate automatically.
+
+## Spans
+
+| Span name | Kind | Emitted when |
+| --- | --- | --- |
+| `workflow.start <name>` | internal | `start()` is called in your application code |
+| `workflow.execute <name>` | consumer (root) | a queue delivery invokes the workflow — replay, orchestration, and inline steps run under it |
+| `step.execute <name>` | internal (inline) / consumer + root (queue-delivered) | a step function executes |
+| `http <method>` | client | the SDK calls the workflow backend (event reads/writes) |
+
+`<name>` is the short function name (for example `processOrder`); the full machine name, including the source module, is available in the `workflow.name` / `step.name` attributes.
+
+## Key attributes
+
+| Attribute | Description |
+| --- | --- |
+| `workflow.run.id` | The run ID (`wrun_...`). Present on every workflow and step span — the primary key for finding all spans of a run. |
+| `workflow.name` | The workflow function name. |
+| `workflow.trace.mode` | The active trace mode (`linked` or `continuous`). |
+| `workflow.trace.propagated` | Whether the invocation received trace context from the queue message. |
+| `workflow.queue.overhead_ms` | Time between the message being enqueued and the handler starting — queue dwell plus any cold start. |
+
+## Trace shape: one trace per invocation
+
+A single workflow run can span hours or days across many separate function invocations: every step completion, `sleep()` wake-up, and retry is a new queue delivery. Stitching all of that into one trace produces giant, slow-loading traces that most tracing backends truncate.
+
+Instead, the SDK creates **one bounded trace per invocation**. Each `workflow.execute` (or background `step.execute`) span starts a new trace root and attaches two **span links**:
+
+- a link to the **enqueue site** — the span that queued the message which triggered this invocation, and
+- a link to the **run origin** — the trace in which `start()` was originally called.
+
+A span link is OpenTelemetry's relationship for "causally related, but in a different trace." It is the standard pattern for asynchronous messaging, where producing and consuming a message can be separated by arbitrary time.
+
+```mermaid
+flowchart LR
+    O["start() request trace"]
+    A["invocation 1"]
+    B["invocation 2"]
+    C["invocation 3 ..."]
+    A -. "link" .-> O
+    B -. "link" .-> O
+    C -. "link" .-> O
+    B -. "link" .-> A
+    C -. "link" .-> B
+
+    style O fill:#a78bfa,stroke:#8b5cf6,color:#000
+```
+
+Each invocation links back to the trace that enqueued it and to the run origin.
+
+To see a whole run, query by attribute rather than by trace ID — for example `workflow.run.id = wrun_...` in your tracing backend — or follow the span links between invocation traces.
+
+## Trace modes
+
+The `WORKFLOW_TRACE_MODE` environment variable controls the shape:
+
+| Mode | Behavior |
+| --- | --- |
+| `linked` (default) | Each invocation is its own trace root with span links to the enqueue site and the run origin. Traces stay small; sampling is decided per invocation. |
+| `continuous` | The run-origin context becomes the **parent** of every invocation, so the entire run shares one trace ID. |
+
+<Callout type="warn">
+This is a behavior change from v4, which always used `continuous`-style tracing. If you have dashboards or queries that assume one trace ID per run, either update them to use `workflow.run.id` and span links, or set `WORKFLOW_TRACE_MODE=continuous` to restore the previous shape. Note that in `linked` mode each invocation root makes its own sampling decision, and the number of root spans increases to one per invocation.
+</Callout>
+
+## Context propagation
+
+When tracing is enabled, the SDK propagates [W3C Trace Context](https://www.w3.org/TR/trace-context/) on its outbound calls:
+
+- **Backend requests** carry `traceparent`, `tracestate`, and `baggage` headers, so backend spans can join your trace.
+- **Queue messages** carry the run-origin trace context in the message payload, and the queue re-delivers the producer's context to the workflow handler, where it becomes the enqueue-site span link.
+- **Baggage** carries `workflow.run_id` and `workflow.name` entries during workflow execution, allowing downstream services you call from steps to tag their own telemetry with the run ID.
+
+<Callout>
+Baggage entries set by your application are propagated as a `baggage` HTTP header on the SDK's backend requests, like any other OpenTelemetry-instrumented HTTP call. Avoid placing sensitive values in baggage.
+</Callout>

package/docs/testing/index.mdx

@@ -109,7 +109,7 @@ That's it. The plugin automatically:
 
 1. Transforms `"use workflow"` and `"use step"` directives via SWC
 2. Builds workflow and step bundles before tests run
-3. Sets up an in-process workflow runtime using a fresh [Local World](/docs/worlds/local) instance in each test worker — all workflow data is cleared automatically between test files for full isolation
+3. Sets up an in-process workflow runtime using a fresh [Local World](/worlds/local) instance in each test worker — all workflow data is cleared automatically between test files for full isolation
 
 <Callout type="info">
 Use a separate Vitest configuration and a distinct file naming convention (e.g. `*.integration.test.ts`) to keep unit tests and integration tests separate. Unit tests run with a standard Vitest config without the workflow plugin, while integration tests use the config above.
@@ -117,7 +117,7 @@ Use a separate Vitest configuration and a distinct file naming convention (e.g.
 
 ### Writing Integration Tests
 
-Use [`start()`](/docs/api-reference/workflow-api/start) to trigger a workflow and [`run.returnValue`](/docs/api-reference/workflow-api/start#returnvalue) to get the result. `returnValue` is a promise that blocks until the workflow completes (or throws if it fails):
+Use [`start()`](/docs/api-reference/workflow-api/start) to trigger a workflow and [`run.returnValue`](/docs/api-reference/workflow-api/start#returns) to get the result. `returnValue` is a promise that blocks until the workflow completes (or throws if it fails):
 
 ```typescript title="workflows/calculate.integration.test.ts" lineNumbers
 import { describe, it, expect } from "vitest";