workflow 4.4.0 → 4.5.0

package/docs/v4/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/v4/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 UI.
+
+```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/v4/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 UI.
+
+```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/v4/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 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.
+
+```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/v4/api-reference/workflow-runtime/create-world.mdx

@@ -0,0 +1,43 @@
+---
+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.
+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).
+
+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 is read from environment variables.
+
+### Returns
+
+Returns a newly constructed `World` instance.
+
+<Callout type="info">
+  In workflow 4.x, `createWorld()` is synchronous and returns `World` directly. It becomes async in 5.x, so writing `await createWorld()` works on both versions.
+</Callout>
+
+<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/v4/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 `WorldHandlers` object (synchronously in workflow 4.x; async in 5.x), 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 and the workflow entrypoint. 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) - The route handler factory built on these handlers.

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

@@ -0,0 +1,124 @@
+---
+title: getWorld
+description: Resolves the World instance for low-level storage, queuing, and streaming operations.
+type: reference
+summary: Resolve the World instance for low-level workflow storage, queuing, and streaming backends.
+prerequisites:
+  - /docs/deploying
+---
+
+Retrieves the World instance for direct access to workflow storage, queuing, and streaming backends. The returned `World` provides low-level access to manage workflow runs, steps, events, and hooks.
+
+Use this function when you need direct access to the underlying workflow infrastructure, such as listing all runs, querying events, or implementing custom workflow management logic.
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = await getWorld(); // [!code highlight]
+```
+
+<Callout type="info">
+  In workflow 4.x, `getWorld()` is synchronous and returns `World` directly. It becomes async in 5.x, so writing `await getWorld()` works on both versions.
+</Callout>
+
+## API Signature
+
+### Parameters
+
+This function does not accept any parameters.
+
+### Returns
+
+Returns the `World` object:
+
+<TSDoc
+definition={`
+import type { World } from "@workflow/world";
+export default World;`}
+showSections={["returns"]}
+/>
+
+## World SDK
+
+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-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 data streams.
+    </Card>
+    <Card href="/docs/api-reference/workflow-runtime/world/queue" title="Queue">
+        Low-level queue dispatch (internal SDK infrastructure).
+    </Card>
+</Cards>
+
+## 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:
+
+```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]
+```
+
+See [`workflow/observability`](/docs/api-reference/workflow-observability) for the full hydration and parsing API.
+
+### 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/observability"; // [!code highlight]
+
+export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const cursor = url.searchParams.get("cursor") ?? undefined;
+
+  try {
+    const world = await getWorld(); // [!code highlight]
+    const runs = await world.runs.list({
+      pagination: { cursor },
+      resolveData: "none",
+    });
+
+    return Response.json({
+      data: runs.data.map((run) => {
+        const parsed = parseWorkflowName(run.workflowName); // [!code highlight]
+
+        return {
+          runId: run.runId,
+          // Use shortName for UI display (e.g., "processOrder") // [!code highlight]
+          displayName: parsed?.shortName ?? run.workflowName, // [!code highlight]
+          // Module info available for debugging // [!code highlight]
+          module: parsed?.moduleSpecifier, // [!code highlight]
+          status: run.status,
+          startedAt: run.startedAt,
+          completedAt: run.completedAt,
+        };
+      }),
+      cursor: runs.cursor,
+    });
+  } catch (error) {
+    return Response.json(
+      { error: "Failed to list workflow runs" },
+      { status: 500 }
+    );
+  }
+}
+```
+
+<Callout type="info">
+  The `workflowName` field contains a machine-readable identifier like `workflow//./src/workflows/order//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
+
+- [`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/v4/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/v4/api-reference/workflow-runtime/index.mdx

@@ -0,0 +1,46 @@
+---
+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/step-entrypoint" title="stepEntrypoint">
+        The HTTP route handler that executes step functions.
+    </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/v4/api-reference/workflow-runtime/meta.json

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

package/docs/v4/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/v4/api-reference/workflow-runtime/step-entrypoint.mdx

@@ -0,0 +1,39 @@
+---
+title: stepEntrypoint
+description: The HTTP route handler that executes step functions.
+type: reference
+summary: Mount stepEntrypoint as the route that executes step functions in custom server environments.
+prerequisites:
+  - /docs/how-it-works/code-transform
+related:
+  - /docs/api-reference/workflow-runtime/workflow-entrypoint
+---
+
+The HTTP route handler that executes step functions. It receives step execution requests from the queue, routes them to the appropriate step function, and reports results back to the workflow run.
+
+Unlike [`workflowEntrypoint()`](/docs/api-reference/workflow-runtime/workflow-entrypoint), this is the handler itself rather than a factory — step bundles register their step functions globally, and the handler routes by step name.
+
+Framework adapters mount this for you at `/.well-known/workflow/v1/step` — you only need it when wiring workflow support into a custom server environment.
+
+{/* @skip-typecheck: stepEntrypoint exists in workflow@4 only; docs samples are type-checked against the v5 packages on main */}
+
+```typescript lineNumbers
+import { stepEntrypoint } from "workflow/runtime";
+
+// Mount on your server, e.g. a fetch-style route:
+export const POST = stepEntrypoint; // [!code highlight]
+```
+
+## API Signature
+
+{/* @skip-typecheck: type-only signature snippet, not compilable code */}
+
+```typescript
+const stepEntrypoint: (req: Request) => Promise<Response>;
+```
+
+A fetch-style request handler.
+
+<Callout type="info">
+  `stepEntrypoint` exists in workflow 4.x only. In 5.x the combined handler created by [`workflowEntrypoint()`](/docs/api-reference/workflow-runtime/workflow-entrypoint) executes steps inline, and the separate step endpoint was removed.
+</Callout>

package/docs/v4/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.