workflow 4.2.0-beta.74 → 4.2.0-beta.75

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

@@ -0,0 +1,67 @@
+---
+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 directly via getWorld() for building observability dashboards, admin tools, and custom integrations.
+prerequisites:
+  - /docs/api-reference/workflow-api/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 = getWorld(); // [!code highlight]
+```
+
+## Entities
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-api/world/runs" title="world.runs">
+        List, filter, and inspect workflow runs with pagination and status filtering.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/steps" title="world.steps">
+        List and inspect step execution data including input/output hydration.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/hooks" title="world.hooks">
+        Look up hooks by ID or token for webhook resume flows.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/events" title="world.events">
+        Query the append-only event log — the source of truth for all workflow state changes.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/streams" title="Streams">
+        Read, write, and manage real-time data streams for workflow runs.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/queue" title="world.queue">
+        Enqueue workflow runs and create queue handlers for processing.
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/observability" title="Observability Utilities">
+        Hydrate step I/O, parse display names, and decrypt workflow data.
+    </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 [Observability Utilities](/docs/api-reference/workflow-api/world/observability) for the full API.

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

@@ -0,0 +1,12 @@
+{
+  "title": "World SDK",
+  "pages": [
+    "runs",
+    "steps",
+    "hooks",
+    "events",
+    "streams",
+    "queue",
+    "observability"
+  ]
+}

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

@@ -0,0 +1,289 @@
+---
+title: Observability Utilities
+description: Hydrate step I/O, parse display names, and decrypt workflow data using workflow/observability.
+type: reference
+summary: "Functions: hydrateResourceIO(), parseStepName(), parseWorkflowName(), parseClassName(), getEncryptionKeyForRun(), hydrateResourceIOWithKey()."
+prerequisites:
+  - /docs/api-reference/workflow-api/get-world
+related:
+  - /docs/api-reference/workflow-api/world/steps
+  - /docs/api-reference/workflow-api/world/runs
+keywords:
+  - workflow/observability
+  - hydrateResourceIO
+  - observabilityRevivers
+  - parseStepName
+  - parseWorkflowName
+  - parseClassName
+  - getEncryptionKeyForRun
+  - hydrateResourceIOWithKey
+  - data hydration
+  - devalue deserialization
+  - encryption decryption
+  - display name parsing
+---
+
+The `workflow/observability` module provides utilities for working with workflow data in observability and debugging tools. It includes functions to hydrate serialized step I/O, parse machine-readable names into display-friendly formats, and decrypt encrypted workflow data.
+
+## Import
+
+```typescript lineNumbers
+import { // [!code highlight]
+  hydrateResourceIO, // [!code highlight]
+  observabilityRevivers, // [!code highlight]
+  parseStepName, // [!code highlight]
+  parseWorkflowName, // [!code highlight]
+  parseClassName, // [!code highlight]
+} from "workflow/observability"; // [!code highlight]
+```
+
+## Data Hydration
+
+### hydrateResourceIO()
+
+Deserialize step or run data that was serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. This is required to display step input/output in your UI.
+
+```typescript lineNumbers
+import { hydrateResourceIO, observabilityRevivers } from "workflow/observability"; // [!code highlight]
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld();
+const step = await world.steps.get(runId, stepId);
+
+const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
+console.log(hydrated.input); // Deserialized input data
+console.log(hydrated.output); // Deserialized output data
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `resource` | `Step \| WorkflowRun` | The step or run with serialized data |
+| `revivers` | `Revivers` | Reviver functions for deserialization. Use `observabilityRevivers` for standard use. |
+
+**Returns:** The resource with hydrated `input` and `output` fields.
+
+### observabilityRevivers
+
+A set of reviver functions that handle standard workflow serialization types (Date, Map, Set, Error, etc.).
+
+```typescript lineNumbers
+import { observabilityRevivers } from "workflow/observability";
+```
+
+## Name Parsing
+
+Workflow and step names are stored as machine-readable identifiers. These utilities extract display-friendly names.
+
+### parseStepName()
+
+Parse a machine-readable step name into its components.
+
+```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"
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `stepName` | `string` | The machine-readable step name |
+
+**Returns:** `{ shortName: string, moduleSpecifier: string } | null`
+
+### parseWorkflowName()
+
+Parse a machine-readable workflow name into its components.
+
+```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"
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `workflowName` | `string` | The machine-readable workflow name |
+
+**Returns:** `{ shortName: string, moduleSpecifier: string } | null`
+
+### parseClassName()
+
+Parse a machine-readable class name into its components.
+
+```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"
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `className` | `string` | The machine-readable class name |
+
+**Returns:** `{ shortName: string, moduleSpecifier: string } | null`
+
+## Encryption
+
+For workflows with encrypted step data, use these utilities to decrypt before hydrating.
+
+### getEncryptionKeyForRun()
+
+Retrieve the encryption key used for a specific workflow run.
+
+{/* @expect-error:2305 */}
+```typescript lineNumbers
+import { getEncryptionKeyForRun } from "workflow/observability"; // [!code highlight]
+
+const key = await getEncryptionKeyForRun(runId); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+
+**Returns:** Encryption key for the run
+
+### hydrateResourceIOWithKey()
+
+Hydrate step or run data using a decryption key. Use this instead of `hydrateResourceIO()` when data is encrypted.
+
+{/* @expect-error:2305,2724 */}
+```typescript lineNumbers
+import { // [!code highlight]
+  getEncryptionKeyForRun, // [!code highlight]
+  hydrateResourceIOWithKey, // [!code highlight]
+} from "workflow/observability"; // [!code highlight]
+
+const key = await getEncryptionKeyForRun(runId); // [!code highlight]
+const hydrated = hydrateResourceIOWithKey(step, key); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `resource` | `Step \| WorkflowRun` | The step or run with encrypted serialized data |
+| `key` | `EncryptionKey` | The encryption key from `getEncryptionKeyForRun()` |
+
+**Returns:** The resource with decrypted and hydrated `input` and `output` fields.
+
+## Examples
+
+### Hydrate Step Input and Output Data
+
+```typescript lineNumbers
+// app/api/workflow-steps/hydrate/route.ts
+import { getWorld } from "workflow/runtime";
+import { // [!code highlight]
+  hydrateResourceIO, // [!code highlight]
+  observabilityRevivers, // [!code highlight]
+  parseStepName, // [!code highlight]
+} from "workflow/observability"; // [!code highlight]
+
+export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const runId = url.searchParams.get("runId");
+  const stepId = url.searchParams.get("stepId");
+
+  if (!runId || !stepId) {
+    return Response.json({ error: "runId and stepId required" }, { status: 400 });
+  }
+
+  const world = getWorld();
+  const step = await world.steps.get(runId, stepId);
+
+  const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highlight]
+  const parsed = parseStepName(step.stepName);
+
+  return Response.json({
+    displayName: parsed?.shortName ?? step.stepName,
+    input: hydrated.input, // [!code highlight]
+    output: hydrated.output, // [!code highlight]
+  });
+}
+```
+
+### Decrypt and Hydrate Encrypted Step Data
+
+For teams with encryption enabled, step data must be decrypted before hydration:
+
+{/* @expect-error:2305,2724 */}
+```typescript lineNumbers
+// app/api/workflow-steps/decrypt/route.ts
+import { getWorld } from "workflow/runtime";
+import { // [!code highlight]
+  getEncryptionKeyForRun, // [!code highlight]
+  hydrateResourceIOWithKey, // [!code highlight]
+  parseStepName, // [!code highlight]
+} from "workflow/observability"; // [!code highlight]
+
+export async function GET(req: Request) {
+  const url = new URL(req.url);
+  const runId = url.searchParams.get("runId");
+  const stepId = url.searchParams.get("stepId");
+
+  if (!runId || !stepId) {
+    return Response.json({ error: "runId and stepId required" }, { status: 400 });
+  }
+
+  const world = getWorld();
+  const step = await world.steps.get(runId, stepId);
+
+  // Decrypt then hydrate // [!code highlight]
+  const key = await getEncryptionKeyForRun(runId); // [!code highlight]
+  const hydrated = hydrateResourceIOWithKey(step, key); // [!code highlight]
+
+  const parsed = parseStepName(step.stepName);
+
+  return Response.json({
+    displayName: parsed?.shortName ?? step.stepName,
+    input: hydrated.input,
+    output: hydrated.output,
+  });
+}
+```
+
+### Parse Display Names for a Run's Steps
+
+Build a progress dashboard with human-readable step names:
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+import { parseStepName, parseWorkflowName } from "workflow/observability"; // [!code highlight]
+
+const world = getWorld();
+
+// Parse workflow name
+const run = await world.runs.get(runId, { resolveData: "none" });
+const workflowDisplay = parseWorkflowName(run.workflowName); // [!code highlight]
+console.log("Workflow:", workflowDisplay?.shortName); // [!code highlight]
+
+// Parse step names
+const steps = await world.steps.list({ runId, resolveData: "none" });
+for (const step of steps.data) {
+  const stepDisplay = parseStepName(step.stepName); // [!code highlight]
+  console.log(`  ${stepDisplay?.shortName}: ${step.status}`); // [!code highlight]
+}
+```
+
+## Related
+
+- [world.steps](/docs/api-reference/workflow-api/world/steps) — Query step data to hydrate
+- [world.runs](/docs/api-reference/workflow-api/world/runs) — Query run data to hydrate
+- [Serialization](/docs/foundations/serialization) — How workflow data is serialized

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

