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

package/docs/api-reference/workflow-observability/hydrate-data.mdx

@@ -0,0 +1,35 @@
+---
+title: hydrateData
+description: Hydrate a single serialized value from workflow storage into a plain JavaScript value.
+type: reference
+summary: Use hydrateData to deserialize a single value when hydrateResourceIO's field mapping doesn't apply.
+related:
+  - /docs/api-reference/workflow-observability/hydrate-resource-io
+  - /docs/api-reference/workflow-observability/observability-revivers
+---
+
+Hydrates (deserializes) a single value that was stored by the workflow runtime. This is the lower-level building block behind [`hydrateResourceIO()`](/docs/api-reference/workflow-observability/hydrate-resource-io). Use it when you have a raw serialized value rather than a whole resource, such as a single field from an event payload.
+
+```typescript lineNumbers
+import { hydrateData, observabilityRevivers } from "workflow/observability"; // [!code highlight]
+declare const serialized: unknown; // @setup
+
+const value = hydrateData(serialized, observabilityRevivers); // [!code highlight]
+```
+
+## API signature
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `value` | `unknown` | The serialized value from workflow storage |
+| `revivers` | `Revivers` | Reviver functions for deserialization. Use [`observabilityRevivers`](/docs/api-reference/workflow-observability/observability-revivers) for standard use. |
+
+### Returns
+
+The hydrated plain JavaScript value. The input is handled by shape:
+
+- Format-prefixed binary data (`Uint8Array`) is decoded and parsed from the [devalue](https://github.com/Rich-Harris/devalue) format.
+- Encrypted data is returned as-is (a raw `Uint8Array`). See [Encrypted data](/docs/api-reference/workflow-observability#encrypted-data).
+- Already-plain values (numbers, strings, and `null`) are returned unchanged.

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

@@ -0,0 +1,62 @@
+---
+title: hydrateResourceIO
+description: Hydrate the serialized data fields of a run, step, hook, or event for display.
+type: reference
+summary: Use hydrateResourceIO with observabilityRevivers to deserialize step input/output for display in observability tools.
+prerequisites:
+  - /docs/api-reference/workflow-runtime/get-world
+related:
+  - /docs/api-reference/workflow-observability/observability-revivers
+  - /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 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`.
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
+declare const runId: string; // @setup
+declare const stepId: string; // @setup
+
+const world = await getWorld();
+const step = await world.steps.get(runId, stepId);
+const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
+console.log(hydrated.input, hydrated.output);
+```
+
+## API signature
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `resource` | `WorkflowRun \| Step \| Hook \| Event` | The resource with serialized data fields |
+| `revivers` | `Revivers` | Reviver functions for deserialization. Use [`observabilityRevivers`](/docs/api-reference/workflow-observability/observability-revivers) for standard use. |
+
+### Returns
+
+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).
+</Callout>
+
+## Examples
+
+### Display a run's steps with hydrated I/O
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
+declare const runId: string; // @setup
+
+const world = await getWorld();
+const steps = await world.steps.list({ runId, resolveData: "all" });
+
+for (const step of steps.data) {
+  const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
+  console.log(step.stepName, hydrated.input, hydrated.output);
+}
+```

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

@@ -0,0 +1,62 @@
+---
+title: "workflow/observability"
+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:
+  - workflow/observability
+  - hydrateResourceIO
+  - observabilityRevivers
+  - hydrateData
+  - parseStepName
+  - parseWorkflowName
+  - parseClassName
+  - data hydration
+  - devalue deserialization
+  - display name parsing
+---
+
+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]
+  hydrateResourceIO, // [!code highlight]
+  observabilityRevivers, // [!code highlight]
+  hydrateData, // [!code highlight]
+  parseStepName, // [!code highlight]
+  parseWorkflowName, // [!code highlight]
+  parseClassName, // [!code highlight]
+} from "workflow/observability"; // [!code highlight]
+```
+
+## Data hydration
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-observability/hydrate-resource-io" title="hydrateResourceIO()">
+        Hydrate the serialized data fields of a run, step, hook, or event for display.
+    </Card>
+    <Card href="/docs/api-reference/workflow-observability/observability-revivers" title="observabilityRevivers">
+        Standard revivers for deserializing workflow data types (Date, Map, Set, streams, etc.).
+    </Card>
+    <Card href="/docs/api-reference/workflow-observability/hydrate-data" title="hydrateData()">
+        Hydrate a single serialized value (lower-level than hydrateResourceIO).
+    </Card>
+</Cards>
+
+## Name parsing
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-observability/parse-step-name" title="parseStepName()">
+        Parse a machine-readable step name into display-friendly components.
+    </Card>
+    <Card href="/docs/api-reference/workflow-observability/parse-workflow-name" title="parseWorkflowName()">
+        Parse a machine-readable workflow name into display-friendly components.
+    </Card>
+    <Card href="/docs/api-reference/workflow-observability/parse-class-name" title="parseClassName()">
+        Parse a machine-readable class ID into display-friendly components.
+    </Card>
+</Cards>
+
+## 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.

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

@@ -0,0 +1,11 @@
+{
+  "title": "workflow/observability",
+  "pages": [
+    "hydrate-resource-io",
+    "observability-revivers",
+    "hydrate-data",
+    "parse-step-name",
+    "parse-workflow-name",
+    "parse-class-name"
+  ]
+}

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

@@ -0,0 +1,50 @@
+---
+title: observabilityRevivers
+description: Standard reviver functions for deserializing workflow data types in observability tools.
+type: reference
+summary: Pass observabilityRevivers to hydrateResourceIO or hydrateData to deserialize standard workflow data types.
+related:
+  - /docs/api-reference/workflow-observability/hydrate-resource-io
+  - /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.
+
+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).
+
+```typescript lineNumbers
+import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
+import type { Step } from "@workflow/world";
+declare const step: Step; // @setup
+
+const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
+```
+
+## API signature
+
+```typescript
+import type { Revivers } from "workflow/observability";
+
+declare const observabilityRevivers: Revivers;
+```
+
+Where `Revivers` is:
+
+```typescript
+type Revivers = Record<string, (value: any) => any>;
+```
+
+Each key is a serialized type tag, and each function revives a serialized value of that type. You can spread `observabilityRevivers` into a custom reviver map to override how specific types are displayed:
+
+```typescript lineNumbers
+import { hydrateData, observabilityRevivers } from "workflow/observability";
+declare const value: unknown; // @setup
+
+const customRevivers = {
+  ...observabilityRevivers,
+  // Render stream references as plain strings instead of marker objects
+  ReadableStream: () => "<stream>",
+};
+
+const hydrated = hydrateData(value, customRevivers);
+```

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

