workflow 5.0.0-beta.14 → 5.0.0-beta.16

package/docs/api-reference/workflow-runtime/workflow-entrypoint.mdx

@@ -0,0 +1,42 @@
+---
+title: workflowEntrypoint
+description: Create the HTTP route handler that executes workflow runs from a workflow bundle.
+type: reference
+summary: Use workflowEntrypoint to wire a compiled workflow bundle into an HTTP route in custom server environments.
+prerequisites:
+  - /docs/how-it-works/code-transform
+related:
+  - /docs/api-reference/workflow-runtime/health-check
+---
+
+Creates the HTTP route handler that executes workflow runs. The handler receives queue messages, replays the workflow from its event log, executes steps inline where possible, and suspends when the workflow waits on sleeps or hooks.
+
+Framework adapters (Next.js, Nitro, SvelteKit, etc.) call this for you and mount the result at `/.well-known/workflow/v1/flow` — you only need it when wiring workflow support into a custom server environment.
+
+```typescript lineNumbers
+import { workflowEntrypoint } from "workflow/runtime";
+declare const workflowBundleCode: string; // @setup
+
+const handler = workflowEntrypoint(workflowBundleCode); // [!code highlight]
+
+// Mount on your server, e.g. a fetch-style route:
+export const POST = (req: Request) => handler(req);
+```
+
+## API Signature
+
+### Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `workflowCode` | `string` | The compiled workflow bundle code containing all workflow functions |
+| `options` | `{ namespace?: string }` | Optional. `namespace` scopes the queue topics this handler consumes. |
+
+### Returns
+
+Returns a fetch-style request handler: `(req: Request) => Promise<Response>`.
+
+## Related Functions
+
+- [`getWorldHandlers()`](/docs/api-reference/workflow-runtime/get-world-handlers) - The build-time World access this handler is built on.
+- [`healthCheck()`](/docs/api-reference/workflow-runtime/health-check) - Verify the entrypoint processes queue messages end-to-end.

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

@@ -4,7 +4,7 @@ description: Low-level API for inspecting and managing workflow runs, steps, eve
 type: overview
 summary: Access workflow infrastructure via await getWorld() for building observability dashboards, admin tools, and custom integrations.
 prerequisites:
-  - /docs/api-reference/workflow-api/get-world
+  - /docs/api-reference/workflow-runtime/get-world
 keywords:
   - getWorld
   - World SDK
@@ -25,18 +25,15 @@ const world = await getWorld(); // [!code highlight]
 ## Interfaces
 
 <Cards>
-    <Card href="/docs/api-reference/workflow-api/world/storage" title="Storage">
+    <Card href="/docs/api-reference/workflow-runtime/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">
+    <Card href="/docs/api-reference/workflow-runtime/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="Queue">
+    <Card href="/docs/api-reference/workflow-runtime/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.
-    </Card>
 </Cards>
 
 <Callout type="info">
@@ -55,4 +52,4 @@ const hydrated = hydrateResourceIO(step, observabilityRevivers); // [!code highl
 console.log(hydrated.input, hydrated.output);
 ```
 
-See [Observability Utilities](/docs/api-reference/workflow-api/world/observability) for the full API.
+See [`workflow/observability`](/docs/api-reference/workflow-observability) for the full API.

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

@@ -0,0 +1,4 @@
+{
+  "title": "World SDK",
+  "pages": ["storage", "streams", "queue"]
+}

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

@@ -4,7 +4,7 @@ description: Low-level queue interface for dispatching workflow and step invocat
 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
@@ -83,4 +83,4 @@ const handler = world.createQueueHandler(prefix, callback); // [!code highlight]
 
 - [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
@@ -116,6 +116,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` |
@@ -229,7 +230,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 +259,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 +409,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

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'` | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. Set to `false` for smaller function bundles (useful for staying under the Vercel 250MB function size limit) at the cost of stack traces pointing at generated code. Can also be set via the `WORKFLOW_SOURCEMAP` environment variable. |
+
+### 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'` | Controls source maps on generated workflow bundles. Accepts the same values as esbuild's `sourcemap` option. Set to `false` for smaller function bundles (useful for staying under the Vercel 250MB function size limit) at the cost of stack traces pointing at generated code. Can also be set via the `WORKFLOW_SOURCEMAP` environment variable. |
+
+### 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/changelog/attributes-mvp.mdx

