workflow 5.0.0-beta.9 → 5.0.0

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

@@ -3,7 +3,19 @@ title: "@workflow/vitest"
 description: Vitest plugin and test helpers for integration testing workflows in-process.
 ---
 
-The `@workflow/vitest` package provides a Vitest plugin and test helpers for running full workflow integration tests in-process — no server required.
+The `@workflow/vitest` package provides a Vitest plugin and test helpers for running full workflow integration tests in-process, no server required.
+
+## Installation
+
+```package-install
+npm i -D @workflow/vitest@beta
+```
+
+<Callout type="warn">
+`@workflow/vitest@latest` is still the 4.x line, so a Workflow 5 app has to install the `beta` tag (or pin the matching beta, for example `@workflow/vitest@5.0.0-beta.53`). The package carries its own copy of `@workflow/core` and runs your workflows against it, so it has to move with `workflow`.
+
+`globalSetup` compares the two copies once per run: a different major fails the run with the install command that fixes it, and any other difference logs a warning. Set [`WORKFLOW_VITEST_VERSION_CHECK=off`](/docs/configuration/build-and-diagnostics#workflow_vitest_version_check) to skip the check.
+</Callout>
 
 ## Plugin
 
@@ -11,7 +23,6 @@ The `@workflow/vitest` package provides a Vitest plugin and test helpers for run
 
 Returns a Vite plugin array that handles SWC transforms, bundle building, and in-process handler registration automatically.
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { defineConfig } from "vitest/config";
@@ -22,9 +33,8 @@ export default defineConfig({
 });
 ```
 
-Pass a [`WorkflowTestOptions`](#workflowtestoptions) object when your project uses a non-standard layout — for example, a monorepo where `workflows/` does not live at the Vitest config's directory, or when the default `.workflow-data` / `.workflow-vitest` output locations need to move. The plugin forwards these paths to `buildWorkflowTests()` and `setupWorkflowTests()` through Vitest's per-project provided context, so each Vitest workspace project stays isolated.
+Pass a [`WorkflowTestOptions`](#workflowtestoptions) object when your project uses a non-standard layout, for example, a monorepo where `workflows/` does not live at the Vitest config's directory, or when the default `.workflow-data` / `.workflow-vitest` output locations need to move. The plugin forwards these paths to `buildWorkflowTests()` and `setupWorkflowTests()` through Vitest's per-project provided context, so each Vitest workspace project stays isolated.
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { defineConfig } from "vitest/config";
@@ -48,13 +58,12 @@ export default defineConfig({
 
 **Returns:** `Plugin[]`
 
-## Setup Functions
+## Setup functions
 
 ### `buildWorkflowTests()`
 
 Builds workflow and step bundles to disk. Called automatically by the `workflow()` plugin in `globalSetup`. Use directly only for [manual setup](/docs/testing#manual-setup).
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { buildWorkflowTests } from "@workflow/vitest";
@@ -72,11 +81,10 @@ 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).
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { beforeAll, afterAll } from "vitest";
@@ -112,13 +120,59 @@ Tears down the workflow test world. Clears the global world and closes the Local
 | `dataDir` | `string` | `<rootDir>/.workflow-data` | Directory for workflow runtime data written by the test world. Relative paths resolve against `cwd`. |
 | `outDir` | `string` | `<rootDir>/.workflow-vitest` | Directory for generated workflow and step bundles. Relative paths resolve against `cwd`. |
 
-## Test Helpers
+## Workflow references
+
+The test build writes the same `manifest.json` the other Workflow builders write into `outDir`. These helpers read it, so a test can name a workflow instead of hand-writing the generated `workflow//...` id. Importing the workflow function is still preferable when a test can do it, because it keeps the argument and return types.
+
+### `getWorkflowRef()`
+
+Looks up one workflow in the test build and returns it in the shape [`start()`](/docs/api-reference/workflow-api/start) accepts.
+
+```typescript
+import { getWorkflowRef } from "@workflow/vitest"; // [!code highlight]
+import { start } from "workflow/api";
+
+const run = await start(getWorkflowRef("approvalWorkflow"), ["doc-1"]); // [!code highlight]
+```
+
+`query` is an exported workflow name, or a file-qualified name when the same name appears in more than one file: `getWorkflowRef("workflows/approval.ts#approvalWorkflow")`. The file part also matches by path suffix, so `"approval.ts#approvalWorkflow"` resolves the same entry.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `query` | `string` | Workflow name, or `<file>#<name>` |
+
+**Returns:** [`WorkflowRef`](#workflowref).
+
+**Throws** when the manifest is missing (the plugin or `buildWorkflowTests()` has not run), when nothing matches, or when the name is ambiguous. The message lists the workflows the build contains.
+
+### `listWorkflowRefs()`
+
+Returns every workflow in the test build, sorted by file and then name.
+
+```typescript
+import { listWorkflowRefs } from "@workflow/vitest"; // [!code highlight]
+
+const names = listWorkflowRefs().map((ref) => ref.name); // [!code highlight]
+```
+
+**Returns:** [`WorkflowRef`](#workflowref)`[]`.
+
+### `WorkflowRef`
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Exported name of the workflow function |
+| `file` | `string` | Project-relative path of the file it was compiled from |
+| `workflowId` | `string` | Generated workflow id, the field `start()` reads |
+
+## Test helpers
 
 ### `waitForSleep()`
 
-Polls the event log until the workflow has a pending `sleep()` call — one with a `wait_created` event but no corresponding `wait_completed` event. Returns the correlation ID of the pending sleep, which can be passed to [`wakeUp()`](/docs/api-reference/workflow-api/get-run) to target a specific sleep.
+Polls the event log until the workflow has a pending `sleep()` call, one with a `wait_created` event but no corresponding `wait_completed` event. Returns the correlation ID of the pending sleep, which can be passed to [`wakeUp()`](/docs/api-reference/workflow-api/get-run) to target a specific sleep.
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { waitForSleep } from "@workflow/vitest"; // [!code highlight]
@@ -136,9 +190,9 @@ await getRun(run.runId).wakeUp({ correlationIds: [sleepId] }); // [!code highlig
 | `run` | `Run<any>` | The workflow run to monitor |
 | `options?` | `WaitOptions` | Polling and timeout configuration |
 
-**Returns:** `Promise<string>` — The correlation ID of the first pending sleep. Pass this to `wakeUp({ correlationIds: [id] })` to target a specific sleep.
+**Returns:** `Promise<string>`, the correlation ID of the first pending sleep. Pass this to `wakeUp({ correlationIds: [id] })` to target a specific sleep.
 
-#### Behavior with Multiple Sleeps
+#### Behavior with multiple sleeps
 
 - **Sequential sleeps**: `waitForSleep()` returns each sleep as the workflow reaches it. After waking one, call `waitForSleep()` again for the next.
 - **Parallel sleeps**: `waitForSleep()` returns whichever pending sleep is found first. After waking it, call `waitForSleep()` again to get the next one.
@@ -147,7 +201,6 @@ await getRun(run.runId).wakeUp({ correlationIds: [sleepId] }); // [!code highlig
 
 Polls the hook list and event log until a hook matching the optional `token` filter exists that hasn't been received yet. Returns the matching hook object.
 
-{/* @skip-typecheck - @workflow/vitest not available in docs-typecheck */}
 
 ```typescript
 import { waitForHook } from "@workflow/vitest"; // [!code highlight]
@@ -165,7 +218,7 @@ await resumeHook(hook.token, { approved: true }); // [!code highlight]
 | `run` | `Run<any>` | The workflow run to monitor |
 | `options?` | `WaitOptions & { token?: string }` | Polling, timeout, and optional token filter |
 
-**Returns:** `Promise<Hook>` — The first pending hook matching the filter. The hook object includes `token`, `hookId`, and `runId`.
+**Returns:** `Promise<Hook>`, the first pending hook matching the filter. The hook object includes `token`, `hookId`, and `runId`.
 
 ### `WaitOptions`
 

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.
@@ -25,7 +26,7 @@ export async function hookWorkflow() {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -65,9 +66,11 @@ export default Hook;`}
 
 The returned `Hook` object also implements `AsyncIterable<T>`, which allows you to iterate over incoming payloads using `for await...of` syntax.
 
+Use `hook.getConflict()` to check whether the hook token is already claimed by another hook, including one kept reserved after its run ends, without waiting for hook payload data. 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 registration, then resolves with `null` once `hook_created` is recorded, or with the conflicting [`Run`](/docs/api-reference/workflow-api/get-run).
+
 ## Examples
 
-### Basic Usage
+### Basic usage
 
 When creating a hook, you can specify a payload type for automatic type safety:
 
@@ -88,7 +91,7 @@ export async function approvalWorkflow() {
 }
 ```
 
-### Customizing Tokens
+### Customizing tokens
 
 Tokens are used to identify a specific hook. You can customize the token to be more specific to a use case.
 
@@ -112,7 +115,159 @@ export async function slackBotWorkflow(channelId: string) {
 }
 ```
 
-### Waiting for Multiple Payloads
+### Detecting token conflicts
+
+Use `hook.getConflict()` when the workflow needs to claim a hook token before doing other work, but does not need a payload yet:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+declare function chargeOrder(orderId: string): Promise<void>; // @setup
+
+async function processOrder(orderId: string) {
+  "use workflow";
+
+  using hook = createHook({ // [!code highlight]
+    token: `order:${orderId}` // [!code highlight]
+  }); // [!code highlight]
+
+  const conflict = await hook.getConflict(); // [!code highlight]
+  if (conflict) { // [!code highlight]
+    // Another active workflow run already owns this token.
+    return { dedupedTo: conflict.runId };
+  }
+
+  await chargeOrder(orderId);
+}
+```
+
+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`.
+
+### Registering a hook before a step uses it
+
+A hook's registration is committed alongside everything else the workflow started before it suspended, not ahead of it. When a workflow creates a hook and calls a step without awaiting anything in between, the step can start running before the hook is registered, and it can run even if the registration turns out to conflict. That matters in two cases:
+
+- The step hands the token to something that may call `resumeHook()` right away, which throws `HookNotFoundError` until the hook exists.
+- The hook guards against duplicate runs. A run that only learns of the conflict after calling the step, for example by awaiting the hook and letting `HookConflictError` end the run, may already have started that step.
+
+In either case, await `hook.getConflict()` before calling the step:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+declare function requestApproval(token: string): Promise<void>; // @setup
+
+async function approvalWorkflow() {
+  "use workflow";
+
+  using hook = createHook<{ approved: boolean }>();
+  await hook.getConflict(); // [!code highlight]
+
+  // The hook is registered, so an approver that resumes it immediately
+  // finds it.
+  await requestApproval(hook.token);
+
+  const { approved } = await hook;
+  return approved;
+}
+```
+
+On a conflict, the resolved value is a `Run` handle for the run that 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>
+
+### Keep a token unavailable after the run ends
+
+By default, another Hook can use the token after its workflow ends. Set `experimental_minRetention` to keep the token unavailable for at least a specific time after `createHook()` runs:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+declare function processOwnedOrder(orderId: string): Promise<void>; // @setup
+
+export async function processOrder(orderId: string) {
+  "use workflow";
+
+  const hook = createHook({ // [!code highlight]
+    token: `order:${orderId}`, // [!code highlight]
+    experimental_minRetention: "30d", // [!code highlight]
+  }); // [!code highlight]
+
+  const conflict = await hook.getConflict();
+  if (conflict) {
+    return { status: "duplicate" as const, runId: conflict.runId };
+  }
+
+  await processOwnedOrder(orderId);
+  return { status: "processed" as const };
+}
+```
+
+`experimental_minRetention` accepts the same values as [`sleep()`](/docs/api-reference/workflow/sleep): a duration string such as `"30d"`, a number of milliseconds, or an absolute `Date`. Durations start when `createHook()` runs.
+
+The Hook remains active until the workflow ends, even if the configured time passes first. Another Hook can use the token only after both the workflow has ended and the configured time has passed. For example, `"30d"` keeps the token unavailable for 29 more days if the workflow ends after 1 day. A workflow that runs for more than 30 days releases the token when it ends.
+
+After the workflow ends, [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) can still find the Hook until retention ends, but the Hook cannot be resumed.
+
+<Callout type="warn">
+`using` auto-disposes the Hook at scope exit, which releases the token immediately and defeats `experimental_minRetention`. Declare retained Hooks with `const` and let the runtime clean them up when the run ends.
+</Callout>
+
+<Callout type="warn">
+This option is experimental. Worlds can limit how long tokens are retained; see [World configuration](/docs/configuration/worlds) for each World's limit. If the configured World does not support minimum retention, the workflow fails when registering the Hook. `createWebhook()` does not accept this option.
+</Callout>
+
+### Take over a token another run holds
+
+By default, a token that another active run already registered makes the new Hook reject with [`HookConflictError`](/docs/api-reference/workflow-errors/hook-conflict-error). Set `experimental_force` when the newest run should own the token instead, for example when a fresh deployment or a restarted conversation must replace a run that is still waiting:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+declare function processMessage(message: SlackMessage): Promise<void>; // @setup
+type SlackMessage = { text: string }; // @setup
+
+export async function slackChannelWorkflow(channelId: string) {
+  "use workflow";
+
+  // Whichever run for this channel started most recently owns the token.
+  const hook = createHook<SlackMessage>({ // [!code highlight]
+    token: `slack_messages:${channelId}`, // [!code highlight]
+    experimental_force: true, // [!code highlight]
+  }); // [!code highlight]
+
+  for await (const message of hook) {
+    await processMessage(message);
+  }
+}
+```
+
+With `experimental_force`, this run always ends up owning the token:
+
+- The previous owner's Hook is disposed, recorded in that run's event log, and the previous owner is woken. If it was awaiting the Hook, that `await` rejects with [`HookForceClaimedError`](/docs/api-reference/workflow-errors/hook-force-claimed-error), which names the run that took the token. Payloads it received before the takeover stay with it; a `for await...of` loop drains them before it throws.
+- Every [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) for the token from then on reaches this run, including a call that was already in flight when the takeover happened. Callers never see the token move; a delivery aimed at the previous owner is redirected to this run inside `resumeHook()`.
+- Any number of runs forcing the same token at the same time converge on a single owner. The takeovers form a chain: each run that loses the token gets `HookForceClaimedError`, exactly one run ends up owning it, and none of them can get stuck. Which run wins among simultaneous claimers is not defined; if the order matters, start them in order.
+- A finished run that still holds the token under [`experimental_minRetention`](#keep-a-token-unavailable-after-the-run-ends) is taken over silently, since there is nothing left to wake. A run can also take over a token held by its own earlier Hook.
+
+The takeover is durable. If either run's compute fails partway through, the next request for the token completes it, so the token never ends up held by nobody or by both runs. The previous owner's wake is durable too: if the new owner's compute fails between registering the Hook and waking the previous owner, the new owner's next invocation republishes the wake, whatever else the new owner has recorded since (a step it started alongside the Hook, for example). Every invocation of the new owner within 24 hours of the takeover republishes it under the same idempotency key, which collapses the repeats into one wake; a repeat that does get through only replays the previous owner, which finds nothing new.
+
+<Callout type="info">
+A token can only be taken from a run whose runtime understands being taken from. Runs started at a Workflow spec version below 8, which includes every run started by an older SDK release, a Python SDK run, or a deployment with `WORKFLOW_SEALED_LOG=0`, would never learn that their Hook was disposed. The World declines to take their token and the forced Hook rejects with the ordinary [`HookConflictError`](/docs/api-reference/workflow-errors/hook-conflict-error) instead, exactly as if `experimental_force` had not been set. Finished runs holding a retained token are taken over at any version.
+</Callout>
+
+`hook.getConflict()` on a forced Hook resolves with `null` once the takeover succeeds: the token is this run's by construction. If the World declines the takeover because the current owner predates spec version 8, `getConflict()` behaves as it does for an ordinary conflict and resolves with that owner's `Run`. Read `hook.claimedFrom` on the value returned by [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) to find out which run, if any, the token was taken from.
+
+<Callout type="warn">
+This option is experimental. It requires an explicit `token` (a generated token can never conflict) and is not accepted by `createWebhook()`. If the configured World does not support force-claiming at all, the workflow fails when registering the Hook; a World that declines a specific takeover because the current owner cannot be woken answers with `HookConflictError` instead.
+
+Senders on an older SDK release are not redirected. A `resumeHook()` from a deployment that predates this option and that looked the token up inside the short handoff window gets an error (`EntityConflictError`) instead of following the token; the payload is refused, never delivered to the wrong run, and a retry resolves the new owner. Upgrade the sending deployment for the transparent redirect.
+
+Webhook requests are not redirected either. [`resumeWebhook()`](/docs/api-reference/workflow-api/resume-webhook) streams the request body once, and buffering a copy of every webhook body on the chance that its token is being taken over at that moment would be a cost paid by everyone who never uses this option. A webhook delivery that lands inside the handoff window fails with a retryable error naming the takeover; nothing is delivered anywhere, and the sender's retry reaches the new owner. A forced `createHook()` can take over a token that a webhook holds, but the token then belongs to a Hook that is not a webhook, so `resumeWebhook()` answers every later request for it as not found, exactly as it does for any `createHook()` token, and never redirects one into it.
+</Callout>
+
+### Waiting for multiple payloads
 
 You can also wait for multiple payloads by using the `for await...of` syntax.
 
@@ -135,7 +290,7 @@ export async function collectHookWorkflow() {
 }
 ```
 
-### Disposing Hooks Early
+### Disposing hooks early
 
 You can dispose a hook early to release its token for reuse by another workflow. This is useful for handoff patterns where one workflow needs to transfer a hook token to another workflow while still running.
 
@@ -164,7 +319,7 @@ export async function handoffWorkflow(channelId: string) {
 
 After calling `dispose()`, the hook will no longer receive events and its token becomes available for other workflows to use.
 
-### Automatic Disposal with `using`
+### Automatic disposal with `using`
 
 Hooks implement the [TC39 Explicit Resource Management](https://github.com/tc39/proposal-explicit-resource-management) proposal, allowing automatic disposal with the `using` keyword:
 
@@ -190,8 +345,9 @@ export async function scopedHookWorkflow(channelId: string) {
 
 This is equivalent to manually calling `dispose()` but ensures the hook is always cleaned up, even if an error occurs.
 
-## Related Functions
+## Related functions
 
-- [`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
+- [`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/create-webhook.mdx

@@ -14,7 +14,7 @@ Creates a webhook that can be used to suspend and resume a workflow run upon rec
 Webhooks provide a way for external systems to send HTTP requests directly to your workflow. Unlike hooks which accept arbitrary payloads, webhooks work with standard HTTP `Request` objects and can return HTTP `Response` objects.
 
 <Callout type="warn">
-`createWebhook()` creates a public endpoint at `/.well-known/workflow/v1/webhook/:token`, and the token in that URL is the only authorization performed for incoming requests resuming that webhook. This is convenient for prototypes and simple resume links because it avoids 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()` creates a public endpoint at `/.well-known/workflow/v1/webhook/:token`, and the token in that URL is the only authorization performed for incoming requests resuming that webhook. This is convenient for prototypes and basic resume links because it avoids 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>
 
 ```ts lineNumbers
@@ -31,7 +31,7 @@ export async function webhookWorkflow() {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -55,6 +55,7 @@ The returned `Webhook` object has:
 
 - `url`: The HTTP endpoint URL that external systems can call
 - `token`: The unique token identifying this webhook
+- `getConflict()`: A promise that resolves with the conflicting run if another active hook already owns this token, or `null` once the webhook endpoint has been registered. The endpoint is registered alongside the steps the workflow starts at the same time, not ahead of them, so await `getConflict()` before a step that hands `url` to a caller who may request it right away. See [Registering a hook before a step uses it](/docs/api-reference/workflow/create-hook#registering-a-hook-before-a-step-uses-it).
 - Implements `AsyncIterable<T>` for handling multiple requests, where `T` is `Request` (default) or `RequestWithResponse` (manual mode)
 
 When using `createWebhook({ respondWith: 'manual' })`, the resolved request type is `RequestWithResponse`, which extends the standard `Request` interface with a `respondWith(response: Response): Promise<void>` method for sending custom responses back to the caller.
@@ -62,22 +63,22 @@ When using `createWebhook({ respondWith: 'manual' })`, the resolved request type
 <Callout type="info">
 Use the simplest option that satisfies the prompt:
 
-- `createWebhook()` — generated callback URL, and the default `202 Accepted` response is fine
-- `createWebhook({ respondWith: 'manual' })` — generated callback URL, but you must send a custom body, status, or headers
-- `createHook()` + `resumeHook()` — the app resumes from server-side code with a deterministic business token instead of a generated callback URL
+- `createWebhook()`: generated callback URL, and the default `202 Accepted` response is fine
+- `createWebhook({ respondWith: 'manual' })`: generated callback URL, but you must send a custom body, status, or headers
+- `createHook()` + `resumeHook()`: the app resumes from server-side code with a deterministic business token instead of a generated callback URL
 </Callout>
 
 <details>
 <summary>Common wrong turns</summary>
 
-- Do not use `respondWith: 'manual'` just because the flow has a callback URL.
+- A callback URL alone does not require `respondWith: 'manual'`.
 - Do not use `RequestWithResponse` unless you chose manual mode.
 - Do not invent a custom callback route when `webhook.url` is the intended callback surface.
 </details>
 
 ## Examples
 
-### Basic Usage
+### Basic usage
 
 Create a webhook that receives HTTP requests and logs the request details:
 
@@ -100,11 +101,11 @@ export async function basicWebhookWorkflow() {
 }
 ```
 
-### Responding to Webhook Requests (Manual Mode)
+### Responding to webhook requests (manual mode)
 
 Use this section only when the caller requires a non-default HTTP response. If `202 Accepted` is acceptable, use `createWebhook()` without `respondWith: "manual"`.
 
-Pass `{ respondWith: "manual" }` to get a `RequestWithResponse` object with a `respondWith()` method. Note that `respondWith()` must be called from within a step function:
+Pass `{ respondWith: "manual" }` to get a `RequestWithResponse` object with a `respondWith()` method. Call `respondWith()` from within a step function:
 
 ```typescript lineNumbers
 import { createWebhook, type RequestWithResponse } from "workflow"
@@ -142,7 +143,7 @@ async function processData(data: any): Promise<void> {
 }
 ```
 
-### Waiting for Multiple Requests
+### Waiting for multiple requests
 
 You can also wait for multiple requests by using the `for await...of` syntax.
 
@@ -181,9 +182,9 @@ export async function eventCollectorWorkflow() {
 }
 ```
 
-## Related Functions
+## Related functions
 
-- [`createHook()`](/docs/api-reference/workflow/create-hook) — Use when the app resumes from server-side code with a deterministic business token.
-- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) — Pairs with `createHook()` for deterministic server-side resume.
-- [`defineHook()`](/docs/api-reference/workflow/define-hook) — Type-safe hook helper.
-- [`resumeWebhook()`](/docs/api-reference/workflow-api/resume-webhook) — Low-level runtime API. Most integrations should call `webhook.url` directly instead of adding a custom callback route.
+- [`createHook()`](/docs/api-reference/workflow/create-hook): Use when the app resumes from server-side code with a deterministic business token.
+- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook): Pairs with `createHook()` for deterministic server-side resume.
+- [`defineHook()`](/docs/api-reference/workflow/define-hook): Type-safe hook helper.
+- [`resumeWebhook()`](/docs/api-reference/workflow-api/resume-webhook): Low-level runtime API. Most integrations should call `webhook.url` directly instead of adding a custom callback route.

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

@@ -33,7 +33,7 @@ export async function nameWorkflow() {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -46,27 +46,24 @@ showSections={['parameters']}
 
 ### Returns
 
+`defineHook()` returns a `TypedHook<TInput, TOutput>`:
+
 <TSDoc
 definition={`
-interface DefineHook<T> {
-  /**
-
-* Creates a new hook with the defined payload type.
-  */
-  create: (options?: HookOptions) => Hook<T>;
-
-  /**
-
-* Resumes a hook by sending a payload with the defined type.
-   */
-  resume: (token: string, payload: T) => Promise<HookEntity | null>;
+interface TypedHook<TInput, TOutput> {
+  /** Creates the hook. Call inside a "use workflow" function. */
+  create(options?: HookOptions): Hook<TOutput>;
+  /** Resumes the hook from runtime code. Resolves to the resumed hook; throws HookNotFoundError if the token does not match an active hook. */
+  resume(token: string, payload: TInput): Promise<HookEntity>;
 }
-export default DefineHook;`}
+export default TypedHook;`}
 />
 
+`create()` is called inside a `"use workflow"` function to create the hook; `resume()` is called from runtime code (an API route or server action). When a `schema` is provided, `resume()` accepts the raw input type (`TInput`) and the workflow receives the validated and possibly transformed output type (`TOutput`); without a schema, `TOutput` defaults to `TInput`. `resume()` throws [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error) if the token does not match an active hook. It does not return `null`.
+
 ## Examples
 
-### Basic Type-Safe Hook Definition
+### Basic type-safe hook definition
 
 By defining the hook once with a specific payload type, you can reuse it in multiple workflows and API routes with automatic type safety.
 
@@ -91,30 +88,35 @@ export async function workflowWithApproval() {
 }
 ```
 
-### Resuming with Type Safety
+### Resuming with type safety
 
-Hooks can be resumed using the same defined hook and a token. By using the same hook, you can ensure that the payload matches the defined type when resuming a hook.
+Hooks can be resumed using the same defined hook and a token. By using the same hook, you can ensure that the payload matches the defined type when resuming a hook. `resume()` resolves to the resumed hook and throws [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error) if the token does not match an active hook.
 
 ```typescript lineNumbers
+import { HookNotFoundError } from "workflow/errors";
+
 // Use the same defined hook to resume
 export async function POST(request: Request) {
   const { token, approved, comment } = await request.json();
 
-  // Type-safe resumption - TypeScript ensures the payload matches
-  const result = await approvalHook.resume(token, { // [!code highlight]
-    approved, // [!code highlight]
-    comment, // [!code highlight]
-  }); // [!code highlight]
-
-  if (!result) {
-    return Response.json({ error: "Hook not found" }, { status: 404 });
+  try {
+    // Type-safe resumption - TypeScript ensures the payload matches
+    const hook = await approvalHook.resume(token, { // [!code highlight]
+      approved, // [!code highlight]
+      comment, // [!code highlight]
+    }); // [!code highlight]
+
+    return Response.json({ success: true, runId: hook.runId });
+  } catch (error) {
+    if (HookNotFoundError.is(error)) { // [!code highlight]
+      return Response.json({ error: "Hook not found" }, { status: 404 });
+    }
+    throw error;
   }
-
-  return Response.json({ success: true, runId: result.runId });
 }
 ```
 
-### Validate and Transform with Schema
+### Validate and transform with schema
 
 You can provide runtime validation and transformation of hook payloads using the `schema` option. This option accepts any validator that conforms to the [Standard Schema v1](https://standardschema.dev) specification.
 
@@ -172,7 +174,7 @@ export async function POST(request: Request) {
 }
 ```
 
-#### Using Other Standard Schema Libraries
+#### Using other Standard Schema libraries
 
 The same pattern works with any Standard Schema v1 compliant library. Here's an example with [Valibot](https://valibot.dev):
 
@@ -188,7 +190,7 @@ export const approvalHook = defineHook({
 });
 ```
 
-### Customizing Tokens
+### Customizing tokens
 
 Tokens are used to identify a specific hook and for resuming a hook. You can customize the token to be more specific to a use case.
 
@@ -209,7 +211,9 @@ export async function slackBotWorkflow(channelId: string) {
 }
 ```
 
-## Related Functions
+`create()` accepts the same options as `createHook()`. If a newer run should replace one that still holds the token, pass [`experimental_force: true`](/docs/api-reference/workflow/create-hook#take-over-a-token-another-run-holds) to take the token over instead of getting [`HookConflictError`](/docs/api-reference/workflow-errors/hook-conflict-error).
+
+## Related functions
 
-* [`createHook()`](/docs/api-reference/workflow/create-hook) - Create a hook in a workflow.
-* [`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.
+- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook): Resume a hook with a payload.