@@ -0,0 +1,41 @@
+---
+title: parseClassName
+description: Parse a machine-readable class ID into display-friendly components.
+type: reference
+summary: Use parseClassName to extract a display-friendly class name from a serialized class instance identifier.
+related:
+  - /docs/api-reference/workflow-observability/parse-step-name
+  - /docs/api-reference/workflow-observability/parse-workflow-name
+  - /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 user interface.
+
+```typescript lineNumbers
+import { parseClassName } from "workflow/observability"; // [!code highlight]
+
+const parsed = parseClassName("class//./src/models//User"); // [!code highlight]
+// parsed?.shortName → "User"
+// parsed?.moduleSpecifier → "./src/models"
+// parsed?.functionName → "User"
+```
+
+## API signature
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | The machine-readable class ID |
+
+### Returns
+
+`{ shortName: string; moduleSpecifier: string; functionName: string } | null`
+
+| 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`). |
+| `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

@@ -0,0 +1,40 @@
+---
+title: parseStepName
+description: Parse a machine-readable step name into display-friendly components.
+type: reference
+summary: Use parseStepName to extract a display-friendly short name from a step's machine-readable identifier.
+related:
+  - /docs/api-reference/workflow-observability/parse-workflow-name
+  - /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 user interface.
+
+```typescript lineNumbers
+import { parseStepName } from "workflow/observability"; // [!code highlight]
+
+const parsed = parseStepName("step//./src/workflows/order//processPayment"); // [!code highlight]
+// parsed?.shortName → "processPayment"
+// parsed?.moduleSpecifier → "./src/workflows/order"
+// parsed?.functionName → "processPayment"
+```
+
+## API signature
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | The machine-readable step name (e.g. from `step.stepName`) |
+
+### Returns
+
+`{ shortName: string; moduleSpecifier: string; functionName: string } | null`
+
+| 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`). |
+| `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