@@ -9,6 +9,18 @@ This is a minimal, **experimental** subset of the [planned Workflow Attributes f
 
 The MVP lets workflow code attach plaintext `string → string` metadata to a run, viewable in any observability surface that reads the `WorkflowRun` entity. It is deliberately narrow: write-only, no reads from inside a run, no list/filter endpoints, no event-log representation. The wire format and SDK surface are chosen so the full 5.0.0 implementation replaces this without source-level breaking changes for end users.
 
+## Native v4 follow-up
+
+The v4 implementation now completes the planned dispatch migration while preserving the experimental SDK name:
+
+- `experimental_setAttributes()` appends a native `attr_set` event from workflow and step bodies instead of mutating through the internal step bridge.
+- Native events carry writer attribution and are materialized immediately onto `run.attributes`.
+- `start(workflow, args, { attributes })` seeds attributes on the initial `run_created` event, including the resilient-start creation path.
+- The World spec is bumped to v4; attributes are supported for v4 runs rather than being backported into older run specifications.
+- The direct server attributes endpoint remains available only as a deprecated compatibility path for clients that shipped with the MVP.
+
+The remainder of this page documents the original MVP motivation and implementation.
+
 ## What MVP supports
 
 - `experimental_setAttributes(record)` callable from a **workflow body** (`"use workflow"` function), dispatched via an internal `__builtin_set_attributes` step bridge so the mutation gets a `step_created → step_completed` event pair
@@ -296,13 +308,13 @@ End-to-end in `workbench/nextjs-turbopack` (exercises the full SWC plugin + work
 - `Promise.all` of disjoint-key writes — every key persists
 - Workflow throws after an awaited `experimental_setAttributes` — the attribute persists on the now-`failed` run (the per-run file lock on `run_failed` re-reads inside the critical section so the attribute snapshot survives the lifecycle write)
 
-## Migration to 5.0.0
+## Migration to native v4
 
-When the full attributes feature ships:
+The native attributes follow-up applies this migration:
 
 - `experimental_setAttributes` (SDK) — unchanged signature, new dispatch path
 - `runs.experimentalSetAttributes` (world interface) — deprecated, then removed; replaced by `events.create(runId, { eventType: 'attr_set', eventData: { changes, writer } })`
-- Wire endpoint — `POST /v2/runs/:runId/attributes` removed; the same `changes` shape posts to `POST /v2/runs/:id/events`
+- Wire endpoint — `POST /v2/runs/:runId/attributes` is deprecated but temporarily retained for older clients; new calls post the same `changes` shape to events as `attr_set`
 - Pre-existing attribute values on MVP-era runs remain on the run entity but are not represented in the event log
 
 Skew protection means workflows started under the MVP will continue to run with the MVP dispatch path on their original deployment. New deployments use the new path. No in-place data migration is needed.

package/docs/changelog/eager-processing.mdx

@@ -157,15 +157,35 @@ To prevent deadlock when polling is executed inline by the step executor, `Run#p
 
 ### Mixed Suspensions
 
-A suspension may contain steps, hooks, and waits simultaneously. The handler creates events for all, then chooses between inline execution and queue dispatch:
+A suspension may contain steps, hooks, and waits simultaneously. The handler creates events for all, then dispatches everything we are not running inline as a single parallel batch of queue messages:
 
-- **Steps only** (no waits): one owned step is executed inline; the rest are queued. The loop continues after the inline step completes.
-- **Steps + at least one wait**: every step is queued (no inline execution). The handler returns with the wait timeout. Whichever lands first — a step's continuation or the wait timer — drives the next replay.
-- **Hooks / waits only**: handler returns with the wait timeout (or no timeout, for hook-only suspensions). The next continuation is driven by external resume or the wait timer.
+```
+ownedPendingSteps = pendingSteps.filter(owned by this handler)
+inlineStep        = ownedPendingSteps[0]   // optional
+
+dispatches = [
+  ...for each non-inline pendingStep: queue stepId message (idempotency=correlationId),
+  ...if soonest pending wait:          queue delayed continuation
+                                       (delaySeconds=min(remaining, maxDelay),
+                                        idempotency=waitCorrelationId[:hop|:secondBucket]),
+]
+await Promise.all(dispatches)
+
+if (!inlineStep) return
+await executeStep(inlineStep)
+```
+
+The wait timer is queued as its own continuation rather than encoded in the handler's return value (`{ timeoutSeconds }`). This is what makes `Promise.race(step, sleep)` behave correctly: even when the inline step blocks the handler for the full step duration, the wait continuation fires in a separate function invocation. If the sleep wins, that parallel invocation observes `wait_completed` via the "complete elapsed waits" pass and finishes the run; if the step wins, the wait continuation fires later and no-ops on the terminal run via the existing terminal-event check.
+
+Step queueing remains unconditional (covers crash recovery: if a prior handler wrote `step_created` but crashed before queueing, a later handler will queue it; idempotency keys dedupe redundant queues across concurrent handlers).
+
+Wait continuations are likewise deduplicated, keyed on the wait's correlation ID: while a wait is pending, every replay pass over the run re-observes it and would otherwise enqueue another delayed continuation. A key is attached in all cases, since some worlds serialize key-less workflow messages per run, which would park the continuation behind the handler's own inline step execution.
+
+Two situations deliver a continuation while its wait is still pending, and each varies the key so the re-enqueue isn't dropped by a world's dedupe window (which outlives the first delivery): waits longer than the maximum queue delay (23h, bounded by VQS's 24h message retention) are clamped and chained across hops, with the hop index suffixed to the key so each hop dedupes within its window but the chain always advances; and near-elapsed waits (≤2s remaining) use a second-bucketed key suffix so a continuation delivered marginally early (clock skew) can enqueue a fresh short-delay retry. See `runtime/wait-continuation.ts` for the full selection logic.
 
-The "no inline when there's a wait" carve-out is necessary to preserve `Promise.race(step, sleep)` semantics. Inline `await executeStep(...)` blocks the handler for the full step duration, and `wait_completed` events are only created on the *next* loop iteration's "complete elapsed waits" pass — so a longer-running step would always swallow the shorter sleep and `Promise.race` would resolve incorrectly. Queueing the step in this case lets the wait timer drive a continuation in parallel.
+The retry/throttle and hook-conflict paths still return `{ timeoutSeconds }` since their semantics are "redeliver THIS message after a delay" rather than "schedule a fresh wait timer." Those can be unified in a follow-up.
 
-Pure step suspensions (without waits) still benefit from inline execution; the carve-out only costs an extra queue roundtrip when a step and a sleep coexist.
+The unified dispatch requires `world-local` to honor `delaySeconds` on the queue (added in the same PR series). Without it, the wait continuation would fire instantly in dev and trigger a spurious replay before the wait elapsed (recoverable via redelivery, but inefficient and observable as duplicate `step_started` events under contention).
 
 ### VM Sandboxing
 

package/docs/changelog/index.mdx

@@ -13,4 +13,4 @@ Stay up to date with the latest changes to Workflow SDK.
 ## 2026
 
 - [Eager processing of steps and incremental event replay](/docs/changelog/eager-processing) - March 2026
-- [Serializable AbortController and AbortSignal](/docs/changelog/serializable-abort-controller) — March 12, 2026
+- Serializable AbortController and AbortSignal — March 12, 2026

package/docs/cookbook/advanced/child-workflows.mdx

@@ -3,6 +3,8 @@ title: Child Workflows
 description: Spawn child workflows from a parent and wait for completion via hook resume.
 type: guide
 summary: Orchestrate independent child workflows from a parent using start(), defineHook(), and startAndWait() — the child resumes the parent's hook when done instead of polling getRun().status.
+related:
+  - /docs/api-reference/workflow-api/start
 ---
 
 Use child workflows when a single workflow needs to orchestrate many independent units of work. Each child runs as its own workflow with a separate event log, retry boundary, and failure scope -- if one child fails, it doesn't take down the parent or siblings.
@@ -145,7 +147,7 @@ Polling with `getRun().status` in a `sleep()` loop works, but hook resume is pre
 - **Zero compute while waiting** — the parent suspends on the hook instead of waking every poll interval
 - **Immediate wake-up** — the parent resumes as soon as the child finishes, not on the next poll tick
 - **Typed payloads** — the child sends `{ status, value | error }` directly; no separate `returnValue` fetch step
-- **No worker-pool pressure** — `Run#returnValue` polling inside steps can hold worker slots while waiting for children (see [Eager Processing](/changelog/eager-processing))
+- **No worker-pool pressure** — `Run#returnValue` polling inside steps can hold worker slots while waiting for children (see [Eager Processing](/docs/changelog/eager-processing))
 
 When a parent calls a child workflow inline with `await` (flattened into the same run), the same wrapper and hook handshake still works — pass the token and `await processDocumentWithCompletion(...)` inside `startAndWait()` instead of calling `start()`.
 

package/docs/cookbook/advanced/publishing-libraries.mdx

@@ -270,14 +270,14 @@ Declare `workflow` as an **optional** peer so consumers without the runtime aren
 
 ### Runtime detection
 
-Wrap a dynamic `import("workflow")` in try/catch. If either the module isn't installed *or* `getWorkflowMetadata()` throws (call site isn't inside a workflow run), fall through to the standalone path.
+Wrap a dynamic `import("workflow")` in try/catch. If either the module isn't installed *or* `getStepMetadata()` throws (call site isn't inside a workflow step), fall through to the standalone path.
 
 ```typescript lineNumbers
-async function getWorkflowRunId(): Promise<string | null> { // [!code highlight]
+async function getWorkflowStepId(): Promise<string | null> { // [!code highlight]
   try {
     const wf = await import("workflow");
-    const { workflowRunId } = wf.getWorkflowMetadata();
-    return workflowRunId;
+    const { stepId } = wf.getStepMetadata();
+    return stepId;
   } catch {
     return null;
   }
@@ -286,13 +286,14 @@ async function getWorkflowRunId(): Promise<string | null> { // [!code highlight]
 
 ### A concrete use case: replay-safe idempotency keys
 
-A payments utility that uses the workflow run ID as a Stripe idempotency key when available, and a fresh UUID otherwise:
+A payments utility that uses the current workflow step ID as a Stripe idempotency key when available, and a fresh UUID otherwise:
 
-{/* @skip-typecheck - depends on getWorkflowRunId defined in the previous block */}
 ```typescript lineNumbers
