workflow 5.0.0-beta.4 → 5.0.0-beta.40

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

@@ -1,10 +1,10 @@
 ---
 title: Queue
-description: Low-level queue interface for dispatching workflow and step invocations.
+description: Low-level queue interface for dispatching workflow invocations.
 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
@@ -17,10 +17,10 @@ keywords:
   - queue dispatch
 ---
 
-Queue methods live directly on the `world` object (not nested). They dispatch internal workflow and step invocations to the queue backend.
+Queue methods live directly on the `world` object (not nested). They dispatch internal workflow invocations, including queued step work, 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.
+  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 flow resumption.
 </Callout>
 
 ## Import
@@ -46,7 +46,7 @@ const deploymentId = await world.getDeploymentId(); // [!code highlight]
 
 ### queue()
 
-Dispatch a message to a named queue. The message payload is an internal SDK type (`WorkflowInvokePayload`, `StepInvokePayload`, or `HealthCheckPayload`).
+Dispatch a message to a named queue. The message payload is an internal SDK type (`WorkflowInvokePayload` or `HealthCheckPayload`). Queued steps use `WorkflowInvokePayload` with `stepId` and `stepName`.
 
 ```typescript lineNumbers
 const { messageId } = await world.queue(queueName, payload, opts); // [!code highlight]
@@ -79,8 +79,10 @@ const handler = world.createQueueHandler(prefix, callback); // [!code highlight]
 
 **Returns:** `(req: Request) => Promise<Response>`
 
+`meta.messageId` should be stable across redeliveries of the same message (one ID per enqueued message, reused on every delivery attempt). The runtime records it on inline `step_started` events as a liveness lease so that only a redelivery of the owning message re-executes a crashed inline step before the lease expires (see [Inline step message ownership](/v5/docs/changelog/step-message-ownership)). A World whose queue mints a fresh ID per delivery degrades gracefully — crashed inline steps recover via the delayed backstop instead of immediately on redelivery — but never wedges or duplicates.
+
 ## Related
 
 - [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/api-reference/{workflow-api → workflow-runtime}/world/storage.mdx

@@ -4,11 +4,11 @@ description: Query workflow runs, steps, hooks, and the underlying event log via
 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
+  - /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-api/world/observability
+  - /docs/api-reference/workflow-observability
 keywords:
   - world.events
   - world.runs
@@ -96,16 +96,20 @@ const result = await world.events.list({ runId, pagination: { cursor } }); // [!
 
 ### events.listByCorrelationId()
 
-List events that share a correlation ID, useful for tracing related events across runs.
+List one run's events that share a correlation ID, useful for tracing a single step, hook or wait through its lifecycle.
+
+A correlation ID is unique within its run, not across runs: two runs can each hold a `step_…`, `hook_…` or `wait_…` ID that reads the same. `runId` is therefore required, and it is also what makes the pagination cursor unambiguous.
 
 ```typescript lineNumbers
 const result = await world.events.listByCorrelationId({ // [!code highlight]
+  runId,
   correlationId: "order-123",
 }); // [!code highlight]
 ```
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
+| `params.runId` | `string` | The run the correlation ID belongs to |
 | `params.correlationId` | `string` | The correlation ID to filter by |
 | `params.pagination.cursor` | `string` | Cursor for the next page |
 
@@ -116,6 +120,7 @@ const result = await world.events.listByCorrelationId({ // [!code highlight]
 | 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` |
