@workflow/core 5.0.0-beta.2 → 5.0.0-beta.21

package/docs/api-reference/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.
@@ -65,6 +66,8 @@ 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 active hook, 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) if another active hook already owns the same token.
+
 ## Examples
 
 ### Basic Usage
@@ -112,6 +115,40 @@ export async function slackBotWorkflow(channelId: string) {
 }
 ```
 
+### 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`.
+
+On a conflict, the resolved value is a `Run` handle for the run that currently owns the token, with durable step-backed accessors. The duplicate run can decide in code how to handle it: return or log `conflict.runId`, inspect `await conflict.status`, wait on `await conflict.returnValue`, or cancel the owner with `await conflict.cancel()` and continue in the current run. See [Run idempotency](/docs/foundations/idempotency#run-idempotency) for these strategies in context.
+
+<Callout type="info">
+Custom hook tokens are the recommended way to coordinate active workflow runs. Use a deterministic token from your domain, such as an order ID or conversation ID, create the hook near the beginning of the workflow, and check `await hook.getConflict()` before work that depends on owning the token. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
+
 ### Waiting for Multiple Payloads
 
 You can also wait for multiple payloads by using the `for await...of` syntax.
@@ -195,3 +232,4 @@ This is equivalent to manually calling `dispose()` but ensures the hook is alway
 - [`defineHook()`](/docs/api-reference/workflow/define-hook) - Type-safe hook helper
 - [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) - Resume a hook with a payload
 - [`createWebhook()`](/docs/api-reference/workflow/create-webhook) - Higher-level HTTP webhook abstraction
+- [Idempotency](/docs/foundations/idempotency) - Deduplicate step side effects and workflow starts

package/docs/api-reference/create-webhook.mdx

@@ -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
 - 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.

package/docs/api-reference/experimental-set-attributes.mdx

@@ -0,0 +1,65 @@
+---
+title: experimental_setAttributes
+description: Attach string metadata to workflow run for observability.
+type: reference
+summary: Use experimental_setAttributes inside a workflow or step function to set run attributes.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/observability/attributes
+  - /docs/api-reference/workflow/fatal-error
+---
+
+Attaches string metadata to the current workflow run.
+
+<Callout>
+This API is experimental and may change before the stable attributes API is released.
+</Callout>
+
+```typescript lineNumbers
+import { experimental_setAttributes } from "workflow"
+
+export async function orderWorkflow(orderId: string) {
+  "use workflow"
+
+  await experimental_setAttributes({
+    phase: "received",
+    orderId,
+  })
+}
+```
+
+## API Signature
+
+### Parameters
+
+<TSDoc
+definition={`
+import { experimental_setAttributes } from "workflow";
+export default experimental_setAttributes;`}
+showSections={['parameters']}
+/>
+
+## Usage
+
+Call `experimental_setAttributes` from a `"use workflow"` function or a `"use step"` function. Calling it from plain application code is not supported because there is no active workflow run.
+
+Attribute values must be strings. Pass `undefined` to remove an attribute:
+
+```typescript lineNumbers
+import { experimental_setAttributes } from "workflow"
+
+export async function cleanupAttributes() {
+  "use workflow"
+
+  await experimental_setAttributes({ staleKey: undefined })
+}
+```
+
+Attribute keys must be 1-256 characters, values must be strings up to 256 bytes, and each run can have up to 64 attributes. Keys that start with `$` are reserved for framework and library code.
+
+Validation errors throw [`FatalError`](/docs/api-reference/workflow/fatal-error) and fail the run before an attribute write is attempted.
+
+Calls from both workflow and step bodies append a native `attr_set` event, which the World materializes onto `run.attributes`. Workflow-originated events record a workflow writer; step-originated events record the originating step ID and attempt.
+
+Native attributes require spec version 4 or later. Step-body storage errors throw from `experimental_setAttributes`; catch them inside the step if the write should be best-effort. Workflow-body writes are committed when the workflow suspends: transient storage errors are retried with the suspension, while a write the World rejects as invalid — such as exceeding the per-run attribute cap across multiple calls — fails the run with the validation error.

package/docs/api-reference/fetch.mdx

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

package/docs/api-reference/index.mdx

@@ -47,6 +47,9 @@ Workflow SDK contains the following functions you can use inside your workflow f
     <Card href="/docs/api-reference/workflow/get-writable" title="getWritable()">
         Access the current workflow run's default stream.
     </Card>
+    <Card href="/docs/api-reference/workflow/experimental-set-attributes" title="experimental_setAttributes()">
+        Attach experimental string metadata to the current workflow run.
+    </Card>
 </Cards>
 
 ## Error Classes

package/docs/foundations/cancellation.mdx

@@ -0,0 +1,459 @@
+---
+title: Cancellation
+description: Cancel long-running steps cooperatively using AbortSignal, or cancel entire workflow runs.
+type: conceptual
+summary: Cancel in-flight work with AbortSignal or stop entire workflow runs.
+prerequisites:
+  - /docs/foundations/workflows-and-steps
+related:
+  - /docs/foundations/hooks
+  - /docs/how-it-works/cancellation
+---
+
+Workflow DevKit supports two cancellation mechanisms: **AbortSignal** for fine-grained, cooperative cancellation of individual operations, and **run cancellation** for stopping an entire workflow. This guide covers both.
+
+## 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.
+
+```typescript lineNumbers
+import { sleep } from "workflow";
+
+export async function cancellableWorkflow() {
+  "use workflow";
+
+  const controller = new AbortController(); // [!code highlight]
+
+  const result = await Promise.race([
+    longRunningStep(controller.signal), // [!code highlight]
+    sleep("30s").then(() => "timeout" as const),
+  ]);
+
+  if (result === "timeout") {
+    controller.abort(); // [!code highlight]
+    return { status: "timed out" };
+  }
+
+  return { status: "completed", result };
+}
+
+async function longRunningStep(signal: AbortSignal) {
+  "use step";
+
+  const response = await fetch("https://api.example.com/slow-operation", {
+    signal, // [!code highlight]
+  });
+
+  return response.json();
+}
+```
+
+No special imports, no wrapper functions — just the standard `AbortController` API.
+
+<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.
+</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
+
+Race a step against a timeout, and cancel the step if the timeout wins:
+
+```typescript lineNumbers
+import { sleep } from "workflow";
+
+export async function fetchWithTimeout(url: string) {
+  "use workflow";
+
+  const controller = new AbortController();
+
+  const result = await Promise.race([
+    fetchUrl(url, controller.signal),
+    sleep("10s").then(() => null),
+  ]);
+
+  if (result === null) {
+    controller.abort(); // [!code highlight]
+    throw new Error(`Request to ${url} timed out after 10s`);
+  }
+
+  return result;
+}
+
+async function fetchUrl(url: string, signal: AbortSignal) {
+  "use step";
+  const response = await fetch(url, { signal });
+  return response.json();
+}
+```
+
+### Cancelling Parallel Work
+
+When racing multiple steps, cancel the losers:
+
+```typescript lineNumbers
+export async function firstResponder(urls: string[]) {
+  "use workflow";
+
+  const controller = new AbortController();
+
+  const result = await Promise.race( // [!code highlight]
+    urls.map((url) => fetchUrl(url, controller.signal)) // [!code highlight]
+  ); // [!code highlight]
+
+  controller.abort(); // Cancel remaining fetches // [!code highlight]
+
+  return result;
+}
+
+async function fetchUrl(url: string, signal: AbortSignal) {
+  "use step";
+  const response = await fetch(url, { signal });
+  return { url, data: await response.json() };
+}
+```
+
+### Passing Signal Through a Pipeline
+
+Pass the same signal to a chain of steps. Aborting cancels whichever step is currently running:
+
+```typescript lineNumbers
+declare function splitIntoChunks(data: ArrayBuffer): ArrayBuffer[]; // @setup
+declare function processChunk(chunk: ArrayBuffer): Promise<Uint8Array>; // @setup
+
+export async function pipelineWorkflow(dataUrl: string) {
+  "use workflow";
+
+  const controller = new AbortController();
+
+  try {
+    const raw = await downloadData(dataUrl, controller.signal);
+    const transformed = await transformData(raw, controller.signal);
+    const result = await uploadData(transformed, controller.signal);
+    return result;
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      return { status: "cancelled" };
+    }
+    throw err;
+  }
+}
+
+async function downloadData(url: string, signal: AbortSignal) {
+  "use step";
+  const response = await fetch(url, { signal });
+  return response.arrayBuffer();
+}
+
+async function transformData(data: ArrayBuffer, signal: AbortSignal) {
+  "use step";
+
+  signal.throwIfAborted(); // [!code highlight]
+
+  const chunks = splitIntoChunks(data);
+  const results = [];
+
+  for (const chunk of chunks) {
+    signal.throwIfAborted(); // [!code highlight]
+    results.push(await processChunk(chunk));
+  }
+
+  return Buffer.concat(results);
+}
+
+async function uploadData(data: ArrayBuffer, signal: AbortSignal) {
+  "use step";
+  await fetch("https://storage.example.com/upload", {
+    method: "POST",
+    body: data,
+    signal,
+  });
+  return { status: "uploaded" };
+}
+```
+
+### 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:
+
+```typescript lineNumbers
+export async function processWithQuotaCheck(userId: string, dataUrl: string) {
+  "use workflow";
+
+  const controller = new AbortController();
+
+  // Run the work and a quota monitor in parallel
+  const [result] = await Promise.all([ // [!code highlight]
+    processData(dataUrl, controller.signal), // [!code highlight]
+    monitorQuota(userId, controller), // [!code highlight]
+  ]); // [!code highlight]
+
+  return result;
+}
+
+async function processData(url: string, signal: AbortSignal) {
+  "use step";
+  const response = await fetch(url, { signal });
+  const data = await response.arrayBuffer();
+  // ... expensive processing ...
+  return { processed: true };
+}
+
+async function monitorQuota(userId: string, controller: AbortController) {
+  "use step";
+
+  // Poll quota status while the other step is running
+  while (!controller.signal.aborted) {
+    const quota = await fetch(`https://api.example.com/quota/${userId}`);
+    const { exceeded } = await quota.json();
+
+    if (exceeded) {
+      controller.abort("Quota exceeded"); // Cancels processData // [!code highlight]
+      return;
+    }
+
+    await new Promise((resolve) => setTimeout(resolve, 5000));
+  }
+}
+```
+
+### User-Triggered Cancellation with Hooks
+
+Combine hooks with abort controllers to let users cancel in-flight work from an external API:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+export async function userCancellableWorkflow(jobId: string) {
+  "use workflow";
+
+  using cancelHook = createHook<{ reason: string }>({
+    token: `cancel:${jobId}`,
+  });
+
+  const controller = new AbortController();
+  const workPromise = doExpensiveWork(controller.signal);
+
+  const result = await Promise.race([ // [!code highlight]
+    workPromise.then((data) => ({ status: "completed", data })),
+    cancelHook.then((payload) => { // [!code highlight]
+      controller.abort(); // [!code highlight]
+      return { status: "cancelled", reason: payload.reason };
+    }),
+  ]);
+
+  return result;
+}
+
+async function doExpensiveWork(signal: AbortSignal) {
+  "use step";
+  const response = await fetch("https://api.example.com/expensive", { signal });
+  return response.json();
+}
+```
+
+```typescript title="app/api/cancel/route.ts" lineNumbers
+import { resumeHook } from "workflow/api";
+
+export async function POST(request: Request) {
+  const { jobId, reason } = await request.json();
+
+  await resumeHook(`cancel:${jobId}`, { reason });
+  return Response.json({ cancelled: true });
+}
+```
+
+### How Steps Handle Abort
+
+When an `AbortSignal` is aborted, the behavior depends on how the step uses it:
+
+| Usage | Behavior on Abort |
+|-------|-------------------|
+| `fetch(url, { signal })` | Request is cancelled, 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
+
+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.
+
+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`.
+
+```typescript lineNumbers
+import { sleep } from "workflow";
+
+export async function workflow() {
+  "use workflow";
+  const controller = new AbortController();
+
+  try {
+    const result = await Promise.race([
+      cancellableStep(controller.signal),
+      sleep("5s").then(() => null),
+    ]);
+    if (result === null) controller.abort();
+    return result;
+  } catch (err) {
+    // AbortError arrives as FatalError — no retries attempted // [!code highlight]
+    return { status: "cancelled" };
+  }
+}
+
+async function cancellableStep(signal: AbortSignal) {
+  "use step";
+  // If this throws AbortError, it's automatically wrapped in FatalError
+  const response = await fetch("https://api.example.com/slow", { signal });
+  return response.json();
+}
+```
+
+### Passing AbortSignal as Workflow Input
+
+You can pass an `AbortSignal` from external code into a workflow via `start()`:
+
+{/* @skip-typecheck: myWorkflow is not declared, this is a conceptual snippet */}
+```typescript lineNumbers
+import { start } from "workflow/api";
+
+export async function POST(request: Request) {
+  const controller = new AbortController();
+  const run = await start(myWorkflow, [controller.signal]); // [!code highlight]
+
+  // Later, cancel from external code
+  controller.abort(); // [!code highlight]
+}
+```
+
+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).
+
+<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 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";
+
+export async function POST(request: Request) {
+  const { runId } = await request.json();
+
+  const run = getRun(runId);
+  await run.cancel(); // [!code highlight]
+
+  return Response.json({ cancelled: true });
+}
+```
+
+<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.
+</Callout>
+
+When a run is cancelled:
+- 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
+- Streams are closed
+
+<Callout type="info">
+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 | 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 |
+| **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
+
+**Use `throwIfAborted()` before expensive work.** This throws the signal's abort reason if the signal is already aborted, preventing wasted compute:
+
+```typescript lineNumbers
+async function expensiveStep(signal: AbortSignal) {
+  "use step";
+  signal.throwIfAborted(); // [!code highlight]
+  // ... expensive work ...
+}
+```
+
+**Handle abort errors in the workflow.** Abort errors arrive as `FatalError` (no retries) and can be caught with a standard try/catch:
+
+```typescript lineNumbers
+declare function cancellableStep(signal: AbortSignal): Promise<void>; // @setup
+import { FatalError } from "workflow";
+
+export async function workflow() {
+  "use workflow";
+  const controller = new AbortController();
+
+  try {
+    await cancellableStep(controller.signal);
+  } catch (err) {
+    if (FatalError.is(err)) { // [!code highlight]
+      return { status: "cancelled" };
+    }
+    throw err;
+  }
+}
+```
+
+**Use `AbortSignal.any()` to combine signals:**
+
+```typescript lineNumbers
+async function stepWithMultipleSignals(
+  userSignal: AbortSignal,
+  timeoutSignal: AbortSignal
+) {
+  "use step";
+
+  const combined = AbortSignal.any([userSignal, timeoutSignal]); // [!code highlight]
+  const response = await fetch("https://api.example.com/data", {
+    signal: combined,
+  });
+  return response.json();
+}
+```
+
+**Abort after a race:**
+
+```typescript lineNumbers
+declare function stepA(signal: AbortSignal): Promise<string>; // @setup
+declare function stepB(signal: AbortSignal): Promise<string>; // @setup
+
+export async function workflow() {
+  "use workflow";
+  const controller = new AbortController();
+
+  const winner = await Promise.race([
+    stepA(controller.signal),
+    stepB(controller.signal),
+  ]);
+
+  controller.abort(); // Clean up whichever step is still running // [!code highlight]
+  return winner;
+}
+```
+
+This is safe even if both steps have already completed — aborting a finished operation is a no-op.
+
+## 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

