workflow 5.0.0-beta.5 → 5.0.0-beta.50

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

@@ -1,16 +1,14 @@
 ---
 title: "workflow/api"
-description: Runtime functions to inspect runs, start workflows, and access world data.
+description: Runtime functions to inspect runs, start workflows, and manage hooks.
 type: overview
 summary: Explore runtime functions for starting workflows, inspecting runs, and managing hooks.
 ---
 
-API reference for runtime functions from the `workflow/api` package.
+The `workflow/api` package provides runtime functions to inspect runs, start new runs, and manage hooks.
 
 ## Functions
 
-The API package is for access and introspection of workflow data to inspect runs, start new runs, or access anything else directly accessible by the world.
-
 <Cards>
     <Card href="/docs/api-reference/workflow-api/start" title="start()">
         Start/enqueue a new workflow run.
@@ -27,10 +25,8 @@ The API package is for access and introspection of workflow data to inspect runs
     <Card href="/docs/api-reference/workflow-api/get-run" title="getRun()">
         Get workflow run status and metadata without waiting for completion.
     </Card>
-    <Card href="/docs/api-reference/workflow-api/get-world" title="getWorld()">
-        Async: resolve the World instance for storage, queuing, and streaming backends.
-    </Card>
-    <Card href="/docs/api-reference/workflow-api/world" title="World SDK">
-        Low-level API for inspecting runs, steps, events, hooks, streams, and queues.
-    </Card>
 </Cards>
+
+<Callout type="info">
+  Looking for `getWorld()` and the World SDK? They are exported from `workflow/runtime`. See the [`workflow/runtime` reference](/docs/api-reference/workflow-runtime).
+</Callout>

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

@@ -7,11 +7,16 @@ prerequisites:
   - /docs/foundations/hooks
 related:
   - /docs/api-reference/workflow-api/resume-webhook
+  - /docs/foundations/idempotency
 ---
 
 Resumes a workflow run by sending a payload to a hook identified by its token.
 
-It creates a `hook_received` event and re-triggers the workflow to continue execution.
+It durably writes the `hook_received` event and only then publishes a workflow wake. The call resolves only after both operations succeed, in that order.
+
+`resumeHook()` throws `HookNotFoundError` when no hook holds the token or when its `hook_received` write is refused because the hook was disposed or the run ended. See [durable hook resume](/docs/changelog/lazy-hook-resume).
+
+If `resumeHook()` throws any other error, the outcome is ambiguous only in dispatch, never in durability: the event may already be durable even though the workflow wake failed, and any later wake of the run delivers it. Calling `resumeHook()` again creates a new `resumeId` and can append a second `hook_received`. Callers that need at-most-once behavior across separate invocations must retain and deduplicate their own request key.
 
 <Callout type="warn">
 `resumeHook` is a runtime function that must be called from outside a workflow function.
