workflow 5.0.0-beta.43 → 5.0.0-beta.46

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

@@ -5,12 +5,10 @@ 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, and manage hooks.
-
 <Cards>
     <Card href="/docs/api-reference/workflow-api/start" title="start()">
         Start/enqueue a new workflow run.
@@ -30,5 +28,5 @@ The API package is for access and introspection of workflow data to inspect runs
 </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).
+  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

@@ -12,9 +12,9 @@ related:
 
 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 publishes a workflow invocation carrying the payload; the runtime creates the `hook_received` event and continues execution from it.
 
-A Hook kept by `experimental_minRetention` after its workflow ends cannot be resumed. `resumeHook()` throws `HookNotFoundError` in that case.
+`resumeHook()` throws `HookNotFoundError` when no hook holds the token. A run that has already ended cannot be resumed, including one whose Hook is kept by `experimental_minRetention`, but whether the call reports that depends on the path it takes: a resume dispatched without reading the run resolves and the ended state is only detected once the payload arrives, while one that reads the run, or that falls back to writing the event up front, throws `HookNotFoundError`. See [lazy hook resume](/docs/changelog/lazy-hook-resume).
 
 <Callout type="warn">
 `resumeHook` 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,7 +50,7 @@ showSections={["parameters"]}
 
 ### Returns
 
