workflow 4.3.1 → 4.5.0

package/docs/{api-reference/workflow-api → v5/api-reference/workflow-runtime}/get-world.mdx

@@ -36,21 +36,18 @@ 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
@@ -64,7 +61,7 @@ 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)
 
@@ -72,7 +69,7 @@ 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,7 +110,7 @@ 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>
 

package/docs/v5/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, "workflow"); // [!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 |
+| `endpoint` | `"workflow" \| "step"` | Which endpoint to check |
+| `options` | `HealthCheckOptions & { namespace?: string }` | 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`. |
+
+### Returns
+
+Returns a `Promise<HealthCheckResult>`:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `healthy` | `boolean` | Whether the 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/v5/api-reference/workflow-runtime/index.mdx

@@ -0,0 +1,43 @@
+---
+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.
+---
+
+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.
+
+## 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.
+    </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/v5/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"
+  ]
+}

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

@@ -0,0 +1,49 @@
+---
+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.
+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.
+
+```typescript lineNumbers
+import { setWorld, getWorld } from "workflow/runtime";
+import type { World } from "@workflow/world";
+declare const customWorld: World; // @setup
+
+setWorld(customWorld); // [!code highlight]
+const world = await getWorld(); // resolves customWorld
+```
+
+## 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 |
+
+### Returns
+
+This function does not return a value.
+
+## Example: Reset After Environment Changes
+
+```typescript lineNumbers
+import { setWorld, getWorld } from "workflow/runtime";
+
+process.env.WORKFLOW_TARGET_WORLD = "@workflow/world-local";
+setWorld(undefined); // clear the cached instance // [!code highlight]
+
+const world = await getWorld(); // reinitialized with new configuration
+```
+
+## 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.

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

@@ -0,0 +1,42 @@
+---
+title: workflowEntrypoint
+description: Create the HTTP route handler that executes workflow runs from a workflow bundle.
+type: reference
+summary: Use workflowEntrypoint to wire a compiled workflow bundle into an HTTP route in custom server environments.
+prerequisites:
+  - /docs/how-it-works/code-transform
+related:
+  - /docs/api-reference/workflow-runtime/health-check
+---
+
+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.
+
+```typescript lineNumbers
+import { workflowEntrypoint } from "workflow/runtime";
+declare const workflowBundleCode: string; // @setup
+
+const handler = workflowEntrypoint(workflowBundleCode); // [!code highlight]
+
+// Mount on your server, e.g. a fetch-style route:
+export const POST = (req: Request) => handler(req);
+```
+
+## API Signature
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `workflowCode` | `string` | The compiled workflow bundle code containing all workflow functions |
+| `options` | `{ namespace?: string }` | Optional. `namespace` scopes the queue topics this handler consumes. |
+
+### Returns
+
+Returns a fetch-style request handler: `(req: Request) => Promise<Response>`.
+
+## 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.

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

@@ -0,0 +1,55 @@
+---
+title: World SDK
+description: Low-level API for inspecting and managing workflow runs, steps, events, hooks, streams, and queues.
+type: overview
+summary: Access workflow infrastructure via await getWorld() for building observability dashboards, admin tools, and custom integrations.
+prerequisites:
+  - /docs/api-reference/workflow-runtime/get-world
+keywords:
+  - getWorld
+  - World SDK
+  - workflow runtime
+  - observability dashboard
+  - admin panel
+  - workflow management
+---
+
+The World SDK provides direct access to workflow infrastructure — runs, steps, events, hooks, streams, and queues. Use it to build observability dashboards, admin panels, debugging tools, and custom workflow management logic.
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = await getWorld(); // [!code highlight]
+```
+
+## Interfaces
+
+<Cards>
+    <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-runtime/world/streams" title="Streams">
+        Read, write, and manage real-time data streams for workflow runs.
+    </Card>
+    <Card href="/docs/api-reference/workflow-runtime/world/queue" title="Queue">
+        Low-level queue dispatch (internal SDK infrastructure).
+    </Card>
+</Cards>
+
+<Callout type="info">
+  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
+
+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`:
+
+```typescript lineNumbers
+import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
+
+const step = await world.steps.get(runId, stepId);
+const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
+console.log(hydrated.input, hydrated.output);
+```
+
+See [`workflow/observability`](/docs/api-reference/workflow-observability) for the full API.

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

@@ -0,0 +1,4 @@
+{
+  "title": "World SDK",
+  "pages": ["storage", "streams", "queue"]
+}

package/docs/{api-reference/workflow-api → v5/api-reference/workflow-runtime}/world/queue.mdx

@@ -4,7 +4,7 @@ description: Low-level queue interface for dispatching workflow and step invocat
 type: reference
 summary: "Methods: getDeploymentId(), queue(), createQueueHandler(). Internal queue dispatch — normally handled by the SDK."
 prerequisites:
-  - /docs/api-reference/workflow-api/get-world
+  - /docs/api-reference/workflow-runtime/get-world
 related:
   - /docs/api-reference/workflow-api/start
   - /docs/foundations/starting-workflows
@@ -83,4 +83,4 @@ const handler = world.createQueueHandler(prefix, callback); // [!code highlight]
 
 - [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-api/world/storage) — Create events that trigger queue dispatch
+- [Storage](/docs/api-reference/workflow-runtime/world/storage) — Create events that trigger queue dispatch