workflow 5.0.0-beta.8 → 5.0.0

package/docs/foundations/hooks.mdx

@@ -11,9 +11,9 @@ related:
   - /docs/ai/human-in-the-loop
 ---
 
-Hooks provide a powerful mechanism for pausing workflow execution and resuming it later with external data. They enable workflows to wait for external events, user interactions (also known as "human in the loop"), or HTTP requests. This guide will teach you the core concepts, starting with the low-level Hook primitive and building up to the higher-level Webhook abstraction.
+Hooks pause workflow execution and resume it later with external data. Workflows can wait for external events, user interactions (also known as "human in the loop"), or HTTP requests.
 
-## Understanding Hooks
+## Understanding hooks
 
 At their core, **Hooks** are a low-level primitive that allows you to pause a workflow and resume it later with arbitrary [serializable data](/docs/foundations/serialization). Think of them as suspension points in your workflow where you're waiting for external input.
 
@@ -23,9 +23,9 @@ When you create a hook, it generates a unique token that external systems can us
 - Receiving data from an external system or service
 - Implementing event-driven workflows that react to multiple events over time
 
-### Creating Your First Hook
+### Creating your first hook
 
-Let's start with a simple example. Here's a workflow that creates a hook and waits for external data:
+This workflow creates a hook and waits for external data:
 
 ```typescript lineNumbers
 import { createHook } from "workflow";
@@ -59,7 +59,7 @@ We recommend using the `using` keyword which implements the [TC39 Explicit Resou
 See the full API reference for [`createHook()`](/docs/api-reference/workflow/create-hook) for all available options.
 </Callout>
 
-### Resuming a Hook
+### Resuming a hook
 
 To send data to a waiting workflow, use [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) from an API route, server action, or any other external context:
 
@@ -85,9 +85,38 @@ The key points:
 - You need the hook's `token` to resume it
 - The workflow will resume execution right where it left off
 
-### Custom Tokens for Deterministic Hooks
+### Checking for token conflicts
 
-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.
+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 (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 their own 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.
 
 For example, imagine a Slack bot where each channel should have its own workflow instance:
 
@@ -139,9 +168,9 @@ export async function POST(request: Request) {
 }
 ```
 
-### Receiving Multiple Events
+### Receiving multiple events
 