@@ -0,0 +1,127 @@
+---
+title: world.queue
+description: Enqueue workflow runs and create queue handlers for background processing.
+type: reference
+summary: "Methods: getDeploymentId(), queue(), createQueueHandler(). Manage workflow run queuing and processing."
+prerequisites:
+  - /docs/api-reference/workflow-api/get-world
+related:
+  - /docs/api-reference/workflow-api/start
+  - /docs/foundations/starting-workflows
+keywords:
+  - world.queue
+  - getDeploymentId
+  - queue
+  - createQueueHandler
+  - background processing
+  - enqueue workflow
+  - ValidQueueName
+---
+
+The `world.queue` interface provides access to workflow run queuing and processing. Use it to enqueue runs for background execution and create handlers to process queued items.
+
+## Import
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld();
+const queue = world.queue; // [!code highlight]
+```
+
+## Methods
+
+### getDeploymentId()
+
+Get the current deployment ID. Useful for routing queue messages to the correct deployment.
+
+```typescript lineNumbers
+const deploymentId = await world.queue.getDeploymentId(); // [!code highlight]
+```
+
+**Returns:** `string` — The current deployment ID
+
+### queue()
+
+Enqueue a workflow run for background processing.
+
+```typescript lineNumbers
+const messageId = await world.queue.queue(name, message, opts); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `ValidQueueName` | The queue name |
+| `message` | `object` | The message payload to enqueue |
+| `opts` | `object` | Optional configuration |
+
+**Returns:** `MessageId`
+
+### createQueueHandler()
+
+Create a handler function for processing queued messages.
+
+```typescript lineNumbers
+const handler = world.queue.createQueueHandler(prefix, callback); // [!code highlight]
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `prefix` | `string` | Queue name prefix to match |
+| `callback` | `function` | Handler function called for each queued message |
+
+**Returns:** Queue handler function
+
+## Examples
+
+### Enqueue a Workflow Run for Background Processing
+
+```typescript lineNumbers
+// app/api/workflow-queue/route.ts
+import { getWorld } from "workflow/runtime";
+
+export async function POST(req: Request) {
+  const { workflowName, input } = await req.json();
+
+  const world = getWorld();
+  const messageId = await world.queue.queue(workflowName, { // [!code highlight]
+    input,
+    priority: "normal",
+  }); // [!code highlight]
+
+  return Response.json({ messageId });
+}
+```
+
+### Create a Queue Handler for Processing
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld();
+
+const handler = world.queue.createQueueHandler("my-workflows", async (message) => { // [!code highlight]
+  console.log("Processing:", message);
+  // Handle the queued workflow message
+}); // [!code highlight]
+```
+
+### Get Current Deployment ID
+
+```typescript lineNumbers
+import { getWorld } from "workflow/runtime";
+
+const world = getWorld();
+const deploymentId = await world.queue.getDeploymentId(); // [!code highlight]
+console.log("Running on deployment:", deploymentId);
+```
+
+## Related
+
+- [start()](/docs/api-reference/workflow-api/start) — Higher-level API for starting workflow runs
+- [Starting Workflows](/docs/foundations/starting-workflows) — Core concepts for workflow invocation
+- [world.runs](/docs/api-reference/workflow-api/world/runs) — Inspect queued and running workflows