workflow 4.2.0-beta.75 → 4.2.0-beta.78

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

@@ -0,0 +1,408 @@
+---
+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-api/get-world
+related:
+  - /docs/api-reference/workflow-api/get-run
+  - /docs/how-it-works/event-sourcing
+  - /docs/api-reference/workflow-api/world/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 = 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` |
+| 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 [Observability Utilities](/docs/api-reference/workflow-api/world/observability).
+</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 = 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 = 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 = 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 = 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 = 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 = 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 = 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
+- [Observability Utilities](/docs/api-reference/workflow-api/world/observability) — Hydrate step I/O, parse display names, decrypt data
+- [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/world/streams.mdx

@@ -2,7 +2,7 @@
 title: Streams
 description: Read, write, and manage real-time data streams for workflow runs.
 type: reference
-summary: "Methods: writeToStream(), readFromStream(), closeStream(), listStreamsByRunId(). Stream methods live directly on the world object."
+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
 related:
@@ -10,9 +10,12 @@ related:
   - /docs/api-reference/workflow/get-writable
 keywords:
   - writeToStream
+  - writeToStreamMulti
   - readFromStream
   - closeStream
   - listStreamsByRunId
+  - getStreamChunks
+  - getStreamInfo
   - Streamer interface
   - real-time streaming
   - stream lifecycle
@@ -37,7 +40,7 @@ const world = getWorld(); // [!code highlight]
 
 ### writeToStream()
 
-Write a data chunk to a named stream for a workflow run.
+Write a data chunk to a named stream.
 
 ```typescript lineNumbers
 await world.writeToStream("default", runId, chunk); // [!code highlight]
@@ -49,11 +52,27 @@ await world.writeToStream("default", runId, chunk); // [!code highlight]
 |-----------|------|-------------|
 | `name` | `string` | The stream name |
 | `runId` | `string` | The workflow run ID |
-| `chunk` | `string \| Uint8Array` | Data to write to the stream |
+| `chunk` | `string \| Uint8Array` | Data to write |
+
+### writeToStreamMulti()
+
+Write multiple chunks in a single operation. Optional optimization — not all World implementations support it. Falls back to sequential `writeToStream()` calls if unavailable.
+
+```typescript lineNumbers
+await world.writeToStreamMulti?.("default", runId, [chunk1, chunk2]); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | The stream name |
+| `runId` | `string` | The workflow run ID |
+| `chunks` | `(string \| Uint8Array)[]` | Chunks to write, in order |
 
 ### readFromStream()
 
-Read data from a named stream as a `ReadableStream`. Returns a live stream that waits for new chunks in real time.
+Read data from a named stream as a live `ReadableStream` that waits for new chunks in real time.
 
 ```typescript lineNumbers
 const readable = await world.readFromStream("default"); // [!code highlight]
@@ -64,7 +83,7 @@ const readable = await world.readFromStream("default"); // [!code highlight]
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `name` | `string` | The stream name |
-| `startIndex` | `number` | Optional starting index for partial reads. Negative values read from the tail (e.g. `-3` starts 3 chunks from the end). |
+| `startIndex` | `number` | Optional. Positive values skip chunks from the start (0-based). Negative values read from the tail (e.g. `-3` starts 3 chunks from the end). Clamped to 0. |
 
 **Returns:** `ReadableStream<Uint8Array>`
 
@@ -97,31 +116,62 @@ const streamNames = await world.listStreamsByRunId(runId); // [!code highlight]
 |-----------|------|-------------|
 | `runId` | `string` | The workflow run ID |
 
-**Returns:** `string[]` — Array of stream names
+**Returns:** `string[]`
 
-## Examples
+### getStreamChunks()
 
-### List All Streams for a Workflow Run
+Fetch stream chunks with cursor-based pagination. Unlike `readFromStream()` (which returns a live `ReadableStream`), this returns a snapshot of currently available chunks.
 
 ```typescript lineNumbers
-// app/api/workflow-streams/route.ts
-import { getWorld } from "workflow/runtime";
+const result = await world.getStreamChunks("default", runId, { // [!code highlight]
+  limit: 50,
+}); // [!code highlight]
+// result.data: StreamChunk[], result.cursor, result.hasMore, result.done
+```
 
