@workflow/core 5.0.0-beta.42 → 5.0.0-beta.44

package/docs/foundations/cancellation.mdx

@@ -14,7 +14,7 @@ Workflow DevKit supports two cancellation mechanisms: **AbortSignal** for fine-g
 
 ## AbortSignal
 
-`AbortController` and `AbortSignal` work across workflow and step boundaries. Create an `AbortController` with `new AbortController()` in a workflow function, pass its signal to steps, and call `abort()` — using the standard [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) API you already know.
+`AbortController` and `AbortSignal` work across workflow and step boundaries. Create an `AbortController` with `new AbortController()` in a workflow function, pass its signal to steps, and call `abort()` using the standard [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController) API.
 
 ```typescript lineNumbers
 import { sleep } from "workflow";
@@ -48,17 +48,17 @@ async function longRunningStep(signal: AbortSignal) {
 }
 ```
 
-No special imports, no wrapper functions — just the standard `AbortController` API.
+Use the standard `AbortController` API without special imports or wrapper functions.
 
 <Callout type="info">
-Cancellation is **cooperative**. Aborting a signal doesn't forcefully kill a step — it's up to the step's code to check `signal.aborted` or pass the signal to APIs like `fetch` that respect it. If a step ignores the signal, it runs to completion.
+Cancellation is **cooperative**. Aborting a signal doesn't forcefully kill a step. The step's code must check `signal.aborted` or pass the signal to APIs like `fetch` that respect it. If a step ignores the signal, it runs to completion.
 </Callout>
 
 <Callout type="info">
 To learn how `AbortController` works durably across workflow suspensions, replays, and step boundaries, see [How Cancellation Works](/docs/how-it-works/cancellation).
 </Callout>
 
-### Timeout with Cancellation
+### Timeout with cancellation
 
 Race a step against a timeout, and cancel the step if the timeout wins:
 
@@ -90,7 +90,7 @@ async function fetchUrl(url: string, signal: AbortSignal) {
 }
 ```
 
-### Cancelling Parallel Work
+### Cancelling parallel work
 
 When racing multiple steps, cancel the losers:
 
@@ -116,7 +116,7 @@ async function fetchUrl(url: string, signal: AbortSignal) {
 }
 ```
 
-### Passing Signal Through a Pipeline
+### Passing signal through a pipeline
 
 Pass the same signal to a chain of steps. Aborting cancels whichever step is currently running:
 
@@ -175,7 +175,7 @@ async function uploadData(data: ArrayBuffer, signal: AbortSignal) {
 }
 ```
 
-### Step-Initiated Abort
+### Step-initiated abort
 
 A step can receive the full `AbortController` and call `abort()` to cancel parallel work. This is useful for watchdog/monitor patterns where one step observes an external condition and cancels other in-flight steps:
 
@@ -220,7 +220,7 @@ async function monitorQuota(userId: string, controller: AbortController) {
 }
 ```
 
-### User-Triggered Cancellation with Hooks
+### User-triggered cancellation with hooks
 
 Combine hooks with abort controllers to let users cancel in-flight work from an external API:
 
@@ -266,23 +266,23 @@ export async function POST(request: Request) {
 }
 ```
 
-### How Steps Handle Abort
+### How steps handle abort
 
 When an `AbortSignal` is aborted, the behavior depends on how the step uses it:
 
-| Usage | Behavior on Abort |
+| Usage | Behavior on abort |
 |-------|-------------------|
-| `fetch(url, { signal })` | Request is cancelled, throws `AbortError` |
+| `fetch(url, { signal })` | Request is canceled, throws `AbortError` |
 | `signal.throwIfAborted()` | Throws the abort reason |
 | `signal.aborted` check | Returns `true`, step can exit gracefully |
 | `signal.addEventListener('abort', fn)` | Callback fires, step can clean up |
 | Ignored | Step runs to completion (abort is cooperative) |
 
-### Abort Errors Skip Retries
+### Abort errors skip retries
 
-When a step throws due to an abort (e.g., `fetch` throws `AbortError`, or `signal.throwIfAborted()` throws), the error is automatically wrapped in a `FatalError`. This means the step **skips retries** and the error bubbles up to the workflow immediately.
+When a step throws due to an abort (for example, `fetch` throws `AbortError`, or `signal.throwIfAborted()` throws), the runtime wraps the error in a `FatalError`. The step **skips retries**, and the error immediately bubbles up to the workflow.
 
-This is the correct behavior because an abort is an intentional cancellation — retrying the step would just result in another abort. You don't need to manually wrap abort errors in `FatalError`.
+An abort is an intentional cancellation, so retrying the step would result in another abort. You don't need to manually wrap abort errors in `FatalError`.
 
 ```typescript lineNumbers
 import { sleep } from "workflow";