@@ -34,7 +39,7 @@ export async function POST(request: Request) {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -47,18 +52,18 @@ showSections={["parameters"]}
 
 ### Returns
 
-Returns a `Promise<Hook>` that resolves to:
+Returns a `Promise<ResumedHook>`, a `Hook` (from `workflow/api`) extended with an optional `resilientResume` flag. Resolving means the payload is durably recorded as `hook_received` and the workflow wake was accepted. `resilientResume` is retained for source compatibility and is no longer set by any path. Resuming never reads the hook's metadata, so the resolved hook's `metadata` is a Promise that hydrates on first access, exactly as with [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token): `await hook.metadata` to read it. The resolved hook:
 
 <TSDoc
 definition={`
-import type { Hook } from "@workflow/world";
+import type { Hook } from "workflow/api";
 export default Hook;`}
 showSections={["returns"]}
 />
 
 ## Examples
 
-### Basic API Route
+### Basic API route
 
 Using `resumeHook` in a basic API route to resume a hook:
 
@@ -81,7 +86,7 @@ export async function POST(request: Request) {
 }
 ```
 
-### With Type Safety
+### With type safety
 
 Defining a payload type and using `resumeHook` to resume a hook with type safety:
 
@@ -109,7 +114,7 @@ export async function POST(request: Request) {
 }
 ```
 
-### Server Action (Next.js)
+### Server action (Next.js)
 
 Using `resumeHook` in Next.js server actions to resume a hook:
 
@@ -128,7 +133,7 @@ export async function approveRequest(token: string, approved: boolean) {
 }
 ```
 
-### Webhook Handler
+### Webhook handler
 
 Using `resumeHook` in a generic webhook handler to resume a hook:
 
@@ -155,8 +160,64 @@ export async function POST(request: Request) {
 }
 ```
 
-## Related Functions
+### Resume or start
+
+A common endpoint shape is "resume or start": one route that resumes the active workflow run for a business key if one exists, or starts a new run otherwise. This comes up when the workflow uses a deterministic hook token as its idempotency key, for example, one active run per order or conversation.
+
+`resumeHook()` is the resume half of that flow. Try it first; if it throws `HookNotFoundError`, no active run owns the token yet, so start the workflow. One subtlety: `start()` returns before the new run executes and registers its hook, so you cannot resume immediately after starting. Retry the resume until the hook is registered: if you drop the payload and only start the workflow, the data from this request is lost.
+
+```typescript lineNumbers
+import { resumeHook, start } from "workflow/api";
+import { HookNotFoundError } from "workflow/errors";
+import { processOrder } from "./workflows/process-order";
+
+type OrderRequest = { confirmed: boolean };
+
+async function resumeWithRetry(token: string, payload: OrderRequest) {
+  for (let attempt = 0; attempt < 5; attempt++) {
+    try {
+      return await resumeHook(token, payload); // [!code highlight]
+    } catch (error) {
+      if (!HookNotFoundError.is(error)) throw error;
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+
+  throw new Error("Workflow did not register its hook in time");
+}
+
+export async function POST(request: Request) {
+  const { orderId, confirmed } = await request.json();
+  const token = `order:${orderId}`;
+  const payload = { confirmed };
+
+  try {
+    // An active run already owns this token: resume it.
+    const hook = await resumeHook(token, payload); // [!code highlight]
+    return Response.json({ runId: hook.runId, reused: true });
+  } catch (error) {
+    if (!HookNotFoundError.is(error)) throw error;
+  }
+
+  // No hook yet: start a new run, then retry the resume so this
+  // request's payload still reaches the workflow.
+  const run = await start(processOrder, [orderId]); // [!code highlight]
+  const resumed = await resumeWithRetry(token, payload);
+
+  // A concurrent request can win the race between `start()` and hook
+  // registration; the resume always reaches the actual active owner.
+  return Response.json({
+    runId: resumed.runId,
+    reused: resumed.runId !== run.runId,
+  });
+}
+```
+
+See [Run idempotency](/docs/foundations/idempotency#run-idempotency) for the full pattern, including how the workflow claims the token with `hook.getConflict()` and how concurrent starts converge on one active owner.
+
+## Related functions
 
-- [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) - Get hook details before resuming.
-- [`createHook()`](/docs/api-reference/workflow/create-hook) - Create a hook in a workflow.
-- [`defineHook()`](/docs/api-reference/workflow/define-hook) - Type-safe hook helper.
+- [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token): Get hook details before resuming.
+- [`createHook()`](/docs/api-reference/workflow/create-hook): Create a hook in a workflow.
+- [`defineHook()`](/docs/api-reference/workflow/define-hook): Type-safe hook helper.
+- [Idempotency](/docs/foundations/idempotency): Deduplicate step side effects and workflow starts.

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

@@ -11,7 +11,7 @@ related:
 
 Resumes a workflow run by sending an HTTP `Request` to a webhook identified by its token.
 
-This function creates a `hook_received` event and re-triggers the workflow to continue execution. It's designed to be called from API routes or server actions that receive external HTTP requests.
+This function publishes a workflow invocation carrying the request; the runtime creates the `hook_received` event from it and continues execution. It's designed to be called from API routes or server actions that receive external HTTP requests.
 
 <Callout type="warn">
 `resumeWebhook` is a runtime function that must be called from outside a workflow function.
@@ -37,7 +37,7 @@ export async function POST(request: Request) {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -50,16 +50,18 @@ showSections={['parameters']}
 
 ### Returns
 
-Returns a `Promise<Response>` that resolves to:
+Returns a `Promise<Response>` that resolves to one of:
 
-- `Response`: The HTTP response from the workflow's `respondWith()` call
+- A `202 Accepted` response when the webhook was created in the default mode (no `respondWith` option).
+- The exact `Response` object configured via `createWebhook({ respondWith: new Response(...) })`.
+- The workflow's manual `Response` when the webhook was created with `createWebhook({ respondWith: "manual" })` and a step calls `request.respondWith(response)`.
 
-Throws an error if the webhook token is not found or invalid.
+Throws [`HookNotFoundError`](/docs/api-reference/workflow-errors/hook-not-found-error) if the token does not match an active webhook.
 
-## Usage Note
+## Usage note
 
 <Callout type="warn">
-In most cases, you should not need to call `resumeWebhook()` directly. When you use `createWebhook()`, the framework automatically generates a random webhook token and provides a public URL at `/.well-known/workflow/v1/webhook/:token`. External systems can send HTTP requests directly to that URL.
+In most cases, you should not need to call `resumeWebhook()` directly. When you use `createWebhook()`, the framework automatically generates a webhook token and provides a public URL at `/.well-known/workflow/v1/webhook/:token`. External systems can send HTTP requests directly to that URL.
 
 For server-side hook resumption with deterministic tokens, use [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) with [`createHook()`](/docs/api-reference/workflow/create-hook) instead.
 </Callout>
@@ -81,14 +83,14 @@ export async function POST(request: Request) {
 
   try {
     const response = await resumeWebhook(token, request); // [!code highlight]
-    return response; // Returns the workflow's custom response
+    return response; // 202 Accepted, a configured static Response, or a manual workflow response
   } catch (error) {
     return new Response("Webhook not found", { status: 404 });
   }
 }
 ```
 
-## Related Functions
+## Related functions
 
 - [`createWebhook()`](/docs/api-reference/workflow/create-webhook) - Create a webhook in a workflow
 - [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) - Resume a hook with arbitrary payload

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

@@ -2,9 +2,11 @@
 title: start
 description: Start and enqueue a new workflow run.
 type: reference
-summary: Use start to programmatically enqueue a new workflow run from outside a workflow function.
+summary: Use start to programmatically enqueue a new workflow run.
 prerequisites:
   - /docs/foundations/starting-workflows
+related:
+  - /docs/foundations/idempotency
 ---
 
 Start/enqueue a new workflow run.
@@ -16,7 +18,7 @@ import { myWorkflow } from "./workflows/my-workflow";
 const run = await start(myWorkflow); // [!code highlight]
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -48,21 +50,26 @@ showSections={["returns"]}
 
 Learn more about [`WorkflowReadableStreamOptions`](/docs/api-reference/workflow-api/get-run#workflowreadablestreamoptions).
 
-## Good to Know
+## Good to know
 
-* The `start()` function is used in runtime/non-workflow contexts to programmatically trigger workflow executions.
+* Use the `start()` function in runtime contexts to programmatically trigger workflow executions.
+* In v5, you can also call `start()` directly from a workflow function to spawn a child run or continue work in a new run. See [Workflow Composition](/cookbook/common-patterns/workflow-composition) and [Versioning](/docs/foundations/versioning).
 * This is different from calling workflow functions directly, which is the typical pattern in Next.js applications.
-* The function returns immediately after enqueuing the workflow - it doesn't wait for the workflow to complete.
+* The function returns immediately after enqueuing the workflow. It doesn't wait for the workflow to complete.
+* Each call to `start()` creates a new workflow run. If retried requests must route to one active workflow, have the workflow create a deterministic hook token and use [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) to reuse an already-registered active hook. The lookup is not atomic with `start()`, so concurrent callers can still create extra runs before the hook is registered. Handle that race inside the workflow by checking `await hook.getConflict()` before duplicate-sensitive work. On a conflict, it resolves with the run that owns the token, so the duplicate can return the active owner to the caller. If duplicates must be rejected before a workflow body runs, keep a durable request record until native atomic start-and-hook registration exists. See [Idempotency](/docs/foundations/idempotency#run-idempotency).
 * All arguments must be [serializable](/docs/foundations/serialization).
-* When `deploymentId` is provided, the argument types and return type become `unknown` since there is no guarantee the workflow function's types will be consistent across different deployments.
+* When you provide `deploymentId`, the argument types and return type become `unknown` because the workflow function's types may differ across deployments.
+* `attributes` seeds plaintext run metadata as part of creation and requires a World implementing spec version 4 or later. Keys that start with `$` are reserved for framework and library code; framework-level callers can pass `allowReservedAttributes: true` to seed reserved keys, with the same semantics as the [`setAttributes`](/docs/api-reference/workflow/set-attributes) option of the same name.
+* `region` pins the new run to a specific region on Worlds with a regional dimension. The [Vercel World](/worlds/vercel#explicit-region-selection) then serves the run's storage, queue dispatch, and streams from that region. When you omit `region`, the run is pinned to the region where it was created. Worlds without regions ignore the option.
+* `experimental_retention` asks the World to delete the run's user data as soon as the run completes or fails, instead of keeping it for the World's default window. `0` requests immediate deletion; `'default'` is identical to omitting the option. These are the only two values accepted — the value is a duration and zero is the only one implemented, and its unit is not yet decided. Recorded as the reserved `$retention` attribute, so it needs a World implementing spec version 4 or later. Retention is enforced by the World, not the SDK: the first-party Worlds implement it and a World that does not keeps the data. Note that `await run.returnValue` on a run started with `experimental_retention: 0` usually throws [`RunExpiredError`](/docs/errors/run-expired) rather than resolving, because the deletion races the read. See [Data retention](/docs/observability/retention).
 
 <Callout type="info">
-If `start()` throws `'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.`, the passed function was not transformed as a workflow. The two most common causes are a missing `"use workflow"` directive or missing framework integration. See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function).
+If `start()` throws `'start' received an invalid workflow function. Ensure the Workflow SDK is configured correctly and the function includes a 'use workflow' directive.`, the compiler did not transform the passed function as a workflow. The two most common causes are a missing `"use workflow"` directive or missing framework integration. See [start-invalid-workflow-function](/docs/errors/start-invalid-workflow-function).
 </Callout>
 
 ## Examples
 
-### With Arguments
+### With arguments
 
 ```typescript
 import { start } from "workflow/api";
@@ -78,13 +85,14 @@ import { start } from "workflow/api";
 import { myWorkflow } from "./workflows/my-workflow";
 
 const run = await start(myWorkflow, ["arg1", "arg2"], { // [!code highlight]
-  deploymentId: "custom-deployment-id" // [!code highlight]
+  deploymentId: "custom-deployment-id", // [!code highlight]
+  attributes: { source: "checkout" } // [!code highlight]
 }); // [!code highlight]
 ```
 
 ### Using `deploymentId: "latest"`
 
-Set `deploymentId` to `"latest"` to automatically resolve the most recent deployment for the current environment. This is useful when you want to ensure a workflow run targets the latest deployed version of your application rather than the deployment that initiated the call.
+Set `deploymentId` to `"latest"` to automatically resolve the most recent deployment for the current environment. This is useful when you want to ensure a workflow run targets the latest deployed version of your application rather than the deployment that initiated the call. For when to use this and how it fits with default run pinning, see [Versioning](/docs/foundations/versioning).
 
 ```typescript
 import { start } from "workflow/api";
@@ -96,12 +104,51 @@ const run = await start(myWorkflow, ["arg1", "arg2"], { // [!code highlight]
 ```
 
 <Callout type="info">
-The `deploymentId` option is currently a Vercel-specific feature. The `"latest"` value resolves to the most recent deployment matching your current environment — the same production target for production deployments, or the same git branch for preview deployments.
+The `deploymentId` option is currently a Vercel-specific feature. Other Worlds may implement this option differently to match their own deployment runtimes, and the World spec may rename it from `deploymentId` to `version` in a future SDK version. On Vercel, `"latest"` resolves to the most recent deployment matching your current environment: the same production target for production deployments, or the same git branch for preview deployments.
+
+In Worlds without atomic, immutable deployments (such as local development or self-hosted Postgres), there is no notion of multiple deployments to resolve between, so `deploymentId: "latest"` has no effect: the SDK logs a warning and the run targets the current deployment. This means a workflow that opts into `"latest"` on Vercel still runs unchanged in local development.
+</Callout>
+
+<Callout type="info">
+Resolving `"latest"` is the one `start()` path that calls the Vercel API, so it
+needs an identity that can see the calling deployment. Inside a Vercel
+deployment the SDK authenticates with the deployment's own OIDC token, which
+carries the owning team, and this takes precedence over a `VERCEL_TOKEN` set in
+the function's environment. A `VERCEL_TOKEN` belongs to a *user* and carries no
+team, so authenticating with it scopes the lookup to that user's default team
+and fails with a 404 whenever that is not the team that owns the deployment.
+Outside a deployment (CLI, CI, the dashboard) `VERCEL_TOKEN` is still used;
+configure the World's `teamId` so the request is scoped explicitly.
 </Callout>
 
 <Callout type="warn">
 When using `deploymentId: "latest"`, the workflow run will execute on a potentially different deployment than the one calling `start()`. Be mindful of forward and backward compatibility:
 
-- **Workflow identity**: The workflow ID is derived from the function name and file path. If the latest deployment has renamed the workflow function or moved it to a different directory, the workflow ID will no longer match and the run will fail to start.
-- **Input and output compatibility**: The arguments passed to `start()` are serialized by the calling deployment but deserialized by the target deployment. Similarly, the workflow's return value is serialized by the target deployment but deserialized by the caller. If the workflow's expected arguments or return type have changed (e.g. added required fields, removed fields, or changed types), the run may fail or behave unexpectedly. Ensure that input and output schemas remain backward-compatible across deployments.
+- **Workflow identity**: The function name and file path determine the workflow ID. If the latest deployment has renamed the workflow function or moved it to a different directory, the workflow ID will no longer match and the run will fail to start.
+- **Input and output compatibility**: The calling deployment serializes the arguments passed to `start()`, and the target deployment deserializes them. Similarly, the target deployment serializes the workflow's return value, and the caller deserializes it. If the workflow's expected arguments or return type have changed (for example, added required fields, removed fields, or changed types), the run may fail or behave unexpectedly. Ensure that input and output schemas remain backward-compatible across deployments.
+</Callout>
+
+### Inside a workflow function
+
+Call `start()` directly from a workflow function to spawn a child run. It is step-backed, so the spawn records a deterministic step boundary in the parent's event log.
+
+```typescript
+import { start } from "workflow/api";
+import { childWorkflow } from "./workflows/child";
+
+export async function parentWorkflow(value: number) {
+  "use workflow";
+
+  const childRun = await start(childWorkflow, [value]); // [!code highlight]
+  const result = await childRun.returnValue; // [!code highlight]
+  return { childRunId: childRun.runId, result };
+}
+```
+
+<Callout type="info">
+The returned `Run` object is fully functional inside a workflow. Each property access or method call (`.status`, `.returnValue`, `.cancel()`) executes as a separate step. See [Workflow Composition](/cookbook/common-patterns/workflow-composition) for choosing between spawning a child run and awaiting a workflow function directly.
+</Callout>
+
+<Callout type="warn">
+`returnValue` polls the child run every second and holds the polling step's worker slot open for as long as the child takes to finish. For long-running children, spawn without awaiting `returnValue` and have the child resume a [hook](/docs/foundations/hooks) when it completes. See the [`startAndWait()` pattern](/cookbook/advanced/child-workflows).
 </Callout>

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

@@ -0,0 +1,18 @@
+---
+title: "workflow/astro"
+description: Astro integration for automatic workflow bundling and route registration.
+type: overview
+summary: Explore the Astro integration for automatic workflow bundling and runtime support.
+related:
+  - /docs/getting-started/astro
+---
+
+Astro integration for Workflow SDK that transforms workflow code and builds the workflow bundles.
+
+## Functions
+
+<Cards>
+    <Card title="workflow()" href="/docs/api-reference/workflow-astro/workflow">
+        Astro integration that transforms workflow code (`"use step"`/`"use workflow"` directives)
+    </Card>
+</Cards>

package/docs/api-reference/workflow-astro/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "workflow/astro",
+  "pages": ["workflow"]
+}

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

@@ -0,0 +1,45 @@
+---
+title: workflow
+description: Configure Astro to transform workflow directives.
+type: reference
+summary: Add the workflow integration to your Astro config to enable workflow directive transformation.
+prerequisites:
+  - /docs/getting-started/astro
+---
+
+Returns an Astro integration that transforms workflow code (`"use step"`/`"use workflow"` directives) and builds the workflow bundles.
+
+## Usage
+
+To enable `"use step"` and `"use workflow"` directives while developing locally or deploying to production, add `workflow()` to the `integrations` array of your Astro config.
+
+```typescript title="astro.config.mjs" lineNumbers
+// @ts-check
+import { defineConfig } from "astro/config";
+import { workflow } from "workflow/astro"; // [!code highlight]
+
+// https://astro.build/config
+export default defineConfig({
+  integrations: [workflow()], // [!code highlight]
+});
+```
+
+The integration registers the workflow Vite transform plugins during `astro:config:setup` and builds the workflow bundles: locally during config setup, or via the Vercel builder after `astro:build:done` when deploying to Vercel.
+
+## API signature
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `WorkflowPluginOptions` | Optional. Configures the workflow build. |
+
+#### WorkflowPluginOptions
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` (dev) / `false` (prod) | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. Defaults to `'inline'` in development and `false` in production (smaller function bundles, which helps stay under the Vercel 250 MB function size limit). Set it explicitly, or use the `WORKFLOW_SOURCEMAP` environment variable, to override in either environment. |
+
+### Returns
+
+Returns an `AstroIntegration` object to include in the `integrations` array of your Astro config.

package/docs/api-reference/workflow-errors/entity-conflict-error.mdx

@@ -26,12 +26,12 @@ try {
   await world.events.create(runId, event);
 } catch (error) {
   if (EntityConflictError.is(error)) { // [!code highlight]
-    // Event already exists — safe to ignore during replay
+    // Event already exists, safe to ignore during replay
   }
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -44,11 +44,11 @@ interface EntityConflictError {
 export default EntityConflictError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `EntityConflictError.is(value)`
 
-Type-safe check for `EntityConflictError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+Type-safe check for `EntityConflictError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.
 
 ```typescript
 import { EntityConflictError } from "workflow/errors"

package/docs/api-reference/workflow-errors/hook-conflict-error.mdx

@@ -0,0 +1,60 @@
+---
+title: HookConflictError
+description: Thrown when creating a hook with a token that is already in use by another workflow run.
+type: reference
+summary: Catch HookConflictError when a hook token is already claimed by another active workflow run.
+related:
+  - /docs/api-reference/workflow/create-hook
+  - /docs/foundations/hooks
+  - /docs/errors/hook-conflict
+---
+
+`HookConflictError` is thrown when creating a hook with a token that is already in use by another active workflow run. Hook tokens must be unique across all running workflows. See the [hook-conflict](/docs/errors/hook-conflict) error guide for resolution strategies.
+
+```typescript lineNumbers
+import { HookConflictError } from "workflow/errors"
+declare function startApprovalWorkflow(token: string): Promise<void>; // @setup
+declare const token: string; // @setup
+
+try {
+  await startApprovalWorkflow(token);
+} catch (error) {
+  if (HookConflictError.is(error)) { // [!code highlight]
+    console.error(
+      `Token "${error.token}" already in use by run ${error.conflictingRunId}`
+    );
+  }
+}
+```
+
+## API signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface HookConflictError {
+  /** The hook token that conflicted. */
+  token: string;
+  /** The run ID of the workflow currently holding the token, when known. */
+  conflictingRunId?: string;
+  /** The error message. */
+  message: string;
+}
+export default HookConflictError;`}
+/>
+
+### Static methods
+
+#### `HookConflictError.is(value)`
+
+Type-safe check for `HookConflictError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.
+
+```typescript
+import { HookConflictError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (HookConflictError.is(error)) {
+  // error is typed as HookConflictError
+}
+```

package/docs/api-reference/workflow-errors/hook-not-found-error.mdx

@@ -10,9 +10,9 @@ related:
 
 `HookNotFoundError` is thrown when calling `resumeHook()` or `resumeWebhook()` with a token that does not match any active hook. This typically happens when:
 
-- The hook has expired (past its TTL)
-- The hook was already consumed and disposed
-- The workflow has not started yet, so the hook does not exist
+- The hook's time to live (TTL) has expired.
+- The hook was already consumed and disposed.
+- The workflow has not started yet, so the hook does not exist.
 
 ```typescript lineNumbers
 import { HookNotFoundError } from "workflow/errors"
@@ -29,7 +29,7 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -44,11 +44,11 @@ interface HookNotFoundError {
 export default HookNotFoundError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `HookNotFoundError.is(value)`
 
-Type-safe check for `HookNotFoundError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+Type-safe check for `HookNotFoundError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.
 
 ```typescript
 import { HookNotFoundError } from "workflow/errors"
@@ -66,7 +66,7 @@ if (HookNotFoundError.is(error)) {
 A common pattern for idempotent workflows is to try resuming a hook, and if it doesn't exist yet, start a new workflow run with the input data.
 
 <Callout>
-This "resume or start" pattern is not atomic — there is a small window where a race condition is possible. A better native approach is being worked on, but this pattern works well for many use cases.
+This "resume or start" pattern is not atomic: there is a small window where a race condition is possible. A better native approach is being worked on, but this pattern works well for many use cases.
 </Callout>
 
 ```typescript lineNumbers
@@ -80,7 +80,7 @@ async function handleIncomingEvent(token: string, data: unknown) {
     await resumeHook(token, data);
   } catch (error) {
     if (HookNotFoundError.is(error)) { // [!code highlight]
-      // Hook doesn't exist yet — start a new workflow run
+      // Hook doesn't exist yet, so start a new workflow run
       await startWorkflow("processEvent", data); // [!code highlight]
     } else {
       throw error;