@@ -0,0 +1,55 @@
+---
+title: parseWorkflowName
+description: Parse a machine-readable workflow name into display-friendly components.
+type: reference
+summary: Use parseWorkflowName to extract a display-friendly short name from a run's workflowName identifier.
+related:
+  - /docs/api-reference/workflow-observability/parse-step-name
+  - /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 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]
+
+const parsed = parseWorkflowName("workflow//./src/workflows/order//processOrder"); // [!code highlight]
+// parsed?.shortName → "processOrder"
+// parsed?.moduleSpecifier → "./src/workflows/order"
+// parsed?.functionName → "processOrder"
+```
+
+## API signature
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | The machine-readable workflow name (e.g. from `run.workflowName`) |
+
+### Returns
+
+`{ shortName: string; moduleSpecifier: string; functionName: string } | null`
+
+| 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`). |
+| `functionName` | The full exported function name. |
+
+Returns `null` when the input is not a valid workflow name.
+
+## Example: list runs with display names
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+import { parseWorkflowName } from "workflow/observability"; // [!code highlight]
+
+const world = await getWorld();
+const runs = await world.runs.list({ resolveData: "none" });
+
+for (const run of runs.data) {
+  const parsed = parseWorkflowName(run.workflowName); // [!code highlight]
+  console.log(`${parsed?.shortName ?? run.workflowName}: ${run.status}`);
+}
+```

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

@@ -0,0 +1,39 @@
+---
+title: createWorld
+description: Create a new World instance from environment configuration.
+type: reference
+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 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.
+
+```typescript lineNumbers
+import { createWorld } from "workflow/runtime";
+
+const world = await createWorld(); // [!code highlight]
+```
+
+## API signature
+
+### Parameters
+
+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
+
+Returns a `Promise<World>` with a newly constructed World instance.
+
+<Callout type="info">
+  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
+
+- [`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

