workflow 5.0.0-beta.43 → 5.0.0-beta.46

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

@@ -31,8 +31,8 @@ keywords:
 
 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.
+- **`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";
@@ -62,7 +62,7 @@ await world.events.create(runId, { // [!code highlight]
 | `data` | `CreateEventRequest` | Event data including `eventType` |
 | `params` | `object` | Optional parameters |
 
-**Returns:** `EventResult` — The created event and the affected entity (run/step/hook)
+**Returns:** `EventResult`, the created event and the affected entity (run/step/hook)
 
 ### events.get()
 
@@ -119,7 +119,7 @@ const result = await world.events.listByCorrelationId({ // [!code highlight]
 
 **Returns:** `{ data: Event[], cursor?: string }`
 
-### Event Types
+### Event types
 
 | Category | Types |
 |----------|-------|
@@ -151,6 +151,40 @@ const run = await world.runs.get(runId); // [!code highlight]
 
 **Returns:** `WorkflowRun` (or `WorkflowRunWithoutData` when `resolveData: 'none'`)
 
+### runs.waitForTerminalStatus()
+
+Optional. Long poll for a run to reach a terminal status (`completed`,
+`failed`, or `cancelled`) instead of re-reading it on an interval. This is what
+`await run.returnValue` uses, so a run's result reaches the awaiting side as
+soon as it finishes rather than at the next poll tick.
+
+```typescript lineNumbers
+const run = await world.runs.waitForTerminalStatus?.(runId, { // [!code highlight]
+  timeoutMs: 25_000, // [!code highlight]
+}); // [!code highlight]
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `runId` | `string` | The workflow run ID |
+| `params.timeoutMs` | `number` | Upper bound on the wait. The call returns earlier, the moment the run is terminal |
+| `params.signal` | `AbortSignal` | Abandons the wait |
+| `params.resolveData` | `'all' \| 'none'` | Whether to include input/output data. Default: `'all'` |
+
+**Returns:** the same `WorkflowRun` as `runs.get()`: terminal if the run
+finished within the budget, otherwise the latest snapshot. An expired budget is
+a normal return, not an error, and a missing run throws
+`WorkflowRunNotFoundError` exactly as `runs.get()` does.
+
+<Callout>
+  Not every backend can hold a read open, so this method is optional and may
+  also return a non-terminal snapshot before `timeoutMs` is up. Callers pace
+  their own retries (`await run.returnValue` keeps consecutive non-terminal
+  observations at least one `WORKFLOW_RETURN_VALUE_POLL_INTERVAL_MS` apart), and
+  worlds that omit the method are polled on that interval instead. Set
+  `WORKFLOW_RETURN_VALUE_LONG_POLL=0` to force interval polling everywhere.
+</Callout>
+
 ### runs.list()
 
 ```typescript lineNumbers
@@ -174,13 +208,13 @@ const result = await world.runs.list({ // [!code highlight]
   reads.
 </Callout>
 
-### Cancelling Runs
+### 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.
+To cancel a run, create a `run_cancelled` event through `world.events.create()` (see [world.events](#worldevents) above), or use the Workflow CLI or web interface 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
+### WorkflowRun type
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -211,7 +245,7 @@ const step = await world.steps.get(runId, stepId); // [!code highlight]
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `runId` | `string \| undefined` | The workflow run ID |
+| `runId` | `string` | The workflow run ID that owns the step |
 | `stepId` | `string` | The step ID |
 | `params.resolveData` | `'all' \| 'none'` | Whether to include input/output data. Default: `'all'` |
 
@@ -234,7 +268,7 @@ const result = await world.steps.list({ // [!code highlight]
 
 **Returns:** `{ data: Step[], cursor?: string }`
 
-### Step Type
+### Step type
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -251,11 +285,11 @@ 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 [`hydrateResourceIO()`](/docs/api-reference/workflow-observability/hydrate-resource-io).
+  Step input/output (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.
+  `stepName` is a machine-readable identifier like `step//./src/workflows/order//processPayment`. Use `parseStepName()` from `workflow/observability` to extract the `shortName` for display in a user interface.
 </Callout>
 
 ---
@@ -283,7 +317,7 @@ Look up a hook by its token. Useful in webhook resume flows where you receive a
 <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).
