workflow 4.4.0 → 4.5.0

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

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

@@ -0,0 +1,409 @@
+---
+title: Storage
+description: Query workflow runs, steps, hooks, and the underlying event log via the World storage interface.
+type: reference
+summary: "Interfaces: world.events, world.runs, world.steps, world.hooks. Events are the source of truth; runs, steps, and hooks are materialized views."
+prerequisites:
+  - /docs/api-reference/workflow-runtime/get-world
+related:
+  - /docs/api-reference/workflow-api/get-run
+  - /docs/how-it-works/event-sourcing
+  - /docs/api-reference/workflow-observability
+keywords:
+  - world.events
+  - world.runs
+  - world.steps
+  - world.hooks
+  - event log
+  - event sourcing
+  - materialized views
+  - WorkflowRun
+  - Step
+  - Hook
+  - Event
+  - cursor pagination
+  - resolveData
+  - run_cancelled
+  - correlation ID
+  - parseStepName
+  - parseWorkflowName
+---
+
+The World storage interface exposes four sub-interfaces for querying workflow data:
+
+- **`world.events`** — The append-only event log. This is the source of truth for all workflow state. See [Event Sourcing](/docs/how-it-works/event-sourcing) for background.
+- **`world.runs`**, **`world.steps`**, **`world.hooks`** — Materialized views derived from the event log, provided as convenience accessors for the most common query patterns.
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = await getWorld(); // [!code highlight]
+```
+
+---
+
+## world.events
+
+The event log drives all workflow state. Use it for audit trails, debugging, and programmatic run cancellation.
+
+### events.create()
+
+Create a new event for a workflow run. Most commonly used to cancel a run.
+
+```typescript lineNumbers
+await world.events.create(runId, { // [!code highlight]
+  eventType: "run_cancelled", // [!code highlight]
+}); // [!code highlight]
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string \| null` | The workflow run ID (`null` only for `run_created` events, where the server generates an ID) |
+| `data` | `CreateEventRequest` | Event data including `eventType` |
+| `params` | `object` | Optional parameters |
+
+**Returns:** `EventResult` — The created event and the affected entity (run/step/hook)
+
+### events.get()
+
+Retrieve a single event by run ID and event ID.
+
+```typescript lineNumbers
+const event = await world.events.get(runId, eventId); // [!code highlight]
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+| `eventId` | `string` | The event ID |
+
+**Returns:** `Event`
+
+### events.list()
+
+List events for a run with cursor pagination.
+
+```typescript lineNumbers
+const result = await world.events.list({ runId, pagination: { cursor } }); // [!code highlight]
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `params.runId` | `string` | Filter events by run ID |
+| `params.pagination.cursor` | `string` | Cursor for the next page |
+
+**Returns:** `{ data: Event[], cursor?: string }`
+
+### events.listByCorrelationId()
+
+List events that share a correlation ID, useful for tracing related events across runs.
+
+```typescript lineNumbers
+const result = await world.events.listByCorrelationId({ // [!code highlight]
+  correlationId: "order-123",
+}); // [!code highlight]
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `params.correlationId` | `string` | The correlation ID to filter by |
+| `params.pagination.cursor` | `string` | Cursor for the next page |
+
+**Returns:** `{ data: Event[], cursor?: string }`
+
+### Event Types
+
+| Category | Types |
+|----------|-------|
+| Run | `run_created`, `run_started`, `run_completed`, `run_failed`, `run_cancelled` |
+| Attribute | `attr_set` |
+| Step | `step_created`, `step_started`, `step_completed`, `step_failed`, `step_retrying` |
+| Hook | `hook_created`, `hook_received`, `hook_disposed`, `hook_conflict` |
+| Wait | `wait_created`, `wait_completed` |
+
+---
+
+## world.runs
+
+Materialized from run events. Use it to list and inspect workflow runs.
+
+### runs.get()
+
+```typescript lineNumbers
+const run = await world.runs.get(runId); // [!code highlight]
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+| `params.resolveData` | `'all' \| 'none'` | Whether to include input/output data. Default: `'all'` |
+
+**Returns:** `WorkflowRun` (or `WorkflowRunWithoutData` when `resolveData: 'none'`)
+
+### runs.list()
+
+```typescript lineNumbers
+const result = await world.runs.list({ // [!code highlight]
+  pagination: { cursor },
+}); // [!code highlight]
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `params.pagination.cursor` | `string` | Cursor for the next page |
+| `params.resolveData` | `'all' \| 'none'` | Whether to include input/output data |
+
+**Returns:** `{ data: WorkflowRun[], cursor?: string }`
+
+### Cancelling Runs
+
+To cancel a run, create a `run_cancelled` event via `world.events.create()` (see [world.events](#worldevents) above), or use the CLI or Web UI helpers.
+
+### WorkflowRun Type
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `runId` | `string` | Unique run identifier |
+| `status` | `string` | `'running'`, `'completed'`, `'failed'`, `'cancelled'` |
+| `workflowName` | `string` | Machine-readable workflow identifier |
+| `input` | `any` | Workflow input data (when `resolveData: 'all'`) |
+| `output` | `any` | Workflow output data (when `resolveData: 'all'`) |
+| `error` | `any` | Error data if the run failed |
+| `startedAt` | `string` | ISO timestamp when the run started |
+| `completedAt` | `string \| null` | ISO timestamp when the run completed |
+
+<Callout type="warn">
+  `workflowName` is a machine-readable identifier like `workflow//./src/workflows/order//processOrder`. Use `parseWorkflowName()` from `workflow/observability` to extract a display-friendly name.
+</Callout>
+
+---
+
+## world.steps
+
+Materialized from step events. Use it to list steps, inspect their input/output, and build progress dashboards.
+
+### steps.get()
+
+```typescript lineNumbers
+const step = await world.steps.get(runId, stepId); // [!code highlight]
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string \| undefined` | The workflow run ID |
+| `stepId` | `string` | The step ID |
+| `params.resolveData` | `'all' \| 'none'` | Whether to include input/output data. Default: `'all'` |
+
+**Returns:** `Step` (or `StepWithoutData` when `resolveData: 'none'`)
+
+### steps.list()
+
+```typescript lineNumbers
+const result = await world.steps.list({ // [!code highlight]
+  runId,
+  pagination: { cursor },
+}); // [!code highlight]
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `params.runId` | `string` | Filter steps by run ID |
+| `params.pagination.cursor` | `string` | Cursor for the next page |
+| `params.resolveData` | `'all' \| 'none'` | Whether to include input/output data |
+
+**Returns:** `{ data: Step[], cursor?: string }`
+
+### Step Type
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `runId` | `string` | Parent workflow run ID |
+| `stepId` | `string` | Unique step identifier |
+| `stepName` | `string` | Machine-readable step identifier |
+| `status` | `string` | `'running'`, `'completed'`, `'failed'` |
+| `input` | `any` | Step input data (when `resolveData: 'all'`) |
+| `output` | `any` | Step output data (when `resolveData: 'all'`) |
+| `error` | `any` | Error data if the step failed |
+| `attempt` | `number` | Current retry attempt number |
+| `startedAt` | `string` | ISO timestamp when the step started |
+| `completedAt` | `string \| null` | ISO timestamp when the step completed |
+| `retryAfter` | `string \| null` | ISO timestamp for next retry attempt |
+
+<Callout type="info">
+  Step I/O is serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. Use `hydrateResourceIO()` from `workflow/observability` to deserialize it for display. See [`hydrateResourceIO()`](/docs/api-reference/workflow-observability/hydrate-resource-io).
+</Callout>
+
+<Callout type="warn">
+  `stepName` is a machine-readable identifier like `step//./src/workflows/order//processPayment`. Use `parseStepName()` from `workflow/observability` to extract the `shortName` for UI display.
+</Callout>
+
+---
+
+## world.hooks
+
+Materialized from hook events. Hooks are pause points in workflows that wait for external input. Use this interface to look up hooks by ID or token, inspect metadata, and build UIs for pending approvals.
+
+### hooks.get()
+
+```typescript lineNumbers
+const hook = await world.hooks.get(hookId); // [!code highlight]
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `hookId` | `string` | The hook ID |
+
+**Returns:** `Hook`
+
+### hooks.getByToken()
+
+Look up a hook by its token. Useful in webhook resume flows where you receive a token in the callback URL.
+
+```typescript lineNumbers
+const hook = await world.hooks.getByToken(token); // [!code highlight]
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `token` | `string` | The hook token |
+
+**Returns:** `Hook`
+
+### hooks.list()
+
+```typescript lineNumbers
+const result = await world.hooks.list({ // [!code highlight]
+  pagination: { cursor },
+}); // [!code highlight]
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `params.pagination.cursor` | `string` | Cursor for the next page |
+
+**Returns:** `{ data: Hook[], cursor?: string }`
+
+### Hook Type
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `runId` | `string` | Parent workflow run ID |
+| `hookId` | `string` | Unique hook identifier |
+| `token` | `string` | Hook token for resuming |
+| `ownerId` | `string` | Owner (team/user) ID |
+| `projectId` | `string` | Project ID |
+| `environment` | `string` | Deployment environment |
+| `metadata` | `object` | Custom metadata attached to the hook |
+| `isWebhook` | `boolean` | Whether this is a webhook-style hook |
+
+---
+
+## Examples
+
+### List Runs with Pagination
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = await getWorld();
+let cursor: string | undefined;
+
+const runs = await world.runs.list({ // [!code highlight]
+  pagination: { cursor },
+}); // [!code highlight]
+
+cursor = runs.cursor; // pass to next call for pagination
+```
+
+### Get a Run — Full Data vs. Metadata Only
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = await getWorld();
+
+// Full data (default) — includes serialized input/output
+const run = await world.runs.get(runId); // [!code highlight]
+
+// Metadata only — lighter, no I/O loaded
+const lightweight = await world.runs.get(runId, { // [!code highlight]
+  resolveData: "none", // [!code highlight]
+}); // [!code highlight]
+```
+
+### List Steps for a Progress Dashboard
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+import { parseStepName } from "workflow/observability"; // [!code highlight]
+
+const world = await getWorld();
+const steps = await world.steps.list({ // [!code highlight]
+  runId,
+  resolveData: "none",
+}); // [!code highlight]
+
+const progress = steps.data.map((step) => {
+  const parsed = parseStepName(step.stepName); // [!code highlight]
+  return {
+    stepId: step.stepId,
+    displayName: parsed?.shortName ?? step.stepName, // [!code highlight]
+    status: step.status,
+  };
+});
+```
+
+### Hydrate Step I/O
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
+
+const world = await getWorld();
+const step = await world.steps.get(runId, stepId); // [!code highlight]
+const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
+console.log(hydrated.input, hydrated.output);
+```
+
+### Cancel a Run
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = await getWorld();
+await world.events.create(runId, { // [!code highlight]
+  eventType: "run_cancelled", // [!code highlight]
+}); // [!code highlight]
+```
+
+### Look Up Hook by Token
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = await getWorld();
+const hook = await world.hooks.getByToken(token); // [!code highlight]
+console.log(hook.runId, hook.metadata); // [!code highlight]
+```
+
+### List Events for Audit Trail
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = await getWorld();
+const events = await world.events.list({ runId }); // [!code highlight]
+
+for (const event of events.data) {
+  console.log(event.eventType, event.createdAt);
+}
+```
+
+## Related
+
+- [Event Sourcing](/docs/how-it-works/event-sourcing) — How the event log powers workflow replay and state
+- [getRun()](/docs/api-reference/workflow-api/get-run) — Higher-level API for working with individual runs
+- [`workflow/observability`](/docs/api-reference/workflow-observability) — Hydrate step I/O and parse display names
+- [resumeHook()](/docs/api-reference/workflow-api/resume-hook) — Resume a workflow by sending a payload to a hook
+- [Hooks](/docs/foundations/hooks) — Core concepts for hooks and pause points
+- [Workflows and Steps](/docs/foundations/workflows-and-steps) — Core concepts for steps

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

@@ -4,7 +4,7 @@ description: Read, write, and manage real-time data streams for workflow runs.
 type: reference
 summary: "Methods: writeToStream(), writeToStreamMulti(), readFromStream(), closeStream(), listStreamsByRunId(), getStreamChunks(), getStreamInfo(). Stream methods live directly on the world object."
 prerequisites:
-  - /docs/api-reference/workflow-api/get-world
+  - /docs/api-reference/workflow-runtime/get-world
 related:
   - /docs/foundations/streaming
   - /docs/api-reference/workflow/get-writable
@@ -211,4 +211,4 @@ do {
 
 - [Streaming](/docs/foundations/streaming) — Core concepts for streaming data from workflows
 - [getWritable()](/docs/api-reference/workflow/get-writable) — The standard way to write to streams from within steps
-- [Storage](/docs/api-reference/workflow-api/world/storage) — Query runs, steps, hooks, and events
+- [Storage](/docs/api-reference/workflow-runtime/world/storage) — Query runs, steps, hooks, and events

package/docs/v5/api-reference/workflow-sveltekit/index.mdx

@@ -0,0 +1,18 @@
+---
+title: "workflow/sveltekit"
+description: SvelteKit integration for automatic workflow bundling via Vite.
+type: overview
+summary: Explore the SvelteKit integration for automatic workflow bundling and runtime support.
+related:
+  - /docs/getting-started/sveltekit
+---
+
+SvelteKit integration for Workflow SDK that configures Vite to transform workflow code and build the workflow bundles.
+
+## Functions
+
+<Cards>
+    <Card title="workflowPlugin()" href="/docs/api-reference/workflow-sveltekit/workflow-plugin">
+        Vite plugin that transforms workflow code (`"use step"`/`"use workflow"` directives) in SvelteKit apps
+    </Card>
+</Cards>

package/docs/v5/api-reference/workflow-sveltekit/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "workflow/sveltekit",
+  "pages": ["workflow-plugin"]
+}

package/docs/v5/api-reference/workflow-sveltekit/workflow-plugin.mdx

@@ -0,0 +1,42 @@
+---
+title: workflowPlugin
+description: Configure Vite to transform workflow directives in SvelteKit.
+type: reference
+summary: Add workflowPlugin to your Vite config to enable workflow directive transformation in SvelteKit apps.
+prerequisites:
+  - /docs/getting-started/sveltekit
+---
+
+Returns the Vite plugins that transform workflow code (`"use step"`/`"use workflow"` directives) and build the workflow bundles in a SvelteKit app.
+
+## Usage
+
+To enable `"use step"` and `"use workflow"` directives while developing locally or deploying to production, add `workflowPlugin()` to the `plugins` array of your Vite config.
+
+```typescript title="vite.config.ts" lineNumbers
+import { sveltekit } from "@sveltejs/kit/vite";
+import { defineConfig } from "vite";
+import { workflowPlugin } from "workflow/sveltekit"; // [!code highlight]
+
+export default defineConfig({
+  plugins: [sveltekit(), workflowPlugin()], // [!code highlight]
+});
+```
+
+## API Signature
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `WorkflowPluginOptions` | Optional. Configures the workflow build. |
+
+#### WorkflowPluginOptions
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. Set to `false` for smaller function bundles (useful for staying under the Vercel 250MB function size limit) at the cost of stack traces pointing at generated code. Can also be set via the `WORKFLOW_SOURCEMAP` environment variable. |
+
+### Returns
+
+Returns an array of Vite `Plugin` objects. Spread or pass the array directly to the `plugins` option of your Vite config — Vite flattens nested plugin arrays automatically.

package/docs/v5/api-reference/workflow-vite/index.mdx

@@ -0,0 +1,18 @@
+---
+title: "workflow/vite"
+description: Vite plugin for automatic workflow bundling in Vite + Nitro apps.
+type: overview
+summary: Explore the Vite plugin for automatic workflow bundling and runtime support.
+related:
+  - /docs/getting-started/vite
+---
+
+Vite integration for Workflow SDK. It wraps the [`workflow/nitro`](/docs/api-reference/workflow-nitro) module as a Vite plugin, for apps using Nitro's Vite plugin (`nitro/vite`).
+
+## Functions
+
+<Cards>
+    <Card title="workflow()" href="/docs/api-reference/workflow-vite/workflow">
+        Vite plugin that transforms workflow code (`"use step"`/`"use workflow"` directives) and configures the Nitro server
+    </Card>
+</Cards>

package/docs/v5/api-reference/workflow-vite/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "workflow/vite",
+  "pages": ["workflow"]
+}