-Returns a `Promise<ResumedHook>` — a `Hook` extended with an optional `resilientResume` flag. Resolving means the resume was accepted and the workflow will continue, whether the `hook_received` event was written directly or, on the parallel fast path, delivered through the workflow queue for the runtime to materialize (see the [lazy hook resume changelog](/docs/changelog/resilient-resume)). `resilientResume` is `true` only when the direct event write failed transiently and the resume was recovered through the queue; on the happy path it is absent. The resolved hook:
+Returns a `Promise<ResumedHook>`, a `Hook` extended with an optional `resilientResume` flag. Resolving means the resume was accepted for delivery: the payload rides the workflow queue message and the runtime materializes the `hook_received` event from it before replaying (see the [lazy hook resume changelog](/docs/changelog/lazy-hook-resume)). `resilientResume` is retained for source compatibility and is no longer set by any path. The resolved hook:
 
 <TSDoc
 definition={`
@@ -61,7 +61,7 @@ showSections={["returns"]}
 
 ## Examples
 
-### Basic API Route
+### Basic API route
 
 Using `resumeHook` in a basic API route to resume a hook:
 
@@ -84,7 +84,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:
 
@@ -112,7 +112,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:
 
@@ -131,7 +131,7 @@ export async function approveRequest(token: string, approved: boolean) {
 }
 ```
 
-### Webhook Handler
+### Webhook handler
 
 Using `resumeHook` in a generic webhook handler to resume a hook:
 
@@ -158,11 +158,11 @@ export async function POST(request: Request) {
 }
 ```
 
-### Resume or Start
+### 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.
+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.
+`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";
@@ -213,9 +213,9 @@ export async function POST(request: Request) {
 
 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
+## 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.
-- [Idempotency](/docs/foundations/idempotency) - Deduplicate step side effects and workflow starts.
+- [`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
 
@@ -58,7 +58,7 @@ Returns a `Promise<Response>` that resolves to one of:
 
 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 webhook token and provides a public URL at `/.well-known/workflow/v1/webhook/:token`. External systems can send HTTP requests directly to that URL.
@@ -90,7 +90,7 @@ export async function POST(request: Request) {
 }
 ```
 
-## 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

@@ -18,7 +18,7 @@ import { myWorkflow } from "./workflows/my-workflow";
 const run = await start(myWorkflow); // [!code highlight]
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -50,24 +50,25 @@ 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 contexts to programmatically trigger workflow executions.
-* In v5, `start()` can also be called 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).
+* 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.
-* 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).
+* 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.
 
 <Callout type="info">
-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 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";
@@ -102,7 +103,7 @@ const run = await start(myWorkflow, ["arg1", "arg2"], { // [!code highlight]
 ```
 
 <Callout type="info">
-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.
+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>
@@ -110,13 +111,13 @@ In Worlds without atomic, immutable deployments (such as local development or se
 <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
+### Inside a workflow function
 
-`start()` can be called 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.
+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";
@@ -136,5 +137,5 @@ The returned `Run` object is fully functional inside a workflow. Each property a
 </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).
+`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/workflow.mdx

@@ -24,9 +24,9 @@ export default defineConfig({
 });
 ```
 
-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.
+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
+## API signature
 
 ### Parameters
 
@@ -38,7 +38,7 @@ The integration registers the workflow Vite transform plugins during `astro:conf
 
 | 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 — helps stay under the Vercel 250MB function size limit). Set it explicitly, or use the `WORKFLOW_SOURCEMAP` environment variable, to override in either environment. |
+| `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
 

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

@@ -9,7 +9,7 @@ related:
   - /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.
+`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"
@@ -27,7 +27,7 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -44,11 +44,11 @@ interface HookConflictError {
 export default HookConflictError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `HookConflictError.is(value)`
 
-Type-safe check for `HookConflictError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+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"

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;

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

@@ -11,7 +11,7 @@ API reference for the error classes exported from the `workflow/errors` package.
 
 All errors extend [`WorkflowError`](/docs/api-reference/workflow-errors/workflow-error), so you can catch any SDK error with a single `instanceof` check, or narrow to a specific class for fine-grained handling.
 
-## Base Classes
+## Base classes
 
 <Cards>
     <Card href="/docs/api-reference/workflow-errors/workflow-error" title="WorkflowError">
@@ -22,7 +22,7 @@ All errors extend [`WorkflowError`](/docs/api-reference/workflow-errors/workflow
     </Card>
 </Cards>
 
-## Registration Errors
+## Registration errors
 
 <Cards>
     <Card href="/docs/api-reference/workflow-errors/workflow-not-registered-error" title="WorkflowNotRegisteredError">
@@ -33,7 +33,7 @@ All errors extend [`WorkflowError`](/docs/api-reference/workflow-errors/workflow
     </Card>
 </Cards>
 
-## Run Errors
+## Run errors
 
 <Cards>
     <Card href="/docs/api-reference/workflow-errors/workflow-run-not-found-error" title="WorkflowRunNotFoundError">
@@ -43,7 +43,7 @@ All errors extend [`WorkflowError`](/docs/api-reference/workflow-errors/workflow
         Thrown when awaiting the return value of a failed workflow run.
     </Card>
     <Card href="/docs/api-reference/workflow-errors/workflow-run-cancelled-error" title="WorkflowRunCancelledError">
-        Thrown when awaiting the return value of a cancelled workflow run.
+        Thrown when awaiting the return value of a canceled workflow run.
     </Card>
     <Card href="/docs/api-reference/workflow-errors/workflow-run-not-completed-error" title="WorkflowRunNotCompletedError">
         Thrown when requesting the result of a workflow run that has not completed yet.
@@ -59,7 +59,7 @@ All errors extend [`WorkflowError`](/docs/api-reference/workflow-errors/workflow
     </Card>
 </Cards>
 
-## Hook Errors
+## Hook errors
 
 <Cards>
     <Card href="/docs/api-reference/workflow-errors/hook-not-found-error" title="HookNotFoundError">
@@ -70,7 +70,7 @@ All errors extend [`WorkflowError`](/docs/api-reference/workflow-errors/workflow
     </Card>
 </Cards>
 
-## Backend Errors
+## Backend errors
 
 <Cards>
     <Card href="/docs/api-reference/workflow-errors/throttle-error" title="ThrottleError">

package/docs/api-reference/workflow-errors/precondition-failed-error.mdx

@@ -1,24 +1,24 @@
 ---
 title: PreconditionFailedError
-description: Thrown when an event creation is rejected because the client's event-log snapshot is stale.
+description: World implementations throw this error when they reject an event creation because the client's event-log snapshot is stale.
 type: reference
-summary: Catch PreconditionFailedError when a world rejects an event creation made from a stale event-log snapshot.
+summary: Catch PreconditionFailedError when a World rejects an event creation made from a stale event-log snapshot.
 related:
   - /docs/api-reference/workflow-errors/workflow-world-error
   - /docs/api-reference/workflow-errors/entity-conflict-error
 ---
 
-`PreconditionFailedError` is thrown by world implementations when an event creation is rejected because the client's event-log snapshot is stale: the log already held more events than the position the creation named. It corresponds to HTTP 412 Precondition Failed semantics.
+World implementations throw `PreconditionFailedError` when they reject an event creation because the client's event-log snapshot is stale: the log already held more events than the position the creation named. It corresponds to HTTP 412 Precondition Failed semantics.
 
-No world in this repository throws it. A stale replay does not need to be refused: its log is a prefix rather than a prefix with a hole in it, replay is deterministic on a prefix, and the write it makes next comes back carrying the events it was pushed past (see [Stale reads](/docs/configuration/runtime-tuning#stale-reads-and-why-nothing-has-to-be-rejected)). The error and the runtime's handling of it remain for a world that would rather refuse than report — one that allocates positions somewhere other than the commit, and so cannot report a gap reliably. Event creations that carry no position are never rejected with it.
+No World in this repository throws it. A stale replay does not need to be refused: its log is a prefix rather than a prefix with a hole in it, replay is deterministic on a prefix, and the write it makes next comes back carrying the events it was pushed past (see [Stale reads](/docs/configuration/runtime-tuning#stale-reads-and-why-nothing-has-to-be-rejected)). The error and the runtime's handling of it remain for a World that would rather refuse than report. Such a World allocates positions somewhere other than the commit, so it cannot report a gap reliably. Event creations that carry no position are never rejected with it.
 
-A world rejects only on evidence and accepts the creation whenever it cannot decide, so this error always means the snapshot really was stale — but not receiving it does not prove the snapshot was current.
+A World rejects only on evidence and accepts the creation whenever it cannot decide. This error always means the snapshot was stale, but not receiving it does not prove the snapshot was current.
 
 <Callout>
-The Workflow runtime handles this error automatically: it restarts the replay in the same invocation from a corrected event log, and re-invokes the run for a fresh replay only once its in-process restart budget is spent. It never retries the rejected creation as-is, because a replay working from a corrected log derives different events. You will only encounter it when interacting with world storage APIs directly.
+The Workflow runtime handles this error by restarting the replay in the same invocation from a corrected event log. It re-invokes the run for a fresh replay only after spending its in-process restart budget. It never retries the rejected creation as-is because a replay working from a corrected log derives different events. You will only encounter it when interacting with World storage APIs directly.
 </Callout>
 
-A world may attach the events the client was missing to the rejection as `details`, which lets the runtime restart without re-reading the event log. Doing so is optional, and the runtime falls back to a full reload when the details are absent or unusable.
+A World may attach the events the client was missing to the rejection as `details`, which lets the runtime restart without re-reading the event log. This is optional, and the runtime falls back to a full reload when the details are absent or unusable.
 
 ```typescript lineNumbers
 import { PreconditionFailedError } from "workflow/errors"
@@ -35,7 +35,7 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -52,7 +52,7 @@ interface PreconditionFailedError {
 export default PreconditionFailedError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `PreconditionFailedError.is(value)`
 

package/docs/api-reference/workflow-errors/run-expired-error.mdx

@@ -29,7 +29,7 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -42,7 +42,7 @@ interface RunExpiredError {
 export default RunExpiredError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `RunExpiredError.is(value)`
 

package/docs/api-reference/workflow-errors/run-not-supported-error.mdx

@@ -7,7 +7,7 @@ related:
   - /docs/foundations/versioning
 ---
 
-`RunNotSupportedError` is thrown when reading a workflow run whose data was written with a newer workflow spec version than the running SDK supports. This typically means the run was created by a newer version of the `workflow` package — upgrade the package to process it.
+`RunNotSupportedError` is thrown when reading a workflow run whose data was written with a newer workflow spec version than the running SDK supports. This typically means the run was created by a newer version of the `workflow` package. Upgrade the package to process it.
 
 ```typescript lineNumbers
 import { RunNotSupportedError } from "workflow/errors"
@@ -25,7 +25,7 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -42,11 +42,11 @@ interface RunNotSupportedError {
 export default RunNotSupportedError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `RunNotSupportedError.is(value)`
 
-Type-safe check for `RunNotSupportedError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+Type-safe check for `RunNotSupportedError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.
 
 ```typescript
 import { RunNotSupportedError } from "workflow/errors"

package/docs/api-reference/workflow-errors/step-not-registered-error.mdx

@@ -8,7 +8,7 @@ related:
   - /docs/api-reference/workflow-errors/workflow-not-registered-error
 ---
 
-`StepNotRegisteredError` is thrown when the runtime tries to execute a step function that is not registered in the current deployment. This is an infrastructure error — not a user code error. It typically indicates a build or bundling issue that caused the step to not be included in the deployment.
+`StepNotRegisteredError` is thrown when the runtime tries to execute a step function that is not registered in the current deployment. This is an infrastructure error, not a user code error. It typically indicates a build or bundling issue that caused the step to not be included in the deployment.
 
 When this error occurs, the step fails (like a `FatalError`) and control is passed back to the workflow function, which can handle the failure gracefully.
 
@@ -21,7 +21,7 @@ if (StepNotRegisteredError.is(error)) { // [!code highlight]
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -36,14 +36,14 @@ interface StepNotRegisteredError {
 export default StepNotRegisteredError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `StepNotRegisteredError.is(value)`
 
-Type-safe check for `StepNotRegisteredError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+Type-safe check for `StepNotRegisteredError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.
 
 <Callout>
-The `.is()` method works in server-side Node.js code (API routes, middleware, hooks). Inside `"use workflow"` functions, step errors arrive deserialized from the event log and won't be actual `StepNotRegisteredError` instances — use `error.message` matching instead. See the [troubleshooting page](/docs/errors/step-not-registered) for workflow-side error handling examples.
+The `.is()` method works in server-side Node.js code (API routes, middleware, hooks). Inside `"use workflow"` functions, step errors arrive deserialized from the event log and won't be actual `StepNotRegisteredError` instances. Use `error.message` matching instead. See the [troubleshooting page](/docs/errors/step-not-registered) for workflow-side error handling examples.
 </Callout>
 
 ```typescript

package/docs/api-reference/workflow-errors/throttle-error.mdx

@@ -31,7 +31,7 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -46,7 +46,7 @@ interface ThrottleError {
 export default ThrottleError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `ThrottleError.is(value)`
 

package/docs/api-reference/workflow-errors/too-early-error.mdx

@@ -31,7 +31,7 @@ try {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -46,7 +46,7 @@ interface TooEarlyError {
 export default TooEarlyError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `TooEarlyError.is(value)`
 

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

@@ -17,7 +17,7 @@ const error = new WorkflowError("something went wrong", {
 });
 ```
 
-## API Signature
+## API signature
 
 ### Properties
 
@@ -32,14 +32,14 @@ interface WorkflowError {
 export default WorkflowError;`}
 />
 
-### Static Methods
+### Static methods
 
 #### `WorkflowError.is(value)`
 
-Type-safe check for `WorkflowError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+Type-safe check for `WorkflowError` instances. Preferred over `instanceof` because it works across module boundaries and virtual machine contexts.
 
 <Callout type="warn">
-  `WorkflowError.is()` matches only direct `WorkflowError` instances — not subclasses, which override the error name it checks. To handle a specific error type, use that subclass's own `.is()` method (e.g. `WorkflowRunFailedError.is(error)`).
+  `WorkflowError.is()` matches only direct `WorkflowError` instances, not subclasses, which override the error name it checks. To handle a specific error type, use that subclass's own `.is()` method (e.g. `WorkflowRunFailedError.is(error)`).
 </Callout>
 
 ```typescript