-Hooks are _reusable_ - they implement `AsyncIterable`, which means you can use `for await...of` to receive multiple events over time:
+Hooks are _reusable_. They implement `AsyncIterable`, which means you can use `for await...of` to receive multiple events over time:
 
 ```typescript lineNumbers
 import { createHook } from "workflow";
@@ -169,7 +198,7 @@ export async function dataCollectionWorkflow() {
 
 Each time you call `resumeHook()` with the same token, the loop receives another value.
 
-### Disposing Hooks Early
+### Disposing hooks early
 
 When a workflow ends, hooks are automatically disposed. However, you may want to release a hook token early so another workflow can use it while your workflow continues running. Use a block scope with `using` to control when disposal happens:
 
@@ -211,9 +240,43 @@ hook.dispose(); // Manually release the token
 After disposal, the hook will no longer receive events and the async iterator will stop yielding values.
 </Callout>
 
-## Understanding Webhooks
+### Taking over a token from another run
+
+Disposing early only works when the run holding the token cooperates. When the newest run should own a token regardless, such as a redeployed bot that must replace the run still waiting on a channel, pass `experimental_force` and let the runtime perform the handoff:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+import { HookForceClaimedError } from "workflow/errors";
+
+declare function processMessage(message: { text: string }): Promise<void>; // @setup
+
+export async function channelWorkflow(channelId: string) {
+  "use workflow";
+
+  const hook = createHook<{ text: string }>({
+    token: `channel:${channelId}`,
+    experimental_force: true, // [!code highlight]
+  });
+
+  try {
+    for await (const message of hook) {
+      await processMessage(message);
+    }
+  } catch (error) {
+    if (HookForceClaimedError.is(error)) { // [!code highlight]
+      // A newer run for this channel took the token. Wrap up and exit.
+      return { replacedBy: error.claimedByRunId };
+    }
+    throw error;
+  }
+}
+```
+
+The run that held the token is woken and its `await hook` (or `for await...of`) rejects with [`HookForceClaimedError`](/docs/api-reference/workflow-errors/hook-force-claimed-error) once it has drained the payloads it received before the takeover. Every `resumeHook()` for the token from then on reaches the new run, including one that was already in flight, so senders never notice the handoff. Several runs forcing the same token at once chain in the same way and always end with exactly one owner. A run started at a spec version below 8 cannot be taken from; the forced hook then gets an ordinary `HookConflictError`. See [`createHook()`](/docs/api-reference/workflow/create-hook#take-over-a-token-another-run-holds) for the full semantics.
+
+## Understanding webhooks
 
-While hooks are powerful, they require you to manually handle HTTP requests and route them to workflows. **Webhooks** solve this by providing a higher-level abstraction built on top of hooks that:
+Hooks require you to manually handle HTTP requests and route them to workflows. **Webhooks** provide a higher-level abstraction built on top of hooks that:
 
 1. Automatically serializes the entire HTTP [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object
 2. Provides an automatically addressable `url` property pointing to the generated webhook endpoint
@@ -222,16 +285,16 @@ While hooks are powerful, they require you to manually handle HTTP requests and
 When using Workflow SDK, webhooks are automatically wired up at `/.well-known/workflow/v1/webhook/:token` without any additional setup.
 
 <Callout type="warn">
-`createWebhook()` exposes a public route at `/.well-known/workflow/v1/webhook/:token`, and the token in that URL is the only authorization performed for incoming requests. This is convenient for prototypes and a simple developer experience because you can share the webhook URL (endpoint) without creating another route, but if you need stronger security, prefer [`createHook()`](/docs/api-reference/workflow/create-hook) behind your own route and authorize the request before calling [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) to avoid unauthenticated workflow resumptions.
+`createWebhook()` exposes a public route at `/.well-known/workflow/v1/webhook/:token`, and the token in that URL is the only authorization performed for incoming requests. This is convenient for prototypes because you can share the webhook URL (endpoint) without creating another route, but if you need stronger security, prefer [`createHook()`](/docs/api-reference/workflow/create-hook) behind your own route and authorize the request before calling [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) to avoid unauthenticated workflow resumptions.
 </Callout>
 
 <Callout type="info">
 See the full API reference for [`createWebhook()`](/docs/api-reference/workflow/create-webhook) for all available options.
 </Callout>
 
-### Creating Your First Webhook
+### Creating your first webhook
 
-Here's a simple webhook that receives HTTP requests. Like hooks, webhooks support the `using` keyword for automatic cleanup:
+Here's a webhook that receives HTTP requests. Like hooks, webhooks support the `using` keyword for automatic cleanup:
 
 ```typescript lineNumbers
 import { createWebhook } from "workflow";
@@ -255,13 +318,13 @@ export async function webhookWorkflow() {
 }
 ```
 
-The webhook will automatically respond with a `202 Accepted` status by default. External systems can simply make an HTTP request to the `webhook.url` to resume your workflow.
+The webhook will automatically respond with a `202 Accepted` status by default. External systems can make an HTTP request to the `webhook.url` to resume your workflow.
 
-### Sending Custom Responses
+### Sending custom responses
 
 Webhooks provide two ways to send custom HTTP responses: **static responses** and **dynamic responses**.
 
-#### Static Responses
+#### Static responses
 
 Use the `respondWith` option to provide a static response that will be sent automatically for every request:
 
@@ -290,7 +353,7 @@ async function processData(data: any) {
 }
 ```
 
-#### Dynamic Responses (Manual Mode)
+#### Dynamic responses (manual mode)
 
 For dynamic responses based on the request content, set `respondWith: "manual"` and call the `respondWith()` method on the request:
 
@@ -336,7 +399,7 @@ export async function webhookWithDynamicResponse() {
 When using `respondWith: "manual"`, the `respondWith()` method **must** be called from within a step function due to serialization requirements. This requirement may be removed in the future.
 </Callout>
 
-### Handling Multiple Webhook Requests
+### Handling multiple webhook requests
 
 Like hooks, webhooks support iteration:
 
@@ -376,7 +439,7 @@ export async function eventCollectorWorkflow() {
 }
 ```
 
-## Hooks vs. Webhooks: When to Use Each
+## Hooks vs. webhooks: when to use each
 
 | Feature | Hooks | Webhooks |
 |---------|-------|----------|
@@ -386,19 +449,19 @@ export async function eventCollectorWorkflow() {
 | **Use Case** | Custom integrations, type-safe payloads | HTTP webhooks, standard REST APIs |
 | **Resuming** | [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) | Automatic via HTTP, or [`resumeWebhook()`](/docs/api-reference/workflow-api/resume-webhook) |
 
-**Use Hooks when:**
+**Use hooks when:**
 - You need full control over the payload structure
 - You're integrating with custom event sources
 - You want strong TypeScript typing with [`defineHook()`](/docs/api-reference/workflow/define-hook)
 
-**Use Webhooks when:**
+**Use webhooks when:**
 - You're receiving HTTP requests from external services
 - You need to send HTTP responses back to the caller
 - You want automatic URL routing without writing API handlers
 
-## Advanced Patterns
+## Advanced patterns
 
-### Type-Safe Hooks with `defineHook()`
+### Type-safe hooks with `defineHook()`
 
 The [`defineHook()`](/docs/api-reference/workflow/define-hook) helper provides type safety and runtime validation between creating and resuming hooks using [Standard Schema v1](https://standardschema.dev). Use any compliant validator like Zod or Valibot:
 
@@ -447,25 +510,25 @@ export async function POST(request: Request) {
 
 This pattern is especially valuable in larger applications where the workflow and API code are in separate files, providing both compile-time type safety and runtime validation.
 
-## Best Practices
+## Best practices
 
-### Token Design
+### Token design
 
-Custom tokens are available for `createHook()` with server-side `resumeHook()` only. Webhooks (`createWebhook()`) always use randomly generated tokens to prevent unauthorized access to public webhook endpoints.
+Custom tokens are available for `createHook()` with server-side `resumeHook()` only. Webhooks (`createWebhook()`) always generate their own unique tokens. A generated token is not trivial to guess, but it is not a strong security contract either, so anyone who obtains the URL can invoke an unintended webhook resumption. To prevent unauthenticated run resumptions entirely, prefer a **hook** over the **webhook** convenience and implement your own authentication on the route that calls `resumeHook()`.
 
 When using custom tokens with `createHook()`:
 
-- **Make them deterministic**: Base them on data the external system can reconstruct (like channel IDs, user IDs, etc.)
-- **Use namespacing**: Prefix tokens to avoid conflicts (e.g., `slack:${channelId}`, `github:${repoId}`)
-- **Include routing information**: Ensure the token contains enough information to identify the correct workflow instance
+- **Make them deterministic**: Base them on data the external system can reconstruct, such as channel IDs or user IDs.
+- **Use namespacing**: Prefix tokens to avoid conflicts, such as `slack:${channelId}` or `github:${repoId}`.
+- **Include routing information**: Ensure the token contains enough information to identify the correct workflow instance.
 
-### Response Handling in Webhooks
+### Response handling in webhooks
 
-- Use **static responses** (`respondWith: Response`) for simple acknowledgments
+- Use **static responses** (`respondWith: Response`) for acknowledgments
 - Use **manual mode** (`respondWith: "manual"`) when responses depend on request processing
 - Remember that `respondWith()` must be called from within a step function
 
-### Iterating Over Events
+### Iterating over events
 
 Both hooks and webhooks support iteration, making them perfect for long-running event loops:
 
@@ -484,7 +547,7 @@ for await (const event of hook) {
 
 This pattern allows a single workflow instance to handle multiple events over time, maintaining state between events.
 
-## Related Documentation
+## Related documentation
 
 - [Serialization](/docs/foundations/serialization) - Understanding what data can be passed through hooks
 - [`createHook()` API Reference](/docs/api-reference/workflow/create-hook)

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 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.
+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 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,265 @@ 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. Check it before calling any step: steps the workflow calls before it suspends are started alongside the hook's registration, so a duplicate run that only learns of the conflict later (for example, by awaiting the hook and letting `HookConflictError` end the run) may already have started them. See [Registering a hook before a step uses it](/docs/api-reference/workflow/create-hook#registering-a-hook-before-a-step-uses-it).
+
+```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 hook can own `order:${orderId}`, so duplicate workflow runs converge on one 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 coordinates active runs by default: the token becomes available when its workflow ends. Set `experimental_minRetention` to keep it unavailable to late duplicates. After the workflow ends, the Hook can still be found with `getHookByToken()` until retention ends, but it cannot be resumed. See [`createHook()` minimum retention](/docs/api-reference/workflow/create-hook#keep-a-token-unavailable-after-the-run-ends) for examples and supported values.
+
+### 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.** Reuse a completed owner's result, but reject other duplicates:
+
+```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 === "completed") {
+      return await conflict.returnValue;
+    }
+    return { status: "duplicate" as const, runId: conflict.runId };
+  }
+
+  return await processOwnedOrder(orderId);
+}
+```
+
+**Signal the owner instead of doing the work.** A conflict can refer to a finished run when `experimental_minRetention` is set, so check its status before sending data to its Hook:
+
+```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 && ["pending", "running"].includes(await conflict.status)) {
+    await forwardToOwner(token, { confirmed }); // [!code highlight]
+    return { status: "forwarded" as const, runId: conflict.runId };
+  }
+  if (conflict) {
+    return { status: "duplicate" as const, runId: conflict.runId };
+  }
+
+  // ... own the token and do the work
+}
+```
+
+**Supersede the owner.** Create the Hook with [`experimental_force: true`](/docs/api-reference/workflow/create-hook#take-over-a-token-another-run-holds) so the newest run takes the token over from the active owner. This also works for a finished run holding the token under `experimental_minRetention`:
+
+```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";
+
+  using request = createHook<OrderRequest>({
+    token: `order:${orderId}`,
+    experimental_force: true, // [!code highlight]
+  });
+
+  // This run now owns the token.
+  const { confirmed } = await request;
+  if (confirmed) {
+    await chargeOrder(orderId);
+  }
+  return { status: "processed" as const };
+}
+```
+
+The previous owner's `await request` rejects with [`HookForceClaimedError`](/docs/api-reference/workflow-errors/hook-force-claimed-error), and every `resumeHook()` for the token reaches the new run from then on. Any run of this workflow can be superseded by a later one, so catch the error and exit cleanly:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+import { HookForceClaimedError } from "workflow/errors";
+
+type OrderRequest = { confirmed: boolean };
+declare function chargeOrder(orderId: string): Promise<void>; // @setup
+
+export async function processOrderNewestWins(orderId: string) {
+  "use workflow";
+
+  using request = createHook<OrderRequest>({
+    token: `order:${orderId}`,
+    experimental_force: true,
+  });
+
+  try {
+    const { confirmed } = await request;
+    if (confirmed) {
+      await chargeOrder(orderId);
+    }
+    return { status: "processed" as const };
+  } catch (error) {
+    if (HookForceClaimedError.is(error)) { // [!code highlight]
+      // A newer run for this order owns the token now. Stop here.
+      return { status: "superseded" as const, runId: error.claimedByRunId }; // [!code highlight]
+    }
+    throw error;
+  }
+}
+```
+
+A run started at a Workflow spec version below 8, including runs started by older SDK releases, can't be taken from. In that case the forced Hook rejects with `HookConflictError`, as it would without `experimental_force`.
+
+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/foundations/index.mdx