+declare function getWorkflowStepId(): Promise<string | null>; // @setup (defined in the previous block)
+
 export async function processPayment(amount: number, currency: string) {
-  const runId = await getWorkflowRunId();
-  const idempotencyKey = runId ?? crypto.randomUUID(); // [!code highlight]
+  const stepId = await getWorkflowStepId();
+  const idempotencyKey = stepId ? `payment:${stepId}` : crypto.randomUUID(); // [!code highlight]
 
   const res = await fetch("https://api.stripe.com/v1/charges", {
     method: "POST",
@@ -306,7 +307,7 @@ export async function processPayment(amount: number, currency: string) {
 }
 ```
 
-When called from inside a workflow run, the step wrapping this utility gets a stable idempotency key across replays — Stripe dedupes retries for free. When called from a plain Node.js process, it behaves like any other function and a fresh UUID is generated.
+When called from inside a workflow step, the utility gets a stable idempotency key for that step across retries — Stripe dedupes retries for free. When called from a plain Node.js process, it behaves like any other function and a fresh UUID is generated. For more patterns, see [Idempotency](/docs/foundations/idempotency).
 
 ### In production
 
@@ -330,7 +331,7 @@ Before publishing a workflow library:
 
 ## Key APIs
 
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
-- [`"use step"`](/docs/api-reference/workflow/use-step) — marks functions for durable execution
-- [`start`](/docs/api-reference/workflow/start) — starts a workflow run
+- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions) — declares the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions) — marks functions for durable execution
+- [`start`](/docs/api-reference/workflow-api/start) — starts a workflow run
 - [`getWorkflowMetadata`](/docs/api-reference/workflow/get-workflow-metadata) — runtime detection and run ID access

package/docs/cookbook/advanced/serializable-steps.mdx

@@ -6,7 +6,7 @@ summary: Return a callback from a step to defer construction of a non-owned clas
 related:
   - /docs/foundations/serialization
   - /docs/foundations/serialization#custom-class-serialization
-  - /docs/api-reference/workflow/use-step
+  - /docs/foundations/workflows-and-steps#step-functions
 ---
 
 <Callout>
@@ -141,7 +141,7 @@ async function uploadFile(
 
 ## Key APIs
 
-- [`"use step"`](/docs/api-reference/workflow/use-step) — marks a function for extraction and serialization
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions) — marks a function for extraction and serialization
+- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions) — declares the orchestrator function
 - [`DurableAgent`](/docs/api-reference/workflow-ai/durable-agent) — accepts a model factory for durable AI agent streaming
 - [Custom class serialization](/docs/foundations/serialization#custom-class-serialization) — the companion pattern for classes you own (`WORKFLOW_SERIALIZE` / `WORKFLOW_DESERIALIZE`)

package/docs/cookbook/agent-patterns/human-in-the-loop.mdx

@@ -247,8 +247,8 @@ const approvalResult = messages
 
 ## Key APIs
 
-- [`"use workflow"`](/docs/api-reference/workflow/use-workflow) — declares the orchestrator function
-- [`"use step"`](/docs/api-reference/workflow/use-step) — declares step functions with retries
+- [`"use workflow"`](/docs/foundations/workflows-and-steps#workflow-functions) — declares the orchestrator function
+- [`"use step"`](/docs/foundations/workflows-and-steps#step-functions) — declares step functions with retries
 - [`defineHook()`](/docs/api-reference/workflow/define-hook) — type-safe hook with schema validation
 - [`sleep()`](/docs/api-reference/workflow/sleep) — durable timeout for approval expiry
 - [`getWritable()`](/docs/api-reference/workflow/get-writable) — stream custom data parts from steps