workflow 5.0.0-beta.14 → 5.0.0-beta.16

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

@@ -1,45 +1,25 @@
 ---
 title: Idempotency
-description: Ensure external side effects happen exactly once, even when steps are retried or workflows are replayed.
+description: Make step retries safe and coordinate duplicate workflow starts with hook tokens.
 type: guide
-summary: Use step IDs as idempotency keys for external APIs like Stripe so that retries and replays don't create duplicate charges.
+summary: Use step IDs for retry-safe external calls, and use deterministic hook tokens when duplicate requests must route to one active workflow.
 ---
 
-Workflow steps can be retried (on failure) and replayed (on cold start). If a step calls an external API that isn't idempotent, retries could create duplicate charges, send duplicate emails, or double-process records. Use idempotency keys to make these operations safe.
+Use idempotency when a retry or duplicate request should not repeat the underlying work. In Workflow, there are two common patterns: use the step ID for retry-safe external calls, and use hook tokens to coordinate duplicate workflow starts.
 
 ## When to use this
 
-- Charging a payment (Stripe, PayPal)
-- Sending transactional emails or SMS
-- Creating records in external systems where duplicates are harmful
-- Any step that has side effects in systems you don't control
+- A step charges a payment, sends an email, enqueues work, or creates an external record.
+- A route may receive duplicate requests that should map to one active workflow run.
 
-## Pattern: Step ID as idempotency key
+## Step idempotency
 
 Every step has a unique, deterministic `stepId` available via `getStepMetadata()`. Pass this as the idempotency key to external APIs:
 
 ```typescript
 import { getStepMetadata } from "workflow";
 
-declare function createCharge(customerId: string, amount: number): Promise<{ id: string }>; // @setup
-declare function sendReceipt(customerId: string, chargeId: string): Promise<void>; // @setup
-
-export async function chargeCustomer(customerId: string, amount: number) {
-  "use workflow";
-
-  const charge = await createCharge(customerId, amount);
-  await sendReceipt(customerId, charge.id);
-
-  return { customerId, chargeId: charge.id, status: "completed" };
-}
-```
-
-### Step function with idempotency key
-
-```typescript
-import { getStepMetadata } from "workflow";
-
-async function createCharge(
+export async function createCharge(
   customerId: string,
   amount: number
 ): Promise<{ id: string }> {
@@ -69,39 +49,43 @@ async function createCharge(
 
   return charge.json();
 }
-
-async function sendReceipt(customerId: string, chargeId: string): Promise<void> {
-  "use step";
-
-  const { stepId } = getStepMetadata();
-
-  await fetch("https://api.example.com/receipts", {
-    method: "POST",
-    headers: { "Idempotency-Key": stepId },
-    body: JSON.stringify({ customerId, chargeId }),
-  });
-}
 ```
 
-## Race condition caveats
+See [Step Idempotency](/docs/foundations/idempotency#step-idempotency) for why `stepId` is stable across retries and how to think about external API conflicts.
 
-Workflow does not currently provide distributed locking or true exactly-once delivery across concurrent runs. If two workflow runs could process the same entity concurrently:
+## Run idempotency
 
-- **Rely on the external API's idempotency** (like Stripe's `Idempotency-Key`) rather than checking a local flag.
-- **Don't use check-then-act patterns** like "read a flag, then write if not set" -- another run could read the same flag between your read and write.
+For duplicate workflow-start requests, derive a hook token from your domain key. You can avoid obvious duplicate starts by checking whether an active hook already owns that token before calling `start()`:
 
-If your external API doesn't support idempotency keys natively, consider adding a deduplication layer (e.g., a database unique constraint on the operation ID).
+```typescript
+import { getHookByToken, start } from "workflow/api";
+import { HookNotFoundError } from "workflow/errors";
+import { processOrder } from "./workflows/process-order";
+
+export async function POST(request: Request) {
+  const { orderId } = await request.json();
+  const token = `order:${orderId}`;
+
+  try {
+    const hook = await getHookByToken(token); // [!code highlight]
+    return Response.json({ runId: hook.runId, reused: true });
+  } catch (error) {
+    if (!HookNotFoundError.is(error)) throw error;
+  }
 
-## Tips
+  const run = await start(processOrder, [orderId]); // [!code highlight]
+  return Response.json({ runId: run.runId, reused: false });
+}
+```
 
-- **`stepId` is deterministic.** It's the same value across retries and replays of the same step, making it a reliable idempotency key.
-- **Always provide idempotency keys for non-idempotent external calls.** Even if you think a step won't be retried, cold-start replay will re-execute it.
-- **Handle 409/conflict as success.** If an external API returns "already processed," treat that as a successful result, not an error.
-- **Make your own APIs idempotent** where possible. Accept an idempotency key and return the cached result on duplicate requests.
+The workflow should create the deterministic hook and check `await hook.getConflict()` before duplicate-sensitive work — awaiting `getConflict()` suspends the workflow to commit the hook registration and resolves with the conflicting run when another active run already owns the token (or `null` once the hook is registered). See [Run idempotency](/docs/foundations/idempotency#run-idempotency) for the full pattern, including how to steer an active run with `resumeHook()` and how to handle the current race between `start()` and hook registration.
 
 ## Key APIs
 
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) -- declares the orchestrator function
-- [`"use step"`](/docs/api-reference/workflow/use-step) -- declares step functions with full Node.js access
-- [`getStepMetadata()`](/docs/api-reference/step/get-step-metadata) -- provides the deterministic `stepId` for idempotency keys
+- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions) -- declares the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions) -- declares step functions with full Node.js access
+- [`getStepMetadata()`](/docs/api-reference/workflow/get-step-metadata) -- provides the deterministic `stepId` for idempotency keys
+- [`createHook()`](/docs/api-reference/workflow/create-hook) -- creates a hook with an optional deterministic token
+- [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) -- finds the active hook for a token
+- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) -- resumes the active hook when the duplicate request carries data
 - [`start()`](/docs/api-reference/workflow-api/start) -- starts a new workflow run