@@ -10,29 +10,4 @@ related:
 
 Workflow programming can be a slight shift from how you traditionally write real-world applications. Learning the foundations now will go a long way toward helping you use workflows effectively.
 
-<Cards>
-    <Card href="/docs/foundations/workflows-and-steps" title="Workflows and Steps">
-        Learn about the building blocks of durability
-    </Card>
-    <Card href="/docs/foundations/starting-workflows" title="Starting Workflows">
-        Trigger workflows and track their execution using the `start()` function.
-    </Card>
-    <Card href="/docs/foundations/errors-and-retries" title="Errors & Retrying">
-        Types of errors and how retrying work in workflows.
-    </Card>
-    <Card href="/docs/foundations/hooks" title="Webhooks (and hooks)">
-        Respond to external events in your workflow using hooks and webhooks.
-    </Card>
-    <Card href="/docs/foundations/streaming" title="Streaming">
-        Stream data in real-time to clients without waiting for the workflow to complete.
-    </Card>
-    <Card href="/docs/foundations/serialization" title="Serialization">
-        Understand which types can be passed between workflow and step functions.
-    </Card>
-    <Card href="/docs/foundations/idempotency" title="Idempotency">
-        Prevent duplicate side effects when retrying operations.
-    </Card>
-    <Card href="/docs/foundations/versioning" title="Versioning">
-        Understand how runs stay pinned to deployments and when to opt in to newer code.
-    </Card>
-</Cards>
+<AutoCards />