-export async function GET(req: Request) {
-  const url = new URL(req.url);
-  const runId = url.searchParams.get("runId");
+**Parameters:**
 
-  if (!runId) {
-    return Response.json({ error: "runId required" }, { status: 400 });
-  }
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | The stream name |
+| `runId` | `string` | The workflow run ID |
+| `options.limit` | `number` | Max chunks per page (default: 100, max: 1000) |
+| `options.cursor` | `string` | Cursor from a previous response |
 
-  const world = getWorld();
-  const streamNames = await world.listStreamsByRunId(runId); // [!code highlight]
+**Returns:** `StreamChunksResponse`
 
-  return Response.json({ streams: streamNames });
-}
+| Field | Type | Description |
+|-------|------|-------------|
+| `data` | `StreamChunk[]` | Chunks in index order. Each has `index` (0-based) and `data` (`Uint8Array`). |
+| `cursor` | `string \| null` | Cursor for the next page |
+| `hasMore` | `boolean` | Whether more pages of already-written chunks exist |
+| `done` | `boolean` | Whether the stream is fully closed. When `false`, new chunks may appear in future requests even after `hasMore` is `false`. |
+
+### getStreamInfo()
+
+Retrieve lightweight metadata about a stream without fetching chunks.
+
+```typescript lineNumbers
+const info = await world.getStreamInfo("default", runId); // [!code highlight]
+// info.tailIndex: last chunk index (-1 if empty), info.done: whether stream is closed
 ```
 
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `string` | The stream name |
+| `runId` | `string` | The workflow run ID |
+
+**Returns:** `StreamInfoResponse`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tailIndex` | `number` | Index of the last known chunk (0-based). `-1` when no chunks have been written. |
+| `done` | `boolean` | Whether the stream is fully complete (closed). |
+
+## Examples
+
 ### Read a Stream as a Response
 
 ```typescript lineNumbers
@@ -130,12 +180,7 @@ import { getWorld } from "workflow/runtime";
 
 export async function GET(req: Request) {
   const url = new URL(req.url);
-  const streamName = url.searchParams.get("name");
-
-  if (!streamName) {
-    return Response.json({ error: "name required" }, { status: 400 });
-  }
-
+  const streamName = url.searchParams.get("name") ?? "default";
   const world = getWorld();
   const readable = await world.readFromStream(streamName); // [!code highlight]
 
@@ -145,8 +190,25 @@ export async function GET(req: Request) {
 }
 ```
 
+### Paginate Through Stream Chunks
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld();
+let cursor: string | undefined;
+
+do {
+  const result = await world.getStreamChunks("default", runId, { cursor }); // [!code highlight]
+  for (const chunk of result.data) {
+    console.log(`Chunk ${chunk.index}:`, chunk.data);
+  }
+  cursor = result.cursor ?? undefined;
+} while (cursor);
+```
+
 ## Related
 
 - [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
-- [world.runs](/docs/api-reference/workflow-api/world/runs) — List runs that may have associated streams
+- [Storage](/docs/api-reference/workflow-api/world/storage) — Query runs, steps, hooks, and events

package/docs/api-reference/workflow-next/with-workflow.mdx

@@ -27,6 +27,57 @@ const workflowConfig = {}
 export default withWorkflow(nextConfig, workflowConfig); // [!code highlight]
 ```
 
+### Monorepos and Workspace Imports
+
+By default, Next.js detects the correct workspace root automatically. If your Next.js app lives in a subdirectory such as `apps/web` and workspace resolution is not working correctly, you can set `outputFileTracingRoot` as a workaround:
+
+```typescript title="apps/web/next.config.ts" lineNumbers
+import { resolve } from "node:path";
+import type { NextConfig } from "next";
+import { withWorkflow } from "workflow/next";
+
+const nextConfig: NextConfig = {
+  outputFileTracingRoot: resolve(process.cwd(), "../.."),
+};
+
+export default withWorkflow(nextConfig);
+```
+
+<Callout type="info">
+Use the smallest directory that contains every workspace package imported by your workflows. If your app already lives at the repository root, you do not need to set `outputFileTracingRoot`.
+</Callout>
+
+## Options
+
+`withWorkflow` accepts an optional second argument to configure the Next.js integration.
+
+```typescript title="next.config.ts" lineNumbers
+import type { NextConfig } from "next";
+import { withWorkflow } from "workflow/next";
+
+const nextConfig: NextConfig = {};
+
+export default withWorkflow(nextConfig, {
+  workflows: {
+    lazyDiscovery: true,
+    local: {
+      port: 4000,
+    },
+  },
+});
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `workflows.lazyDiscovery` | `boolean` | `false` | When `true`, defers workflow discovery until files are requested instead of scanning eagerly at startup. Useful for large projects where startup time matters. |
+| `workflows.local.port` | `number` | — | Overrides the `PORT` environment variable for local development. Has no effect when deployed to Vercel. |
+
+<Callout type="info">
+The `workflows.local` options only affect local development. When deployed to Vercel, the runtime ignores `local` settings and uses the Vercel world automatically.
+</Callout>
+
+## Exporting a Function
+
 If you are exporting a function in your `next.config` you will need to ensure you call the function returned from `withWorkflow`.
 
 ```typescript title="next.config.ts" lineNumbers

package/docs/changelog/meta.json

@@ -1,5 +1,5 @@
 {
   "title": "Changelog",
-  "pages": ["index", "eager-processing"],
+  "pages": ["index", "eager-processing", "resilient-start"],
   "defaultOpen": false
 }