workflow 4.2.0-beta.75 → 4.2.0-beta.76

package/README.md

@@ -5,7 +5,7 @@
       <img alt="Workflow SDK logo" src="https://useworkflow.dev/workflow-circle-symbol-light.svg" height="128">
     </picture>
   </a>
-  <h1>Workflow Development Kit</h1>
+  <h1>Workflow SDK</h1>
 
 <a href="https://vercel.com"><img alt="Vercel logo" src="https://img.shields.io/badge/MADE%20BY%20Vercel-000000.svg?style=for-the-badge&logo=Vercel&labelColor=000"></a>
 <a href="https://www.npmjs.com/package/workflow"><img alt="NPM version" src="https://img.shields.io/npm/v/workflow?style=for-the-badge&labelColor=000000"></a>
@@ -16,7 +16,7 @@
 
 ## Getting Started
 
-The **Workflow Development Kit** lets you easily add durability, reliability, and observability to async JavaScript. Build apps and AI agents that can suspend, resume, and maintain state with ease.
+The **Workflow SDK** lets you easily add durability, reliability, and observability to async JavaScript. Build apps and AI agents that can suspend, resume, and maintain state with ease.
 
 Visit [https://useworkflow.dev](https://useworkflow.dev) to view the full documentation.
 

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

@@ -39,23 +39,17 @@ showSections={["returns"]}
 The World object provides access to several entity interfaces. See the [World SDK](/docs/api-reference/workflow-api/world) reference for complete documentation:
 
 <Cards>
-    <Card href="/docs/api-reference/workflow-api/world/runs" title="world.runs">
-        List, filter, and inspect workflow runs.
+    <Card href="/docs/api-reference/workflow-api/world/storage" title="Storage">
+        Query runs, steps, hooks, and the underlying event log.
     </Card>
-    <Card href="/docs/api-reference/workflow-api/world/steps" title="world.steps">
-        List and inspect step execution data.
-    </Card>
-    <Card href="/docs/api-reference/workflow-api/world/hooks" title="world.hooks">
-        Look up hooks by ID or token.
-    </Card>
-    <Card href="/docs/api-reference/workflow-api/world/events" title="world.events">
-        Query the append-only event log.
-    </Card>
-    <Card href="/docs/api-reference/workflow-api/world/streams" title="world.streams">
+    <Card href="/docs/api-reference/workflow-api/world/streams" title="Streams">
         Read, write, and manage data streams.
     </Card>
-    <Card href="/docs/api-reference/workflow-api/world/queue" title="world.queue">
-        Enqueue runs and create queue handlers.
+    <Card href="/docs/api-reference/workflow-api/world/queue" title="Queue">
+        Low-level queue dispatch (internal SDK infrastructure).
+    </Card>
+    <Card href="/docs/api-reference/workflow-api/world/observability" title="Observability">
+        Hydrate step I/O, parse display names, decrypt data.
     </Card>
 </Cards>
 

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

@@ -22,26 +22,17 @@ import { getWorld } from "workflow/runtime";
 const world = getWorld(); // [!code highlight]
 ```
 
-## Entities
+## Interfaces
 
 <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 href="/docs/api-reference/workflow-api/world/storage" title="Storage">
+        Query runs, steps, hooks, and the underlying event log.
     </Card>
     <Card href="/docs/api-reference/workflow-api/world/streams" title="Streams">
         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 href="/docs/api-reference/workflow-api/world/queue" title="Queue">
+        Low-level queue dispatch (internal SDK infrastructure).
     </Card>
     <Card href="/docs/api-reference/workflow-api/world/observability" title="Observability Utilities">
         Hydrate step I/O, parse display names, and decrypt workflow data.

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

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

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

@@ -6,8 +6,7 @@ summary: "Functions: hydrateResourceIO(), parseStepName(), parseWorkflowName(),
 prerequisites:
   - /docs/api-reference/workflow-api/get-world
 related:
-  - /docs/api-reference/workflow-api/world/steps
-  - /docs/api-reference/workflow-api/world/runs
+  - /docs/api-reference/workflow-api/world/storage
 keywords:
   - workflow/observability
   - hydrateResourceIO
@@ -41,18 +40,14 @@ import { // [!code highlight]
 
 ### 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.
+Deserialize step or run data that was serialized using the [devalue](https://github.com/Rich-Harris/devalue) format. 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
+console.log(hydrated.input, hydrated.output);
 ```
 
 **Parameters:**
@@ -68,77 +63,41 @@ console.log(hydrated.output); // Deserialized output data
 
 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.
+Workflow and step names are stored as machine-readable identifiers. These utilities extract display-friendly names. All return `{ shortName: string, moduleSpecifier: string } | null`.
 
 ### 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"
+// 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"
+// parsed?.shortName → "processOrder"
 ```
 
-**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"
+// parsed?.shortName → "User"
 ```
 
-**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.
+For workflows with encrypted step data, decrypt before hydrating.
 
 ### getEncryptionKeyForRun()
 
@@ -165,10 +124,7 @@ Hydrate step or run data using a decryption key. Use this instead of `hydrateRes
 
 {/* @expect-error:2305,2724 */}
 ```typescript lineNumbers
-import { // [!code highlight]
-  getEncryptionKeyForRun, // [!code highlight]
-  hydrateResourceIOWithKey, // [!code highlight]
-} from "workflow/observability"; // [!code highlight]
+import { getEncryptionKeyForRun, hydrateResourceIOWithKey } from "workflow/observability"; // [!code highlight]
 
 const key = await getEncryptionKeyForRun(runId); // [!code highlight]
 const hydrated = hydrateResourceIOWithKey(step, key); // [!code highlight]
@@ -185,105 +141,24 @@ const hydrated = hydrateResourceIOWithKey(step, key); // [!code highlight]
 
 ## 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]
+console.log("Workflow:", parseWorkflowName(run.workflowName)?.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]
+  const parsed = parseStepName(step.stepName); // [!code highlight]
+  console.log(`  ${parsed?.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
+- [Storage](/docs/api-reference/workflow-api/world/storage) — Query runs, steps, hooks, and events
 - [Serialization](/docs/foundations/serialization) — How workflow data is serialized

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

@@ -1,8 +1,8 @@
 ---
-title: world.queue
-description: Enqueue workflow runs and create queue handlers for background processing.
+title: Queue
+description: Low-level queue interface for dispatching workflow and step invocations.
 type: reference
-summary: "Methods: getDeploymentId(), queue(), createQueueHandler(). Manage workflow run queuing and processing."
+summary: "Methods: getDeploymentId(), queue(), createQueueHandler(). Internal queue dispatch — normally handled by the SDK."
 prerequisites:
   - /docs/api-reference/workflow-api/get-world
 related:
@@ -13,115 +13,74 @@ keywords:
   - getDeploymentId
   - queue
   - createQueueHandler
-  - background processing
-  - enqueue workflow
   - ValidQueueName
+  - queue dispatch
 ---
 
-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.
+Queue methods live directly on the `world` object (not nested). They dispatch internal workflow and step invocations to the queue backend.
+
+<Callout type="warn">
+  These methods are used internally by the Workflow SDK to dispatch execution. You do not need to call them in normal operations — use [`start()`](/docs/api-reference/workflow-api/start) to trigger workflows instead. Direct queue access is only needed if you programmatically create a run via `world.events.create()` with a `run_created` event and need to kick off its initial execution, or for debugging resumption of a flow or step route.
+</Callout>
 
 ## Import
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
 
-const world = getWorld();
-const queue = world.queue; // [!code highlight]
+const world = getWorld(); // [!code highlight]
+// Queue methods are called directly on world — e.g. world.queue()
 ```
 
 ## Methods
 
 ### getDeploymentId()
 
-Get the current deployment ID. Useful for routing queue messages to the correct deployment.
+Get the current deployment ID. Used internally for routing queue messages to the correct deployment.
 
 ```typescript lineNumbers
-const deploymentId = await world.queue.getDeploymentId(); // [!code highlight]
+const deploymentId = await world.getDeploymentId(); // [!code highlight]
 ```
 
 **Returns:** `string` — The current deployment ID
 
 ### queue()
 
-Enqueue a workflow run for background processing.
+Dispatch a message to a named queue. The message payload is an internal SDK type (`WorkflowInvokePayload`, `StepInvokePayload`, or `HealthCheckPayload`).
 
 ```typescript lineNumbers
-const messageId = await world.queue.queue(name, message, opts); // [!code highlight]
+const { messageId } = await world.queue(queueName, payload, opts); // [!code highlight]
 ```
 
 **Parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `name` | `ValidQueueName` | The queue name |
-| `message` | `object` | The message payload to enqueue |
-| `opts` | `object` | Optional configuration |
+| `queueName` | `ValidQueueName` | The queue name (branded string) |
+| `message` | `QueuePayload` | Internal SDK payload |
+| `opts` | `QueueOptions` | Optional — `deploymentId`, `idempotencyKey`, `delaySeconds`, `headers` |
 
-**Returns:** `MessageId`
+**Returns:** `{ messageId: MessageId | null }`
 
 ### createQueueHandler()
 
-Create a handler function for processing queued messages.
+Create an HTTP handler that processes messages from a queue. Used to set up the queue consumer endpoint.
 
 ```typescript lineNumbers
-const handler = world.queue.createQueueHandler(prefix, callback); // [!code highlight]
+const handler = world.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
+| `prefix` | `QueuePrefix` | Queue name prefix to match |
+| `callback` | `(message, meta) => Promise<void \| { timeoutSeconds: number }>` | Handler called for each message. `meta` contains `attempt`, `queueName`, `messageId`, `requestId`. |
 
-```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);
-```
+**Returns:** `(req: Request) => Promise<Response>`
 
 ## Related
 
-- [start()](/docs/api-reference/workflow-api/start) — Higher-level API for starting workflow runs
+- [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
-- [world.runs](/docs/api-reference/workflow-api/world/runs) — Inspect queued and running workflows
+- [Storage](/docs/api-reference/workflow-api/world/storage) — Create events that trigger queue dispatch