package/docs/foundations/errors-and-retries.mdx

@@ -141,7 +141,7 @@ callApi.maxRetries = 5; // Retry up to 5 times on failure (6 total attempts)
 
 ## Error Codes
 
-When a workflow run fails, the error may include a `code` that classifies the failure. You can access it programmatically via the `Run` class:
+When a workflow run fails, the error includes an `errorCode` that classifies the failure, alongside the original thrown value (preserved as `cause`):
 
 ```typescript lineNumbers
 import { WorkflowRunFailedError } from "@workflow/errors";
@@ -153,8 +153,12 @@ try {
   const result = await run.returnValue;
 } catch (err) {
   if (WorkflowRunFailedError.is(err)) {
-    console.log(err.cause.code); // "USER_ERROR", "RUNTIME_ERROR", or undefined
-    console.log(err.cause.message); // The error message
+    console.log(err.errorCode); // "USER_ERROR", "RUNTIME_ERROR", 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) {
+      console.log(err.cause.message); // The error message
+    }
   }
 }
 ```

package/docs/foundations/hooks.mdx

@@ -85,6 +85,35 @@ 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
+
+Sometimes you need to know that a hook token has been claimed, but you do not want to wait for external data yet. Await `hook.getConflict()` for that:
+
+```typescript lineNumbers
+import { createHook } from "workflow";
+
+declare function processOrder(orderId: string): Promise<void>; // @setup
+
+export async function orderWorkflow(orderId: string) {
+  "use workflow";
+
+  using hook = createHook({
+    token: `order:${orderId}`
+  });
+
+  const conflict = await hook.getConflict(); // [!code highlight]
+  if (conflict) { // [!code highlight]
+    // Another active run already owns this token.
+    return { dedupedTo: conflict.runId };
+  }
+
+  // The hook token is registered and reserved here.
+  await processOrder(orderId);
+}
+```
+
+Calling `createHook()` on its own does not register the hook — registration is only committed when the workflow suspends. Awaiting `hook.getConflict()` suspends the workflow to commit the hook registration, then resolves with `null` once the hook is registered and ready to receive payloads, or with a `Run` handle for the run that owns the token if another active hook already claimed it (see [`HookConflictError`](/docs/errors/hook-conflict)). For `hook_conflict` events persisted by older worlds that did not record the owning run's ID, `getConflict()` rejects with `HookConflictError` instead of resolving with an incomplete handle. The conflicting run's accessors are durable steps, so the workflow can inspect `await conflict.status`, wait on `await conflict.returnValue`, or cancel the owner with `await conflict.cancel()` — see [Run idempotency](/docs/foundations/idempotency#run-idempotency) for these strategies.
+
 ### Custom Tokens for Deterministic Hooks
 
 By default, hooks generate 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.