package/docs/cookbook/common-patterns/rate-limiting.mdx

@@ -224,5 +224,5 @@ export async function downloadWithRetry(url: string) {
 - [`"use step"`](/docs/foundations/workflows-and-steps) -- marks functions that run with full Node.js access
 - [`RetryableError`](/docs/api-reference/workflow/retryable-error) -- signals the runtime to retry after a delay
 - [`FatalError`](/docs/api-reference/workflow/fatal-error) -- signals a permanent failure, skipping retries
-- [`getStepMetadata()`](/docs/api-reference/step/get-step-metadata) -- provides the current attempt number and step ID
+- [`getStepMetadata()`](/docs/api-reference/workflow/get-step-metadata) -- provides the current attempt number and step ID
 - [`sleep()`](/docs/api-reference/workflow/sleep) -- durable pause for circuit breaker cooldowns

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

@@ -241,7 +241,7 @@ export async function subscriptionUpgradeSaga(accountId: string, seats: number)
 
 ## Key APIs
 
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) -- declares the orchestrator function
-- [`"use step"`](/docs/api-reference/workflow/use-step) -- declares step functions with full Node.js access
+- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions) -- declares the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions) -- declares step functions with full Node.js access
 - [`FatalError`](/docs/api-reference/workflow/fatal-error) -- non-retryable error that triggers compensation
 - [`getWritable()`](/docs/api-reference/workflow/get-writable) -- streams data from workflows for real-time UI updates

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

@@ -106,6 +106,10 @@ export async function POST(req: Request) {
 3. **Race** — `Promise.race([sleep(...), hook])` blocks until either the timer fires or the hook is resumed, whichever comes first.
 4. **Fresh hooks per window** — after a sleep completes normally, the previous hook instance is consumed. A new `.create()` call registers a fresh hook for the next sleep window, reusing the same token.
 
+<Callout type="info">
+Deterministic hook tokens can also serve as the idempotency point for scheduled runs. If duplicate schedule starts would send duplicate campaigns or reminders, create a hook with a token derived from the campaign key near the beginning of the workflow and route retries through that hook. If two scheduled starts race, the duplicate run can detect the conflict early with `await hook.getConflict()`, which resolves with the active owner so the duplicate can defer to it. See [Idempotency](/docs/foundations/idempotency).
+</Callout>
+
 ## Adapting to your use case
 
 - **Change durations** — replace `"2d"` with any duration string (`"1h"`, `"7d"`, `"30m"`) or a `Date` object for absolute times.

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

@@ -80,7 +80,7 @@ export async function waitForApproval(requestId: string) {
 4. **Throw to fail the workflow** — inside a workflow function, throwing an `Error` exits the run with that error. Use `FatalError` inside steps; throw plain errors inside workflows.
 
 <Callout type="warn">
-**The losing operation keeps running.** `Promise.race` doesn't cancel — when the sleep wins, the underlying step (or model call, or HTTP request) continues to completion in the background. This is fine for idempotent reads but matters when the operation has side effects or costs money. Pass an `AbortSignal` into the step to cancel it cooperatively — see the [Cancellation Guide](/docs/foundations/cancellation) for patterns.
+**The losing operation keeps running.** `Promise.race` doesn't cancel — when the sleep wins, the underlying step (or model call, or HTTP request) continues to completion in the background. This is fine for idempotent reads but matters when the operation has side effects or costs money. Pass an `AbortSignal` into the step to cancel it cooperatively, and use idempotency keys for non-idempotent side effects. See the [Cancellation Guide](/docs/foundations/cancellation) and [Idempotency](/docs/foundations/idempotency) for patterns.
 </Callout>
 
 ## Adapting to your use case
@@ -96,4 +96,5 @@ export async function waitForApproval(requestId: string) {
 - [`sleep()`](/docs/api-reference/workflow/sleep) — durable wait (survives restarts, zero compute cost)
 - [`createWebhook()`](/docs/api-reference/workflow/create-webhook) — create a webhook URL the workflow can race against
 - [`defineHook()`](/docs/api-reference/workflow/define-hook) — typed hook for in-process cancellation
+- [Idempotency](/docs/foundations/idempotency) — protect side effects that may keep running after a timeout
 - [`Promise.race()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race) — race operations against deadlines

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

@@ -85,6 +85,35 @@ The key points:
 - You need the hook's `token` to resume it
 - The workflow will resume execution right where it left off
 
+### Checking for Token Conflicts
+
+Sometimes you need to know that a hook token has been claimed, but you do not want to wait for external data yet. Await `hook.getConflict()` for that:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+declare function processOrder(orderId: string): Promise<void>; // @setup
+
+export async function orderWorkflow(orderId: string) {
+  "use workflow";
+
+  using hook = createHook({
+    token: `order:${orderId}`
+  });
+
+  const conflict = await hook.getConflict(); // [!code highlight]
+  if (conflict) { // [!code highlight]
+    // Another active run already owns this token.
+    return { dedupedTo: conflict.runId };
+  }
+
+  // The hook token is registered and reserved here.
+  await processOrder(orderId);
+}
+```
+
+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
 
 By default, hooks generate a random token. However, you often want to use a **custom token** that external systems can reconstruct. This is especially useful for long-running workflows where the same workflow instance should handle multiple events.