@@ -158,6 +163,8 @@ const result = await world.runs.list({ // [!code highlight]
 
 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.
 
+To cancel a batch in one call, a world may implement the optional `runs.cancelMany({ runIds })`. It returns a summary plus a per-run outcome (`cancelled`, `already_cancelled`, `not_cancellable`, `not_found`, or `failed`). Backends that omit it fall back to per-run cancellation automatically.
+
 ### WorkflowRun Type
 
 | Field | Type | Description |
@@ -229,7 +236,7 @@ const result = await world.steps.list({ // [!code highlight]
 | `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).
+  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">
@@ -258,6 +265,12 @@ const hook = await world.hooks.get(hookId); // [!code highlight]
 
 Look up a hook by its token. Useful in webhook resume flows where you receive a token in the callback URL.
 
+<Callout type="info">
+For runtime application code, prefer [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token). Use `world.hooks.getByToken()` when you are working directly with the World storage interface for custom tooling, admin views, or low-level integrations.
+
+Hook-token lookup is the low-level form of the recommended idempotency flow: if a hook is already registered for your business key, reuse the hook's `runId` or resume that hook instead of starting another run. If no hook exists yet, start a workflow that creates the deterministic hook near the beginning and checks `await hook.getConflict()` to detect whether another run claimed the token first — on a conflict it resolves with the run that owns the token. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
+</Callout>
+
 ```typescript lineNumbers
 const hook = await world.hooks.getByToken(token); // [!code highlight]
 ```
@@ -402,7 +415,7 @@ for (const event of events.data) {
 
 - [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
+- [`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 → 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: streams.write(), streams.writeMulti(), streams.get(), streams.close(), streams.list(), streams.getChunks(), streams.getInfo(). Stream methods live on world.streams."
 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
@@ -213,4 +213,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/api-reference/workflow-serde/index.mdx

@@ -29,7 +29,6 @@ The `@workflow/serde` package provides two symbols that allow you to define cust
 
 ## Quick Example
 
-{/* @expect-error:2351 */}
 
 ```typescript lineNumbers
 import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde";

package/docs/api-reference/workflow-serde/workflow-deserialize.mdx

@@ -6,7 +6,6 @@ A symbol used to define custom deserialization for user-defined class instances.
 
 ## Usage
 
-{/* @expect-error:2351 */}
 
 ```typescript lineNumbers
 import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde";
@@ -26,7 +25,7 @@ class Point {
 
 ## API Signature
 
-{/* @skip-typecheck */}
+{/* @skip-typecheck: type-only signature snippet, not compilable code */}
 
 ```typescript
 static [WORKFLOW_DESERIALIZE](data: SerializableData): T

package/docs/api-reference/workflow-serde/workflow-serialize.mdx

@@ -6,7 +6,6 @@ A symbol used to define custom serialization for user-defined class instances. T
 
 ## Usage
 
-{/* @expect-error:2351 */}
 
 ```typescript lineNumbers
 import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde";
@@ -26,7 +25,7 @@ class Point {
 
 ## API Signature
 
-{/* @skip-typecheck */}
+{/* @skip-typecheck: type-only signature snippet, not compilable code */}
 
 ```typescript
 static [WORKFLOW_SERIALIZE](instance: T): SerializableData
@@ -70,6 +69,7 @@ This method runs inside the workflow context and is subject to the same constrai
 - No Node.js-specific APIs (like `fs`, `path`, `crypto`, etc.)
 - No non-deterministic operations (like `Math.random()` or `Date.now()`)
 - No external network calls
+- No side effects on workflow state — the method may run outside deterministic replay, so mutations would not be reconstructed
 
 Keep this method simple and focused on extracting data from the instance.
 </Callout>

package/docs/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/api-reference/workflow-sveltekit/meta.json

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

package/docs/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'` (dev) / `false` (prod) | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. Defaults to `'inline'` in development and `false` in production (smaller function bundles — helps stay under the Vercel 250MB function size limit). Set it explicitly, or use the `WORKFLOW_SOURCEMAP` environment variable, to override in either environment. |
+
+### 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/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/api-reference/workflow-vite/meta.json

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

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

@@ -0,0 +1,48 @@
+---
+title: workflow
+description: Configure Vite and Nitro to transform workflow directives.
+type: reference
+summary: Add the workflow plugin to your Vite config to enable workflow directive transformation in Vite + Nitro apps.
+prerequisites:
+  - /docs/getting-started/vite
+---
+
+Returns the Vite plugins that transform workflow code (`"use step"`/`"use workflow"` directives) and configure the [`workflow/nitro`](/docs/api-reference/workflow-nitro) module on the Nitro server. It is designed to be used alongside `nitro()` from `nitro/vite`, which provides the server framework for API routes and deployment.
+
+## Usage
+
+To enable `"use step"` and `"use workflow"` directives while developing locally or deploying to production, add `workflow()` to the `plugins` array of your Vite config, together with `nitro()`.
+
+```typescript title="vite.config.ts" lineNumbers
+import { nitro } from "nitro/vite";
+import { defineConfig } from "vite";
+import { workflow } from "workflow/vite"; // [!code highlight]
+
+export default defineConfig({
+  plugins: [nitro(), workflow()], // [!code highlight]
+  nitro: {
+    serverDir: "./",
+  },
+});
+```
+
+## API Signature
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `options` | `ModuleOptions` | Optional. Forwarded to the `workflow/nitro` module as its module options. |
+
+#### ModuleOptions
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dirs` | `string[]` | — | Directories to scan for workflows and steps. By default, the `workflows/` directory is scanned from the project root and all layer source directories. |
+| `typescriptPlugin` | `boolean` | `false` | Adds the `workflow` TypeScript plugin to the generated `tsconfig.json` for IDE IntelliSense. |
+| `runtime` | `string` | — | Node.js runtime version for Vercel Functions (e.g. `'nodejs22.x'`, `'nodejs24.x'`). Only applies when deploying to Vercel. |
+| `sourcemap` | `boolean \| 'inline' \| 'linked' \| 'external' \| 'both'` | `'inline'` (dev) / `false` (prod) | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. Defaults to `'inline'` in development and `false` in production (smaller function bundles — helps stay under the Vercel 250MB function size limit). Set it explicitly, or use the `WORKFLOW_SOURCEMAP` environment variable, to override in either environment. |
+
+### 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.