workflow 5.0.0-beta.42 → 5.0.0-beta.44

package/docs/api-reference/workflow-observability/hydrate-resource-io.mdx

@@ -10,7 +10,7 @@ related:
   - /docs/api-reference/workflow-runtime/world/storage
 ---
 
-Hydrates (deserializes) the data fields of a resource returned by the [World SDK](/docs/api-reference/workflow-runtime/world) — a workflow run, step, hook, or event. Workflow data is serialized using the [devalue](https://github.com/Rich-Harris/devalue) format, so this is required before displaying step input/output in a UI.
+Hydrates (deserializes) the data fields of a resource returned by the [World SDK](/docs/api-reference/workflow-runtime/world): a workflow run, step, hook, or event. Workflow data is serialized using the [devalue](https://github.com/Rich-Harris/devalue) format, so this is required before displaying step input/output in a user interface.
 
 The function dispatches on the resource shape: steps get `input`/`output` hydrated, hooks get `metadata`, events get `eventData`, and runs get `input`/`output`.
 
@@ -26,7 +26,7 @@ const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highl
 console.log(hydrated.input, hydrated.output);
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -40,12 +40,12 @@ console.log(hydrated.input, hydrated.output);
 The same resource with its data fields hydrated into plain JavaScript values.
 
 <Callout type="info">
-  Encrypted data fields pass through as raw `Uint8Array` values rather than being decrypted — see [Encrypted Data](/docs/api-reference/workflow-observability#encrypted-data).
+  Encrypted data fields pass through as raw `Uint8Array` values rather than being decrypted. See [Encrypted Data](/docs/api-reference/workflow-observability#encrypted-data).
 </Callout>
 
 ## Examples
 
-### Display a Run's Steps with Hydrated I/O
+### Display a run's steps with hydrated I/O
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";

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

@@ -1,6 +1,6 @@
 ---
 title: "workflow/observability"
-description: Utilities to hydrate serialized step I/O and parse machine-readable workflow names for display.
+description: Utilities to hydrate serialized step input/output (I/O) and parse machine-readable workflow names for display.
 type: overview
 summary: Explore utilities for hydrating serialized workflow data and parsing display names in observability tools.
 keywords:
@@ -16,9 +16,7 @@ keywords:
   - display name parsing
 ---
 
-API reference for observability utilities from the `workflow/observability` package.
-
-The observability package provides utilities for working with workflow data in observability and debugging tools — hydrating serialized step I/O for display, and parsing machine-readable names into display-friendly formats.
+The `workflow/observability` package provides utilities for observability and debugging tools. Use it to hydrate serialized step input/output (I/O) for display and parse machine-readable names into display-friendly formats.
 
 ```typescript lineNumbers
 import { // [!code highlight]
@@ -31,7 +29,7 @@ import { // [!code highlight]
 } from "workflow/observability"; // [!code highlight]
 ```
 
-## Data Hydration
+## Data hydration
 
 <Cards>
     <Card href="/docs/api-reference/workflow-observability/hydrate-resource-io" title="hydrateResourceIO()">
@@ -45,7 +43,7 @@ import { // [!code highlight]
     </Card>
 </Cards>
 
-## Name Parsing
+## Name parsing
 
 <Cards>
     <Card href="/docs/api-reference/workflow-observability/parse-step-name" title="parseStepName()">
@@ -59,6 +57,6 @@ import { // [!code highlight]
     </Card>
 </Cards>
 
-## Encrypted Data
+## Encrypted data
 
-When a [World](/docs/api-reference/workflow-runtime/world) stores encrypted data, the hydration utilities intentionally leave encrypted values untouched: [`hydrateData()`](/docs/api-reference/workflow-observability/hydrate-data) and [`hydrateResourceIO()`](/docs/api-reference/workflow-observability/hydrate-resource-io) return encrypted fields as raw `Uint8Array` values so observability tools can detect them and decide how to render them (for example, the Workflow CLI shows an "Encrypted" placeholder). Decryption is handled by the runtime and the World implementation — see [Encryption](/docs/how-it-works/encryption) for how keys are managed.
+When a [World](/docs/api-reference/workflow-runtime/world) stores encrypted data, the hydration utilities intentionally leave encrypted values untouched: [`hydrateData()`](/docs/api-reference/workflow-observability/hydrate-data) and [`hydrateResourceIO()`](/docs/api-reference/workflow-observability/hydrate-resource-io) return encrypted fields as raw `Uint8Array` values so observability tools can detect them and decide how to render them (for example, the Workflow CLI shows an "Encrypted" placeholder). Decryption is handled by the runtime and the World implementation. See [Encryption](/docs/how-it-works/encryption) for how keys are managed.

package/docs/api-reference/workflow-observability/observability-revivers.mdx

@@ -8,7 +8,7 @@ related:
   - /docs/api-reference/workflow-observability/hydrate-data
 ---
 
-A set of reviver functions that handle the workflow serialization format's workflow-specific types — streams, step/workflow function references, class instances, `AbortController`/`AbortSignal`, and `DOMException` — reviving them as display-friendly marker objects or strings. Built-in JavaScript types (`Date`, `Map`, `Set`, `RegExp`, etc.) are handled by the devalue format itself and need no revivers.
+A set of reviver functions that handle the workflow serialization format's workflow-specific types (streams, step/workflow function references, class instances, `AbortController`/`AbortSignal`, and `DOMException`), reviving them as display-friendly marker objects or strings. Built-in JavaScript types (`Date`, `Map`, `Set`, `RegExp`, etc.) are handled by the devalue format itself and need no revivers.
 
 Pass it as the `revivers` argument to [`hydrateResourceIO()`](/docs/api-reference/workflow-observability/hydrate-resource-io) or [`hydrateData()`](/docs/api-reference/workflow-observability/hydrate-data).
 
@@ -20,7 +20,7 @@ declare const step: Step; // @setup
 const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
 ```
 
-## API Signature
+## API signature
 
 ```typescript
 import type { Revivers } from "workflow/observability";

package/docs/api-reference/workflow-observability/parse-class-name.mdx

@@ -9,7 +9,7 @@ related:
   - /docs/api-reference/workflow-serde
 ---
 
-Serialized class instances reference their class with machine-readable IDs like `class//./src/models//User`. This function parses them into components suitable for display in a UI.
+Serialized class instances reference their class with machine-readable IDs like `class//./src/models//User`. This function parses them into components suitable for display in a user interface.
 
 ```typescript lineNumbers
 import { parseClassName } from "workflow/observability"; // [!code highlight]
@@ -20,7 +20,7 @@ const parsed = parseClassName("class//./src/models//User"); // [!code highlight]
 // parsed?.functionName → "User"
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -35,7 +35,7 @@ const parsed = parseClassName("class//./src/models//User"); // [!code highlight]
 | Property | Description |
 |----------|-------------|
 | `shortName` | The display name of the class (e.g. `"User"`). |
-| `moduleSpecifier` | The module the class is defined in — a relative path (`./src/models`) or a package specifier (`point@0.0.1`). |
+| `moduleSpecifier` | The module the class is defined in: a relative path (`./src/models`) or a package specifier (`point@0.0.1`). |
 | `functionName` | The class name as recorded by the compiler. |
 
 Returns `null` when the input is not a valid class ID.

package/docs/api-reference/workflow-observability/parse-step-name.mdx

@@ -8,7 +8,7 @@ related:
   - /docs/api-reference/workflow-observability/parse-class-name
 ---
 
-Step names are stored as machine-readable identifiers like `step//./src/workflows/order//processPayment`. This function parses them into components suitable for display in a UI.
+Step names are stored as machine-readable identifiers like `step//./src/workflows/order//processPayment`. This function parses them into components suitable for display in a user interface.
 
 ```typescript lineNumbers
 import { parseStepName } from "workflow/observability"; // [!code highlight]
@@ -19,7 +19,7 @@ const parsed = parseStepName("step//./src/workflows/order//processPayment"); //
 // parsed?.functionName → "processPayment"
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -33,8 +33,8 @@ const parsed = parseStepName("step//./src/workflows/order//processPayment"); //
 
 | Property | Description |
 |----------|-------------|
-| `shortName` | The display name — the last segment of the function name. For nested steps like `processOrder/chargeCard`, this is `"chargeCard"`. |
-| `moduleSpecifier` | The module the step is defined in — a relative path (`./src/workflows/order`) or a package specifier (`@myorg/tasks@2.0.0`). |
+| `shortName` | The display name: the last segment of the function name. For nested steps like `processOrder/chargeCard`, this is `"chargeCard"`. |
+| `moduleSpecifier` | The module the step is defined in: a relative path (`./src/workflows/order`) or a package specifier (`@myorg/tasks@2.0.0`). |
 | `functionName` | The full function name including nesting (e.g. `processOrder/chargeCard`). |
 
 Returns `null` when the input is not a valid step name.

package/docs/api-reference/workflow-observability/parse-workflow-name.mdx

@@ -8,7 +8,7 @@ related:
   - /docs/api-reference/workflow-observability/parse-class-name
 ---
 
-Workflow names are stored as machine-readable identifiers like `workflow//./src/workflows/order//processOrder`. This function parses them into components suitable for display in a UI — for example when listing runs from the [World SDK](/docs/api-reference/workflow-runtime/world/storage), where `run.workflowName` holds the machine-readable form.
+Workflow names are stored as machine-readable identifiers like `workflow//./src/workflows/order//processOrder`. This function parses them into components suitable for display in a user interface, for example when listing runs from the [World SDK](/docs/api-reference/workflow-runtime/world/storage), where `run.workflowName` holds the machine-readable form.
 
 ```typescript lineNumbers
 import { parseWorkflowName } from "workflow/observability"; // [!code highlight]
@@ -19,7 +19,7 @@ const parsed = parseWorkflowName("workflow//./src/workflows/order//processOrder"
 // parsed?.functionName → "processOrder"
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -34,12 +34,12 @@ const parsed = parseWorkflowName("workflow//./src/workflows/order//processOrder"
 | Property | Description |
 |----------|-------------|
 | `shortName` | The display name. For default exports, falls back to the module's short name (e.g. `"order"` for `./src/workflows/order`). |
-| `moduleSpecifier` | The module the workflow is defined in — a relative path (`./src/workflows/order`) or a package specifier (`@myorg/flows@1.0.0`). |
+| `moduleSpecifier` | The module the workflow is defined in: a relative path (`./src/workflows/order`) or a package specifier (`@myorg/flows@1.0.0`). |
 | `functionName` | The full exported function name. |
 
 Returns `null` when the input is not a valid workflow name.
 
-## Example: List Runs with Display Names
+## Example: list runs with display names
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";

package/docs/api-reference/workflow-runtime/create-world.mdx

@@ -2,16 +2,16 @@
 title: createWorld
 description: Create a new World instance from environment configuration.
 type: reference
-summary: Use createWorld to instantiate a World from WORKFLOW_TARGET_WORLD environment configuration, bypassing the cached instance.
+summary: Use createWorld to construct a fresh instance of the build-injected World, bypassing the cached instance.
 prerequisites:
   - /docs/api-reference/workflow-runtime/get-world
 related:
   - /docs/api-reference/workflow-runtime/set-world
 ---
 
-Creates a new [World](/docs/api-reference/workflow-runtime/world) instance based on environment configuration. The `WORKFLOW_TARGET_WORLD` environment variable determines which World implementation is instantiated (for example the local development World or the Vercel production World).
+Creates a new [World](/docs/api-reference/workflow-runtime/world) instance by invoking the World factory that was statically injected into the bundle at build time. The `WORKFLOW_TARGET_WORLD` environment variable selects the implementation, such as the local development World or the Vercel production World, when the app is built. Changing the variable at runtime has no effect.
 
-Unlike [`getWorld()`](/docs/api-reference/workflow-runtime/get-world), which caches a singleton instance, `createWorld()` constructs a fresh instance on every call. Application code should almost always use `getWorld()` — `createWorld()` is for infrastructure code that manages World lifecycles itself.
+Unlike [`getWorld()`](/docs/api-reference/workflow-runtime/get-world), which caches a singleton instance, `createWorld()` constructs a fresh instance on every call. Application code should almost always use `getWorld()`. `createWorld()` is for infrastructure code that manages World lifecycles itself.
 
 ```typescript lineNumbers
 import { createWorld } from "workflow/runtime";
@@ -19,11 +19,11 @@ import { createWorld } from "workflow/runtime";
 const world = await createWorld(); // [!code highlight]
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
-This function does not accept any parameters. Configuration is read from environment variables.
+This function does not accept any parameters. Configuration comes from the World that was injected at build time (World implementations typically read their own settings from environment variables when constructed).
 
 ### Returns
 
@@ -33,7 +33,7 @@ Returns a `Promise<World>` with a newly constructed World instance.
   Tooling that needs to construct a World with explicit (non-environment) configuration should instantiate the specific World implementation directly and register it with [`setWorld()`](/docs/api-reference/workflow-runtime/set-world).
 </Callout>
 
-## Related Functions
+## Related functions
 
-- [`getWorld()`](/docs/api-reference/workflow-runtime/get-world) - Resolve the cached World instance (preferred in application code).
-- [`setWorld()`](/docs/api-reference/workflow-runtime/set-world) - Override the cached World instance.
+- [`getWorld()`](/docs/api-reference/workflow-runtime/get-world): Resolve the cached World instance (preferred in application code).
+- [`setWorld()`](/docs/api-reference/workflow-runtime/set-world): Override the cached World instance.

package/docs/api-reference/workflow-runtime/get-world-handlers.mdx

@@ -9,7 +9,7 @@ prerequisites:
 
 Returns a restricted view of the [World](/docs/api-reference/workflow-runtime/world) exposing only the members that are safe to use at build time: `createQueueHandler` and `specVersion`. Framework adapters use it while generating workflow route handlers, before the deployment's runtime environment variables exist.
 
-Unlike [`getWorld()`](/docs/api-reference/workflow-runtime/get-world), this function does not cache a fully configured World instance — caching at build time would lock in incomplete environment configuration.
+Unlike [`getWorld()`](/docs/api-reference/workflow-runtime/get-world), this function does not cache a fully configured World instance: caching at build time would lock in incomplete environment configuration.
 
 ```typescript lineNumbers
 import { getWorldHandlers } from "workflow/runtime";
@@ -18,7 +18,7 @@ const handlers = await getWorldHandlers(); // [!code highlight]
 console.log(handlers.specVersion);
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -35,10 +35,10 @@ type WorldHandlers = Pick<World, "createQueueHandler" | "specVersion">;
 ```
 
 <Callout type="warn">
-  This is SDK infrastructure used by framework adapters and the workflow entrypoint. Application code should use [`getWorld()`](/docs/api-reference/workflow-runtime/get-world) instead.
+  This is SDK infrastructure used by framework adapters at build time. Runtime routes and application code should use [`getWorld()`](/docs/api-reference/workflow-runtime/get-world) instead.
 </Callout>
 
-## Related Functions
+## Related functions
 
-- [`getWorld()`](/docs/api-reference/workflow-runtime/get-world) - Resolve the full World instance at runtime.
-- [`workflowEntrypoint()`](/docs/api-reference/workflow-runtime/workflow-entrypoint) - The route handler factory built on these handlers.
+- [`getWorld()`](/docs/api-reference/workflow-runtime/get-world): Resolve the full World instance at runtime.
+- [`workflowEntrypoint()`](/docs/api-reference/workflow-runtime/workflow-entrypoint): Create the runtime route handler that shares the full World instance.

package/docs/api-reference/workflow-runtime/get-world.mdx

@@ -17,7 +17,7 @@ import { getWorld } from "workflow/runtime";
 const world = await getWorld(); // [!code highlight]
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -50,7 +50,7 @@ The World object provides access to several entity interfaces. See the [World SD
     </Card>
 </Cards>
 
-## Data Hydration
+## Data hydration
 
 Step and run data is serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. Use `workflow/observability` to hydrate it for display:
 
@@ -63,7 +63,7 @@ const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highl
 
 See [`workflow/observability`](/docs/api-reference/workflow-observability) for the full hydration and parsing API.
 
-### List Workflow Runs (Display Names)
+### List workflow runs (display names)
 
 List workflow runs and derive human-readable names from the `workflowName` field:
 
@@ -114,7 +114,7 @@ export async function GET(req: Request) {
   and `moduleSpecifier` for display in your UI.
 </Callout>
 
-## Related Functions
+## Related functions
 
 - [`getRun()`](/docs/api-reference/workflow-api/get-run) - Higher-level API for working with individual runs by ID.
 - [`start()`](/docs/api-reference/workflow-api/start) - Start a new workflow run.

package/docs/api-reference/workflow-runtime/health-check.mdx

@@ -20,7 +20,7 @@ if (!result.healthy) {
 }
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 

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

@@ -5,9 +5,7 @@ type: overview
 summary: Explore runtime functions for resolving the World instance and configuring workflow infrastructure.
 ---
 
-API reference for runtime functions from the `workflow/runtime` package.
-
-The runtime package provides low-level access to the workflow runtime — resolving the [World](/docs/api-reference/workflow-runtime/world) instance that backs storage, queuing, and streaming, and wiring up workflow infrastructure in custom server environments.
+The `workflow/runtime` package provides low-level access to the workflow runtime. Use it to resolve the [World](/docs/api-reference/workflow-runtime/world) instance that backs storage, queuing, and streaming or to wire up workflow infrastructure in custom server environments.
 
 ## Functions
 
@@ -20,7 +18,7 @@ The runtime package provides low-level access to the workflow runtime — resolv
     </Card>
 </Cards>
 
-## Infrastructure Functions
+## Infrastructure functions
 
 These functions are primarily used by framework adapters and custom world setups, and are rarely needed in application code:
 

package/docs/api-reference/workflow-runtime/set-world.mdx

@@ -2,14 +2,14 @@
 title: setWorld
 description: Override or reset the cached World instance used by the workflow runtime.
 type: reference
-summary: Use setWorld to inject a custom World instance or reset the cache after environment configuration changes.
+summary: Use setWorld to inject a custom World instance or reset the cache to the build-injected World.
 prerequisites:
   - /docs/api-reference/workflow-runtime/get-world
 related:
   - /docs/api-reference/workflow-runtime/create-world
 ---
 
-Overrides the cached [World](/docs/api-reference/workflow-runtime/world) instance that [`getWorld()`](/docs/api-reference/workflow-runtime/get-world) returns. Use it to inject a World constructed with explicit configuration (rather than environment variables), or pass `undefined` to clear the cache so the next `getWorld()` call reinitializes from the current environment.
+Overrides the cached [World](/docs/api-reference/workflow-runtime/world) instance that [`getWorld()`](/docs/api-reference/workflow-runtime/get-world) returns. Use it to inject a World constructed with explicit configuration, or pass `undefined` to clear the cache so the next `getWorld()` call reconstructs the World that was statically injected into the bundle at build time.
 
 ```typescript lineNumbers
 import { setWorld, getWorld } from "workflow/runtime";
@@ -20,30 +20,32 @@ setWorld(customWorld); // [!code highlight]
 const world = await getWorld(); // resolves customWorld
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `world` | `World \| undefined` | The World instance to use, or `undefined` to reset the cache and reinitialize from environment variables on next access |
+| `world` | `World \| undefined` | The World instance to use, or `undefined` to reset the cache so the next access reconstructs the build-injected World |
 
 ### Returns
 
 This function does not return a value.
 
-## Example: Reset After Environment Changes
+## Example: inject a specific World
 
-```typescript lineNumbers
-import { setWorld, getWorld } from "workflow/runtime";
+The build selects the target World via `WORKFLOW_TARGET_WORLD` and statically injects it into the bundle. Changing the environment variable at runtime has no effect. To use a different World at runtime, construct it explicitly with the World package's `createWorld()` factory and inject it:
 
-process.env.WORKFLOW_TARGET_WORLD = "@workflow/world-local";
-setWorld(undefined); // clear the cached instance // [!code highlight]
+```typescript lineNumbers
+import { setWorld } from "workflow/runtime";
+import { createWorld } from "@workflow/world-local";
 
-const world = await getWorld(); // reinitialized with new configuration
+setWorld(createWorld({ dataDir: "/tmp/workflow-test" })); // [!code highlight]
 ```
 
-## Related Functions
+Calling `setWorld(undefined)` afterwards restores the build-injected World on the next `getWorld()` call.
+
+## Related functions
 
-- [`getWorld()`](/docs/api-reference/workflow-runtime/get-world) - Resolve the cached World instance.
-- [`createWorld()`](/docs/api-reference/workflow-runtime/create-world) - Construct a fresh World from environment configuration.
+- [`getWorld()`](/docs/api-reference/workflow-runtime/get-world): Resolve the cached World instance.
+- [`createWorld()`](/docs/api-reference/workflow-runtime/create-world): Construct a fresh instance of the build-injected World.

package/docs/api-reference/workflow-runtime/workflow-entrypoint.mdx

@@ -11,7 +11,7 @@ related:
 
 Creates the HTTP route handler that executes workflow runs. The handler receives queue messages, replays the workflow from its event log, executes steps inline where possible, and suspends when the workflow waits on sleeps or hooks.
 
-Framework adapters (Next.js, Nitro, SvelteKit, etc.) call this for you and mount the result at `/.well-known/workflow/v1/flow` — you only need it when wiring workflow support into a custom server environment.
+Framework adapters (Next.js, Nitro, SvelteKit, etc.) call this for you and mount the result at `/.well-known/workflow/v1/flow`. You only need it when wiring workflow support into a custom server environment.
 
 ```typescript lineNumbers
 import { workflowEntrypoint } from "workflow/runtime";
@@ -23,7 +23,7 @@ const handler = workflowEntrypoint(workflowBundleCode); // [!code highlight]
 export const POST = (req: Request) => handler(req);
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -36,7 +36,8 @@ export const POST = (req: Request) => handler(req);
 
 Returns a fetch-style request handler: `(req: Request) => Promise<Response>`.
 
-## Related Functions
+## Related functions
 
-- [`getWorldHandlers()`](/docs/api-reference/workflow-runtime/get-world-handlers) - The build-time World access this handler is built on.
-- [`healthCheck()`](/docs/api-reference/workflow-runtime/health-check) - Verify the entrypoint processes queue messages end-to-end.
+- [`getWorld()`](/docs/api-reference/workflow-runtime/get-world): Resolve the runtime World instance this handler shares with workflow execution.
+- [`getWorldHandlers()`](/docs/api-reference/workflow-runtime/get-world-handlers): Access build-time-safe World handlers for framework tooling.
+- [`healthCheck()`](/docs/api-reference/workflow-runtime/health-check): Verify the entrypoint processes queue messages end-to-end.

package/docs/api-reference/workflow-runtime/world/analytics.mdx

@@ -20,7 +20,7 @@ keywords:
   - metadata-only
 ---
 
-`world.analytics` is an optional, read-only namespace for observability surfaces — dashboards, CLIs, and admin tools that list large numbers of runs without touching payload data.
+`world.analytics` is an optional, read-only namespace for observability surfaces: dashboards, command-line interface (CLI) tools, and admin tools that list large numbers of runs without touching payload data.
 
 For observability and inspection listings, prefer this namespace over
 [`world.runs.list()`](/docs/api-reference/workflow-runtime/world/storage#runslist).
@@ -28,10 +28,10 @@ The storage API remains available for operational and payload-bearing reads.
 
 It differs from [Storage](/docs/api-reference/workflow-runtime/world/storage) in two ways:
 
-- **Metadata only.** Results never include run input/output, step data, or hook tokens. There is no `resolveData` option.
-- **Served from the observability pipeline.** On Vercel, queries are served from the Vercel observability data pipeline, so large listings do not compete with workflow execution. Data is ingested asynchronously and may trail the live state by a few seconds.
+- **Metadata only**: Results never include run input/output, step data, or hook tokens. There is no `resolveData` option.
+- **Served from the observability pipeline**: On Vercel, queries are served from the Vercel observability data pipeline, so large listings do not compete with workflow execution. Data is ingested asynchronously and may trail the live state by a few seconds.
 
-The namespace is optional — worlds that don't implement it (such as the local development world) leave it `undefined`, so feature-detect before use:
+The namespace is optional: worlds that don't implement it (such as the local development world) leave it `undefined`, so feature-detect before use:
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
@@ -67,13 +67,13 @@ const page = await world.analytics.runs.list({
 | `params.attributes` | `Record<string, string>` | Only return runs whose latest attributes match every pair (up to 8) |
 | `params.pagination` | `PaginationOptions` | Cursor pagination |
 
-**Returns:** `PaginatedResponse<AnalyticsRun>` — each run includes `runId`, `status`, `workflowName`, `deploymentId`, `attributes`, and lifecycle timestamps.
+**Returns:** `PaginatedResponse<AnalyticsRun>`. Each run includes `runId`, `status`, `workflowName`, `deploymentId`, `attributes`, and lifecycle timestamps.
 
 Attribute matching is latest-write-wins: a run whose attribute moved from `"v1"` to `"v2"` no longer matches `{ key: "v1" }`. Reserved `$`-prefixed keys may be used in filters even though user code cannot write them.
 
 ### runs.get()
 
-Fetch one run by ID. Point lookups search the full plan window, not just the trailing 24 hours.
+Fetch one run by ID. Point lookups search the full plan window rather than only the trailing 24 hours.
 
 ```typescript lineNumbers
 const run = await world.analytics.runs.get(runId);
@@ -83,7 +83,7 @@ const run = await world.analytics.runs.get(runId);
 
 ## analytics.attributes
 
-Discover which [attributes](/docs/observability/attributes) exist on your runs — for example to build filter dropdowns over arbitrary user-defined keys.
+Discover which [attributes](/docs/observability/attributes) exist on your runs, for example to build filter dropdowns over arbitrary user-defined keys.
 
 ### attributes.list()
 
@@ -104,7 +104,7 @@ for (const { key, runCount, lastSeenAt } of page.data) {
 | `params.startTime` / `params.endTime` | `string` | ISO 8601 window; must be provided together |
 | `params.pagination` | `PaginationOptions` | Cursor pagination |
 
-**Returns:** `PaginatedResponse<AnalyticsAttributeKey>` — `{ key, runCount, firstSeenAt, lastSeenAt }`
+**Returns:** `PaginatedResponse<AnalyticsAttributeKey>`: `{ key, runCount, firstSeenAt, lastSeenAt }`
 
 ---
 
@@ -120,7 +120,7 @@ const hooks = await world.analytics.hooks.list({ runId });
 const waits = await world.analytics.waits.list({ runId, status: "waiting" });
 ```
 
-Each namespace also has a `get()` for point lookups (`steps.get(runId, stepId)`, `events.get(runId, eventId)`, `hooks.get(hookId)`, `waits.get(runId, waitId)`). Hook listings never include the hook token — resolve it separately through the runtime APIs if you need to deliver a payload.
+Each namespace also has a `get()` for point lookups (`steps.get(runId, stepId)`, `events.get(runId, eventId)`, `hooks.get(hookId)`, `waits.get(runId, waitId)`). Hook listings never include the hook token. Resolve it separately through the runtime APIs if you need to deliver a payload.
 
 ---
 

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

@@ -14,7 +14,7 @@ keywords:
   - workflow management
 ---
 
-The World SDK provides direct access to workflow infrastructure — runs, steps, events, hooks, streams, and queues — plus a metadata-only [Analytics](/docs/api-reference/workflow-runtime/world/analytics) namespace with attribute discovery and filtering. Use it to build observability dashboards, admin panels, debugging tools, and custom workflow management logic.
+The World SDK provides direct access to workflow infrastructure, including runs, steps, events, hooks, streams, and queues. It also provides a metadata-only [Analytics](/docs/api-reference/workflow-runtime/world/analytics) namespace with attribute discovery and filtering. Use it to build observability dashboards, admin panels, debugging tools, and custom workflow management logic.
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
@@ -43,9 +43,11 @@ const world = await getWorld(); // [!code highlight]
   The World SDK is the low-level foundation that higher-level functions like [`getRun()`](/docs/api-reference/workflow-api/get-run) and [`start()`](/docs/api-reference/workflow-api/start) are built on. Use it when you need capabilities beyond what those functions provide.
 </Callout>
 
-## Data Hydration
+Beyond these namespaces, the `World` interface carries several top-level members for World authors: `specVersion`, `capabilities`, lifecycle hooks (`start()`/`close()`), `getEncryptionKeyForRun()`, and the optional `createRunId()` / `describeRun()` hooks behind regional run placement and World-specific `inspect` output. [Building a World](/worlds/building-a-world) documents these members.
 
-Step input/output data is serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. To display this data in your UI, use the hydration utilities from `workflow/observability`:
+## Data hydration
+
+The [devalue](https://github.com/Rich-Harris/devalue) format serializes step input/output data. To display this data in your UI, use the hydration utilities from `workflow/observability`:
 
 ```typescript lineNumbers
 import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]

package/docs/api-reference/workflow-runtime/world/queue.mdx

@@ -2,7 +2,7 @@
 title: Queue
 description: Low-level queue interface for dispatching workflow invocations.
 type: reference
-summary: "Methods: getDeploymentId(), queue(), createQueueHandler(). Internal queue dispatch — normally handled by the SDK."
+summary: "Methods: getDeploymentId(), queue(), createQueueHandler(). The SDK normally handles internal queue dispatch."
 prerequisites:
   - /docs/api-reference/workflow-runtime/get-world
 related:
@@ -20,7 +20,7 @@ keywords:
 Queue methods live directly on the `world` object (not nested). They dispatch internal workflow invocations, including queued step work, to the queue backend.
 
 <Callout type="warn">
-  These methods are used internally by the Workflow SDK to dispatch execution. You do not need to call them in normal operations — use [`start()`](/docs/api-reference/workflow-api/start) to trigger workflows instead. Direct queue access is only needed if you programmatically create a run via `world.events.create()` with a `run_created` event and need to kick off its initial execution, or for debugging flow resumption.
+  The Workflow SDK uses these methods internally to dispatch execution. In normal operations, use [`start()`](/docs/api-reference/workflow-api/start) to trigger workflows instead. You only need direct queue access to start the initial execution of a run you programmatically created via `world.events.create()` with a `run_created` event, or to debug flow resumption.
 </Callout>
 
 ## Import
@@ -29,20 +29,20 @@ Queue methods live directly on the `world` object (not nested). They dispatch in
 import { getWorld } from "workflow/runtime";
 
 const world = await getWorld(); // [!code highlight]
-// Queue methods are called directly on world — e.g. world.queue()
+// Call queue methods directly on world, for example, world.queue()
 ```
 
 ## Methods
 
 ### getDeploymentId()
 
-Get the current deployment ID. Used internally for routing queue messages to the correct deployment.
+Get the current deployment ID. The SDK uses it internally to route queue messages to the correct deployment.
 
 ```typescript lineNumbers
 const deploymentId = await world.getDeploymentId(); // [!code highlight]
 ```
 
-**Returns:** `string` — The current deployment ID
+**Returns:** `string`. The current deployment ID.
 
 ### queue()
 
@@ -58,13 +58,13 @@ const { messageId } = await world.queue(queueName, payload, opts); // [!code hig
 |-----------|------|-------------|
 | `queueName` | `ValidQueueName` | The queue name (branded string) |
 | `message` | `QueuePayload` | Internal SDK payload |
-| `opts` | `QueueOptions` | Optional — `deploymentId`, `idempotencyKey`, `delaySeconds`, `headers` |
+| `opts` | `QueueOptions` | Optional: `deploymentId`, `idempotencyKey`, `delaySeconds`, `headers`, `region` (regional routing hint), `specVersion` |
 
 **Returns:** `{ messageId: MessageId | null }`
 
 ### createQueueHandler()
 
-Create an HTTP handler that processes messages from a queue. Used to set up the queue consumer endpoint.
+Create an HTTP handler that processes messages from a queue. Use it to set up the queue consumer endpoint.
 
 ```typescript lineNumbers
 const handler = world.createQueueHandler(prefix, callback); // [!code highlight]
@@ -79,10 +79,10 @@ const handler = world.createQueueHandler(prefix, callback); // [!code highlight]
 
 **Returns:** `(req: Request) => Promise<Response>`
 
-`meta.messageId` should be stable across redeliveries of the same message (one ID per enqueued message, reused on every delivery attempt). The runtime records it on inline `step_started` events as a liveness lease so that only a redelivery of the owning message re-executes a crashed inline step before the lease expires (see [Inline step message ownership](/v5/docs/changelog/step-message-ownership)). A World whose queue mints a fresh ID per delivery degrades gracefully — crashed inline steps recover via the delayed backstop instead of immediately on redelivery — but never wedges or duplicates.
+`meta.messageId` should be stable across redeliveries of the same message (one ID per enqueued message, reused on every delivery attempt). The runtime records it on inline `step_started` events as a liveness lease so that only a redelivery of the owning message re-executes a crashed inline step before the lease expires (see [Inline step message ownership](/docs/changelog/step-message-ownership)). A World whose queue mints a fresh ID per delivery degrades gracefully. Crashed inline steps recover via the delayed backstop instead of immediately on redelivery, but never wedge or duplicate.
 
 ## Related
 
-- [start()](/docs/api-reference/workflow-api/start) — The standard way to start workflow runs
-- [Starting Workflows](/docs/foundations/starting-workflows) — Core concepts for workflow invocation
-- [Storage](/docs/api-reference/workflow-runtime/world/storage) — Create events that trigger queue dispatch
+- [start()](/docs/api-reference/workflow-api/start): The standard way to start workflow runs
+- [Starting Workflows](/docs/foundations/starting-workflows): Core concepts for workflow invocation
+- [Storage](/docs/api-reference/workflow-runtime/world/storage): Create events that trigger queue dispatch