workflow 5.0.0-beta.5 → 5.0.0-beta.51

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"
+  ]
+}

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

@@ -0,0 +1,51 @@
+---
+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 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, 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";
+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 so the next access reconstructs the build-injected World |
+
+### Returns
+
+This function does not return a value.
+
+## Example: inject a specific World
+
+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:
+
+```typescript lineNumbers
+import { setWorld } from "workflow/runtime";
+import { createWorld } from "@workflow/world-local";
+
+setWorld(createWorld({ dataDir: "/tmp/workflow-test" })); // [!code highlight]
+```
+
+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 instance of the build-injected World.

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

@@ -0,0 +1,43 @@
+---
+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
+
+- [`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.