workflow 5.0.0-beta.36 → 5.0.0-beta.38

package/README.md

@@ -28,22 +28,6 @@ The Workflow SDK community can be found on [GitHub Discussions](https://github.c
 
 Contributions to Workflow SDK are welcome and highly appreciated. Please use GitHub [issues](https://github.com/vercel/workflow/issues) and [discussions](https://github.com/vercel/workflow/discussions) to collaborate with the team and wider community.
 
-## Author list
-
-Workflow SDK was built by engineers at [Vercel](https://vercel.com) and the [Open Source Community](https://github.com/vercel/workflow/graphs/contributors).
-
-The initial core contributing engineers are:
-
-- Adrian Lam ([@adriandlam](https://github.com/adriandlam))
-- Dillon Mulroy ([@dmmulroy](https://github.com/dmmulroy))
-- Gal Schlezinger ([@Schniz](https://github.com/Schniz))
-- JJ Kasper ([@ijjk](https://github.com/ijjk))
-- Nathan Rajlich ([@TooTallNate](https://github.com/TooTallNate))
-- Peter Wielander ([@VaguelySerious](https://github.com/VaguelySerious))
-- Pranay Prakash ([@pranaygp](https://github.com/pranaygp))
-
-The Workflow SDK logo was designed by Cecilio Ruiz [@ceciliorz](https://x.com/ceciliorz)
-
 ---
 
 ## Security

package/dist/runtime.d.ts

@@ -1,3 +1,3 @@
 import '@workflow/core/runtime/world-init';
-export { createWorld, getWorld, getWorldHandlers, type HealthCheckEndpoint, type HealthCheckOptions, type HealthCheckResult, healthCheck, setWorld, workflowEntrypoint, } from '@workflow/core/runtime';
+export { createWorld, getWorld, getWorldHandlers, type HealthCheckOptions, type HealthCheckResult, healthCheck, setWorld, workflowEntrypoint, } from '@workflow/core/runtime';
 //# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAEA,OAAO,mCAAmC,CAAC;AAE3C,OAAO,EACL,WAAW,EACX,QAAQ,EACR,gBAAgB,EAChB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,WAAW,EACX,QAAQ,EACR,kBAAkB,GACnB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAEA,OAAO,mCAAmC,CAAC;AAE3C,OAAO,EACL,WAAW,EACX,QAAQ,EACR,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,WAAW,EACX,QAAQ,EACR,kBAAkB,GACnB,MAAM,wBAAwB,CAAC"}

package/dist/runtime.js

@@ -2,4 +2,4 @@
 // through stream helpers, so register getWorld before exporting runtime APIs.
 import '@workflow/core/runtime/world-init';
 export { createWorld, getWorld, getWorldHandlers, healthCheck, setWorld, workflowEntrypoint, } from '@workflow/core/runtime';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicnVudGltZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9ydW50aW1lLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLDZFQUE2RTtBQUM3RSw4RUFBOEU7QUFDOUUsT0FBTyxtQ0FBbUMsQ0FBQztBQUUzQyxPQUFPLEVBQ0wsV0FBVyxFQUNYLFFBQVEsRUFDUixnQkFBZ0IsRUFJaEIsV0FBVyxFQUNYLFFBQVEsRUFDUixrQkFBa0IsR0FDbkIsTUFBTSx3QkFBd0IsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEhvc3Qtc2lkZSBzaWRlIGVmZmVjdDogcnVudGltZS1vbmx5IGltcG9ydHMgY2FuIHN0aWxsIHJlYWNoIGdldFdvcmxkTGF6eSgpXG4vLyB0aHJvdWdoIHN0cmVhbSBoZWxwZXJzLCBzbyByZWdpc3RlciBnZXRXb3JsZCBiZWZvcmUgZXhwb3J0aW5nIHJ1bnRpbWUgQVBJcy5cbmltcG9ydCAnQHdvcmtmbG93L2NvcmUvcnVudGltZS93b3JsZC1pbml0JztcblxuZXhwb3J0IHtcbiAgY3JlYXRlV29ybGQsXG4gIGdldFdvcmxkLFxuICBnZXRXb3JsZEhhbmRsZXJzLFxuICB0eXBlIEhlYWx0aENoZWNrRW5kcG9pbnQsXG4gIHR5cGUgSGVhbHRoQ2hlY2tPcHRpb25zLFxuICB0eXBlIEhlYWx0aENoZWNrUmVzdWx0LFxuICBoZWFsdGhDaGVjayxcbiAgc2V0V29ybGQsXG4gIHdvcmtmbG93RW50cnlwb2ludCxcbn0gZnJvbSAnQHdvcmtmbG93L2NvcmUvcnVudGltZSc7XG4iXX0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicnVudGltZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9ydW50aW1lLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLDZFQUE2RTtBQUM3RSw4RUFBOEU7QUFDOUUsT0FBTyxtQ0FBbUMsQ0FBQztBQUUzQyxPQUFPLEVBQ0wsV0FBVyxFQUNYLFFBQVEsRUFDUixnQkFBZ0IsRUFHaEIsV0FBVyxFQUNYLFFBQVEsRUFDUixrQkFBa0IsR0FDbkIsTUFBTSx3QkFBd0IsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEhvc3Qtc2lkZSBzaWRlIGVmZmVjdDogcnVudGltZS1vbmx5IGltcG9ydHMgY2FuIHN0aWxsIHJlYWNoIGdldFdvcmxkTGF6eSgpXG4vLyB0aHJvdWdoIHN0cmVhbSBoZWxwZXJzLCBzbyByZWdpc3RlciBnZXRXb3JsZCBiZWZvcmUgZXhwb3J0aW5nIHJ1bnRpbWUgQVBJcy5cbmltcG9ydCAnQHdvcmtmbG93L2NvcmUvcnVudGltZS93b3JsZC1pbml0JztcblxuZXhwb3J0IHtcbiAgY3JlYXRlV29ybGQsXG4gIGdldFdvcmxkLFxuICBnZXRXb3JsZEhhbmRsZXJzLFxuICB0eXBlIEhlYWx0aENoZWNrT3B0aW9ucyxcbiAgdHlwZSBIZWFsdGhDaGVja1Jlc3VsdCxcbiAgaGVhbHRoQ2hlY2ssXG4gIHNldFdvcmxkLFxuICB3b3JrZmxvd0VudHJ5cG9pbnQsXG59IGZyb20gJ0B3b3JrZmxvdy9jb3JlL3J1bnRpbWUnO1xuIl19

package/docs/ai/index.mdx

@@ -382,7 +382,7 @@ export async function checkBaggageAllowance(
 
 With `"use step"`:
 
-- The tool execution runs in a separate step with full Node.js access. In production, each step is executed in a separate worker process, which scales automatically with your workload.
+- The tool execution runs as a durable step with full Node.js access. The combined runtime may execute it inline in the flow request or resume it through the workflow queue, and can scale queued work with your workload.
 - Failed tool calls are automatically retried (up to 3 times by default). See [Errors and Retries](/docs/foundations/errors-and-retries) for more details.
 - Each tool execution appears as a discrete step in observability tools. See [Observability](/docs/observability) for more details.
 </Step>

package/docs/api-reference/workflow/set-attributes.mdx

@@ -59,7 +59,3 @@ Validation errors throw [`FatalError`](/docs/api-reference/workflow/fatal-error)
 Calls from both workflow and step bodies append a native `attr_set` event, which the World materializes onto `run.attributes`. Workflow-originated events record a workflow writer; step-originated events record the originating step ID and attempt.
 
 Native attributes require spec version 4 or later. Step-body storage errors throw from `setAttributes`; catch them inside the step if the write should be best-effort. Workflow-body writes are committed when the workflow suspends: transient storage errors are retried with the suspension, while a write the World rejects as invalid — such as exceeding the per-run attribute cap across multiple calls — fails the run with the validation error.
-
-<Callout>
-This function was previously exported as `experimental_setAttributes`. The old name still works as a deprecated alias — update imports to `setAttributes`.
-</Callout>

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

@@ -26,7 +26,7 @@ These APIs are available but are **seeded or fixed** to ensure deterministic beh
 | [`Date`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) / `Date.now()` / `new Date()` | Returns a fixed timestamp that advances with the workflow's logical clock |
 | [`crypto.getRandomValues()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) | Seeded — produces deterministic output for a given workflow run |
 | [`crypto.randomUUID()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID) | Seeded — produces deterministic UUIDs for a given workflow run |
-| [`crypto.subtle.digest()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest) | Passes through to the real implementation (SHA-256, etc. are deterministic by nature) |
+| [`crypto.subtle.digest()`](https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest) | Computed synchronously via `node:crypto` (values are byte-identical to WebCrypto), so the promise settles at a deterministic point during replay |
 
 <Callout type="info">
 You can safely use `Math.random()`, `Date.now()`, and `crypto.randomUUID()` in workflow functions. The framework ensures these return the same values across replays.
@@ -100,3 +100,6 @@ The following are **not available** in workflow functions. Move this logic to [s
 - **Global `fetch`**: Use [`import { fetch } from "workflow"`](/docs/api-reference/workflow/fetch) instead. See [fetch-in-workflow](/docs/errors/fetch-in-workflow).
 - **Timers**: `setTimeout`, `setInterval`, `setImmediate`, and their `clear*` counterparts. Use [`sleep()`](/docs/api-reference/workflow/sleep) instead. See [timeout-in-workflow](/docs/errors/timeout-in-workflow).
 - **`Buffer`**: Node.js-specific API. Use `Uint8Array` with `toBase64()` / `fromBase64()` / `toHex()` / `fromHex()` for binary data encoding, or `atob()` / `btoa()` for string-based base64.
+- **`WeakRef` and `FinalizationRegistry`**: garbage-collection timing is not deterministic, so observing it would make workflow code impossible to replay. (`WeakMap` and `WeakSet` remain available — they do not expose GC state.)
+- **`Atomics.waitAsync`**: a wall-clock timer, which cannot be replayed. Use [`sleep()`](/docs/api-reference/workflow/sleep) instead.
+- **Async `WebAssembly` compilation** (`compile`, `instantiate`, `compileStreaming`, `instantiateStreaming`): resolves on compile-thread timing. The synchronous `new WebAssembly.Module()` and `new WebAssembly.Instance()` constructors remain available.

package/docs/api-reference/workflow-runtime/health-check.mdx

@@ -13,7 +13,7 @@ Performs an end-to-end health check of a deployment's workflow infrastructure by
 import { getWorld, healthCheck } from "workflow/runtime";
 
 const world = await getWorld();
-const result = await healthCheck(world, "workflow"); // [!code highlight]
+const result = await healthCheck(world); // [!code highlight]
 
 if (!result.healthy) {
   console.error("Workflow infrastructure unhealthy:", result.error);
@@ -27,8 +27,7 @@ if (!result.healthy) {
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `world` | `World` | The World instance to send the health check through |
-| `endpoint` | `"workflow" \| "step"` | Which endpoint to check |
-| `options` | `HealthCheckOptions & { namespace?: string }` | Optional configuration |
+| `options` | `HealthCheckOptions` | Optional configuration |
 
 Where `HealthCheckOptions` is:
 
@@ -36,6 +35,7 @@ Where `HealthCheckOptions` is:
 |--------|------|-------------|
 | `timeout` | `number` | Milliseconds to wait for the health check response. Default: `30000`. |
 | `deploymentId` | `string` | Deployment to target. Falls back to `process.env.VERCEL_DEPLOYMENT_ID`. |
+| `namespace` | `string` | Queue namespace of the target deployment. Falls back to `WORKFLOW_QUEUE_NAMESPACE`. |
 
 ### Returns
 
@@ -43,7 +43,7 @@ Returns a `Promise<HealthCheckResult>`:
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `healthy` | `boolean` | Whether the endpoint processed the health check message |
+| `healthy` | `boolean` | Whether the combined workflow endpoint processed the health check message |
 | `error` | `string \| undefined` | Error message when the check failed |
 | `latencyMs` | `number \| undefined` | Round-trip latency when the check succeeded |
 | `specVersion` | `number \| undefined` | Workflow spec version of the responding deployment |

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

@@ -1,6 +1,6 @@
 ---
 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:
@@ -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]

package/docs/configuration/build-and-diagnostics.mdx

@@ -42,6 +42,17 @@ Accepted values:
 - Set `1` to expose the workflow manifest at `/.well-known/workflow/v1/manifest.json`.
 - Useful for e2e tests and tools that need to discover workflows over HTTP.
 
+## Discovery
+
+### `WORKFLOW_DISCOVER_NODE_MODULES`
+
+- Framework option: `discoverWorkflowsInNodeModules` where supported
+- Default: enabled
+- Controls whether workflow discovery descends into `node_modules`. By default, dependencies that declare a `workflow`/`@workflow/*` dependency can ship `"use workflow"`/`"use step"` files that are discovered and compiled into your app's bundles.
+- Set `0` or `false` to opt out — imports from your application code that resolve into `node_modules` are not followed, so the build never reads, scans, or descends into dependency file graphs. This skips the cost of scanning `node_modules` and stops third-party workflow/step/serde code from being discovered. Useful when a dependency ships workflow code you don't want compiled into your app, or trips discovery with directive strings you don't intend to run.
+- The SDK's own runtime serde classes (e.g. `Run`) stay registered — they are reached through a seeded entry point, and imports *within* `node_modules` are still followed.
+- Explicit framework config wins over this environment variable.
+
 ## Development diagnostics
 
 ### `WORKFLOW_DEV_HMR_LOGS`
@@ -49,3 +60,11 @@ Accepted values:
 - Default: disabled
 - Set `1` to log workflow rebuild activity during `next dev`.
 - Useful for diagnosing watch and HMR issues.
+
+### `WORKFLOW_DEV_WATCH_IGNORED_PATHS`
+
+- Default: unset
+- Dev-mode only (`next dev`). Comma-separated list of path fragments the file watcher should never watch, in addition to the built-in ignores and your project's `.gitignore`.
+- Each entry is matched as a substring of the absolute path (e.g. `/fixtures/,/generated/`).
+- The watcher already respects `.gitignore` (walking from the app directory up to the workspace root). Use this variable only for large directories you cannot or do not want to add to `.gitignore`.
+- Useful when a project has thousands of non-ignored directories and `next dev` fails with `EMFILE: too many open files, watch`.

package/docs/configuration/runtime-tuning.mdx

@@ -115,6 +115,14 @@ For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPL
 - Debug log filter with wildcards and negation.
 - Examples: `workflow:*`, `workflow:*,-workflow:telemetry:*`.
 
+## Transport
+
+### `WORKFLOW_H2_MULTIPLEX`
+
+- Default: enabled
+- On the Vercel World, lets concurrent event-log requests share one HTTP/2 connection instead of one connection per in-flight request.
+- Set `0` to send one event request per connection.
+
 ## Queue namespace
 
 ### `WORKFLOW_QUEUE_NAMESPACE`
@@ -130,9 +138,9 @@ These variables are primarily for tests, debugging, or unusual deployments.
 
 ### `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
 
-- Default: `10`
-- Stream write buffering interval.
-- Also available as `streamFlushIntervalMs` on Worlds that expose it.
+- Default: `0` (dispatch the first chunk of an idle stream immediately)
+- Group-commit window for the *leading* chunk of an idle stream. `0` sends it at once; a positive value holds it up to that many milliseconds to collect a group — an opt-in trade of first-chunk latency for larger batches, useful for slow-but-steady producers. Chunks arriving while a request is already in flight always coalesce into the next group regardless of this setting.
+- Also available as `streamFlushIntervalMs` on Worlds that expose it (the env var, when set, takes precedence over the World option).
 
 ### `WORKFLOW_STREAM_MAX_INFLIGHT_CHUNKS`
 
@@ -149,6 +157,11 @@ These variables are primarily for tests, debugging, or unusual deployments.
 - Default: `1048576` (1 MiB)
 - Wire limit: maximum cumulative bytes in a single coalesced multi-write, so large chunks don't produce a request body that platform limits reject. A single chunk larger than this is still sent on its own.
 
+### `WORKFLOW_STREAM_MAX_BUFFERED_BYTES`
+
+- Default: `8388608` (8 MiB)
+- Flow-control bound: maximum cumulative bytes accepted into the stream writer's group-commit buffer before `write()` applies backpressure. The byte-denominated counterpart of `WORKFLOW_STREAM_MAX_INFLIGHT_CHUNKS`; distinct from `WORKFLOW_STREAM_MAX_BYTES_PER_BATCH`, which only splits how much goes out in one request.
+
 ### `WORKFLOW_FRAMED_STREAM_MAX_RECONNECTS`
 
 - Default: `50`

package/docs/configuration/worlds.mdx

@@ -21,6 +21,12 @@ A [World](/docs/deploying) stores workflow state and delivers queue messages.
 
 Outside Vercel, Workflow defaults to the Local World. On Vercel, leave `WORKFLOW_TARGET_WORLD` unset for the normal case; Workflow detects the Vercel deployment and selects the Vercel World automatically.
 
+The World is selected when your app **runs**, from the environment of the process serving it, so changing `WORKFLOW_TARGET_WORLD` takes effect on the next start without a rebuild. Detection keys off `VERCEL_DEPLOYMENT_ID`, which Vercel sets in every deployed function and nothing else sets: with it, the Vercel World; without it, the Local World.
+
+Broader signals are deliberately ignored. `vercel env pull` writes `VERCEL=1` into `.env.local`, so a dev server or a production server started on your own machine sees it while running against a writable filesystem — where the Local World is the right choice. Set `WORKFLOW_TARGET_WORLD=vercel` explicitly if you want such a process to talk to the Vercel World; starting a run then fails with an error naming the missing `VERCEL_DEPLOYMENT_ID`.
+
+A deployment that pins `WORKFLOW_TARGET_WORLD=local` warns at startup and fails on its first write, because a Vercel deployment's filesystem is read-only.
+
 Set `WORKFLOW_TARGET_WORLD` only when you want to use a custom or self-hosted World:
 
 - `local` - alias for `@workflow/world-local`.
@@ -95,8 +101,8 @@ The Local World is the default outside Vercel and is intended for development.
 ### `streamFlushIntervalMs`
 
 - Environment variable fallback: `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
-- Default: `10`
-- Flush interval for buffered stream writes. The World option wins when set.
+- Default: `0` (dispatch the leading chunk of an idle stream immediately)
+- Group-commit window for the leading chunk of an idle stream; a positive value trades first-chunk latency for larger groups. The `WORKFLOW_STREAM_FLUSH_INTERVAL_MS` environment variable, when set, overrides this option; otherwise the World option governs, including the very first chunk.
 
 ## Postgres World
 
@@ -128,6 +134,14 @@ The Postgres World is a self-hosted durable backend for long-running server proc
 - Number of concurrent workers polling for jobs.
 - Also bounds concurrent parent-to-child workflow return-value polls.
 
+### `applicationManagedShutdown`
+
+- Environment variable: `WORKFLOW_POSTGRES_APPLICATION_MANAGED_SHUTDOWN` (`1` enables)
+- Default: `false`
+- Whether the application coordinates shutdown instead of Graphile Worker responding automatically.
+- Set to `true` only when the application awaits `world.close()` before closing its workflow HTTP server and caller-owned pool.
+- Prevents Graphile Worker's default handler from terminating the process before the application's remaining cleanup finishes.
+
 ### `maxPoolSize`
 
 - Environment variable: `WORKFLOW_POSTGRES_MAX_POOL_SIZE`
@@ -143,8 +157,8 @@ The Postgres World is a self-hosted durable backend for long-running server proc
 ### `streamFlushIntervalMs`
 
 - Environment variable fallback: `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
-- Default: `10`
-- Flush interval for buffered stream writes. The World option wins when set.
+- Default: `0` (dispatch the leading chunk of an idle stream immediately)
+- Group-commit window for the leading chunk of an idle stream; a positive value trades first-chunk latency for larger groups. The `WORKFLOW_STREAM_FLUSH_INTERVAL_MS` environment variable, when set, overrides this option; otherwise the World option governs, including the very first chunk.
 
 ## Vercel World
 

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

@@ -2,11 +2,11 @@
 title: Publishing Libraries
 description: Structure and publish npm packages that export workflow functions for consumers to use with Workflow SDK.
 type: guide
-summary: Learn how to build, export, and test npm packages that ship workflow and step functions — including package.json exports, re-exporting for stable workflow IDs, keeping step I/O clean, and integration testing.
+summary: Learn how to build, export, and test npm packages that ship workflow and step functions — including package.json exports, re-exporting so the consumer's compiler discovers your workflows, keeping step I/O clean, and integration testing.
 ---
 
 <CopyPrompt
-  text="Package these workflow functions as a publishable npm library. Give the package a dedicated workflows entry point (for example `exports[&quot;./workflows&quot;]`) that ships the workflow and step source for the consumer's compiler to process. Keep every workflow and step input and output serializable, and read credentials from environment variables inside steps instead of accepting client instances. Document the consumer re-export requirement: consumers create a file in their `workflows/` directory containing `export * from &quot;<pkg>/workflows&quot;` so their build assigns stable workflow IDs and replay can resolve functions after cold starts. Add an integration test that runs a library workflow end to end from a consumer-style setup. Verify the build, stable IDs across deployments, and replay safety."
+  text="Package these workflow functions as a publishable npm library. Give the package a dedicated workflows entry point (for example `exports[&quot;./workflows&quot;]`) that ships the workflow and step source for the consumer's compiler to process. Keep every workflow and step input and output serializable, and read credentials from environment variables inside steps instead of accepting client instances. Document the consumer re-export requirement: consumers create a file in their `workflows/` directory containing `export * from &quot;<pkg>/workflows&quot;` so their build discovers and compiles the library's workflow and step files and replay can resolve them after cold starts. Add an integration test that runs a library workflow end to end from a consumer-style setup. Verify the build, that the library's workflows and steps show up as compiled entries, and replay safety."
 />
 
 import { File, Folder, Files } from "fumadocs-ui/components/files";
@@ -114,31 +114,35 @@ export default defineConfig({
 });
 ```
 
-## Re-Exporting for Workflow ID Stability
+## Re-Exporting for Compiler Discovery
 
-Workflow SDK's compiler assigns each workflow function a stable ID based on its position in the source file that the build system processes. When a consumer imports a pre-built workflow from an npm package, the compiler never sees the original source — it only sees the compiled output. This means workflow IDs won't match between the library's development environment and the consumer's app.
+The workflow compiler only transforms files it discovers, and discovery starts from the consumer's `workflows/` directory and follows imports out from there. A library's workflow functions are not on that graph by default, so nothing compiles them and the runtime has no definition to run.
 
-The fix is a **re-export file**. The consumer creates a file in their `workflows/` directory that re-exports the library's workflows. The build system then processes this file and assigns stable IDs.
+The fix is a **re-export file**. The consumer creates a file in their `workflows/` directory that re-exports the library's workflows, which pulls the library's source onto the discovery graph and gives its entry point an address the runtime can resolve.
 
 ### Consumer Setup
 
 ```typescript lineNumbers
 // workflows/media.ts (in the consumer's project)
-// Re-export library workflows so the build system assigns stable IDs
+// Re-export library workflows so the compiler discovers and transforms them
 export * from "@acme/media/workflows"; // [!code highlight]
 ```
 
-This one-line file is all that's needed. The workflow compiler transforms this file, discovers the workflow and step functions from the library, and assigns IDs that are stable across deployments.
+This one-line file is all that's needed. The compiler follows the re-export into the package, transforms the workflow and step functions it finds, and registers them under IDs the runtime can resolve.
 
 ### Why This Is Necessary
 
-Without re-exporting, the workflow runtime cannot match a running workflow to its function definition. When a workflow run is replayed after a cold start, the runtime looks up functions by their compiler-assigned IDs. If the IDs don't exist (because the compiler never processed the library's source), replay fails.
+Without re-exporting, the workflow runtime cannot match a running workflow to its function definition. When a run is replayed after a cold start, the runtime looks up functions by their compiler-assigned IDs. If those functions were never compiled, the IDs don't exist and replay fails.
 
-The re-export pattern ensures:
+Point the re-export at the package's dedicated workflows entry point rather than a deep path into `dist/`. Files reachable through the package's `exports` map get an ID of the form `name/subpath@version`; a deep, non-exported file falls back to a path-based ID instead.
 
-1. **Stable IDs** — the compiler assigns IDs based on the consumer's source tree
-2. **Replay safety** — IDs persist across deployments and cold starts
-3. **Version upgrades** — re-exported IDs remain stable as long as the consumer's file doesn't change
+<Callout type="info">
+**IDs for code you ship embed your package version.** A step in `@acme/media` version `1.4.0` gets the ID `step//@acme/media/workflows@1.4.0//transcode`, so publishing `1.5.0` renames every workflow and step the package ships.
+
+That is safe on worlds with deployment pinning, such as Vercel, because runs are pinned to the deployment that started them. A run records its deployment ID and every resume targets that same deployment, so after a consumer upgrades, new runs execute the new version while runs already in flight keep replaying against the old one. Consumers do not need to drain anything before upgrading.
+
+The re-export file does not change any of this. An ID is derived from where the file lives, not from how it was imported, so a package file keeps its `name@version` ID whether or not a consumer re-exports it.
+</Callout>
 
 ## Keeping Step I/O Clean
 
@@ -252,7 +256,7 @@ Some libraries want to be useful to consumers who *aren't* using Workflow SDK at
 Two rules for isomorphic packages:
 
 1. **Any runtime reference to the `workflow` package must be loaded via dynamic `import("workflow")` inside a try/catch.** A static top-level import makes the module fail to load for consumers who haven't installed workflow.
-2. **The `"use workflow"` and `"use step"` directives are safe to keep in your library source.** When a consumer compiles your code with the Workflow SDK toolchain (via the [re-export pattern](#re-exporting-for-workflow-id-stability) above), the SWC plugin transforms them into durable-execution glue. When they're not compiled — plain Node, plain tests, a consumer without the runtime — they are just string expression statements and run as no-ops.
+2. **The `"use workflow"` and `"use step"` directives are safe to keep in your library source.** When a consumer compiles your code with the Workflow SDK toolchain (via the [re-export pattern](#re-exporting-for-compiler-discovery) above), the SWC plugin transforms them into durable-execution glue. When they're not compiled — plain Node, plain tests, a consumer without the runtime — they are just string expression statements and run as no-ops.
 </Callout>
 
 ### Optional peer dependency

package/docs/getting-started/astro.mdx

@@ -160,7 +160,7 @@ async function sendOnboardingEmail(user: { id: string; email: string}) {
 
 Taking a look at this code:
 
-* Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+* Business logic lives inside **steps**. When a workflow invokes a step, the workflow suspends while the step runs with full Node.js access. The combined handler may execute it inline; queued retries and continuations return through the same flow route.
 * If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count).
 * Steps can throw a `FatalError` if an error is intentional and should not be retried.
 

package/docs/getting-started/express.mdx

@@ -185,7 +185,7 @@ async function sendOnboardingEmail(user: { id: string; email: string }) {
 
 Taking a look at this code:
 
-- Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+- Business logic lives inside **steps**. When a workflow invokes a step, the workflow suspends while the step runs with full Node.js access. The combined handler may execute it inline; queued retries and continuations return through the same flow route.
 - If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count).
 - Steps can throw a `FatalError` if an error is intentional and should not be retried.
 

package/docs/getting-started/fastify.mdx

@@ -174,7 +174,7 @@ async function sendOnboardingEmail(user: { id: string; email: string }) {
 ```
 Taking a look at this code:
 
-- Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+- Business logic lives inside **steps**. When a workflow invokes a step, the workflow suspends while the step runs with full Node.js access. The combined handler may execute it inline; queued retries and continuations return through the same flow route.
 - If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count).
 - Steps can throw a `FatalError` if an error is intentional and should not be retried.
 

package/docs/getting-started/hono.mdx

@@ -170,7 +170,7 @@ async function sendOnboardingEmail(user: { id: string; email: string }) {
 
 Taking a look at this code:
 
-- Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+- Business logic lives inside **steps**. When a workflow invokes a step, the workflow suspends while the step runs with full Node.js access. The combined handler may execute it inline; queued retries and continuations return through the same flow route.
 - If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count).
 - Steps can throw a `FatalError` if an error is intentional and should not be retried.
 

package/docs/getting-started/nestjs.mdx

@@ -289,7 +289,7 @@ async function sendOnboardingEmail(user: { id: string; email: string }) {
 
 Taking a look at this code:
 
-- Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+- Business logic lives inside **steps**. When a workflow invokes a step, the workflow suspends while the step runs with full Node.js access. The combined handler may execute it inline; queued retries and continuations return through the same flow route.
 - If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count).
 - Steps can throw a `FatalError` if an error is intentional and should not be retried.
 

package/docs/getting-started/next.mdx

@@ -192,7 +192,7 @@ async function sendOnboardingEmail(user: { id: string; email: string}) {
 
 Taking a look at this code:
 
-* Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+* Business logic lives inside **steps**. When a workflow invokes a step, the workflow suspends while the step runs with full Node.js access. The combined handler may execute it inline; queued retries and continuations return through the same flow route.
 * If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count).
 * Steps can throw a `FatalError` if an error is intentional and should not be retried.
 

package/docs/getting-started/nitro.mdx

@@ -172,7 +172,7 @@ async function sendOnboardingEmail(user: { id: string; email: string }) {
 
 Taking a look at this code:
 
-- Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+- Business logic lives inside **steps**. When a workflow invokes a step, the workflow suspends while the step runs with full Node.js access. The combined handler may execute it inline; queued retries and continuations return through the same flow route.
 - If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count).
 - Steps can throw a `FatalError` if an error is intentional and should not be retried.
 

package/docs/getting-started/nuxt.mdx

@@ -149,7 +149,7 @@ async function sendOnboardingEmail(user: { id: string; email: string }) {
 
 Taking a look at this code:
 
-- Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+- Business logic lives inside **steps**. When a workflow invokes a step, the workflow suspends while the step runs with full Node.js access. The combined handler may execute it inline; queued retries and continuations return through the same flow route.
 - If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count).
 - Steps can throw a `FatalError` if an error is intentional and should not be retried.
 

package/docs/getting-started/sveltekit.mdx

@@ -157,7 +157,7 @@ async function sendOnboardingEmail(user: { id: string; email: string}) {
 
 Taking a look at this code:
 
-* Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+* Business logic lives inside **steps**. When a workflow invokes a step, the workflow suspends while the step runs with full Node.js access. The combined handler may execute it inline; queued retries and continuations return through the same flow route.
 * If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count).
 * Steps can throw a `FatalError` if an error is intentional and should not be retried.
 

package/docs/getting-started/tanstack-start.mdx

@@ -155,7 +155,7 @@ async function sendOnboardingEmail(user: { id: string; email: string}) {
 
 Taking a look at this code:
 
-* Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+* Business logic lives inside **steps**. When a workflow invokes a step, the workflow suspends while the step runs with full Node.js access. The combined handler may execute it inline; queued retries and continuations return through the same flow route.
 * If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count).
 * Steps can throw a `FatalError` if an error is intentional and should not be retried.
 

package/docs/getting-started/vite.mdx

@@ -160,7 +160,7 @@ async function sendOnboardingEmail(user: { id: string; email: string}) {
 
 Taking a look at this code:
 
-* Business logic lives inside **steps**. When a step is invoked inside a **workflow**, it gets enqueued to run on a separate request while the workflow is suspended, just like `sleep`.
+* Business logic lives inside **steps**. When a workflow invokes a step, the workflow suspends while the step runs with full Node.js access. The combined handler may execute it inline; queued retries and continuations return through the same flow route.
 * If a step throws an error, like in `sendWelcomeEmail`, the step will automatically be retried until it succeeds (or hits the step's max retry count).
 * Steps can throw a `FatalError` if an error is intentional and should not be retried.
 

package/docs/how-it-works/cancellation.mdx

@@ -176,12 +176,12 @@ The step's `ops` array is awaited via `waitUntil(Promise.all(ops))` after the st
 
 ### Abort Errors Are Wrapped in FatalError
 
-When a step throws due to an abort — whether from `fetch` throwing `AbortError`, `signal.throwIfAborted()`, or any other abort-induced error — the step handler wraps the error in `FatalError` before recording it in the event log. This ensures:
+When a step throws due to an abort — whether from `fetch` throwing `AbortError`, `signal.throwIfAborted()`, or any other abort-induced error — the step executor wraps the error in `FatalError` before recording it in the event log. This ensures:
 
 - **No retries**: An abort is intentional cancellation, not a transient failure. Retrying would just abort again.
 - **Immediate propagation**: The error bubbles up to the workflow as a `FatalError`, which the workflow can catch with `FatalError.is(err)`.
 
-The wrapping happens at the step handler level (`runtime/step-handler.ts`), during error hydration. When the step's thrown error is an `AbortError` (checked via `err.name === 'AbortError'`), it is treated as fatal regardless of the step's `maxRetries` configuration.
+The wrapping happens in `runtime/step-executor.ts` during error hydration. When the step's thrown error is an `AbortError` (checked via `err.name === 'AbortError'`), it is treated as fatal regardless of the step's `maxRetries` configuration.
 
 ### abort() in the Workflow
 

package/docs/how-it-works/code-transform.mdx

@@ -53,18 +53,20 @@ flowchart LR
     A["Source Code<br/>with directives"] --> B["Step Mode"]
     A --> C["Workflow Mode"]
     A --> D["Client Mode"]
-    B --> E["step.js<br/>(Step Execution)"]
-    C --> F["flow.js<br/>(Workflow Execution)"]
+    B --> E["Step registration bundle"]
+    C --> F["Workflow bundle"]
+    E --> H["Combined flow handler"]
+    F --> H
     D --> G["Your App Code<br/>(Enables `start`)"]
 ```
 
 ### Comparison Table
 
-| Mode     | Used In    | Purpose                        | Output API Route                   | Required? |
-|----------|------------|--------------------------------|------------------------------------|-----------|
-| Step     | Build time | Bundles step handlers          | `.well-known/workflow/v1/step`  | Yes       |
-| Workflow | Build time | Bundles workflow orchestrators | `.well-known/workflow/v1/flow`  | Yes       |
-| Client   | Build/Runtime | Provides workflow IDs and types to `start`   | Your application code              | Optional* |
+| Mode     | Used In    | Purpose                        | Runtime role | Required? |
+|----------|------------|--------------------------------|--------------|-----------|
+| Step     | Build time | Registers executable step functions | Imported by the combined flow handler | Yes |
+| Workflow | Build time | Bundles workflow orchestrators | Executed by `.well-known/workflow/v1/flow` | Yes |
+| Client   | Build/Runtime | Provides workflow IDs and types to `start` | Your application code | Optional* |
 
 \* Client mode is **recommended** for better developer experience—it provides automatic ID generation and type safety. Without it, you must manually construct workflow IDs or use the build manifest.
 
@@ -73,7 +75,7 @@ flowchart LR
 <Tabs items={["Step Mode", "Workflow Mode", "Client Mode"]}>
 <Tab value="Step Mode">
 
-**Step Mode** creates the step execution bundle served at `/.well-known/workflow/v1/step`.
+**Step Mode** creates a registration bundle that the combined flow handler imports. It is not an HTTP route.
 
 **Input:**
 
@@ -211,7 +213,7 @@ The IDs are generated exactly like in workflow mode to ensure they can be direct
 
 ## Generated Files
 
-When you build your application, the Workflow SDK generates three handler files in `.well-known/workflow/v1/`:
+When you build your application, the Workflow SDK generates a combined flow handler, an internal step registration bundle, and a webhook handler. Exact filenames vary by framework.
 
 ### `flow.js`
 
@@ -245,15 +247,17 @@ Most invalid patterns cause **build-time errors**, catching issues before deploy
   **Why a VM?** Workflow functions must be deterministic to support replay. The VM sandbox prevents accidental use of non-deterministic APIs or side effects. All side effects should be performed in [step functions](/docs/foundations/workflows-and-steps#step-functions) instead.
 </Callout>
 
-### `step.js`
+### `__step_registrations.js`
 
-Contains all step functions transformed in **step mode**. This file is imported by your framework to handle step execution requests at `POST /.well-known/workflow/v1/step`.
+Contains all step functions transformed in **step mode**. The combined flow handler imports this module for its registration side effects.
 
 **What it does:**
 
-- Exports a `POST` handler that accepts Web standard `Request` objects
-- Executes individual steps with full runtime access
-- Returns step results to the orchestration layer
+- Adds step functions to the runtime step registry
+- Keeps step bodies in the full host runtime
+- Makes registered steps available when a flow queue message includes `stepId` and `stepName`
+
+This module must not be exposed as an HTTP endpoint.
 
 ### `webhook.js`
 
@@ -336,7 +340,7 @@ These transformations are framework-agnostic—they output standard JavaScript t
 
 If you need to debug transformation issues, you can inspect the generated files:
 
-1. **Look in `.well-known/workflow/v1/`**: Check the generated `flow.js`, `step.js`,`webhook.js`, and other emitted debug files.
+1. **Inspect the generated output**: Check the combined flow handler, step registration bundle, webhook handler, and emitted debug files.
 2. **Check build logs**: Most frameworks log transformation activity during builds
 3. **Verify directives**: Ensure `"use workflow"` and `"use step"` are the first statements in functions
 4. **Check file locations**: Transformations only apply to files in configured source directories

package/docs/how-it-works/framework-integrations.mdx

@@ -2,7 +2,7 @@
 title: Framework Integrations
 description: Guide for framework authors to integrate Workflow SDK with custom frameworks or runtimes.
 type: guide
-summary: Build a custom framework integration using the Workflow SDK compiler and runtime.
+summary: Build a custom framework integration using the Workflow SDK compiler and combined runtime handler.
 prerequisites:
   - /docs/foundations/workflows-and-steps
 related:
@@ -10,55 +10,45 @@ related:
 ---
 
 <Callout>
-  **For users:** If you just want to use Workflow SDK with an existing framework, check out the [Getting Started](/docs/getting-started) guide instead. This page is for framework authors who want to integrate Workflow SDK with their framework or runtime.
+  **For users:** If you just want to use Workflow SDK with an existing framework, see [Getting Started](/docs/getting-started). This page is for framework authors.
 </Callout>
 
-This guide walks you through building a framework integration for Workflow SDK using Bun as a concrete example. The same principles apply to any JavaScript runtime (Node.js, Deno, Cloudflare Workers, etc.).
+This guide uses Bun as a concrete example, but the same build and routing model applies to other JavaScript frameworks and runtimes.
 
 <Callout type="info">
-  **Prerequisites:** Before building a framework integration, we recommend reading [How the Directives Work](/docs/how-it-works/code-transform) to understand the transformation system that powers Workflow SDK.
+  Read [How the Directives Work](/docs/how-it-works/code-transform) first if you are not familiar with the three compiler modes.
 </Callout>
 
-## What You'll Build
+## Integration shape
 
-A framework integration has two main components:
+A framework integration has two responsibilities:
 
-1. **Build-time**: Generate workflow handler files (`flow.js`, `step.js`, `webhook.js`)
-2. **Runtime**: Expose these handlers as HTTP endpoints in your application server
+1. **Build time:** transform workflow and step code, register the steps, and generate the combined flow handler.
+2. **Runtime:** expose the generated flow and webhook handlers as HTTP routes.
 
 ```mermaid
 flowchart TD
-    A["Source Code<br/>'use workflow'"] --> B["Workflow Builder"]
-    B --> C["SWC Transform"]
-    C --> D["Step Mode"]
-    C --> E["Workflow Mode"]
-    C --> F["Client Mode"]
-    D --> G["Generated Handlers<br/>step.js"]
-    E --> H["Generated Handlers<br/>flow.js"]
-    B --> L["Generated Handlers<br/>webhook.js"]
-    F --> I["Used by framework loader"]
-    G --> J["HTTP Server<br/>(Your Runtime)"]
-    H --> J
-    L --> J
+    A["Source code<br/>'use workflow' / 'use step'"] --> B["Workflow builder"]
+    B --> C["Workflow-mode bundle"]
+    B --> D["Step registration bundle"]
+    D --> E["Combined flow handler"]
+    C --> E
+    B --> F["Webhook handler"]
+    E --> G["POST /.well-known/workflow/v1/flow"]
+    F --> H["/.well-known/workflow/v1/webhook/:token"]
 
     style B fill:#a78bfa,stroke:#8b5cf6,color:#000
-    style I fill:#a78bfa,stroke:#8b5cf6,color:#000
-    style J fill:#a78bfa,stroke:#8b5cf6,color:#000
+    style G fill:#a78bfa,stroke:#8b5cf6,color:#000
+    style H fill:#a78bfa,stroke:#8b5cf6,color:#000
 ```
 
-The purple boxes are what you implement—everything else is provided by Workflow SDK.
+Steps do not have their own HTTP route. A queued step invocation contains `stepId` and `stepName` and is delivered to the flow handler on the workflow queue. The handler executes the registered step in the full host runtime, then replays the workflow in its sandboxed VM.
 
-## Example: Bun Integration
+## Example: Bun integration
 
-Let's build a complete integration for Bun. Bun is unique because it serves as both a runtime (needs code transformations) and a framework (provides `Bun.serve()` for HTTP routing).
+### 1. Generate the bundles
 
-<Callout type="info">
-  A working example can be [found here](https://github.com/vercel/workflow-examples/tree/main/custom-adapter). For a production-ready reference, see the [Next.js integration](https://github.com/vercel/workflow/tree/main/packages/next).
-</Callout>
-
-### Step 1: Generate Handler Files
-
-Use the `workflow` CLI to generate the handler bundles. The CLI scans your `workflows/` directory and creates `flow.js`, `step.js`, and `webhook.js`.
+The standalone CLI scans `workflows/` and creates the combined flow handler, an internal step registration module, and the webhook handler.
 
 ```json title="package.json"
 {
@@ -68,21 +58,19 @@ Use the `workflow` CLI to generate the handler bundles. The CLI scans your `work
 }
 ```
 
-<Callout>
-  **For production integrations:** Instead of using the CLI, extend the `BaseBuilder` class directly in your framework plugin. This gives you control over file watching, custom output paths, and framework-specific hooks. See the [Next.js plugin](https://github.com/vercel/workflow/tree/main/packages/next) for an example.
-</Callout>
-
-**What gets generated:**
+The default output is:
 
-- `/.well-known/workflow/v1/flow.js` - Handles workflow execution (workflow mode transform)
-- `/.well-known/workflow/v1/step.js` - Handles step execution (step mode transform)
-- `/.well-known/workflow/v1/webhook.js` - Handles webhook delivery
+- `/.well-known/workflow/v1/flow.mjs` — the combined workflow and step queue consumer
+- `/.well-known/workflow/v1/__step_registrations.mjs` — an internal module imported by `flow.mjs`; do not route to it
+- `/.well-known/workflow/v1/webhook.mjs` — webhook delivery
 
-Each file exports a `POST` function that accepts Web standard `Request` objects.
+<Callout>
+  Production integrations should extend `BaseBuilder` from `@workflow/builders` so they can participate in the framework's build, watch, and routing lifecycle.
+</Callout>
 
-### Step 2: Add Client Mode Transform (Optional)
+### 2. Add the client transform
 
-Client mode transforms your application code to provide better DX. Add a Bun plugin to apply this transformation at runtime:
+Client mode gives application code the workflow IDs used by `start()` and prevents accidental direct workflow execution.
 
 {/* @skip-typecheck: incomplete code sample */}
 ```typescript title="workflow-plugin.ts" lineNumbers
@@ -94,8 +82,6 @@ plugin({
   setup(build) {
     build.onLoad({ filter: /\.(ts|tsx|js|jsx)$/ }, async (args) => {
       const source = await Bun.file(args.path).text();
-
-      // Optimization: Skip files that do not have any directives
       if (!source.match(/(use step|use workflow)/)) {
         return { contents: source };
       }
@@ -105,7 +91,7 @@ plugin({
         jsc: {
           experimental: {
             plugins: [
-              [require.resolve("@workflow/swc-plugin"), { mode: "client" }], // [!code highlight]
+              [require.resolve("@workflow/swc-plugin"), { mode: "client" }],
             ],
           },
         },
@@ -123,23 +109,14 @@ Activate the plugin in `bunfig.toml`:
 preload = ["./workflow-plugin.ts"]
 ```
 
-**What this does:**
-
-- Attaches workflow IDs to functions for use with `start()`
-- Provides TypeScript type safety
-- Prevents accidental direct execution of workflows
-
-**Why optional?** Without client mode, you can still use workflows by manually constructing IDs or referencing the build manifest.
-
-### Step 3: Expose HTTP Endpoints
+### 3. Expose the HTTP routes
 
-Wire up the generated handlers to HTTP endpoints using `Bun.serve()`:
+Only the combined flow handler and webhook handler are routable:
 
 {/* @skip-typecheck: incomplete code sample */}
 ```typescript title="server.ts" lineNumbers
-import flow from "./.well-known/workflow/v1/flow.js";
-import step from "./.well-known/workflow/v1/step.js";
-import * as webhook from "./.well-known/workflow/v1/webhook.js";
+import * as flow from "./.well-known/workflow/v1/flow.mjs";
+import * as webhook from "./.well-known/workflow/v1/webhook.mjs";
 
 import { start } from "workflow/api";
 import { handleUserSignup } from "./workflows/user-signup.js";
@@ -148,23 +125,14 @@ const server = Bun.serve({
   port: process.env.PORT,
   routes: {
     "/.well-known/workflow/v1/flow": {
-      POST: (req) => flow.POST(req),
+      POST: flow.POST,
     },
-    "/.well-known/workflow/v1/step": {
-      POST: (req) => step.POST(req),
-    },
-    // webhook exports handlers for GET, POST, DELETE, etc.
     "/.well-known/workflow/v1/webhook/:token": webhook,
-
-    // Example: Start a workflow
     "/": {
-      GET: async (req) => {
+      GET: async () => {
         const email = `test-${crypto.randomUUID()}@test.com`;
         const run = await start(handleUserSignup, [email]);
-        return Response.json({
-          message: "User signup workflow started",
-          runId: run.runId,
-        });
+        return Response.json({ runId: run.runId });
       },
     },
   },
@@ -173,222 +141,90 @@ const server = Bun.serve({
 console.log(`Server listening on http://localhost:${server.port}`);
 ```
 
-**That's it!** Your Bun integration is complete.
-
-## Understanding the Endpoints
-
-Your integration must expose three HTTP endpoints. The generated handlers manage all protocol details—you just route requests.
+## Runtime routes
 
-### Workflow Endpoint
+### Combined flow endpoint
 
 **Route:** `POST /.well-known/workflow/v1/flow`
 
-Executes workflow orchestration logic. The workflow function is "rendered" multiple times during execution—each time it progresses until it encounters the next step.
+The handler consumes every workflow queue message. Depending on the payload and event log, it can:
 
-**Called when:**
+- start or replay workflow orchestration in the sandboxed VM;
+- execute a queued step in the host runtime;
+- continue replay inline after a step completes;
+- resume a run after a hook, webhook, sleep, retry, or recovery event.
 
-- Starting a new workflow
-- Resuming after a step completes
-- Resuming after a webhook or hook triggers
-- Recovering from failures
+### Webhook endpoint
 
-### Step Endpoint
+**Route:** `/.well-known/workflow/v1/webhook/:token`
 
-**Route:** `POST /.well-known/workflow/v1/step`
+This handler delivers data to [`createWebhook()`](/docs/api-reference/workflow/create-webhook). Its generated file structure varies by framework; for example, Next.js uses `webhook/[token]/route.js`.
 
-Executes individual atomic operations within workflows. Each step runs exactly once per execution (unless retried due to failure). Steps have full runtime access (Node.js APIs, file system, databases, etc.).
+## Building with `BaseBuilder`
 
-### Webhook Endpoint
+Use `createCombinedBundle()` so the flow bundle imports the generated step registrations. Calling `createWorkflowsBundle()` and `createStepsBundle()` independently does not create a complete runtime route.
 
-**Route:** `POST /.well-known/workflow/v1/webhook/:token`
-
-Delivers webhook data to running workflows via [`createWebhook()`](/docs/api-reference/workflow/create-webhook). The `:token` parameter identifies which workflow run should receive the data.
-
-<Callout type="info">
-  The webhook file structure varies by framework. Next.js generates `webhook/[token]/route.js` to leverage App Router's dynamic routing, while other frameworks generate a single `webhook.js` handler.
-</Callout>
-
-## Adapting to Other Frameworks
-
-The Bun example demonstrates the core pattern. To adapt for your framework:
-
-### Build-Time
-
-**Option 1: Use the CLI** (simplest)
-
-```bash
-workflow build
-```
-
-This will default to scanning the `./workflows` top-level directory for workflow files, and will output bundled files directly into your working directory.
-
-**Option 2: Extend `BaseBuilder`** (recommended)
-
-{/* @skip-typecheck: @workflow/cli internal module */}
-```typescript lineNumbers
-import { BaseBuilder } from "@workflow/cli/dist/lib/builders/base-builder";
+{/* @skip-typecheck: incomplete framework adapter */}
+```typescript title="my-framework-builder.ts" lineNumbers
+import { join } from "node:path";
+import { BaseBuilder } from "@workflow/builders";
 
 class MyFrameworkBuilder extends BaseBuilder {
-  constructor(options) {
-    super({
-      dirs: ["workflows"],
-      workingDir: options.rootDir,
-      watch: options.dev,
-    });
-  }
-
   override async build(): Promise<void> {
     const inputFiles = await this.getInputFiles();
+    const tsconfigPath = await this.findTsConfigPath();
+    const outputDir = join(this.config.workingDir, ".workflow");
 
-    await this.createWorkflowsBundle({
-      outfile: "/path/to/.well-known/workflow/v1/flow.js",
-      format: "esm",
+    await this.createCombinedBundle({
       inputFiles,
-    });
-
-    await this.createStepsBundle({
-      outfile: "/path/to/.well-known/workflow/v1/step.js",
+      stepsOutfile: join(outputDir, "__step_registrations.mjs"),
+      flowOutfile: join(outputDir, "flow.mjs"),
+      tsconfigPath,
       format: "esm",
-      inputFiles,
     });
 
     await this.createWebhookBundle({
-      outfile: "/path/to/.well-known/workflow/v1/webhook.js",
+      outfile: join(outputDir, "webhook.mjs"),
     });
   }
 }
 ```
 
-If your framework supports virtual server routes and dev mode watching, make sure to adapt accordingly. Please open a PR to the Workflow SDK if the base builder class is missing necessary functionality.
-
-### Monorepos and Workspace Imports
-
-If your framework integration lives in a subdirectory and your workflows import code from sibling workspace packages, pass `projectRoot` to `BaseBuilder`. Use the smallest directory that contains every workspace package imported by your workflows.
-
-{/* @skip-typecheck: @workflow/cli internal module */}
-```typescript title="my-framework-builder.ts" lineNumbers
-import { BaseBuilder } from "@workflow/cli/dist/lib/builders/base-builder";
+If workflows import sibling workspace packages, set `projectRoot` to the smallest directory containing all imported packages.
 
-class MyFrameworkBuilder extends BaseBuilder {
-  constructor(options: {
-    rootDir: string;
-    workspaceRoot?: string;
-    dev: boolean;
-  }) {
-    super({
-      dirs: ["workflows"],
-      workingDir: options.rootDir,
-      projectRoot: options.workspaceRoot ?? options.rootDir, // [!code highlight]
-      watch: options.dev,
-    });
-  }
-
-  override async build(): Promise<void> {
-    const inputFiles = await this.getInputFiles();
-    // ...
-  }
-}
-```
-
-Hook into your framework's build:
-
-{/* @skip-typecheck: incomplete code sample */}
-```typescript title="pseudocode.ts" lineNumbers
-framework.hooks.hook("build:before", async () => {
-  await new MyFrameworkBuilder(framework).build();
+{/* @skip-typecheck: partial constructor configuration */}
+```typescript
+super({
+  dirs: ["workflows"],
+  workingDir: options.rootDir,
+  projectRoot: options.workspaceRoot ?? options.rootDir,
+  watch: options.dev,
 });
 ```
 
-### Runtime (Client Mode)
-
-Add a loader/plugin for your bundler:
-
-**Rollup/Vite:**
-
-```typescript lineNumbers
-export function workflowPlugin() {
-  return {
-    name: "workflow-client-transform",
-    async transform(code, id) {
-      if (!code.match(/(use step|use workflow)/)) return null;
+Your integration can expose physical files, virtual modules, or framework-native routes. In every case, the step registration module is a dependency of the flow handler, not a route of its own.
 
-      const result = await transform(code, {
-        filename: id,
-        jsc: {
-          experimental: {
-            plugins: [[require.resolve("@workflow/swc-plugin"), { mode: "client" }]], // [!code highlight]
-          },
-        },
-      });
+## Vercel queue configuration
 
-      return { code: result.code, map: result.map };
-    },
-  };
-}
-```
+On Vercel, configure the flow function as the sole queue consumer. `getWorkflowQueueTrigger()` handles the optional queue namespace and `WORKFLOW_SEQUENTIAL_REPLAYS=1` behavior.
 
-**Webpack:**
+```typescript
+import { getWorkflowQueueTrigger } from "@workflow/builders";
 
-```javascript lineNumbers
-module.exports = {
-  module: {
-    rules: [
-      {
-        test: /\.(ts|tsx|js|jsx)$/,
-        use: "workflow-client-loader", // Similar implementation
-      },
-    ],
-  },
+const flowConfig = {
+  maxDuration: "max",
+  experimentalTriggers: [getWorkflowQueueTrigger()],
 };
 ```
 
-### HTTP Server
-
-Route the three endpoints to the generated handlers. The exact implementation depends on your framework's routing API.
-
-In the bun example above, we left routing to the user. Essentially, the user has to serve routes like this:
+The generated trigger listens to one topic family:
 
-{/* @skip-typecheck: incomplete code sample */}
-```typescript title="server.ts" lineNumbers
-import flow from "./.well-known/workflow/v1/flow.js";
-import step from "./.well-known/workflow/v1/step.js";
-import * as webhook from "./.well-known/workflow/v1/webhook.js";
-
-// Expose the 3 generated routes
-const server = Bun.serve({
-  routes: {
-    "/.well-known/workflow/v1/flow": {
-      POST: (req) => flow.POST(req),
-    },
-    "/.well-known/workflow/v1/step": {
-      POST: (req) => step.POST(req),
-    },
-    // webhook exports handlers for GET, POST, DELETE, etc.
-    "/.well-known/workflow/v1/webhook/:token": webhook,
-  },
-});
-```
-
-Production framework integrations should handle this routing in the plugin instead of leaving it to the user, and this depends on each framework's unique implementaiton.
-Check the Workflow SDK source code for examples of production framework implementations.
-In the future, the Workflow SDK will emit more routes under the `.well-known/workflow` namespace.
-
-## Security
-
-The workflow and step handler endpoints are invoked by the world's queuing infrastructure, not by end users. How they're secured depends on which world you're deploying to.
-
-### Vercel (`@workflow/world-vercel`)
-
-On Vercel, workflow handler functions are not accessible through public endpoints. Handlers use the same [consumer function security](https://vercel.com/docs/queues/concepts#consumer-function-security) mechanism that secures [Vercel Queues](https://vercel.com/docs/queues) consumers.
-
-During the build step, the Workflow SDK automatically configures each handler as a queue consumer by writing `experimentalTriggers` to the function's `.vc-config.json`:
-
-```json title=".vc-config.json (generated by Workflow SDK)"
+```json title=".vc-config.json (excerpt)"
 {
   "experimentalTriggers": [
     {
       "type": "queue/v2beta",
-      "topic": "__wkf_step_*",
+      "topic": "__wkf_workflow_*",
       "consumer": "default",
       "retryAfterSeconds": 5,
       "initialDelaySeconds": 0
@@ -397,110 +233,28 @@ During the build step, the Workflow SDK automatically configures each handler as
 }
 ```
 
+Both orchestration messages and step messages use this topic family. A step message is distinguished by its payload, not by a second topic or function.
 
-Two queue topics are created per deployment:
-
-| Handler | Topic | Description |
-| --- | --- | --- |
-| `step.func` | `__wkf_step_*` | Step execution (long-running, `maxDuration: max`) |
-| `flow.func` | `__wkf_workflow_*` | Workflow orchestration (`maxDuration: 60`) |
-
-If you're building a framework integration that targets Vercel, you should write these triggers into the `.vc-config.json` for each generated function. Use `getWorkflowQueueTrigger()` for flow functions so `WORKFLOW_SEQUENTIAL_REPLAYS=1` is reflected in the generated trigger configuration (it also accepts a `namespace` option, matching `createWorkflowQueueTrigger`); `STEP_QUEUE_TRIGGER` is exported for step functions:
-
-```typescript
-import { getWorkflowQueueTrigger, STEP_QUEUE_TRIGGER } from "@workflow/builders";
-
-const flowTriggers = [getWorkflowQueueTrigger()];
-const stepTriggers = [STEP_QUEUE_TRIGGER];
-```
-
-If your integration constructs the flow trigger object itself instead of calling `getWorkflowQueueTrigger()`, it must add `maxConcurrency: 1` to that trigger when sequential replays are enabled at build time (`WORKFLOW_SEQUENTIAL_REPLAYS=1` — the exported `isSequentialReplaysEnabled()` helper implements this check). The runtime half of the feature (per-run queue topics) activates from the environment variable alone — without the trigger half, those per-run topics are not serialized and the setting only adds queue-topic cardinality.
-
+If you construct the trigger yourself, add `maxConcurrency: 1` when `WORKFLOW_SEQUENTIAL_REPLAYS=1`. The exported `isSequentialReplaysEnabled()` helper implements that build-time check.
 
-### Custom implementations
-
-For self-hosted or non-Vercel deployments, you are responsible for securing the handler endpoints:
-
-- **Framework middleware** — Add authentication (API keys, JWT, OIDC) in front of the `/.well-known/workflow/v1/*` routes
-- **Network-level security** — Deploy handlers behind a VPC, private network, or firewall rules so only your queue infrastructure can reach them
-- **Rate limiting** — Add request validation and rate limiting to prevent abuse
-
-Learn more about [building custom Worlds](/worlds/building-a-world).
-
-## Testing Your Integration
-
-### 1. Test Build Output
-
-Create a test workflow:
-
-```typescript title="workflows/test.ts" lineNumbers
-import { sleep, createWebhook } from "workflow";
-
-export async function handleUserSignup(email: string) {
-  "use workflow";
-
-  const user = await createUser(email);
-  await sendWelcomeEmail(user);
-
-  await sleep("5s");
-
-  const webhook = createWebhook();
-  await sendOnboardingEmail(user, webhook.url);
-
-  await webhook;
-  console.log("Webhook Resolved");
-
-  return { userId: user.id, status: "onboarded" };
-}
-
-async function createUser(email: string) {
-  "use step";
-
-  console.log(`Creating a new user with email: ${email}`);
-
-  return { id: crypto.randomUUID(), email };
-}
-
-async function sendWelcomeEmail(user: { id: string; email: string }) {
-  "use step";
-
-  console.log(`Sending welcome email to user: ${user.id}`);
-}
-
-async function sendOnboardingEmail(user: { id: string; email: string }, callback: string) {
-  "use step";
-
-  console.log(`Sending onboarding email to user: ${user.id}`);
-
-  console.log(`Click this link to resolve the webhook: ${callback}`);
-}
+## Security
 
-```
+On Vercel, the flow handler uses [queue consumer security](https://vercel.com/docs/queues/concepts#consumer-function-security). For self-hosted worlds, protect the flow and webhook routes with the authentication, network controls, and rate limits appropriate to your queue transport.
 
-Run your build and verify:
+## Testing an integration
 
-- `.well-known/workflow/v1/flow.js` exists
-- `.well-known/workflow/v1/step.js` exists
-- `.well-known/workflow/v1/webhook.js` exists
+After a build, verify that:
 
-### 2. Test HTTP Endpoints
+- the flow handler exists and imports or embeds the step registration bundle;
+- the webhook handler exists;
+- no step HTTP route or step queue trigger is generated;
+- the flow function has the workflow queue trigger and the required maximum duration;
+- starting a workflow executes a real step and resumes the workflow.
 
-Start your server and verify routes respond:
+The flow route exposes a lightweight direct health mode:
 
 ```bash
-curl -X POST http://localhost:3000/.well-known/workflow/v1/flow
-curl -X POST http://localhost:3000/.well-known/workflow/v1/step
-curl -X POST http://localhost:3000/.well-known/workflow/v1/webhook/test
+curl -X POST "http://localhost:3000/.well-known/workflow/v1/flow?__health"
 ```
 
-(Should respond but not trigger meaningful code without authentication/proper workflow run)
-
-### 3. Run a Workflow End-to-End
-
-```typescript
-import { start } from "workflow/api";
-import { handleUserSignup } from "./workflows/test";
-
-const run = await start(handleUserSignup, ["test@example.com"]);
-console.log("Workflow started:", run.runId);
-```
+For an end-to-end queue check, use [`healthCheck()`](/docs/api-reference/workflow-runtime/health-check).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.36",
+  "version": "5.0.0-beta.38",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -59,18 +59,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "5.0.0-beta.36",
-    "@workflow/cli": "5.0.0-beta.36",
-    "@workflow/core": "5.0.0-beta.36",
+    "@workflow/astro": "5.0.0-beta.38",
+    "@workflow/cli": "5.0.0-beta.38",
+    "@workflow/core": "5.0.0-beta.38",
+    "@workflow/errors": "5.0.0-beta.14",
     "@workflow/typescript-plugin": "5.0.0-beta.5",
-    "@workflow/errors": "5.0.0-beta.12",
-    "@workflow/utils": "5.0.0-beta.6",
-    "@workflow/next": "5.0.0-beta.36",
-    "@workflow/nest": "5.0.0-beta.36",
-    "@workflow/nitro": "5.0.0-beta.36",
-    "@workflow/nuxt": "5.0.0-beta.36",
-    "@workflow/sveltekit": "5.0.0-beta.36",
-    "@workflow/rollup": "5.0.0-beta.36"
+    "@workflow/utils": "5.0.0-beta.8",
+    "@workflow/next": "5.0.0-beta.38",
+    "@workflow/nest": "5.0.0-beta.38",
+    "@workflow/nitro": "5.0.0-beta.38",
+    "@workflow/nuxt": "5.0.0-beta.38",
+    "@workflow/sveltekit": "5.0.0-beta.38",
+    "@workflow/rollup": "5.0.0-beta.38"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",