workflow 5.0.0-beta.43 → 5.0.0-beta.44

package/docs/cookbook/agent-patterns/human-in-the-loop.mdx

@@ -13,14 +13,14 @@ summary: Use defineHook with the tool call ID to suspend an agent for human appr
 This recipe uses the deprecated `DurableAgent` API. For new agents, use AI SDK's [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) and follow the [migration guide](https://ai-sdk.dev/v7/docs/agents/workflow-agent#migrating-from-durableagent). The human-in-the-loop pattern here (hooks, `Promise.race`, approval gating) applies to either API.
 </Callout>
 
-Use this pattern when an AI agent needs human confirmation before performing a consequential action like booking, purchasing, or publishing. The workflow suspends without consuming resources until the human responds.
+Use this pattern when an AI agent needs human confirmation before performing a consequential action like booking, purchasing, or publishing. The workflow suspends without consuming resources until the human responds through a user interface (UI) or API.
 
 ## When to use this
 
 - Booking confirmations where users must approve before charges are made
 - Content publishing gates where an editor must sign off
-- Any agent action where the cost of getting it wrong justifies a human check
-- Actions with side effects that can't be easily undone
+- Agent actions where the cost of an error justifies a human check
+- Actions with side effects that are difficult to reverse
 
 ## Pattern
 