@@ -299,7 +299,7 @@ export async function workflow() {
     if (result === null) controller.abort();
     return result;
   } catch (err) {
-    // AbortError arrives as FatalError — no retries attempted // [!code highlight]
+    // AbortError arrives as FatalError, with no retries attempted // [!code highlight]
     return { status: "cancelled" };
   }
 }
@@ -312,7 +312,7 @@ async function cancellableStep(signal: AbortSignal) {
 }
 ```
 
-### Passing AbortSignal as Workflow Input
+### Passing AbortSignal as workflow input
 
 You can pass an `AbortSignal` from external code into a workflow via `start()`:
 
@@ -329,15 +329,15 @@ export async function POST(request: Request) {
 }
 ```
 
-When the signal is serialized at the `start()` boundary, an event listener is attached to the external signal that writes the cancellation packet to the backing stream. This means the external `abort()` propagates into the workflow — but only while the originating process is still alive (same constraint as passing a `ReadableStream` as input).
+When the signal is serialized at the `start()` boundary, an event listener attaches to the external signal and writes the cancellation packet to the backing stream. The external `abort()` propagates into the workflow only while the originating process is still alive (the same constraint as passing a `ReadableStream` as input).
 
 <Callout type="info">
 For reliable external cancellation that works regardless of process lifetime, prefer the [User-Triggered Cancellation with Hooks](#user-triggered-cancellation-with-hooks) pattern. Hooks are durable and don't depend on the caller's process staying alive.
 </Callout>
 
-## Run Cancellation
+## Run cancellation
 
-Run cancellation stops an entire workflow at the next suspension point. Unlike `AbortSignal`, it is not cooperative — the workflow does not continue executing after cancellation.
+Run cancellation stops an entire workflow at the next suspension point. Unlike `AbortSignal`, it is not cooperative. The workflow does not continue executing after cancellation.
 
 ```typescript title="app/api/cancel-run/route.ts" lineNumbers
 import { getRun } from "workflow/api";
@@ -353,10 +353,10 @@ export async function POST(request: Request) {
 ```
 
 <Callout type="info">
-Calling `run.cancel()` is the same action as clicking the **Cancel** button on a run in the observability UI — both produce identical `run_cancelled` events in the event log.
+Calling `run.cancel()` is the same action as clicking the **Cancel** button on a run in the observability UI. Both produce identical `run_cancelled` events in the event log.
 </Callout>
 
-When a run is cancelled:
+When a run is canceled:
 - The workflow stops at its next suspension point (step call, hook await, or sleep)
 - A `run_cancelled` event is recorded in the [event log](/docs/how-it-works/event-sourcing)
 - All associated hooks are disposed and their tokens released
@@ -366,19 +366,19 @@ When a run is cancelled:
 Run cancellation does **not** automatically abort any outstanding `AbortSignal`s. Steps that are currently executing will run to completion. If you need in-flight cancellation of specific operations, use `AbortSignal`.
 </Callout>
 
-## AbortSignal vs. Run Cancellation
+## AbortSignal vs. run cancellation
 
 | | AbortSignal | Run Cancellation |
 |---|---|---|
 | **Scope** | Individual operations within a step | Entire workflow run |
 | **Triggered by** | Your code (`controller.abort()`) | External API (`run.cancel()`) |
-| **Cooperative** | Yes — steps must check the signal | No — workflow stops at the next suspension point |
+| **Cooperative** | Yes. Steps must check the signal | No. The workflow stops at the next suspension point |
 | **Granularity** | Can target specific steps or operations | All-or-nothing |
 | **In-flight steps** | Aborted immediately if using the signal | Run to completion |
 
 Use `AbortSignal` when you need fine-grained, in-flight cancellation of specific operations. Use run cancellation when you want to stop the entire workflow.
 
-## Best Practices
+## Best practices
 
 **Use `throwIfAborted()` before expensive work.** This throws the signal's abort reason if the signal is already aborted, preventing wasted compute:
 
@@ -448,12 +448,12 @@ export async function workflow() {
 }
 ```
 
-This is safe even if both steps have already completed — aborting a finished operation is a no-op.
+This is safe even if both steps have already completed because aborting a finished operation is a no-op.
 
-## Related Documentation
+## Related documentation
 
-- [How Cancellation Works](/docs/how-it-works/cancellation) — Hook and stream backing, serialization internals
-- [Serialization](/docs/foundations/serialization) — Understanding serializable types
-- [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
+- [How Cancellation Works](/docs/how-it-works/cancellation): Hook and stream backing, serialization internals
+- [Serialization](/docs/foundations/serialization): Understanding serializable types
+- [Cookbook](/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/errors-and-retries.mdx

@@ -1,6 +1,6 @@
 ---
 title: Errors & Retrying
-description: Customize retry behavior with FatalError and RetryableError for robust error handling.
+description: Customize retry behavior with FatalError and RetryableError.
 type: conceptual
 summary: Control how steps handle failures and customize retry behavior.
 prerequisites:
@@ -12,7 +12,7 @@ related:
 
 By default, errors thrown inside steps are retried. Additionally, Workflow SDK provides two new types of errors you can use to customize retries.
 
-## Default Retrying
+## Default retrying
 
 By default, steps retry up to 3 times on arbitrary errors. You can customize the number of retries by adding a `maxRetries` property to the step function.
 
@@ -42,9 +42,9 @@ Steps get enqueued immediately after a failure. Read on to see how this can be c
   more information.
 </Callout>
 
-## Intentional Errors
+## Intentional errors
 
-When your step needs to intentionally throw an error and skip retrying, simply throw a [`FatalError`](/docs/api-reference/workflow/fatal-error).
+When your step needs to intentionally throw an error and skip retrying, throw a [`FatalError`](/docs/api-reference/workflow/fatal-error).
 
 ```typescript lineNumbers
 import { FatalError } from "workflow";
@@ -67,7 +67,7 @@ async function callApi(endpoint: string) {
 }
 ```
 
-## Customize Retry Behavior
+## Customize retry behavior
 
 When you need to customize the delay on a retry, use [`RetryableError`](/docs/api-reference/workflow/retryable-error) and set the `retryAfter` property.
 
@@ -97,7 +97,7 @@ async function callApi(endpoint: string) {
 }
 ```
 
-## Advanced Example
+## Advanced example
 
 This final example combines everything we've learned, along with [`getStepMetadata`](/docs/api-reference/workflow/get-step-metadata).
 
@@ -139,7 +139,32 @@ callApi.maxRetries = 5; // Retry up to 5 times on failure (6 total attempts)
   step can run up to 4 times total (1 initial attempt + 3 retries).
 </Callout>
 
-## Error Codes
+## Serialization failures
+
+A step whose arguments or return value cannot be [serialized](/docs/foundations/serialization) fails like a step whose body threw a `FatalError`: the failure is deterministic, so it skips the retry loop, and a `try/catch` around the step call observes the `SerializationError`:
+
+```typescript lineNumbers
+async function someStep(input: unknown) {
+  "use step";
+  return input;
+}
+
+export async function myWorkflow(input: unknown) {
+  "use workflow";
+
+  try {
+    await someStep(input);
+  } catch (err) {
+    if ((err as Error).name === "SerializationError") {
+      // e.g. `Failed to serialize step arguments at path "..."`
+    }
+  }
+}
+```
+
+Uncaught, the run fails immediately with the `USER_ERROR` code, without retrying. See [serialization-failed](/docs/errors/serialization-failed) for common causes and fixes.
+
+## Error codes
 
 When a workflow run fails, the error includes an `errorCode` that classifies the failure, alongside the original thrown value (preserved as `cause`):
 
@@ -153,7 +178,7 @@ try {
   const result = await run.returnValue;
 } catch (err) {
   if (WorkflowRunFailedError.is(err)) {
-    console.log(err.errorCode); // "USER_ERROR", "RUNTIME_ERROR", or undefined
+    console.log(err.errorCode); // e.g. "USER_ERROR", "MAX_EVENTS_EXCEEDED", or undefined
     // `cause` is the original thrown value, hydrated through the workflow
     // serialization pipeline. It can be any thrown value, so check shape.
     if (err.cause instanceof Error) {
@@ -166,13 +191,19 @@ try {
 | Code | Meaning |
 | --- | --- |
 | `USER_ERROR` | An error thrown in your workflow or step code (including propagated step failures like `FatalError`) |
-| `RUNTIME_ERROR` | An internal runtime error such as a corrupted event log or missing data. If you see this, please [file an issue](https://github.com/vercel/workflow/issues) |
+| `MAX_EVENTS_EXCEEDED` | The run reached the World's per-run event ceiling (25,000 on the Local and Vercel Worlds). Split unbounded loops into [child workflows](/cookbook/advanced/child-workflows); see [Limits](/docs/configuration/runtime-tuning#limits) |
+| `MAX_DELIVERIES_EXCEEDED` | The run exceeded the maximum number of queue deliveries |
+| `REPLAY_TIMEOUT` | A workflow replay exceeded the maximum allowed duration |
+| `REPLAY_DIVERGENCE` | A replay could not consume the event log deterministically, usually because of non-deterministic workflow code. |
+| `CORRUPTED_EVENT_LOG` | The event log contains orphaned or mismatched events and cannot be replayed. If you see this, please [file an issue](https://github.com/vercel/workflow/issues) |
+| `WORLD_CONTRACT_ERROR` | A World response violated the SDK contract; points at a World implementation bug |
+| `RUNTIME_ERROR` | An internal runtime error. If you see this, please [file an issue](https://github.com/vercel/workflow/issues) |
 
 <Callout type="info">
-  The error code is also available on the run entity via the CLI (`npx workflow inspect runs <runId>`) in the `error.code` field, and as an OTEL span attribute (`workflow.error.code`) for observability.
+  The error code is also available on the run entity through the Workflow CLI (`npx workflow inspect runs <runId>`) in the `error.code` field, and as an OpenTelemetry span attribute (`workflow.error.code`) for observability.
 </Callout>
 
-## Rolling Back Failed Steps
+## Rolling back failed steps
 
 When a workflow fails partway through, it can leave the system in an inconsistent state.
 A common pattern to address this is "rollbacks": for each successful step, record a corresponding rollback action that can undo it.

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,7 +85,7 @@ 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
+### 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:
 
@@ -112,11 +112,11 @@ export async function orderWorkflow(orderId: string) {
 }
 ```
 
-Calling `createHook()` on its own does not register the hook — registration is only committed when the workflow suspends. Awaiting `hook.getConflict()` suspends the workflow to commit the hook registration, then resolves with `null` once the hook is registered and ready to receive payloads, or with a `Run` handle for the run that owns the token (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.
+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
+### 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.
+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:
 
@@ -168,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";
@@ -198,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:
 
@@ -240,9 +240,9 @@ 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
+## 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
@@ -251,16 +251,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";
@@ -284,13 +284,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:
 
@@ -319,7 +319,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:
 
@@ -365,7 +365,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:
 
@@ -405,7 +405,7 @@ export async function eventCollectorWorkflow() {
 }
 ```
 
-## Hooks vs. Webhooks: When to Use Each
+## Hooks vs. webhooks: when to use each
 
 | Feature | Hooks | Webhooks |
 |---------|-------|----------|
@@ -415,19 +415,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:
 
@@ -476,25 +476,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:
 
@@ -513,7 +513,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

@@ -15,9 +15,9 @@ Idempotency is a property of an operation that ensures repeated attempts have th
 
 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
+## Step idempotency
 
-In distributed systems (calling external APIs), it is not always possible to ensure an operation has only been performed once just by seeing if it succeeds.
+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.
@@ -61,7 +61,7 @@ Because [hooks](/docs/foundations/hooks) already ensure globally unique active t
 
 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.
+The token should come from your domain, such as an order ID, invoice ID, import ID, or request ID. Create the hook near the beginning of the workflow and check `await hook.getConflict()` before doing duplicate-sensitive work that depends on owning the active token. Calling `createHook()` alone does not register the hook; awaiting `getConflict()` suspends the workflow to commit the registration.
 
 ```typescript lineNumbers
 import { createHook } from "workflow";
@@ -96,7 +96,7 @@ export async function processOrder(orderId: string): Promise<OrderResult> {
 }
 ```
 
-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.
+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:
 
@@ -146,14 +146,14 @@ export async function POST(request: Request) {
 ```
 
 <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()`.
+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.
+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:
 
@@ -260,7 +260,7 @@ export async function processOrderNewestWins(orderId: string) {
 
     const conflict = await request.getConflict();
     if (!conflict) {
-      // Token claimed — this run is now the owner.
+      // Token claimed: this run is now the owner.
       const { confirmed } = await request;
       if (confirmed) {
         await chargeOrder(orderId);
@@ -271,12 +271,12 @@ export async function processOrderNewestWins(orderId: string) {
     await conflict.cancel(); // [!code highlight]
   }
 
-  throw new Error(`Could not claim ${token} after cancelling the owner`);
+  throw new Error(`Could not claim ${token} after canceling the owner`);
 }
 ```
 
 <Callout type="warn">
-This pattern does not work with `experimental_minRetention`: cancelling the old run does not make its token available early.
+This pattern does not work with `experimental_minRetention`: canceling the old run does not make its token available early.
 </Callout>
 
 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.