+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
@@ -310,7 +344,7 @@ const result = await world.hooks.list({ // [!code highlight]
 
 **Returns:** `{ data: Hook[], cursor?: string }`
 
-### Hook Type
+### Hook type
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -327,7 +361,7 @@ const result = await world.hooks.list({ // [!code highlight]
 
 ## Examples
 
-### List Runs with Pagination
+### List runs with pagination
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
@@ -342,23 +376,23 @@ const runs = await world.runs.list({ // [!code highlight]
 cursor = runs.cursor; // pass to next call for pagination
 ```
 
-### Get a Run — Full Data vs. Metadata Only
+### 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
+// Full data (default): includes serialized input/output
 const run = await world.runs.get(runId); // [!code highlight]
 
-// Metadata only — lighter, no I/O loaded
+// 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
+### List steps for a progress dashboard
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
@@ -380,7 +414,7 @@ const progress = steps.data.map((step) => {
 });
 ```
 
-### Hydrate Step I/O
+### Hydrate step I/O
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
@@ -392,7 +426,7 @@ const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highl
 console.log(hydrated.input, hydrated.output);
 ```
 
-### Cancel a Run
+### Cancel a run
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
@@ -403,7 +437,7 @@ await world.events.create(runId, { // [!code highlight]
 }); // [!code highlight]
 ```
 
-### Look Up Hook by Token
+### Look up hook by token
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
@@ -413,7 +447,7 @@ const hook = await world.hooks.getByToken(token); // [!code highlight]
 console.log(hook.runId, hook.metadata); // [!code highlight]
 ```
 
-### List Events for Audit Trail
+### List events for audit trail
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
@@ -428,9 +462,9 @@ for (const event of events.data) {
 
 ## 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
+- [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-runtime/world/streams.mdx

@@ -33,7 +33,7 @@ Stream methods live on `world.streams` (the `streams` sub-object of the `World`
 import { getWorld } from "workflow/runtime";
 
 const world = await getWorld(); // [!code highlight]
-// Stream methods are called on world.streams — e.g. world.streams.write()
+// Stream methods are called on world.streams, e.g. world.streams.write()
 ```
 
 ## Methods
@@ -56,7 +56,7 @@ await world.streams.write(runId, "default", chunk); // [!code highlight]
 
 ### writeMulti()
 
-Write multiple chunks in a single operation. Optional optimization — not all World implementations support it. Falls back to sequential `write()` calls if unavailable.
+Write multiple chunks in a single operation. Optional optimization: not all World implementations support it. Falls back to sequential `write()` calls if unavailable.
 
 ```typescript lineNumbers
 await world.streams.writeMulti?.(runId, "default", [chunk1, chunk2]); // [!code highlight]
@@ -173,7 +173,7 @@ const info = await world.streams.getInfo(runId, "default"); // [!code highlight]
 
 ## Examples
 
-### Read a Stream as a Response
+### Read a stream as a response
 
 ```typescript lineNumbers
 // app/api/workflow-streams/read/route.ts
@@ -192,7 +192,7 @@ export async function GET(req: Request) {
 }
 ```
 
-### Paginate Through Stream Chunks
+### Paginate through stream chunks
 
 ```typescript lineNumbers
 import { getWorld } from "workflow/runtime";
@@ -211,6 +211,6 @@ do {
 
 ## 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
-- [Storage](/docs/api-reference/workflow-runtime/world/storage) — Query runs, steps, hooks, and events
+- [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-runtime/world/storage): Query runs, steps, hooks, and events

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

@@ -27,7 +27,7 @@ The `@workflow/serde` package provides two symbols that allow you to define cust
     </Card>
 </Cards>
 
-## Quick Example
+## Quick example
 
 
 ```typescript lineNumbers

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

@@ -23,7 +23,7 @@ class Point {
 }
 ```
 
-## API Signature
+## API signature
 
 {/* @skip-typecheck: type-only signature snippet, not compilable code */}
 
@@ -65,5 +65,5 @@ This method runs inside the workflow context and is subject to the same constrai
 - No non-deterministic operations (like `Math.random()` or `Date.now()`)
 - No external network calls
 
-Keep this method simple and focused on reconstructing the instance from the provided data.
+Keep this method focused on reconstructing the instance from the provided data.
 </Callout>

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

@@ -2,7 +2,7 @@
 title: WORKFLOW_SERIALIZE
 ---
 
-A symbol used to define custom serialization for user-defined class instances. The static method should accept an instance and return serializable data.
+`WORKFLOW_SERIALIZE` defines custom serialization for user-defined class instances. The static method accepts an instance and returns serializable data.
 
 ## Usage
 
@@ -23,7 +23,7 @@ class Point {
 }
 ```
 
-## API Signature
+## API signature
 
 {/* @skip-typecheck: type-only signature snippet, not compilable code */}
 
@@ -60,16 +60,16 @@ The method should return serializable data. This can be:
 The method must be implemented as a **static** method on the class. Instance methods are not supported.
 </Callout>
 
-- Both `WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE` must be implemented together
-- The returned data must itself be serializable
-- The SWC compiler plugin automatically detects and registers classes that implement these symbols
+- Both `WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE` must be implemented together.
+- The returned data must itself be serializable.
+- The SWC compiler plugin automatically detects and registers classes that implement these symbols.
 
 <Callout type="warn">
 This method runs inside the workflow context and is subject to the same constraints as `"use workflow"` functions:
 - 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
+- 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.
+Keep this method focused on extracting data from the instance.
 </Callout>

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

@@ -23,7 +23,7 @@ export default defineConfig({
 });
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -35,8 +35,8 @@ export default defineConfig({
 
 | 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. |
+| `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, which helps stay under the Vercel 250 MB 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.
+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/workflow.mdx

@@ -26,7 +26,7 @@ export default defineConfig({
 });
 ```
 
-## API Signature
+## API signature
 
 ### Parameters
 
@@ -39,10 +39,10 @@ export default defineConfig({
 | 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. |
+| `typescriptPlugin` | `boolean` | `false` | Adds the `workflow` TypeScript plugin to the generated `tsconfig.json` for integrated development environment (IDE) IntelliSense. |
+| `runtime` | `string` | — | Node.js runtime version for Vercel Functions (for example, `'nodejs22.x'` or `'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, which helps stay under the Vercel 250 MB 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.
+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.