@@ -0,0 +1,44 @@
+---
+title: getWorldHandlers
+description: Build-time-safe access to the World's queue handlers without binding to runtime environment variables.
+type: reference
+summary: Use getWorldHandlers at build time to access queue handler creation without caching an environment-bound World.
+prerequisites:
+  - /docs/api-reference/workflow-runtime/get-world
+---
+
+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.
+
+```typescript lineNumbers
+import { getWorldHandlers } from "workflow/runtime";
+
+const handlers = await getWorldHandlers(); // [!code highlight]
+console.log(handlers.specVersion);
+```
+
+## API signature
+
+### Parameters
+
+This function does not accept any parameters.
+
+### Returns
+
+Returns a `Promise<WorldHandlers>`, where:
+
+```typescript
+import type { World } from "@workflow/world";
+
+type WorldHandlers = Pick<World, "createQueueHandler" | "specVersion">;
+```
+
+<Callout type="warn">
+  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
+
+- [`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-api → 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
 
@@ -36,24 +36,21 @@ showSections={["returns"]}
 
 ## World SDK
 
-The World object provides access to several entity interfaces. See the [World SDK](/docs/api-reference/workflow-api/world) reference for complete documentation:
+The World object provides access to several entity interfaces. See the [World SDK](/docs/api-reference/workflow-runtime/world) reference for complete documentation:
 
 <Cards>
-    <Card href="/docs/api-reference/workflow-api/world/storage" title="Storage">
+    <Card href="/docs/api-reference/workflow-runtime/world/storage" title="Storage">
         Query runs, steps, hooks, and the underlying event log.
     </Card>
-    <Card href="/docs/api-reference/workflow-api/world/streams" title="Streams">
+    <Card href="/docs/api-reference/workflow-runtime/world/streams" title="Streams">
         Read, write, and manage data streams.
     </Card>
-    <Card href="/docs/api-reference/workflow-api/world/queue" title="Queue">
+    <Card href="/docs/api-reference/workflow-runtime/world/queue" title="Queue">
         Low-level queue dispatch (internal SDK infrastructure).
     </Card>
-    <Card href="/docs/api-reference/workflow-api/world/observability" title="Observability">
-        Hydrate step I/O, parse display names, decrypt data.
-    </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:
 
@@ -64,15 +61,15 @@ const step = await world.steps.get(runId, stepId);
 const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
 ```
 
-See [Observability Utilities](/docs/api-reference/workflow-api/world/observability) for the full hydration, parsing, and encryption API.
+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:
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
-import { parseWorkflowName } from "@workflow/utils/parse-name"; // [!code highlight]
+import { parseWorkflowName } from "workflow/observability"; // [!code highlight]
 
 export async function GET(req: Request) {
   const url = new URL(req.url);
@@ -113,11 +110,11 @@ export async function GET(req: Request) {
 
 <Callout type="info">
   The `workflowName` field contains a machine-readable identifier like `workflow//./src/workflows/order//processOrder`.
-  Use `parseWorkflowName()` from `@workflow/utils/parse-name` to extract the `shortName` (e.g., `"processOrder"`)
+  Use [`parseWorkflowName()`](/docs/api-reference/workflow-observability/parse-workflow-name) to extract the `shortName` (e.g., `"processOrder"`)
   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

@@ -0,0 +1,50 @@
+---
+title: healthCheck
+description: Verify a deployment's workflow infrastructure by sending a message through the queue pipeline.
+type: reference
+summary: Use healthCheck to verify the workflow endpoint of a deployment processes queue messages end-to-end.
+prerequisites:
+  - /docs/api-reference/workflow-runtime/get-world
+---
+
+Performs an end-to-end health check of a deployment's workflow infrastructure by sending a message through the queue pipeline and verifying it is processed by the workflow endpoint. Because it goes through the queue rather than direct HTTP, it works even when the deployment is behind Deployment Protection on Vercel.
+
+```typescript lineNumbers
+import { getWorld, healthCheck } from "workflow/runtime";
+
+const world = await getWorld();
+const result = await healthCheck(world); // [!code highlight]
+
+if (!result.healthy) {
+  console.error("Workflow infrastructure unhealthy:", result.error);
+}
+```
+
+## API signature
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `world` | `World` | The World instance to send the health check through |
+| `options` | `HealthCheckOptions` | Optional configuration |
+
+Where `HealthCheckOptions` is:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `timeout` | `number` | Milliseconds to wait for the health check response. Default: `30000`. |
+| `deploymentId` | `string` | Deployment to target. Falls back to `process.env.VERCEL_DEPLOYMENT_ID`. |
+| `namespace` | `string` | Queue namespace of the target deployment. Falls back to `WORKFLOW_QUEUE_NAMESPACE`. |
+
+### Returns
+
+Returns a `Promise<HealthCheckResult>`:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `healthy` | `boolean` | Whether the combined workflow endpoint processed the health check message |
+| `error` | `string \| undefined` | Error message when the check failed |
+| `latencyMs` | `number \| undefined` | Round-trip latency when the check succeeded |
+| `specVersion` | `number \| undefined` | Workflow spec version of the responding deployment |
+| `workflowCoreVersion` | `string \| undefined` | `@workflow/core` version of the responding deployment |

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

@@ -0,0 +1,41 @@
+---
+title: "workflow/runtime"
+description: Runtime functions for accessing the World instance and wiring up workflow infrastructure.
+type: overview
+summary: Explore runtime functions for resolving the World instance and configuring workflow infrastructure.
+---
+
+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
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-runtime/get-world" title="getWorld()">
+        Async: resolve the World instance for storage, queuing, and streaming backends.
+    </Card>
+    <Card href="/docs/api-reference/workflow-runtime/world" title="World SDK">
+        Low-level API for inspecting runs, steps, events, hooks, streams, and queues, plus metadata-only analytics with attribute search.
+    </Card>
+</Cards>
+
+## Infrastructure functions
+
+These functions are primarily used by framework adapters and custom world setups, and are rarely needed in application code:
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-runtime/create-world" title="createWorld()">
+        Create a World instance from environment configuration.
+    </Card>
+    <Card href="/docs/api-reference/workflow-runtime/set-world" title="setWorld()">
+        Override the cached World instance with a custom World.
+    </Card>
+    <Card href="/docs/api-reference/workflow-runtime/get-world-handlers" title="getWorldHandlers()">
+        Build-time-safe access to the World's queue handlers.
+    </Card>
+    <Card href="/docs/api-reference/workflow-runtime/workflow-entrypoint" title="workflowEntrypoint()">
+        Create the HTTP route handler that executes workflow runs.
+    </Card>
+    <Card href="/docs/api-reference/workflow-runtime/health-check" title="healthCheck()">
+        Check the health of a deployment's workflow infrastructure.
+    </Card>
+</Cards>

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

@@ -0,0 +1,12 @@
+{
+  "title": "workflow/runtime",
+  "pages": [
+    "get-world",
+    "world",
+    "create-world",
+    "set-world",
+    "get-world-handlers",
+    "workflow-entrypoint",
+    "health-check"
+  ]
+}