@@ -67,7 +67,7 @@ async function confirmBooking({ flightId, passenger }: {
 }
 
 // Stream a custom data part so the client can render the approval UI.
-// This MUST run before the hook suspends the workflow — otherwise
+// This MUST run before the hook suspends the workflow, otherwise
 // the tool-invocation won't appear in the stream until the tool returns,
 // and the client would have no way to show approval buttons.
 async function emitApprovalRequest(details: {
@@ -107,7 +107,7 @@ async function emitApprovalResolved(details: {
   }
 }
 
-// No "use step" — hooks are workflow-level primitives
+// No "use step": hooks are workflow-level primitives
 async function requestBookingApproval(
   { flightId, passenger, price }: {
     flightId: string;
@@ -238,26 +238,26 @@ const approvalResult = messages
 
 ## How it works
 
-1. **`defineHook()` with schema** — creates a typed hook with Zod validation. The approval payload is validated before the workflow receives it.
-2. **`toolCallId` as token** — the approval tool uses the tool call ID as the hook token, naturally linking the hook to the specific tool invocation.
-3. **`emitApprovalRequest` step** — writes a `data-approval-needed` custom data part to the stream *before* the hook suspends. Without this, the client would never see the approval controls because tool invocations don't stream until the tool returns.
-4. **No `"use step"` on the approval tool** — the tool runs at the workflow level because `defineHook().create()` is a workflow primitive. It calls step functions (`emitApprovalRequest`, `emitApprovalResolved`, `confirmBooking`) for I/O.
-5. **`Promise.race` with sleep** — the approval races against a durable timeout. If nobody responds, the workflow continues with an expiration message.
-6. **`emitApprovalResolved` step** — writes the outcome to the stream so the client can update the card immediately, without waiting for the tool-invocation result.
+1. **`defineHook()` with schema**: Creates a typed hook with Zod validation. The approval payload is validated before the workflow receives it.
+2. **`toolCallId` as token**: Uses the tool call ID as the hook token, linking the hook to the specific tool invocation.
+3. **`emitApprovalRequest` step**: Writes a `data-approval-needed` custom data part to the stream *before* the hook suspends. Without this step, the client wouldn't see the approval controls because tool invocations don't stream until the tool returns.
+4. **No `"use step"` on the approval tool**: Runs the tool at the workflow level because `defineHook().create()` is a workflow primitive. The tool calls step functions (`emitApprovalRequest`, `emitApprovalResolved`, and `confirmBooking`) for I/O.
+5. **`Promise.race` with sleep**: Races the approval against a durable timeout. If nobody responds, the workflow continues with an expiration message.
+6. **`emitApprovalResolved` step**: Writes the outcome to the stream so the client can update the card immediately without waiting for the tool-invocation result.
 
 ## Adapting to your use case
 
-- **Change the approval schema** — add fields like `reason`, `amount`, `reviewerEmail` to match your domain.
-- **Multiple approval gates** — the pattern works for any number of tools. Each tool creates its own hook with its own `toolCallId`.
-- **Escalation** — if the first approver doesn't respond, use `sleep()` + another hook to escalate to a backup reviewer.
-- **Adjust timeout** — use `"24h"` for production, shorter durations for demos.
-- **Workflow-level vs step tools** — tools that use `sleep()`, `defineHook()`, or other workflow primitives must NOT use `"use step"`. Tools with only I/O (API calls, DB queries) should use `"use step"` for retries.
+- **Change the approval schema**: Add fields such as `reason`, `amount`, and `reviewerEmail` to match your domain.
+- **Multiple approval gates**: Apply the pattern to any number of tools. Each tool creates its own hook with its own `toolCallId`.
+- **Escalation**: If the first approver doesn't respond, use `sleep()` and another hook to escalate to a backup reviewer.
+- **Adjust the timeout**: Use `"24h"` for production and shorter durations for demos.
+- **Workflow-level versus step tools**: Tools that use `sleep()`, `defineHook()`, or other workflow primitives must not use `"use step"`. Tools with only I/O, such as API calls and database queries, should use `"use step"` for retries.
 
 ## Key APIs
 
-- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions) — declares the orchestrator function
-- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions) — declares step functions with retries
-- [`defineHook()`](/docs/api-reference/workflow/define-hook) — type-safe hook with schema validation
-- [`sleep()`](/docs/api-reference/workflow/sleep) — durable timeout for approval expiry
-- [`getWritable()`](/docs/api-reference/workflow/get-writable) — stream custom data parts from steps
-- [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent) — AI SDK's durable agent (replaces `DurableAgent`)
+- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions): Declares the orchestrator function.
+- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions): Declares step functions with retries.
+- [`defineHook()`](/docs/api-reference/workflow/define-hook): Defines a type-safe hook with schema validation.
+- [`sleep()`](/docs/api-reference/workflow/sleep): Provides a durable timeout for approval expiration.
+- [`getWritable()`](/docs/api-reference/workflow/get-writable): Streams custom data parts from steps.
+- [`WorkflowAgent`](https://ai-sdk.dev/v7/docs/agents/workflow-agent#workflowagent): Provides AI SDK's durable agent and replaces `DurableAgent`.

package/docs/cookbook/common-patterns/batching.mdx

@@ -13,7 +13,7 @@ Use batching when you need to process a large list of items in parallel while co
 
 ## When to use this
 
-- Bulk data imports (contacts, orders, products from a CSV)
+- Bulk data imports (contacts, orders, or products from a comma-separated values (CSV) file)
 - Processing hundreds or thousands of items against external APIs
 - Calling rate-limited APIs where you need to control concurrency
 - Any fan-out where you want failure isolation between groups
@@ -21,7 +21,7 @@ Use batching when you need to process a large list of items in parallel while co
 ## How it works
 
 1. Records are split into fixed-size batches.
-2. Each batch runs in parallel via `Promise.allSettled` — failures in one record don't affect others.
+2. Each batch runs in parallel through `Promise.allSettled`, so failures in one record don't affect others.
 3. A `sleep()` between batches paces requests to avoid overloading downstream services.
 4. After all batches, a summary is returned with succeeded/failed counts.
 
@@ -45,7 +45,7 @@ export async function batchImport(records: Record[], batchSize: number) {
   for (let i = 0; i < records.length; i += batchSize) {
     const batch = records.slice(i, i + batchSize);
 
-    // Run batch in parallel — failures are isolated per record
+    // Run batch in parallel: failures are isolated per record
     const outcomes = await Promise.allSettled( // [!code highlight]
       batch.map((record) => processRecord(record))
     );
@@ -89,21 +89,21 @@ async function processRecord(record: Record): Promise<string> {
 
 ## Adapting to your use case
 
-- Replace the `Record` type with your actual data shape (orders, images, products, etc.).
-- Replace `processRecord()` with your real import logic — DB upserts, API calls, file processing.
+- Replace the `Record` type with your actual data shape, such as orders, images, or products.
+- Replace `processRecord()` with your import logic, such as database upserts, API calls, or file processing.
 - Tune `batchSize` and the `sleep()` duration to match your downstream rate limits.
-- Add or remove tracking as needed — the pattern works with any item type.
+- Add or remove tracking as needed; the pattern works with any item type.
 
 ## Tips
 
-- **Use `Promise.allSettled` over `Promise.all`** when you want to continue even if some items fail. `Promise.all` rejects on the first failure; `allSettled` waits for everything and tells you what failed.
-- **Tune batch size to your downstream API limits.** If the API allows 10 concurrent requests, use `batchSize: 10`.
-- **Add pacing with `sleep()`** between batches to respect rate limits. The sleep is durable — it survives cold starts.
-- **Each `processRecord` call is an independent step.** If one fails, it retries up to 3 times without affecting other items in the batch.
+- **Use `Promise.allSettled` instead of `Promise.all`**: Use this pattern when you want to continue even if some items fail. `Promise.all` rejects on the first failure, while `allSettled` waits for everything and identifies failures.
+- **Tune batch size to your downstream API limits**: If the API allows 10 concurrent requests, use `batchSize: 10`.
+- **Add pacing with `sleep()`**: Add a delay between batches to respect rate limits. The sleep is durable and survives cold starts.
+- **Treat each `processRecord` call as an independent step**: If one call fails, it retries up to three times without affecting other items in the batch.
 
 ## Key APIs
 
-- [`"use workflow"`](/docs/foundations/workflows-and-steps) -- marks the orchestrator function
-- [`"use step"`](/docs/foundations/workflows-and-steps) -- marks functions that run with full Node.js access
-- [`sleep()`](/docs/api-reference/workflow/sleep) -- pacing delay between batches
-- [`Promise.allSettled()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled) -- runs items in parallel, isolating failures
+- [`"use workflow"`](/docs/foundations/workflows-and-steps): Marks the orchestrator function.
+- [`"use step"`](/docs/foundations/workflows-and-steps): Marks functions that run with full Node.js access.
+- [`sleep()`](/docs/api-reference/workflow/sleep): Adds a pacing delay between batches.
+- [`Promise.allSettled()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled): Runs items in parallel and isolates failures.

package/docs/cookbook/common-patterns/idempotency.mdx

@@ -6,7 +6,7 @@ summary: Use step IDs for retry-safe external calls, and use deterministic hook
 ---
 
 <CopyPrompt
-  text="Make this workflow's side effects idempotent. For retry-safe external calls, read the deterministic step ID inside the &quot;use step&quot; function with `getStepMetadata()` from `workflow` and pass `stepId` as the idempotency key to the external API (for example Stripe's `Idempotency-Key` header) so step retries deduplicate. For duplicate workflow starts, derive a deterministic hook token from the domain key (for example `order:${orderId}`): in the API route, look up the active hook with `getHookByToken(token)` from `workflow/api` — catching `HookNotFoundError` from `workflow/errors` — and reuse its `runId`, otherwise call `start(...)`; inside the workflow, create the hook with the same token and check `await hook.getConflict()` before duplicate-sensitive work. Verify retried steps deduplicate, duplicate starts reuse the active run, and conflicts are handled."
+  text="Make this workflow's side effects idempotent. For retry-safe external calls, read the deterministic step ID inside the &quot;use step&quot; function with `getStepMetadata()` from `workflow` and pass `stepId` as the idempotency key to the external API (for example Stripe's `Idempotency-Key` header) so step retries deduplicate. For duplicate workflow starts, derive a deterministic hook token from the domain key (for example `order:${orderId}`): in the API route, look up the active hook with `getHookByToken(token)` from `workflow/api` (catching `HookNotFoundError` from `workflow/errors`) and reuse its `runId`, otherwise call `start(...)`; inside the workflow, create the hook with the same token and check `await hook.getConflict()` before duplicate-sensitive work. Verify retried steps deduplicate, duplicate starts reuse the active run, and conflicts are handled."
 />
 
 Use idempotency when a retry or duplicate request should not repeat the underlying work. In Workflow, there are two common patterns: use the step ID for retry-safe external calls, and use hook tokens to coordinate duplicate workflow starts.
@@ -82,14 +82,14 @@ export async function POST(request: Request) {
 }
 ```
 
-The workflow should create the deterministic hook and check `await hook.getConflict()` before duplicate-sensitive work — awaiting `getConflict()` suspends the workflow to commit the hook registration and resolves with the conflicting run when another active run already owns the token (or `null` once the hook is registered). See [Run idempotency](/docs/foundations/idempotency#run-idempotency) for the full pattern, including how to steer an active run with `resumeHook()` and how to handle the current race between `start()` and hook registration.
+The workflow should create the deterministic hook and check `await hook.getConflict()` before duplicate-sensitive work: awaiting `getConflict()` suspends the workflow to commit the hook registration and resolves with the conflicting run when another active run already owns the token (or `null` once the hook is registered). See [Run idempotency](/docs/foundations/idempotency#run-idempotency) for the full pattern, including how to steer an active run with `resumeHook()` and how to handle the current race between `start()` and hook registration.
 
 ## Key APIs
 
-- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions) -- declares the orchestrator function
-- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions) -- declares step functions with full Node.js access
-- [`getStepMetadata()`](/docs/api-reference/workflow/get-step-metadata) -- provides the deterministic `stepId` for idempotency keys
-- [`createHook()`](/docs/api-reference/workflow/create-hook) -- creates a hook with an optional deterministic token
-- [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) -- finds the Hook that owns a token
-- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) -- resumes the active hook when the duplicate request carries data
-- [`start()`](/docs/api-reference/workflow-api/start) -- starts a new workflow run
+- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions): Declares the orchestrator function.
+- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions): Declares step functions with full Node.js access.
+- [`getStepMetadata()`](/docs/api-reference/workflow/get-step-metadata): Provides the deterministic `stepId` for idempotency keys.
+- [`createHook()`](/docs/api-reference/workflow/create-hook): Creates a hook with an optional deterministic token.
+- [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token): Finds the hook that owns a token.
+- [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook): Resumes the active hook when the duplicate request carries data.
+- [`start()`](/docs/api-reference/workflow-api/start): Starts a new workflow run.

package/docs/cookbook/common-patterns/rate-limiting.mdx

@@ -67,7 +67,7 @@ async function upsertToWarehouse(contactId: string, contact: unknown) {
 }
 ```
 
-## Pattern: Exponential backoff
+## Pattern: exponential backoff
 
 Use `getStepMetadata()` to access the current attempt number and calculate increasing delays:
 
@@ -90,7 +90,7 @@ async function callFlakeyApi(endpoint: string) {
 }
 ```
 
-## Pattern: Circuit breaker with sleep
+## Pattern: circuit breaker with sleep
 
 When a dependency is completely down, stop hitting it for a cooldown period using `sleep()`, then probe with a single test request:
 
@@ -138,7 +138,7 @@ async function callService(requestNum: number): Promise<boolean> {
 }
 ```
 
-## Pattern: Custom max retries
+## Pattern: custom max retries
 
 Override the default retry count (3) for steps that need more or fewer attempts:
 

package/docs/cookbook/common-patterns/saga.mdx

@@ -20,8 +20,8 @@ Use the saga pattern when a business transaction spans multiple services and you
 ## How it works
 
 1. Each forward step does work and registers a compensation function.
-2. If any step throws `FatalError`, the catch block runs compensations in reverse (LIFO) order to restore consistency.
-3. Regular errors are retried automatically (up to 3x by default). Use `FatalError` only for permanent failures where retrying won't help.
+2. If any step throws `FatalError`, the catch block runs compensations in reverse, or last in, first out (LIFO), order to restore consistency.
+3. Regular errors are retried automatically, up to three times by default. Use `FatalError` only for permanent failures where retrying won't help.
 
 ## Pattern
 
@@ -53,7 +53,7 @@ export async function subscriptionUpgradeSaga(accountId: string, seats: number)
     const entitlementId = await provisionSeats(accountId, seats);
     compensations.push(() => deprovisionSeats(accountId, entitlementId)); // [!code highlight]
 
-    // No compensation — notifications are fire-and-forget
+    // No compensation: notifications are fire-and-forget
     await sendConfirmation(accountId, invoiceId, entitlementId);
 
     return { status: "completed" };
@@ -70,7 +70,7 @@ export async function subscriptionUpgradeSaga(accountId: string, seats: number)
 
 ### Step functions
 
-Each step is a `"use step"` function with full Node.js access (fetch, fs, npm packages). Forward steps do the work and throw `FatalError` on permanent failure; compensation steps undo it and must be idempotent — safe to call multiple times if the workflow restarts mid-rollback.
+Each step is a `"use step"` function with full Node.js access (fetch, fs, npm packages). Forward steps do the work and throw `FatalError` on permanent failure; compensation steps undo it and must be idempotent: safe to call multiple times if the workflow restarts mid-rollback.
 
 ```typescript
 import { FatalError } from "workflow";
@@ -122,7 +122,7 @@ async function sendConfirmation(
   });
 }
 
-// Compensation steps — must be idempotent
+// Compensation steps: must be idempotent
 
 async function releaseSeats(accountId: string, reservationId: string): Promise<void> {
   "use step";
@@ -151,7 +151,7 @@ async function deprovisionSeats(accountId: string, entitlementId: string): Promi
 
 ### Streaming step progress (optional)
 
-Use `getWritable()` to stream progress events to a UI so users can see each step execute in real time.
+Use `getWritable()` to stream progress events to a user interface (UI) so users can see each step execute in real time.
 
 ```typescript
 import { FatalError } from "workflow";
@@ -204,7 +204,7 @@ export async function subscriptionUpgradeSaga(accountId: string, seats: number)
     compensations.push({ name: "Deprovision Seats", execute: () => deprovisionSeats(accountId, entitlementId) });
     await emit({ type: "step_done", step: "Provision Seats", detail: entitlementId });
 
-    // No compensation — notifications are fire-and-forget
+    // No compensation: notifications are fire-and-forget
     await emit({ type: "step_start", step: "Send Confirmation" });
     await sendConfirmation(accountId, invoiceId, entitlementId);
     await emit({ type: "step_done", step: "Send Confirmation", detail: "sent" });
@@ -231,21 +231,21 @@ export async function subscriptionUpgradeSaga(accountId: string, seats: number)
 ## Adapting to your use case
 
 - Replace the step functions with real API calls. Each `"use step"` function has full Node.js access.
-- Add or remove steps as needed — the pattern scales to any number of steps.
-- Make compensations idempotent — they may be retried if the workflow restarts mid-rollback.
-- The `emit()` calls and `SagaEvent` type are optional — remove them if you don't need real-time UI progress.
+- Add or remove steps as needed; the pattern scales to any number of steps.
+- Make compensations idempotent, since they may be retried if the workflow restarts mid-rollback.
+- The `emit()` calls and `SagaEvent` type are optional; remove them if you don't need real-time UI progress.
 
 ## Tips
 
-- **Use `FatalError` for permanent failures.** Regular errors trigger automatic retries (up to 3 by default). Throw `FatalError` when retrying won't help (e.g., insufficient funds, invalid input).
-- **Make compensations idempotent.** If a compensation step is retried, it should produce the same result. Check whether the resource was already released before releasing it again.
-- **Compensation steps are also `"use step"` functions.** This makes them durable — if the workflow restarts mid-rollback, it resumes where it left off.
-- **Capture values in closures carefully.** Use block-scoped variables or copy values before pushing compensations to avoid referencing stale state.
-- **Notifications don't need compensations.** Fire-and-forget steps like sending emails or Slack messages typically don't register a compensation.
+- **Use `FatalError` for permanent failures**: Regular errors trigger automatic retries, up to three times by default. Throw `FatalError` when retrying won't help, such as for insufficient funds or invalid input.
+- **Make compensations idempotent**: If a compensation step is retried, it should produce the same result. Check whether the resource was already released before releasing it again.
+- **Use `"use step"` functions for compensation steps**: This makes them durable. If the workflow restarts during rollback, it resumes where it left off.
+- **Capture values in closures carefully**: Use block-scoped variables or copy values before pushing compensations to avoid referencing stale state.
+- **Skip compensations for notifications**: Fire-and-forget steps such as sending emails or Slack messages typically don't register a compensation.
 
 ## Key APIs
 
-- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions) -- declares the orchestrator function
-- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions) -- declares step functions with full Node.js access
-- [`FatalError`](/docs/api-reference/workflow/fatal-error) -- non-retryable error that triggers compensation
-- [`getWritable()`](/docs/api-reference/workflow/get-writable) -- streams data from workflows for real-time UI updates
+- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions): Declares the orchestrator function.
+- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions): Declares step functions with full Node.js access.
+- [`FatalError`](/docs/api-reference/workflow/fatal-error): Represents a non-retryable error that triggers compensation.
+- [`getWritable()`](/docs/api-reference/workflow/get-writable): Streams data from workflows for real-time UI updates.

package/docs/cookbook/common-patterns/scheduling.mdx

@@ -6,10 +6,10 @@ summary: Schedule future actions with durable sleep that survives cold starts, a
 ---
 
 <CopyPrompt
-  text="Create an interruptible scheduled workflow. Import `defineHook` and `sleep` from `workflow`. Define a cancellation hook such as `export const cancelDrip = defineHook<{ reason?: string }>()`. In an exported workflow function with &quot;use workflow&quot;, create the hook once, send the first message in a &quot;use step&quot; helper, then `await Promise.race([sleep(&quot;2d&quot;).then(() => false), cancelHook.then(() => true)])` before each delayed action. If the hook wins, return a cancelled status; if sleep wins, continue to the next step. Add an API route that calls `cancelDrip.resume(runIdOrToken, { reason })` or `resumeHook()` from `workflow/api`. Verify scheduled delivery, cancellation before sleep completes, and resume after server restart."
+  text="Create an interruptible scheduled workflow. Import `defineHook` and `sleep` from `workflow`. Define a cancellation hook such as `export const cancelDrip = defineHook<{ reason?: string }>()`. In an exported workflow function with &quot;use workflow&quot;, create the hook once, send the first message in a &quot;use step&quot; helper, then `await Promise.race([sleep(&quot;2d&quot;).then(() => false), cancelHook.then(() => true)])` before each delayed action. If the hook wins, return a canceled status; if sleep wins, continue to the next step. Add an API route that calls `cancelDrip.resume(runIdOrToken, { reason })` or `resumeHook()` from `workflow/api`. Verify scheduled delivery, cancellation before sleep completes, and resume after server restart."
 />
 
-Workflow's `sleep()` is durable — it survives cold starts, restarts, and deployments. Combined with `defineHook()` and `Promise.race()`, it becomes the foundation for interruptible scheduled workflows like drip campaigns, reminders, and timed sequences.
+Workflow's `sleep()` is durable: it survives cold starts, restarts, and deployments. Combined with `defineHook()` and `Promise.race()`, it becomes the foundation for interruptible scheduled workflows like drip campaigns, reminders, and timed sequences.
 
 <Callout type="info">
 Scheduled workflows are still pinned to the deployment that started them. If you are building recurring or indefinitely running schedules that should adopt newer code over time, see [Versioning](/docs/foundations/versioning) for the explicit `deploymentId: "latest"` continuation pattern.
@@ -17,13 +17,13 @@ Scheduled workflows are still pinned to the deployment that started them. If you
 
 ## When to use this
 
-- Sending emails on a schedule (drip campaigns, onboarding sequences, reminders)
-- Waiting for a deadline but allowing early cancellation
-- Any pattern where "do X, wait N hours, then do Y" needs to be both reliable and interruptible
+- Sending emails on a schedule, such as drip campaigns, onboarding sequences, or reminders
+- Waiting for a deadline while allowing early cancellation
+- Reliable, interruptible patterns that perform one action, wait for a specified time, and then perform another action
 
 ## Drip campaign with cancellation
 
-A drip campaign sends emails at intervals, sleeping between each. Each sleep races against a cancellation hook — if an external event fires the hook (e.g. user converts, unsubscribes), the campaign stops immediately.
+A drip campaign sends emails at intervals, sleeping between each message. Each sleep races against a cancellation hook. If an external event fires the hook, such as when a user converts or unsubscribes, the campaign stops immediately.
 
 ```typescript
 import { defineHook, sleep } from "workflow";
@@ -105,10 +105,10 @@ export async function POST(req: Request) {
 
 ## How it works
 
-1. **Durable sleep** — `sleep("2d")` persists through restarts at zero compute cost. The workflow resumes precisely when the timer fires.
-2. **Hook creation** — `cancelDrip.create({ token })` registers a hook that resolves when any external system calls `.resume()` with the same token.
-3. **Race** — `Promise.race([sleep(...), hook])` blocks until either the timer fires or the hook is resumed, whichever comes first.
-4. **Fresh hooks per window** — after a sleep completes normally, the previous hook instance is consumed. A new `.create()` call registers a fresh hook for the next sleep window, reusing the same token.
+1. **Durable sleep**: `sleep("2d")` persists through restarts at zero compute cost. The workflow resumes when the timer fires.
+2. **Hook creation**: `cancelDrip.create({ token })` registers a hook that resolves when any external system calls `.resume()` with the same token.
+3. **Race**: `Promise.race([sleep(...), hook])` blocks until either the timer fires or the hook is resumed, whichever comes first.
+4. **Fresh hooks per window**: After a sleep completes normally, the previous hook instance is consumed. A new `.create()` call registers a fresh hook for the next sleep window, reusing the same token.
 
 <Callout type="info">
 Deterministic hook tokens can also serve as the idempotency point for scheduled runs. If duplicate schedule starts would send duplicate campaigns or reminders, create a hook with a token derived from the campaign key near the beginning of the workflow and route retries through that hook. If two scheduled starts race, the duplicate run can detect the conflict early with `await hook.getConflict()`, which resolves with the active owner so the duplicate can defer to it. See [Idempotency](/docs/foundations/idempotency).
@@ -116,22 +116,22 @@ Deterministic hook tokens can also serve as the idempotency point for scheduled
 
 ## Adapting to your use case
 
-- **Change durations** — replace `"2d"` with any duration string (`"1h"`, `"7d"`, `"30m"`) or a `Date` object for absolute times.
-- **Add more steps** — the pattern scales to any number of email-then-sleep pairs.
-- **Snooze instead of cancel** — resolve the hook with a `snooze` payload and sleep again: `sleep(new Date(Date.now() + payload.snoozeMs))`.
-- **Timeout any operation** — the same `Promise.race(sleep, work)` pattern works for adding deadlines to slow steps.
-- **Real providers** — swap the `sendEmail` step body for Resend, Postmark, or any HTTP API. The `"use step"` function has full Node.js access.
+- **Change durations**: Replace `"2d"` with any duration string (`"1h"`, `"7d"`, or `"30m"`) or a `Date` object for absolute times.
+- **Add more steps**: The pattern scales to any number of email-then-sleep pairs.
+- **Snooze instead of cancel**: Resolve the hook with a `snooze` payload and sleep again with `sleep(new Date(Date.now() + payload.snoozeMs))`.
+- **Set a timeout for any operation**: Use the same `Promise.race(sleep, work)` pattern to add deadlines to slow steps.
+- **Use production providers**: Replace the `sendEmail` step body with Resend, Postmark, or any HTTP API. The `"use step"` function has full Node.js access.
 
 ## Tips
 
-- **`sleep()` accepts** duration strings (`"1d"`, `"2h"`, `"30s"`), milliseconds, or `Date` objects for sleeping until a specific time.
-- **Durable means durable.** A `sleep("7d")` workflow costs nothing while sleeping — no compute, no memory.
-- **Use `sleep()` in workflow context only.** Step functions cannot call `sleep()` directly. If a step needs a delay, use `setTimeout` inside the step.
+- **Pass supported values to `sleep()`**: Use duration strings (`"1d"`, `"2h"`, or `"30s"`), milliseconds, or `Date` objects for sleeping until a specific time.
+- **Sleeping consumes no compute or memory**: A workflow waiting on `sleep("7d")` consumes no compute or memory while sleeping.
+- **Use `sleep()` only in workflow context**: Step functions cannot call `sleep()` directly. If a step needs a delay, use `setTimeout` inside the step.
 
 ## Key APIs
 
-- [`"use workflow"`](/docs/foundations/workflows-and-steps) — marks the orchestrator function
-- [`"use step"`](/docs/foundations/workflows-and-steps) — marks functions that run with full Node.js access
-- [`sleep()`](/docs/api-reference/workflow/sleep) — durable wait (survives restarts, zero compute cost)
-- [`defineHook()`](/docs/api-reference/workflow/define-hook) — creates a typed hook that external systems can fire
-- [`Promise.race()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race) — races sleep against hooks for interruptible waits
+- [`"use workflow"`](/docs/foundations/workflows-and-steps): Marks the orchestrator function.
+- [`"use step"`](/docs/foundations/workflows-and-steps): Marks functions that run with full Node.js access.
+- [`sleep()`](/docs/api-reference/workflow/sleep): Provides a durable wait that survives restarts with zero compute cost.
+- [`defineHook()`](/docs/api-reference/workflow/define-hook): Creates a typed hook that external systems can fire.
+- [`Promise.race()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race): Races sleep against hooks for interruptible waits.

package/docs/cookbook/common-patterns/sequential-and-parallel.mdx

@@ -1,8 +1,8 @@
 ---
 title: Sequential & Parallel Execution
-description: Compose steps with familiar async/await patterns — sequential await, Promise.all, and Promise.race.
+description: Compose steps with familiar async/await patterns, sequential await, Promise.all, and Promise.race.
 type: guide
-summary: Workflows are just async functions, so all the standard composition primitives (await, Promise.all, Promise.race) apply unchanged — including racing webhooks against durable sleeps.
+summary: Workflows are plain async functions, so all the standard composition primitives (await, Promise.all, Promise.race) apply unchanged, including racing webhooks against durable sleeps.
 related:
   - /docs/foundations/workflows-and-steps
   - /cookbook/common-patterns/timeouts
@@ -10,17 +10,17 @@ related:
 ---
 
 <CopyPrompt
-  text="Compose these workflow steps with standard async/await patterns. In the exported &quot;use workflow&quot; function, chain dependent &quot;use step&quot; calls with sequential `await`; run independent steps concurrently by starting them without `await` and awaiting `Promise.all([...])`; and use `Promise.race([...])` to act on whichever promise settles first. These compose with durable primitives — race a step or a webhook from `createWebhook()` against `sleep()` from `workflow` for deadlines. Keep every step input and output serializable, and remember `Promise.race` does not cancel the losing branch — it keeps running — so side-effectful losers need idempotency keys. Verify sequential ordering, parallel execution, and both race outcomes."
+  text="Compose these workflow steps with standard async/await patterns. In the exported &quot;use workflow&quot; function, chain dependent &quot;use step&quot; calls with sequential `await`; run independent steps concurrently by starting them without `await` and awaiting `Promise.all([...])`; and use `Promise.race([...])` to act on whichever promise settles first. These compose with durable primitives: race a step or a webhook from `createWebhook()` against `sleep()` from `workflow` for deadlines. Keep every step input and output serializable, and remember `Promise.race` does not cancel the losing branch (it keeps running), so side-effectful losers need idempotency keys. Verify sequential ordering, parallel execution, and both race outcomes."
 />
 
-Workflows are written in plain async/await — there's no new control-flow API to learn. Sequential awaits chain steps that depend on each other, `Promise.all` runs independent steps in parallel, and `Promise.race` returns whichever finishes first. These compose with workflow primitives like [`sleep()`](/docs/api-reference/workflow/sleep) and [`createWebhook()`](/docs/api-reference/workflow/create-webhook) since those are also just promises.
+Workflows are written in plain async/await: there's no new control-flow API to learn. Sequential awaits chain steps that depend on each other, `Promise.all` runs independent steps in parallel, and `Promise.race` returns whichever finishes first. These compose with workflow primitives like [`sleep()`](/docs/api-reference/workflow/sleep) and [`createWebhook()`](/docs/api-reference/workflow/create-webhook) since those are also promises.
 
 ## When to use this
 
-- **Pipelines** — each step depends on the previous step's output (validate → process → store)
-- **Independent fan-out** — fetch multiple resources or perform multiple actions that don't depend on each other
-- **Race conditions** — return as soon as one of N operations completes (timeout, first-responder, deadline)
-- **Mixing primitives** — running steps, sleeps, and webhooks side-by-side in the same control-flow expression
+- **Pipelines**: Each step depends on the previous step's output (validate → process → store).
+- **Independent fan-out**: Fetch multiple resources or perform multiple actions that don't depend on each other.
+- **Race conditions**: Return as soon as one operation completes, such as for a timeout, first responder, or deadline.
+- **Mixing primitives**: Run steps, sleeps, and webhooks side by side in the same control-flow expression.
 
 ## Pattern
 
@@ -68,7 +68,7 @@ export async function fetchUserData(userId: string) {
 
 ### Race with `Promise.race`
 
-`Promise.race` resolves as soon as the first promise settles. Since [`sleep()`](/docs/api-reference/workflow/sleep) and [`createWebhook()`](/docs/api-reference/workflow/create-webhook) return promises, they compose naturally — for example, waiting for a webhook callback with a deadline:
+`Promise.race` resolves as soon as the first promise settles. Since [`sleep()`](/docs/api-reference/workflow/sleep) and [`createWebhook()`](/docs/api-reference/workflow/create-webhook) return promises, they compose naturally. For example, waiting for a webhook callback with a deadline:
 
 ```typescript lineNumbers
 import { sleep, createWebhook } from "workflow";
@@ -90,11 +90,11 @@ export async function runExternalTask(userId: string) {
 }
 ```
 
-For racing operations against deadlines specifically (timeouts), see the dedicated [Timeouts](/cookbook/common-patterns/timeouts) recipe — it covers result discrimination, `FatalError` semantics, and the "loser keeps running" caveat.
+For racing operations against deadlines specifically (timeouts), see the dedicated [Timeouts](/cookbook/common-patterns/timeouts) recipe, which covers result discrimination, `FatalError` semantics, and the "loser keeps running" caveat.
 
 ### Combining sequential, parallel, and durable primitives
 
-Most real workflows combine all three. Here's a simplified version of the [birthday card generator demo](https://github.com/vercel/workflow-examples/tree/main/birthday-card-generator) — sequential card generation, parallel RSVP fan-out, non-blocking webhook collection, and a durable sleep until the birthday:
+Most workflows combine all three patterns. The following simplified version of the [birthday card generator demo](https://github.com/vercel/workflow-examples/tree/main/birthday-card-generator) uses sequential card generation, parallel invitation-response fan-out, non-blocking webhook collection, and a durable sleep until the birthday:
 
 ```typescript lineNumbers
 import { createWebhook, sleep, type Webhook } from "workflow";
@@ -136,24 +136,24 @@ export async function birthdayWorkflow(
 
 ## How it works
 
-1. **`await` is durable.** When the workflow awaits a step, the runtime persists the step's input, suspends the workflow, runs the step, and replays the workflow with the step's result on resume. The same applies to `sleep()` and `createWebhook()`.
-2. **`Promise.all` runs steps concurrently.** Each promise in the array is suspended on its own and the workflow resumes only when all have settled. Failures propagate — if any promise rejects, the whole `Promise.all` rejects.
-3. **`Promise.race` resolves on the first settle.** The losing promises keep running in the background but their results are discarded by the workflow.
-4. **All primitives are promises.** `sleep("1 day")` and `createWebhook()` return promises, so they compose with `Promise.all` / `Promise.race` exactly like steps do — this is what makes patterns like "race a webhook against a 24-hour deadline" a one-liner.
+1. **`await` is durable**: When the workflow awaits a step, the runtime persists the step's input, suspends the workflow, runs the step, and replays the workflow with the step's result on resume. The same applies to `sleep()` and `createWebhook()`.
+2. **`Promise.all` runs steps concurrently**: Each promise in the array is suspended on its own, and the workflow resumes only when all have settled. If any promise rejects, the whole `Promise.all` rejects.
+3. **`Promise.race` resolves when the first promise settles**: The losing promises keep running in the background, but the workflow discards their results.
+4. **All primitives are promises**: `sleep("1 day")` and `createWebhook()` return promises, so they compose with `Promise.all` and `Promise.race` like steps do. This behavior enables patterns such as racing a webhook against a 24-hour deadline.
 
 ## Adapting to your use case
 
-- **Replace `Promise.all` with `Promise.allSettled`** when partial failures should not abort the rest. You'll get an array of `{ status, value | reason }` instead of throwing on the first rejection.
-- **Bound the parallelism** — `Promise.all` over 1000 items will fan out 1000 concurrent steps. If your downstream APIs can't handle that, batch the array into chunks (see [Batching](/cookbook/common-patterns/batching)).
-- **Add a deadline to any race** — pair the operation with `sleep("30s").then(() => "timeout" as const)` and check the discriminated result. See [Timeouts](/cookbook/common-patterns/timeouts).
-- **Mix steps and hooks in a race** — wait for an external signal *or* a deadline *or* a step result, all in the same `Promise.race`. The first one to resolve wins.
+- **Replace `Promise.all` with `Promise.allSettled`**: Use this option when partial failures shouldn't abort the remaining operations. You'll get an array of `{ status, value | reason }` instead of an error on the first rejection.
+- **Bound the parallelism**: `Promise.all` over 1,000 items will fan out 1,000 concurrent steps. If your downstream APIs can't handle that, batch the array into chunks (see [Batching](/cookbook/common-patterns/batching)).
+- **Add a deadline to any race**: Pair the operation with `sleep("30s").then(() => "timeout" as const)` and check the discriminated result. See [Timeouts](/cookbook/common-patterns/timeouts).
+- **Mix steps and hooks in a race**: Wait for an external signal, a deadline, or a step result in the same `Promise.race`. The first promise to resolve wins.
 
 ## Key APIs
 
-- [`"use workflow"`](/docs/foundations/workflows-and-steps) — marks the orchestrator function
-- [`"use step"`](/docs/foundations/workflows-and-steps) — marks functions with full Node.js access
-- [`sleep()`](/docs/api-reference/workflow/sleep) — durable sleep that survives restarts
-- [`createWebhook()`](/docs/api-reference/workflow/create-webhook) — webhook URL the workflow can race against
-- [`Promise.all()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all) — wait for all promises
-- [`Promise.race()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race) — wait for the first to settle
-- [`Promise.allSettled()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled) — wait for all, including failures
+- [`"use workflow"`](/docs/foundations/workflows-and-steps): Marks the orchestrator function.
+- [`"use step"`](/docs/foundations/workflows-and-steps): Marks functions with full Node.js access.
+- [`sleep()`](/docs/api-reference/workflow/sleep): Provides durable sleep that survives restarts.
+- [`createWebhook()`](/docs/api-reference/workflow/create-webhook): Provides a webhook URL that the workflow can race against.
+- [`Promise.all()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all): Waits for all promises.
+- [`Promise.race()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race): Waits for the first promise to settle.
+- [`Promise.allSettled()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled): Waits for all promises, including failures.

package/docs/cookbook/common-patterns/timeouts.mdx

@@ -2,7 +2,7 @@
 title: Timeouts
 description: Add deadlines to slow operations by racing them against a durable sleep.
 type: guide
-summary: Use `Promise.race` with `sleep()` to bound the time any step, hook, or webhook is allowed to take — and recover gracefully when the deadline fires first.
+summary: Use `Promise.race` with `sleep()` to bound the time any step, hook, or webhook is allowed to take, and recover gracefully when the deadline fires first.
 related:
   - /docs/api-reference/workflow/sleep
   - /docs/foundations/hooks
@@ -11,17 +11,17 @@ related:
 ---
 
 <CopyPrompt
-  text="Add a deadline to this slow workflow operation. Import `sleep` from `workflow`. In the exported &quot;use workflow&quot; function, race the operation against a durable sleep: `await Promise.race([slowStep(...), deadline(&quot;10m&quot;)])`, where `deadline` is a helper that awaits `sleep(duration)` and returns a sentinel value or throws. Branch on the winner: continue normally on success, run the fallback or compensation path on timeout. Use the same pattern to bound hooks and webhooks. `Promise.race` does not cancel the loser — the underlying step keeps running — so pass an `AbortSignal` into the step for cooperative cancellation and make non-idempotent side effects retry-safe with idempotency keys. Verify the fast path, the timeout path, and side-effect safety when the loser completes late."
+  text="Add a deadline to this slow workflow operation. Import `sleep` from `workflow`. In the exported &quot;use workflow&quot; function, race the operation against a durable sleep: `await Promise.race([slowStep(...), deadline(&quot;10m&quot;)])`, where `deadline` is a helper that awaits `sleep(duration)` and returns a sentinel value or throws. Branch on the winner: continue normally on success, run the fallback or compensation path on timeout. Use the same pattern to bound hooks and webhooks. `Promise.race` does not cancel the loser (the underlying step keeps running), so pass an `AbortSignal` into the step for cooperative cancellation and make non-idempotent side effects retry-safe with idempotency keys. Verify the fast path, the timeout path, and side-effect safety when the loser completes late."
 />
 
-A common requirement is bounding how long a workflow waits for something to finish — a slow step, an external webhook, a human approval. Race the operation against a durable `sleep()` with `Promise.race()` — whichever finishes first wins, and the loser keeps running but its result is ignored.
+Workflows often need to limit how long they wait for a slow step, an external webhook, or human approval. Race the operation against a durable `sleep()` with `Promise.race()`. The first operation to finish wins, while the other keeps running and its result is ignored.
 
 ## When to use this
 
-- **Slow steps** — bound the time spent waiting on third-party APIs, model calls, or expensive computation
-- **External callbacks** — give webhooks a deadline so the workflow doesn't hang forever waiting for an event that may never arrive
-- **Human approvals** — auto-decline or escalate when a hook isn't resumed within a window
-- **Polling loops** — give an outer poll-until-ready loop an overall budget
+- **Slow steps**: bound the time spent waiting on third-party APIs, model calls, or expensive computation
+- **External callbacks**: give webhooks a deadline so the workflow doesn't hang forever waiting for an event that may never arrive
+- **Human approvals**: auto-decline or escalate when a hook isn't resumed within a window
+- **Polling loops**: give an outer poll-until-ready loop an overall budget
 
 ## Pattern
 
@@ -50,7 +50,7 @@ export async function processWithTimeout(data: string) {
 
 ### Timeout on a webhook
 
-The same pattern works for any promise — including hooks and webhooks. Here a webhook waits for an external service to call back, with a hard deadline of 7 days:
+The same pattern works for any promise, including hooks and webhooks. Here a webhook waits for an external service to call back, with a hard deadline of 7 days:
 
 ```typescript lineNumbers
 import { sleep, createWebhook } from "workflow";
@@ -78,27 +78,27 @@ export async function waitForApproval(requestId: string) {
 
 ## How it works
 
-1. **Durable sleep** — `sleep("30s")` persists through restarts at zero compute cost. The workflow resumes precisely when the timer fires.
-2. **Race** — `Promise.race([work, sleep(...)])` returns the value of whichever promise resolves first. The loser keeps running in the background but its result is ignored by the workflow.
-3. **Discriminated result** — tagging the sleep branch with a sentinel value (`"timeout" as const`, `{ timedOut: true }`) lets TypeScript narrow the result and pick the right branch.
-4. **Throw to fail the workflow** — inside a workflow function, throwing an `Error` exits the run with that error. Use `FatalError` inside steps; throw plain errors inside workflows.
+1. **Durable sleep**: `sleep("30s")` persists through restarts at zero compute cost. The workflow resumes precisely when the timer fires.
+2. **Race**: `Promise.race([work, sleep(...)])` returns the value of whichever promise resolves first. The loser keeps running in the background but its result is ignored by the workflow.
+3. **Discriminated result**: tagging the sleep branch with a sentinel value (`"timeout" as const`, `{ timedOut: true }`) lets TypeScript narrow the result and pick the right branch.
+4. **Throw to fail the workflow**: inside a workflow function, throwing an `Error` exits the run with that error. Use `FatalError` inside steps; throw plain errors inside workflows.
 
 <Callout type="warn">
-**The losing operation keeps running.** `Promise.race` doesn't cancel — when the sleep wins, the underlying step (or model call, or HTTP request) continues to completion in the background. This is fine for idempotent reads but matters when the operation has side effects or costs money. Pass an `AbortSignal` into the step to cancel it cooperatively, and use idempotency keys for non-idempotent side effects. See the [Cancellation Guide](/docs/foundations/cancellation) and [Idempotency](/docs/foundations/idempotency) for patterns.
+**The losing operation keeps running.** `Promise.race` doesn't cancel: when the sleep wins, the underlying step (or model call, or HTTP request) continues to completion in the background. This is fine for idempotent reads but matters when the operation has side effects or costs money. Pass an `AbortSignal` into the step to cancel it cooperatively, and use idempotency keys for non-idempotent side effects. See the [Cancellation Guide](/docs/foundations/cancellation) and [Idempotency](/docs/foundations/idempotency) for patterns.
 </Callout>
 
 ## Adapting to your use case
 
-- **Different durations** — `sleep()` accepts duration strings (`"30s"`, `"5m"`, `"7 days"`), milliseconds, or `Date` objects for absolute deadlines.
-- **Soft timeout (retry)** — instead of throwing, loop and retry with a fresh `Promise.race` and a backoff.
-- **Soft timeout (fallback)** — return a default value when the timer wins instead of throwing: `if (result === "timeout") return cachedFallback`.
-- **Combine with cancellation** — race three promises: the operation, a deadline `sleep()`, and a cancellation hook. See the [Scheduling cookbook](/cookbook/common-patterns/scheduling) for the cancellation half of this pattern.
-- **Per-step deadlines** — wrap each step in its own `Promise.race` for independent budgets, or use a single outer race for an overall workflow deadline.
+- **Different durations**: `sleep()` accepts duration strings (`"30s"`, `"5m"`, `"7 days"`), milliseconds, or `Date` objects for absolute deadlines.
+- **Soft timeout (retry)**: instead of throwing, loop and retry with a fresh `Promise.race` and a backoff.
+- **Soft timeout (fallback)**: return a default value when the timer wins instead of throwing: `if (result === "timeout") return cachedFallback`.
+- **Combine with cancellation**: race three promises: the operation, a deadline `sleep()`, and a cancellation hook. See the [Scheduling cookbook](/cookbook/common-patterns/scheduling) for the cancellation half of this pattern.
+- **Per-step deadlines**: wrap each step in its own `Promise.race` for independent budgets, or use a single outer race for an overall workflow deadline.
 
 ## Key APIs
 
-- [`sleep()`](/docs/api-reference/workflow/sleep) — durable wait (survives restarts, zero compute cost)
-- [`createWebhook()`](/docs/api-reference/workflow/create-webhook) — create a webhook URL the workflow can race against
-- [`defineHook()`](/docs/api-reference/workflow/define-hook) — typed hook for in-process cancellation
-- [Idempotency](/docs/foundations/idempotency) — protect side effects that may keep running after a timeout
-- [`Promise.race()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race) — race operations against deadlines
+- [`sleep()`](/docs/api-reference/workflow/sleep): durable wait (survives restarts, zero compute cost)
+- [`createWebhook()`](/docs/api-reference/workflow/create-webhook): create a webhook URL the workflow can race against
+- [`defineHook()`](/docs/api-reference/workflow/define-hook): typed hook for in-process cancellation
+- [Idempotency](/docs/foundations/idempotency): protect side effects that may keep running after a timeout
+- [`Promise.race()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race): race operations against deadlines