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

package/docs/api-reference/vitest/index.mdx

@@ -69,7 +69,7 @@ export async function setup() {
 
 ### `setupWorkflowTests()`
 
-Sets up an in-process workflow runtime in each test worker. Imports pre-built bundles, creates a [Local World](/docs/worlds/local) instance with direct handlers, and sets it as the global world. Clears all workflow data on each invocation for full test isolation.
+Sets up an in-process workflow runtime in each test worker. Imports pre-built bundles, creates a [Local World](/worlds/local) instance with direct handlers, and sets it as the global world. Clears all workflow data on each invocation for full test isolation.
 
 Called automatically by the `workflow()` plugin in `setupFiles`. Use directly only for [manual setup](/docs/testing#manual-setup).
 

package/docs/api-reference/workflow/create-hook.mdx

@@ -8,6 +8,7 @@ prerequisites:
 related:
   - /docs/api-reference/workflow/define-hook
   - /docs/api-reference/workflow/create-webhook
+  - /docs/foundations/idempotency
 ---
 
 Creates a low-level hook primitive that can be used to resume a workflow run with arbitrary payloads.
@@ -142,7 +143,11 @@ async function processOrder(orderId: string) {
 
 Because `createHook()` alone does not suspend the workflow, awaiting `hook.getConflict()` is what actually suspends the run and commits the hook registration. It only waits for registration — to receive payload data from a future `resumeHook()` call, await the hook itself or iterate it with `for await...of`.
 
-On a conflict, the resolved value is a `Run` handle for the run that currently owns the token, with durable step-backed accessors. The duplicate run can decide in code how to handle it: return or log `conflict.runId`, inspect `await conflict.status`, wait on `await conflict.returnValue`, or cancel the owner with `await conflict.cancel()` and continue in the current run. See [Idempotency](/docs/foundations/idempotency) for these strategies in context.
+On a conflict, the resolved value is a `Run` handle for the run that currently owns the token, with durable step-backed accessors. The duplicate run can decide in code how to handle it: return or log `conflict.runId`, inspect `await conflict.status`, wait on `await conflict.returnValue`, or cancel the owner with `await conflict.cancel()` and continue in the current run. See [Run idempotency](/docs/foundations/idempotency#run-idempotency) for these strategies in context.
+
+<Callout type="info">
+Custom hook tokens are the recommended way to coordinate active workflow runs. Use a deterministic token from your domain, such as an order ID or conversation ID, create the hook near the beginning of the workflow, and check `await hook.getConflict()` before work that depends on owning the token. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
 
 ### Waiting for Multiple Payloads
 
@@ -227,3 +232,4 @@ This is equivalent to manually calling `dispose()` but ensures the hook is alway
 - [`defineHook()`](/docs/api-reference/workflow/define-hook) - Type-safe hook helper
 - [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) - Resume a hook with a payload
 - [`createWebhook()`](/docs/api-reference/workflow/create-webhook) - Higher-level HTTP webhook abstraction
+- [Idempotency](/docs/foundations/idempotency) - Deduplicate step side effects and workflow starts

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

@@ -7,12 +7,17 @@ prerequisites:
   - /docs/foundations/workflows-and-steps
 related:
   - /docs/errors/fetch-in-workflow
+  - /docs/foundations/idempotency
 ---
 
 Makes HTTP requests from within a workflow. This is a special step function that wraps the standard `fetch` API, automatically handling serialization and providing retry semantics.
 
 This is useful when you need to call external APIs or services from within your workflow.
 
+<Callout type="warn">
+Because workflow `fetch()` has retry semantics, use idempotency keys when the request mutates an external system, such as creating a charge, sending an email, or enqueueing work. See [Idempotency](/docs/foundations/idempotency).
+</Callout>
+
 <Callout>
 `fetch` is a *special* type of step function provided and should be called directly inside workflow functions.
 </Callout>

package/docs/api-reference/workflow-api/get-hook-by-token.mdx

@@ -5,6 +5,8 @@ type: reference
 summary: Use getHookByToken to look up a hook's metadata and associated workflow run before resuming it.
 prerequisites:
   - /docs/foundations/hooks
+related:
+  - /docs/foundations/idempotency
 ---
 
 Retrieves a hook by its unique token, returning the associated workflow run information and any metadata that was set when the hook was created. This function is useful for inspecting hook details before deciding whether to resume a workflow.
@@ -13,6 +15,10 @@ Retrieves a hook by its unique token, returning the associated workflow run info
 `getHookByToken` is a runtime function that must be called from outside a workflow function.
 </Callout>
 
+<Callout type="info">
+Looking up a deterministic hook token is useful in hook-based idempotency flows, but it is only an advisory check. If no hook exists yet, another request can still start the same workflow before your `start()` call registers its hook. Use the lookup to avoid obvious duplicate starts, and handle the race inside the workflow by checking `await hook.getConflict()` before duplicate-sensitive work — on a conflict it resolves with the run that owns the token, so the duplicate can route the caller to the active owner. If duplicates must be rejected before a workflow body runs, keep a durable request record until native atomic start-and-hook registration exists. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
+
 ```typescript lineNumbers
 import { getHookByToken } from "workflow/api";
 
@@ -178,3 +184,4 @@ export async function POST(request: Request) {
 - [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) - Resume a hook with a payload.
 - [`createHook()`](/docs/api-reference/workflow/create-hook) - Create a hook in a workflow.
 - [`defineHook()`](/docs/api-reference/workflow/define-hook) - Type-safe hook helper.
+- [Idempotency](/docs/foundations/idempotency) - Deduplicate step side effects and workflow starts.

package/docs/api-reference/workflow-api/get-run.mdx

@@ -5,12 +5,18 @@ type: reference
 summary: Use getRun to check a workflow run's status and metadata without blocking on completion.
 prerequisites:
   - /docs/foundations/starting-workflows
+related:
+  - /docs/foundations/idempotency
 ---
 
 Retrieves the workflow run metadata and status information for a given run ID. This function provides immediate access to workflow run details without waiting for completion, making it ideal for status checking and monitoring.
 
 Use this function when you need to check workflow status, get timing information, or access workflow metadata without blocking on workflow completion.
 
+<Callout type="info">
+`getRun()` retrieves a run when you already have its `runId`. It does not look up runs by a business key. For retried requests that should route to one active workflow, use a deterministic hook token and [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token). After a hook conflict, `HookConflictError.conflictingRunId` can be passed to `getRun()` to inspect, stream, or return the active owner. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
+
 ```typescript lineNumbers
 import { getRun } from "workflow/api";
 

package/docs/api-reference/workflow-api/resume-hook.mdx

@@ -7,6 +7,7 @@ prerequisites:
   - /docs/foundations/hooks
 related:
   - /docs/api-reference/workflow-api/resume-webhook
+  - /docs/foundations/idempotency
 ---
 
 Resumes a workflow run by sending a payload to a hook identified by its token.
@@ -155,8 +156,64 @@ export async function POST(request: Request) {
 }
 ```
 
+### Resume or Start
+
+A common endpoint shape is "resume or start": one route that resumes the active workflow run for a business key if one exists, or starts a new run otherwise. This comes up when the workflow uses a deterministic hook token as its idempotency key — for example, one active run per order or conversation.
+
+`resumeHook()` is the resume half of that flow. Try it first; if it throws `HookNotFoundError`, no active run owns the token yet, so start the workflow. One subtlety: `start()` returns before the new run executes and registers its hook, so you cannot resume immediately after starting. Retry the resume until the hook is registered — if you drop the payload and only start the workflow, the data from this request is lost.
+
+```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 resumeWithRetry(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("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 {
+    // An active run already owns this token: resume it.
+    const hook = await resumeHook(token, payload); // [!code highlight]
+    return Response.json({ runId: hook.runId, reused: true });
+  } catch (error) {
+    if (!HookNotFoundError.is(error)) throw error;
+  }
+
+  // No hook yet: start a new run, then retry the resume so this
+  // request's payload still reaches the workflow.
+  const run = await start(processOrder, [orderId]); // [!code highlight]
+  const resumed = await resumeWithRetry(token, payload);
+
+  // A concurrent request can win the race between `start()` and hook
+  // registration; the resume always reaches the actual active owner.
+  return Response.json({
+    runId: resumed.runId,
+    reused: resumed.runId !== run.runId,
+  });
+}
+```
+
+See [Run idempotency](/docs/foundations/idempotency#run-idempotency) for the full pattern, including how the workflow claims the token with `hook.getConflict()` and how concurrent starts converge on one active owner.
+
 ## Related Functions
 
 - [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) - Get hook details before resuming.
 - [`createHook()`](/docs/api-reference/workflow/create-hook) - Create a hook in a workflow.
 - [`defineHook()`](/docs/api-reference/workflow/define-hook) - Type-safe hook helper.
+- [Idempotency](/docs/foundations/idempotency) - Deduplicate step side effects and workflow starts.

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

@@ -5,6 +5,8 @@ type: reference
 summary: Use start to programmatically enqueue a new workflow run.
 prerequisites:
   - /docs/foundations/starting-workflows
+related:
+  - /docs/foundations/idempotency
 ---
 
 Start/enqueue a new workflow run.
@@ -54,9 +56,10 @@ Learn more about [`WorkflowReadableStreamOptions`](/docs/api-reference/workflow-
 * 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.
+* Each call to `start()` creates a new workflow run. If retried requests must route to one active workflow, have the workflow create a deterministic hook token and use [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) to reuse an already-registered active hook. The lookup is not atomic with `start()`, so concurrent callers can still create extra runs before the hook is registered; handle that race inside the workflow by checking `await hook.getConflict()` before duplicate-sensitive work — on a conflict it resolves with the run that owns the token, so the duplicate can return the active owner to the caller. If duplicates must be rejected before a workflow body runs, keep a durable request record until native atomic start-and-hook registration exists. See [Idempotency](/docs/foundations/idempotency#run-idempotency).
 * All arguments must be [serializable](/docs/foundations/serialization).
 * When `deploymentId` is provided, the argument types and return type become `unknown` since there is no guarantee the workflow function's types will be consistent across different deployments.
-* `attributes` seeds plaintext run metadata as part of creation and requires a World implementing spec version 4 or later.
+* `attributes` seeds plaintext run metadata as part of creation and requires a World implementing spec version 4 or later. Keys that start with `$` are reserved for framework and library code; framework-level callers can pass `allowReservedAttributes: true` to seed reserved keys, with the same semantics as the [`experimental_setAttributes`](/docs/api-reference/workflow/experimental-set-attributes) option of the same name.
 
 <Callout type="info">
 If `start()` throws `'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.`, the passed function was not transformed as a workflow. The two most common causes are a missing `"use workflow"` directive or missing framework integration. See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function).

package/docs/api-reference/workflow-errors/index.mdx

@@ -0,0 +1,85 @@
+---
+title: "workflow/errors"
+description: Semantic error types thrown by the Workflow SDK and its storage backends.
+type: overview
+summary: Explore the error classes exported from workflow/errors for handling workflow failures.
+related:
+  - /docs/foundations/errors-and-retries
+---
+
+API reference for the error classes exported from the `workflow/errors` package.
+
+All errors extend [`WorkflowError`](/docs/api-reference/workflow-errors/workflow-error), so you can catch any SDK error with a single `instanceof` check, or narrow to a specific class for fine-grained handling.
+
+## Base Classes
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-errors/workflow-error" title="WorkflowError">
+        Base class for all workflow error types.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/workflow-world-error" title="WorkflowWorldError">
+        Base error for failures from workflow storage backends.
+    </Card>
+</Cards>
+
+## Registration Errors
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-errors/workflow-not-registered-error" title="WorkflowNotRegisteredError">
+        Thrown when a workflow function is not registered in the current deployment.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/step-not-registered-error" title="StepNotRegisteredError">
+        Thrown when a step function is not registered in the current deployment.
+    </Card>
+</Cards>
+
+## Run Errors
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-errors/workflow-run-not-found-error" title="WorkflowRunNotFoundError">
+        Thrown when operating on a workflow run that does not exist.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/workflow-run-failed-error" title="WorkflowRunFailedError">
+        Thrown when awaiting the return value of a failed workflow run.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/workflow-run-cancelled-error" title="WorkflowRunCancelledError">
+        Thrown when awaiting the return value of a cancelled workflow run.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/workflow-run-not-completed-error" title="WorkflowRunNotCompletedError">
+        Thrown when requesting the result of a workflow run that has not completed yet.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/workflow-runtime-error" title="WorkflowRuntimeError">
+        Thrown when the workflow runtime encounters an execution error, such as serialization failures or timeouts.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/run-expired-error" title="RunExpiredError">
+        Thrown when a workflow run has expired and can no longer be operated on.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/run-not-supported-error" title="RunNotSupportedError">
+        Thrown when a workflow run requires a newer workflow spec version than the installed SDK supports.
+    </Card>
+</Cards>
+
+## Hook Errors
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-errors/hook-not-found-error" title="HookNotFoundError">
+        Thrown when resuming a hook that does not exist.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/hook-conflict-error" title="HookConflictError">
+        Thrown when creating a hook with a token that is already in use by another workflow run.
+    </Card>
+</Cards>
+
+## Backend Errors
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-errors/throttle-error" title="ThrottleError">
+        Thrown when a request is rate-limited by the workflow backend.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/entity-conflict-error" title="EntityConflictError">
+        Thrown when a storage operation conflicts with the current entity state.
+    </Card>
+    <Card href="/docs/api-reference/workflow-errors/too-early-error" title="TooEarlyError">
+        Thrown when a request is made before the system is ready to process it.
+    </Card>
+</Cards>

package/docs/api-reference/workflow-next/with-workflow.mdx

@@ -31,8 +31,8 @@ export default withWorkflow(nextConfig, workflowConfig); // [!code highlight]
 If a package in `serverExternalPackages` contains workflow code (`"use step"`,
 `"use workflow"`, or serialization classes), `withWorkflow()` automatically
 removes it from `serverExternalPackages` for the current build and prints a
-warning. This ensures the package still gets transformed by the Workflow
-compiler. Remove that package from `serverExternalPackages` in your
+warning. Workflow still compiles the package so its directives are transformed.
+Remove that package from `serverExternalPackages` in your
 `next.config` to silence the warning.
 </Callout>
 

package/docs/api-reference/workflow-runtime/world/storage.mdx

@@ -259,6 +259,12 @@ const hook = await world.hooks.get(hookId); // [!code highlight]
 
 Look up a hook by its token. Useful in webhook resume flows where you receive a token in the callback URL.
 
+<Callout type="info">
+For runtime application code, prefer [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token). Use `world.hooks.getByToken()` when you are working directly with the World storage interface for custom tooling, admin views, or low-level integrations.
+
+Hook-token lookup is the low-level form of the recommended idempotency flow: if a hook is already registered for your business key, reuse the hook's `runId` or resume that hook instead of starting another run. If no hook exists yet, start a workflow that creates the deterministic hook near the beginning and checks `await hook.getConflict()` to detect whether another run claimed the token first — on a conflict it resolves with the run that owns the token. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
+
 ```typescript lineNumbers
 const hook = await world.hooks.getByToken(token); // [!code highlight]
 ```

package/docs/changelog/index.mdx

@@ -13,4 +13,4 @@ Stay up to date with the latest changes to Workflow SDK.
 ## 2026
 
 - [Eager processing of steps and incremental event replay](/docs/changelog/eager-processing) - March 2026
-- [Serializable AbortController and AbortSignal](/docs/changelog/serializable-abort-controller) — March 12, 2026
+- Serializable AbortController and AbortSignal — March 12, 2026

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

@@ -3,6 +3,8 @@ title: Child Workflows
 description: Spawn child workflows from a parent and wait for completion via hook resume.
 type: guide
 summary: Orchestrate independent child workflows from a parent using start(), defineHook(), and startAndWait() — the child resumes the parent's hook when done instead of polling getRun().status.
+related:
+  - /docs/api-reference/workflow-api/start
 ---
 
 Use child workflows when a single workflow needs to orchestrate many independent units of work. Each child runs as its own workflow with a separate event log, retry boundary, and failure scope -- if one child fails, it doesn't take down the parent or siblings.
@@ -145,7 +147,7 @@ Polling with `getRun().status` in a `sleep()` loop works, but hook resume is pre
 - **Zero compute while waiting** — the parent suspends on the hook instead of waking every poll interval
 - **Immediate wake-up** — the parent resumes as soon as the child finishes, not on the next poll tick
 - **Typed payloads** — the child sends `{ status, value | error }` directly; no separate `returnValue` fetch step
-- **No worker-pool pressure** — `Run#returnValue` polling inside steps can hold worker slots while waiting for children (see [Eager Processing](/changelog/eager-processing))
+- **No worker-pool pressure** — `Run#returnValue` polling inside steps can hold worker slots while waiting for children (see [Eager Processing](/docs/changelog/eager-processing))
 
 When a parent calls a child workflow inline with `await` (flattened into the same run), the same wrapper and hook handshake still works — pass the token and `await processDocumentWithCompletion(...)` inside `startAndWait()` instead of calling `start()`.
 

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

@@ -270,14 +270,14 @@ Declare `workflow` as an **optional** peer so consumers without the runtime aren
 
 ### Runtime detection
 
-Wrap a dynamic `import("workflow")` in try/catch. If either the module isn't installed *or* `getWorkflowMetadata()` throws (call site isn't inside a workflow run), fall through to the standalone path.
+Wrap a dynamic `import("workflow")` in try/catch. If either the module isn't installed *or* `getStepMetadata()` throws (call site isn't inside a workflow step), fall through to the standalone path.
 
 ```typescript lineNumbers
-async function getWorkflowRunId(): Promise<string | null> { // [!code highlight]
+async function getWorkflowStepId(): Promise<string | null> { // [!code highlight]
   try {
     const wf = await import("workflow");
-    const { workflowRunId } = wf.getWorkflowMetadata();
-    return workflowRunId;
+    const { stepId } = wf.getStepMetadata();
+    return stepId;
   } catch {
     return null;
   }
@@ -286,13 +286,14 @@ async function getWorkflowRunId(): Promise<string | null> { // [!code highlight]
 
 ### A concrete use case: replay-safe idempotency keys
 
-A payments utility that uses the workflow run ID as a Stripe idempotency key when available, and a fresh UUID otherwise:
+A payments utility that uses the current workflow step ID as a Stripe idempotency key when available, and a fresh UUID otherwise:
 
-{/* @skip-typecheck - depends on getWorkflowRunId defined in the previous block */}
 ```typescript lineNumbers
+declare function getWorkflowStepId(): Promise<string | null>; // @setup (defined in the previous block)
+
 export async function processPayment(amount: number, currency: string) {
-  const runId = await getWorkflowRunId();
-  const idempotencyKey = runId ?? crypto.randomUUID(); // [!code highlight]
+  const stepId = await getWorkflowStepId();
+  const idempotencyKey = stepId ? `payment:${stepId}` : crypto.randomUUID(); // [!code highlight]
 
   const res = await fetch("https://api.stripe.com/v1/charges", {
     method: "POST",
@@ -306,7 +307,7 @@ export async function processPayment(amount: number, currency: string) {
 }
 ```
 
-When called from inside a workflow run, the step wrapping this utility gets a stable idempotency key across replays — Stripe dedupes retries for free. When called from a plain Node.js process, it behaves like any other function and a fresh UUID is generated.
+When called from inside a workflow step, the utility gets a stable idempotency key for that step across retries — Stripe dedupes retries for free. When called from a plain Node.js process, it behaves like any other function and a fresh UUID is generated. For more patterns, see [Idempotency](/docs/foundations/idempotency).
 
 ### In production
 
@@ -330,7 +331,7 @@ Before publishing a workflow library:
 
 ## Key APIs
 
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
-- [`"use step"`](/docs/api-reference/workflow/use-step) — marks functions for durable execution
-- [`start`](/docs/api-reference/workflow/start) — starts a workflow run
+- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions) — declares the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions) — marks functions for durable execution
+- [`start`](/docs/api-reference/workflow-api/start) — starts a workflow run
 - [`getWorkflowMetadata`](/docs/api-reference/workflow/get-workflow-metadata) — runtime detection and run ID access

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

@@ -6,7 +6,7 @@ summary: Return a callback from a step to defer construction of a non-owned clas
 related:
   - /docs/foundations/serialization
   - /docs/foundations/serialization#custom-class-serialization
-  - /docs/api-reference/workflow/use-step
+  - /docs/foundations/workflows-and-steps#step-functions
 ---
 
 <Callout>
@@ -141,7 +141,7 @@ async function uploadFile(
 
 ## Key APIs
 
-- [`"use step"`](/docs/api-reference/workflow/use-step) — marks a function for extraction and serialization
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions) — marks a function for extraction and serialization
+- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions) — declares the orchestrator function
 - [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — accepts a model factory for durable AI agent streaming
 - [Custom class serialization](/docs/foundations/serialization#custom-class-serialization) — the companion pattern for classes you own (`WORKFLOW_SERIALIZE` / `WORKFLOW_DESERIALIZE`)

package/docs/cookbook/agent-patterns/human-in-the-loop.mdx

@@ -247,8 +247,8 @@ const approvalResult = messages
 
 ## 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 retries
+- [`"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 retries
 - [`defineHook()`](/docs/api-reference/workflow/define-hook) — type-safe hook with schema validation
 - [`sleep()`](/docs/api-reference/workflow/sleep) — durable timeout for approval expiry
 - [`getWritable()`](/docs/api-reference/workflow/get-writable) — stream custom data parts from steps

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