workflow 5.0.0 → 5.1.0

package/docs/advanced/dynamic-workflows.mdx

@@ -140,7 +140,7 @@ Supply a unique, deterministic approval token from the caller. The workflow must
 
 `start()` validates the source before it writes anything, so a definition that could never run fails at the call site rather than on a queue delivery:
 
-- It must declare `async function workflow(...)`. Pass `experimental_dynamic.exportName` to use a different name; export names may contain letters, digits, and `_`, and cannot start with a digit.
+- It must declare `async function workflow(...)`. Pass `experimental_dynamic.exportName` to use a different name; export names may contain letters, digits, and `_`, cannot start with a digit, and are at most 64 characters.
 - The function's first statement must be the `"use workflow"` directive.
 - No `import` or `export`. Reach steps through `steps`, not through modules.
 - JavaScript only — no TypeScript syntax, no npm dependencies, no bundling.
@@ -182,6 +182,8 @@ Both paths are transparent — there is nothing to configure. Here, “inline”
 
 Alongside the serialized code, the run records small plaintext metadata on `executionContext.dynamicWorkflow`: the source hash, the export name, and the alias-to-step-ID map. That is what lets a run be identified as dynamic without decoding the source. It is plaintext even when the code is encrypted, so anyone who can read the run can see which step IDs it was given and the aliases they were given under.
 
+In the [observability UI](/docs/observability), a dynamic run's detail view shows its stored code in a **Workflow Code** section, behind the same decrypt action as the run's input and output. **Replay Run** is unavailable for dynamic runs. To run the definition again, call `start()` with the same source.
+
 ## World support
 
 Dynamic workflows need a World that can store the run's workflow code.
@@ -219,6 +221,7 @@ Treat dynamic source the way you would treat code in a pull request: written or
 - Steps must already be registered in the deployment; no runtime step registration.
 - No inline `"use step"` functions, `createWebhook`, or `getWritable`.
 - No caller-provided workflow IDs.
+- No **Replay Run** from the observability UI.
 - Parser-based validation checks JavaScript syntax and the required source/wrapper shape without executing it. It does not validate behavior, determinism, or intent.
 - On Vercel, roughly 30 step aliases fit the 2,048-byte execution-context limit.
 - Requires a World with dynamic-source storage.

package/docs/advanced/index.mdx

@@ -0,0 +1,13 @@
+---
+title: Advanced
+description: Features for workflows that go beyond the build-time execution model.
+type: overview
+summary: Explore features for cases that workflows compiled into your build do not cover.
+related:
+  - /docs/foundations
+  - /docs/how-it-works/code-transform
+---
+
+These features build on the [foundations](/docs/foundations) for cases that workflows compiled into your build do not cover, such as orchestration whose shape is only known after you deploy.
+
+<AutoCards />

package/docs/advanced/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Advanced",
+  "pages": ["dynamic-workflows"],
+  "defaultOpen": false
+}

package/docs/ai/chat-session-modeling.mdx

@@ -267,9 +267,9 @@ Use the multi-turn pattern when:
 
 The multi-turn pattern also supports messages from system events, external services, and multiple users. Every source resumes the same Hook; the workflow queues those messages and processes them between model turns.
 
-<Tabs items={['System event', 'External service', 'Multiple users']}>
+<TabsWithChildren tabs={["System event","External service","Multiple users"]}>
 
-<Tab value="System event">
+<TabContent order={1}>
 
 Scheduled tasks, background jobs, or database triggers can inject updates into an active conversation:
 
@@ -287,9 +287,9 @@ export async function POST(request: Request) {
 }
 ```
 
-</Tab>
+</TabContent>
 
-<Tab value="External service">
+<TabContent order={2}>
 
 A third-party webhook can notify the conversation about an external event:
 
@@ -309,9 +309,9 @@ export async function POST(request: Request) {
 }
 ```
 
-</Tab>
+</TabContent>
 
-<Tab value="Multiple users">
+<TabContent order={3}>
 
 Multiple authenticated users can participate in the same workflow-owned session. Include attribution when resuming the Hook:
 
@@ -337,9 +337,9 @@ export async function POST(
 
 To preserve structured attribution across refreshes, persist the corresponding `UIMessage` using the application-history approach described above.
 
-</Tab>
+</TabContent>
 
-</Tabs>
+</TabsWithChildren>
 
 ## Related documentation
 

package/docs/ai/human-in-the-loop.mdx

@@ -154,6 +154,10 @@ export async function POST(request: Request) {
 }
 ```
 
+<Callout type="warn">
+This route resumes whichever hook owns `toolCallId`, so anyone who learns the ID can submit a decision. In production, authenticate the request and check that the signed-in user may approve this booking before calling `resume()`. See [Hook and webhook security](/docs/foundations/hooks#security).
+</Callout>
+
 </Step>
 
 <Step>
@@ -185,7 +189,7 @@ export function BookingApproval({ toolCallId, input, output }: BookingApprovalPr
   if (output) {
     return (
       <div className="border rounded-lg p-4">
-        <p className="text-sm text-muted-foreground">{output}</p>
+        <p className="text-sm text-gray-900">{output}</p>
       </div>
     );
   }
@@ -207,7 +211,7 @@ export function BookingApproval({ toolCallId, input, output }: BookingApprovalPr
     <div className="border rounded-lg p-4 space-y-4">
       <div className="space-y-2">
         <p className="font-medium">Approve this booking?</p>
-        <div className="text-sm text-muted-foreground">
+        <div className="text-sm text-gray-900">
           {input && (
             <div className="space-y-2">
               <div>Flight: {input.flightNumber}</div>
@@ -334,7 +338,7 @@ export default function ChatPage() {
 
 ## Using webhooks directly
 
-For simpler cases where you don't need type-safe validation or programmatic resumption, you can use [`createWebhook()`](/docs/api-reference/workflow/create-webhook) directly. This generates a unique URL that can be called to resume the workflow:
+For simpler cases where you don't need type-safe validation or programmatic resumption, you can use [`createWebhook()`](/docs/api-reference/workflow/create-webhook) directly. This generates a unique URL that can be called to resume the workflow. Anyone with the URL can resume it, so avoid this for approvals that need to know who approved, unless you use the incoming payload for authorization. See [Hook and webhook security](/docs/foundations/hooks#security).
 
 ```typescript title="workflows/chat/steps/tools.ts" lineNumbers
 import { createWebhook } from "workflow";

package/docs/ai/index.mdx

@@ -59,9 +59,9 @@ cd workflow-examples/flight-booking-app
 
 ### Configure model access
 
-<Tabs items={['AI Gateway', 'Provider package']}>
+<TabsWithChildren tabs={["AI Gateway","Provider package"]}>
 
-<Tab value="AI Gateway">
+<TabContent order={1}>
 
 AI SDK uses [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) as its default global provider, so plain `"provider/model"` strings need no provider-specific package. Vercel deployments authenticate with OIDC automatically. For local development, link the project and pull a short-lived OIDC token:
 
@@ -72,9 +72,9 @@ vercel env pull .env.local
 
 You can alternatively set `AI_GATEWAY_API_KEY` from the [AI Gateway authentication](https://vercel.com/docs/ai-gateway/authentication) page.
 
-</Tab>
+</TabContent>
 
-<Tab value="Provider package">
+<TabContent order={2}>
 
 `WorkflowAgent` accepts any AI SDK provider. To use OpenAI, install its provider package:
 
@@ -98,9 +98,9 @@ const model = openai("gpt-5.6-sol");
 
 See the [AI SDK provider guide](https://ai-sdk.dev/providers/ai-sdk-providers) for Anthropic, Google, Amazon Bedrock, and other providers.
 
-</Tab>
+</TabContent>
 
-</Tabs>
+</TabsWithChildren>
 </Step>
 
 <Step>
@@ -111,9 +111,9 @@ Run the app with `npm run dev` and open [http://localhost:3000](http://localhost
 
 The following sections break down the core code. You don't need to make changes yet.
 
-<Tabs items={['API Route', 'Tools', 'Client']}>
+<TabsWithChildren tabs={["API Route","Tools","Client"]}>
 
-<Tab value="API Route">
+<TabContent order={1}>
 
 Our API route calls [AI SDK's `ToolLoopAgent` class](https://ai-sdk.dev/docs/agents/overview), which encapsulates the LLM call, tool execution loop, and stopping conditions on top of [AI SDK's `streamText` function](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text#streamtext). This is also where we pass tools to the agent.
 
@@ -137,9 +137,9 @@ export async function POST(req: Request) {
 }
 ```
 
-</Tab>
+</TabContent>
 
-<Tab value="Tools">
+<TabContent order={2}>
 
 Our tools are mostly mocked out for the sake of the example. We use AI SDK's `tool` function to define the tool, and pass it to the agent. In your own app, this might be any kind of tool call, like database queries, calls to external services, etc.
 
@@ -160,9 +160,9 @@ async function searchFlights({ from, to, date }: { from: string; to: string; dat
 }
 ```
 
-</Tab>
+</TabContent>
 
-<Tab value="Client">
+<TabContent order={3}>
 
 Our `ChatPage` component contains logic for displaying chat messages, but its core responsibility is managing input and output for the [`useChat` hook](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#usechat) from AI SDK.
 
@@ -207,9 +207,9 @@ export default function ChatPage() {
 }
 ```
 
-</Tab>
+</TabContent>
 
-</Tabs>
+</TabsWithChildren>
 
 </Step>
 

package/docs/ai/streaming-updates-from-tools.mdx

@@ -120,9 +120,9 @@ Update your chat component to detect and render the custom data parts. Data part
       to: string; // [!code highlight]
     }; // [!code highlight]
     return ( // [!code highlight]
-      <div key={`${part.id}-${flight.flightNumber}`} className="p-3 bg-muted rounded-md"> // [!code highlight]
+      <div key={`${part.id}-${flight.flightNumber}`} className="p-3 bg-gray-100 rounded-md"> // [!code highlight]
         <div className="font-medium">{flight.airline} - {flight.flightNumber}</div> // [!code highlight]
-        <div className="text-muted-foreground">{flight.from} → {flight.to}</div> // [!code highlight]
+        <div className="text-gray-900">{flight.from} → {flight.to}</div> // [!code highlight]
       </div> // [!code highlight]
     ); // [!code highlight]
   } // [!code highlight]

package/docs/api-reference/vitest/index.mdx

@@ -8,11 +8,11 @@ The `@workflow/vitest` package provides a Vitest plugin and test helpers for run
 ## Installation
 
 ```package-install
-npm i -D @workflow/vitest@beta
+npm i -D @workflow/vitest
 ```
 
 <Callout type="warn">
-`@workflow/vitest@latest` is still the 4.x line, so a Workflow 5 app has to install the `beta` tag (or pin the matching beta, for example `@workflow/vitest@5.0.0-beta.53`). The package carries its own copy of `@workflow/core` and runs your workflows against it, so it has to move with `workflow`.
+The package carries its own copy of `@workflow/core` and runs your workflows against it, so it has to move with `workflow` and stay on the same major.
 
 `globalSetup` compares the two copies once per run: a different major fails the run with the install command that fixes it, and any other difference logs a warning. Set [`WORKFLOW_VITEST_VERSION_CHECK=off`](/docs/configuration/build-and-diagnostics#workflow_vitest_version_check) to skip the check.
 </Callout>

package/docs/api-reference/workflow/create-hook.mdx

@@ -15,6 +15,10 @@ Creates a low-level hook primitive that can be used to resume a workflow run wit
 
 Hooks allow external systems to send data to a paused workflow without the HTTP-specific constraints of webhooks. They're identified by a token and can receive any serializable payload.
 
+<Callout type="warn">
+A hook token routes a payload to the right hook; it does not authorize the sender. Generated tokens are hard to guess but are not secrets, and custom tokens are usually easy to reconstruct. Authorize callers in the route that calls [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook). See [Hook and webhook security](/docs/foundations/hooks#security).
+</Callout>
+
 ```ts lineNumbers
 import { createHook } from "workflow"
 

package/docs/api-reference/workflow/create-webhook.mdx

@@ -14,7 +14,7 @@ Creates a webhook that can be used to suspend and resume a workflow run upon rec
 Webhooks provide a way for external systems to send HTTP requests directly to your workflow. Unlike hooks which accept arbitrary payloads, webhooks work with standard HTTP `Request` objects and can return HTTP `Response` objects.
 
 <Callout type="warn">
-`createWebhook()` creates a public endpoint at `/.well-known/workflow/v1/webhook/:token`, and the token in that URL is the only authorization performed for incoming requests resuming that webhook. This is convenient for prototypes and basic resume links because it avoids creating another route, but if you need stronger security, prefer [`createHook()`](/docs/api-reference/workflow/create-hook) behind your own route and authorize the request before calling [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) to avoid unauthenticated workflow resumptions.
+`createWebhook()` creates a public endpoint at `/.well-known/workflow/v1/webhook/:token`, and the token in that URL is the only authorization performed for incoming requests resuming that webhook. Anyone who has the URL can resume the workflow with a request of their choosing, so verify requests before acting on them or use [`createHook()`](/docs/api-reference/workflow/create-hook) behind your own authorized route. See [Hook and webhook security](/docs/foundations/hooks#security).
 </Callout>
 
 ```ts lineNumbers

package/docs/api-reference/workflow/define-hook.mdx

@@ -17,6 +17,10 @@ This is a lightweight wrapper around [`createHook()`](/docs/api-reference/workfl
 We recommend using `defineHook()` over `createHook()` in production codebases for better type safety and optional runtime validation.
 </Callout>
 
+<Callout type="warn">
+Schema validation checks the payload's shape, not who sent it. Authorize callers before calling `resume()`. See [Hook and webhook security](/docs/foundations/hooks#security).
+</Callout>
+
 ```ts lineNumbers
 import { defineHook } from "workflow";
 

package/docs/api-reference/workflow-api/get-hook-by-token.mdx

@@ -93,13 +93,19 @@ export async function POST(request: Request) {
 
 ### Validating hook before resume
 
-Use `getHookByToken` to validate hook ownership or metadata before resuming:
+Use `getHookByToken` to validate hook ownership or metadata before resuming. Take the user's identity from your authentication layer, not from the request body. See [Hook and webhook security](/docs/foundations/hooks#security).
 
 ```typescript lineNumbers
 import { getHookByToken, resumeHook } from "workflow/api";
 
+declare function getSession(request: Request): Promise<{ userId: string } | null>; // @setup
+
 export async function POST(request: Request) {
-  const { token, userId, data } = await request.json();
+  const session = await getSession(request);
+  if (!session) {
+    return Response.json({ error: "Unauthorized" }, { status: 401 });
+  }
+  const { token, data } = await request.json();
 
   try {
     const hook = await getHookByToken(token); // [!code highlight]
@@ -107,7 +113,7 @@ export async function POST(request: Request) {
     const metadata = (await hook.metadata) as { allowedUserId?: string } | undefined; // [!code highlight]
 
     // Validate that the hook metadata matches the user
-    if (metadata?.allowedUserId !== userId) {
+    if (metadata?.allowedUserId !== session.userId) {
       return Response.json(
         { error: "Unauthorized to resume this hook" },
         { status: 403 }

package/docs/api-reference/workflow-api/resume-hook.mdx

@@ -22,6 +22,10 @@ If `resumeHook()` throws any other error, the outcome is ambiguous only in dispa
 `resumeHook` is a runtime function that must be called from outside a workflow function.
 </Callout>
 
+<Callout type="warn">
+`resumeHook()` does not check who is calling it. Authenticate the caller and confirm they may resume this hook before calling it; knowing the token is not enough. The examples below omit that check for brevity. See [Hook and webhook security](/docs/foundations/hooks#security).
+</Callout>
+
 ```typescript lineNumbers
 import { resumeHook } from "workflow/api";
 

package/docs/api-reference/workflow-api/resume-webhook.mdx

@@ -17,6 +17,10 @@ This function publishes a workflow invocation carrying the request; the runtime
 `resumeWebhook` is a runtime function that must be called from outside a workflow function.
 </Callout>
 
+<Callout type="warn">
+The webhook token is the only authorization `resumeWebhook()` and the public webhook route perform. Verify requests before acting on them. See [Hook and webhook security](/docs/foundations/hooks#security).
+</Callout>
+
 ```typescript lineNumbers
 import { resumeWebhook } from "workflow/api";
 

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

@@ -32,6 +32,10 @@ These APIs are available but are **seeded or fixed** to ensure deterministic beh
 You can safely use `Math.random()`, `Date.now()`, and `crypto.randomUUID()` in workflow functions. The framework ensures these return the same values across replays.
 </Callout>
 
+<Callout type="warn">
+`Math.random()`, `crypto.randomUUID()`, and `crypto.getRandomValues()` are derived from the run's seed rather than a secret, so their values are predictable to anyone who knows that seed. Don't use them for secrets, one-time codes, or tokens that must be unguessable; generate those in a step instead. See [Hook and webhook security](/docs/foundations/hooks#security).
+</Callout>
+
 ## Web platform APIs
 
 These standard Web APIs are available in workflow functions:

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

@@ -10,7 +10,7 @@ related:
 NestJS integration for Workflow SDK. The `WorkflowModule` builds the workflow bundles on application startup and registers the controller that serves the workflow runtime routes.
 
 <Callout>
-NestJS integration is experimental and not yet supported for deployment to Vercel. The same exports are also available from the `@workflow/nest` package.
+NestJS integration is in beta. Both `@nestjs/platform-express` and `@nestjs/platform-fastify` are supported, and deploying to Vercel goes through [`workflow-nest build --vercel`](/docs/getting-started/nestjs#deploy-to-vercel). The same exports are also available from the `@workflow/nest` package.
 </Callout>
 
 ## Exports
@@ -25,6 +25,9 @@ NestJS integration is experimental and not yet supported for deployment to Verce
     <Card title="WorkflowController" href="/docs/api-reference/workflow-nest/workflow-controller">
         Controller that serves the workflow runtime routes under `.well-known/workflow/v1`
     </Card>
+    <Card title="isWorkflowRequest()" href="/docs/api-reference/workflow-nest/is-workflow-request">
+        Recognises a workflow request in a guard, so queue deliveries and webhooks are not rejected by your own auth
+    </Card>
     <Card title="configureWorkflowController()" href="/docs/api-reference/workflow-nest/configure-workflow-controller">
         Points `WorkflowController` at the directory containing the generated workflow bundles
     </Card>

package/docs/api-reference/workflow-nest/is-workflow-request.mdx

@@ -0,0 +1,58 @@
+---
+title: isWorkflowRequest
+description: Recognise a Workflow SDK request inside a NestJS guard or interceptor.
+type: reference
+summary: Let queue deliveries and webhooks past an application guard.
+prerequisites:
+  - /docs/getting-started/nestjs
+---
+
+Returns `true` when NestJS routed the request an `ExecutionContext` is handling to [`WorkflowController`](/docs/api-reference/workflow-nest/workflow-controller), which serves the Workflow SDK's protocol routes under `.well-known/workflow/v1`. The check is on the selected controller rather than the URL, so an application route that can be reached through a URL containing `.well-known/workflow/v1` (a wildcard such as `files/*path`) is still treated as your route.
+
+[`WorkflowController`](/docs/api-reference/workflow-nest/workflow-controller) is a controller inside your application, so a global guard runs for it too. A guard that rejects unauthenticated requests rejects every queue delivery and webhook with `403`, and runs stop making progress with no other symptom. Use this helper to exempt them.
+
+The workflow routes authenticate their own callers — queue deliveries are signed and webhook tokens are single-use secrets — so letting them past an application guard exposes nothing.
+
+## Usage
+
+{/* @skip-typecheck - NestJS decorators require special TypeScript config */}
+
+```typescript title="src/auth.guard.ts" lineNumbers
+import {
+  Injectable,
+  type CanActivate,
+  type ExecutionContext,
+} from "@nestjs/common";
+import { isWorkflowRequest } from "workflow/nest"; // [!code highlight]
+
+@Injectable()
+export class AuthGuard implements CanActivate {
+  canActivate(context: ExecutionContext) {
+    if (isWorkflowRequest(context)) return true; // [!code highlight]
+    return this.authenticate(context);
+  }
+}
+```
+
+## API signature
+
+### Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `context` | `ExecutionContext` | The execution context NestJS passes to a guard or interceptor. |
+
+### Returns
+
+`boolean`. `false` for a request to any other route, and for non-HTTP execution contexts (RPC, WebSockets), where there is no workflow route to match.
+
+## Related exports
+
+| Export | Description |
+| --- | --- |
+| `isWorkflowRoutePath(path, globalPrefix?)` | Whether a raw URL or path addresses a workflow route, for middleware that has a request rather than an `ExecutionContext`. The match is anchored to `globalPrefix` (default `''`), so pass the prefix given to `app.setGlobalPrefix()` unless it excludes the workflow routes. |
+| `WORKFLOW_ROUTE_PREFIX` | `'.well-known/workflow/v1'`, the path the controller is mounted at. |
+
+<Callout type="info">
+Interceptors and exception filters need no exemption. The workflow handlers write through `@Res()`, so the exact status and body the workflow runtime produced reach the caller, which is what the queue and third-party webhook senders key off.
+</Callout>

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

@@ -4,6 +4,7 @@
     "workflow-module",
     "nest-local-builder",
     "workflow-controller",
+    "is-workflow-request",
     "configure-workflow-controller"
   ]
 }

package/docs/api-reference/workflow-nest/workflow-controller.mdx

@@ -9,9 +9,13 @@ prerequisites:
 
 NestJS controller that handles the well-known workflow endpoints under `.well-known/workflow/v1`. It dynamically imports the generated workflow bundles and converts between Express/Fastify requests and the Web API `Request`/`Response` objects the workflow runtime expects. Both the Express and Fastify HTTP adapters are supported.
 
-The conversion preserves bytes in both directions: request bodies come from `req.rawBody` when the app is created with `{ rawBody: true }`, from a `Buffer`/string body left by a parser, or read directly from the request stream when no parser claimed the content type. Responses are written as bytes, and every `set-cookie` value is kept. See [Raw request bodies](/docs/getting-started/nestjs#raw-request-bodies).
+The conversion preserves bytes in both directions. [`WorkflowModule`](/docs/api-reference/workflow-nest/workflow-module) keeps the application's body parsers off these routes, so the request body is normally read straight from the stream; a `req.rawBody` left by `{ rawBody: true }`, or a `Buffer`/string body left by a parser, is used when one is present. Responses are written as bytes, and every `set-cookie` value is kept. See [Request bodies and body parsers](/docs/getting-started/nestjs#request-bodies-and-body-parsers).
 
-Handlers take `@Res()`, so the application's interceptors and exception filters do not wrap these routes. That is deliberate: the queue and third-party webhook senders key off the exact status and body the workflow runtime produces.
+Handlers take `@Res()` and write the response themselves, so an interceptor or exception filter cannot reshape it. That is deliberate: the queue and third-party webhook senders key off the exact status and body the workflow runtime produces.
+
+Guards do run, because NestJS runs them before the handler. A global guard that rejects unauthenticated requests rejects queue deliveries too; see [`isWorkflowRequest`](/docs/api-reference/workflow-nest/is-workflow-request).
+
+The controller is registered as `VERSION_NEUTRAL`, so `app.enableVersioning()` does not move these routes away from the paths the SDK generates URLs for. A global prefix does apply, and `WorkflowModule` adopts it automatically.
 
 [`WorkflowModule.forRoot()`](/docs/api-reference/workflow-nest/workflow-module) registers this controller automatically. You only register it yourself if you are not using `WorkflowModule`.
 

package/docs/api-reference/workflow-nest/workflow-module.mdx

@@ -86,6 +86,7 @@ Extends [`NestBuilderOptions`](/docs/api-reference/workflow-nest/nest-local-buil
 | `basePath` | `string` | adopted from `app.setGlobalPrefix()` | Route prefix the workflow endpoints are served under, applied to generated callback and webhook URLs. Set it when a reverse proxy mounts the app on a sub-path NestJS cannot see. |
 | `manageWorldLifecycle` | `boolean` | `false` | Start the target World's background workers with the app and close them on shutdown. Required for self-hosted Worlds, which otherwise never pick up runs. |
 | `preloadBundles` | `boolean` | `false` when `VERCEL` is set, else `true` | Load the generated bundles during startup instead of on the first request. On Vercel, dedicated functions serve the bundles, so there is nothing to preload. |
+| `bypassBodyParser` | `boolean` | `true` | Keep the application's body parsers away from `.well-known/workflow/v1`, so queue deliveries are not rejected by Express's 100 KB limit and signed webhook bodies stay byte-exact. The application's own routes are untouched. On Fastify, where the body limit is enforced per instance rather than per route, nothing is patched and a limit low enough to reject deliveries is reported at startup instead. |
 | `workingDir` | `string` | `process.cwd()` | Working directory for the NestJS application. |
 | `dirs` | `string[]` | `['src']` | Directories to scan for workflow files. |
 | `outDir` | `string` | `'.nestjs/workflow'` (relative to `workingDir`) | Output directory for generated workflow bundles. |
@@ -126,9 +127,16 @@ The older `WORKFLOW_OPTIONS` token resolves to the same value and is kept for co
 
 | Hook | Behaviour |
 | --- | --- |
-| `onModuleInit` | Reconciles the base path against `app.setGlobalPrefix()`, builds the bundles (or verifies they exist when `skipBuild` is set), optionally starts the World, and preloads the bundles. |
+| `onModuleInit` | Takes the application's body parsers off the workflow routes (unless `bypassBodyParser` is `false`), reconciles the base path against `app.setGlobalPrefix()`, builds the bundles (or verifies they exist when `skipBuild` is set), optionally starts the World, and preloads the bundles. |
 | `onApplicationShutdown` | Closes the World when `manageWorldLifecycle` is set. Call `app.enableShutdownHooks()` so this runs on a signal. |
 
+<Callout type="warn">
+`WorkflowModule` reads NestJS's global prefix and HTTP adapter through the
+injector, which only works while a single copy of `@nestjs/core` is installed.
+With two copies the injection tokens differ, prefix handling and the
+body-parser bypass both stop working, and a warning is logged at startup.
+</Callout>
+
 <Callout type="warn">
 Workflows and steps run outside the NestJS injector, so providers cannot be injected into `"use workflow"` or `"use step"` code. See [NestJS dependency injection is not available in workflows and steps](/docs/getting-started/nestjs#nestjs-dependency-injection-is-not-available-in-workflows-and-steps).
 </Callout>

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

@@ -204,6 +204,35 @@ const result = await world.runs.list({ // [!code highlight]
 
 **Returns:** `{ data: WorkflowRun[], cursor?: string }`
 
+The array form of `status` lets you express set filters without restating the
+status vocabulary. `@workflow/world` exports
+`TERMINAL_WORKFLOW_RUN_STATUSES` (`['completed', 'failed', 'cancelled']`) for
+that purpose:
+
+```typescript lineNumbers
+import { TERMINAL_WORKFLOW_RUN_STATUSES } from "@workflow/world";
+
+// Every run that has not reached a terminal status
+const inFlight = await world.runs.list({
+  status: ["pending", "running"],
+});
+
+// The complement, without hardcoding the list
+const finished = await world.runs.list({
+  status: [...TERMINAL_WORKFLOW_RUN_STATUSES],
+});
+```
+
+<Callout type="warn">
+  `status: []` matches **no** runs, mirroring SQL `IN ()`. To leave the filter
+  unset, omit the field entirely.
+
+  Support for the array form is per World. The Local and Postgres Worlds accept
+  it; the Vercel World's `/v2/runs` endpoint takes a single status today and
+  throws a `WorkflowWorldError` (`INVALID_ARGUMENT`) when given an array, rather
+  than silently filtering on something else.
+</Callout>
+
 <Callout type="warn">
   Observability and inspection usage of `world.runs.list()` is deprecated. Use
   [`world.analytics.runs.list()`](/docs/api-reference/workflow-runtime/world/analytics#runslist)

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

@@ -76,4 +76,14 @@ Accepted values:
 - 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 (for example, `/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`.
+
+#### What the dev watcher tracks
+
+In `next dev`, Workflow watches the modules your app actually imports, not your whole project:
+
+- Every file the workflow build reached from your Next.js entrypoints. Editing one rebuilds the affected workflow bundles.
+- The directories those files live in, so a module you add under an import you have already written is picked up.
+- The paths behind imports that do not resolve yet. Write `import './billing/workflow'` before creating the file, or delete a workflow module and restore it, and the module is bundled as soon as it exists, wherever it lives.
+- The `app` and `pages` directories (`src/` variants included), so a route you create is noticed even though nothing imports it yet, along with root entrypoints such as `middleware.ts` and `instrumentation.ts`.
+
+A directory your app never imports is not watched at all, so files there never produce workflow bundles or rebuilds. Import one from a page and the next rebuild brings it into the watched set. Files are only ever watched through the directory that contains them, so the watcher's cost scales with the number of watched directories rather than the number of source files.

package/docs/configuration/framework-options.mdx

@@ -126,6 +126,12 @@ Configure Workflow through `WorkflowModule.forRoot()`.
 - Default: `false`
 - Skips bundle generation when bundles are already pre-built.
 
+### `bypassBodyParser`
+
+- Environment override: none
+- Default: `true`
+- Keeps the application's body parsers away from `.well-known/workflow/v1`, so queue deliveries are not rejected by Express's 100 KB limit and signed webhook bodies stay byte-exact. Other routes are untouched. On Fastify, where the body limit is enforced per instance rather than per route, nothing is patched and a limit low enough to reject deliveries is reported at startup instead.
+
 ## Astro
 
 ### `sourcemap`

package/docs/configuration/runtime-tuning.mdx

@@ -220,7 +220,7 @@ For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPL
 - Values: `node` or `quickjs`
 - Selects the sandboxed VM engine that executes workflow functions (`"use workflow"`). Step functions are unaffected and always run with full Node.js access.
 - `node` (default) runs workflow code in a [`node:vm`](https://nodejs.org/api/vm.html) context.
-- `quickjs` (experimental) runs workflow code in a [QuickJS](https://github.com/quickjs-ng/quickjs) VM compiled to WebAssembly (via [`quickjs-wasi`](https://github.com/vercel-labs/quickjs-wasi)). Both engines implement the same event-replay execution model (seeded PRNG, deterministic clock, and correlation-ID sequences are identical), but the **global surface is not identical**. Review the differences below before switching an existing deployment. The QuickJS engine is intended for platforms that do not implement `node:vm`, and is the foundation for future VM-memory snapshotting.
+- `quickjs` (experimental) runs workflow code in a [QuickJS](https://github.com/quickjs-ng/quickjs) VM compiled to WebAssembly (via [`quickjs-wasi`](https://github.com/vercel-labs/quickjs-wasi)). Both engines implement the same event-replay execution model (seeded PRNG, deterministic clock, and correlation-ID sequences are identical), but the **global surface is not identical**. Review the differences below before switching an existing deployment. The QuickJS engine is intended for platforms that do not implement `node:vm`, and supports VM-memory snapshotting (see [`WORKFLOW_SNAPSHOT_THRESHOLD`](#workflow_snapshot_threshold)).
 - Global-surface differences under `quickjs` apply to workflow functions only. Step functions always have full Node.js:
   - `crypto.getRandomValues()` and `crypto.randomUUID()` are provided and deterministic (seeded like the node engine's). All `crypto.subtle.*` methods, including `digest`, throw with guidance to move to a step function. The node engine supports `digest`.
   - `Intl` is not available (QuickJS has no ICU). The `Intl.*` constructors throw, and `toLocaleString`-family methods (including `localeCompare`) throw when called **with an explicit locale**. Calling them without arguments keeps the engine default. Perform locale-sensitive formatting in a step function.
@@ -237,6 +237,31 @@ For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPL
 - A bundle whose module scope consumes randomness, reads the clock, or replaces a serialization intrinsic cannot be snapshotted safely. The runtime detects these cases when preparing the snapshot and falls back to per-invocation evaluation.
 - Set `0` or `false` to always evaluate the bundle per invocation.
 
+### `WORKFLOW_SNAPSHOT_THRESHOLD`
+
+- Default: `0` (disabled)
+- Values: non-negative integer
+- Experimental. Only used by the QuickJS engine (`WORKFLOW_VM=quickjs`), and only with a World that provides snapshot storage (world-local, world-postgres, and world-vercel do).
+- When set above `0`, the runtime persists a **VM-memory snapshot** at a suspension once at least this many events have been processed since the last snapshot. Subsequent invocations restore the VM from the snapshot and replay only the events recorded since, instead of re-executing the workflow from the top against the full event log.
+- Short-lived runs below the threshold never pay the snapshot cost; long-running or unbounded runs stop scaling their resume cost with total event-log length. `1` snapshots at every qualifying suspension.
+- Choosing a value: a restore costs roughly the same regardless of log length (tens of milliseconds to decompress and restore the heap, plus fetching the snapshot), while a full replay grows with the log (tens of milliseconds at a few hundred events, seconds at several thousand). Restoring starts to pay off at a few hundred events, so values in the hundreds suit most long-running workflows. Very low values mostly add snapshot saves to runs that replay quickly anyway.
+- Snapshots are an optimization, not a source of truth: the event log remains authoritative, and a missing, corrupt, oversized, or incompatible snapshot automatically falls back to a full replay. Snapshots over 32 MB uncompressed are not saved.
+- Like `WORKFLOW_VM`, the policy is stamped into the run's `executionContext` at start, so a run keeps the snapshot policy it started with. `start()` rejects an invalid value. An invalid value on the workflow handler disables snapshotting with a warning.
+- A snapshot can only be restored by the exact QuickJS engine build that captured it. On Vercel, runs keep executing on the deployment they started on, so deploys don't affect in-flight snapshots. If your deployment serves in-flight runs from new code (for example, a self-hosted rolling update), an upgrade that changes the embedded engine makes every in-flight run fall back to a full replay at its next resume, all at once, before re-snapshotting at its next qualifying suspension. Plan for that one-time replay load when upgrading.
+
+What a snapshot contains, and how it is protected:
+
+- A snapshot is the workflow VM's memory: the workflow's code and in-memory state, including step results and hook payloads it holds, and the copy of `process.env` the VM exposes. It is executable state, so write access to snapshot storage is equivalent to running code in the workflow VM.
+- Snapshots are compressed and then encrypted with the run's encryption key. The encryption also authenticates the snapshot: on restore, the runtime rejects any snapshot that isn't encrypted with the run's key, or whose stored metadata doesn't match the metadata sealed inside it.
+- By default, runs without an encryption key are never snapshotted. Only world-vercel provides run encryption keys. On world-local and world-postgres, set `WORKFLOW_SNAPSHOT_ALLOW_UNENCRYPTED=1` on the workflow handler to snapshot anyway. Those snapshots are stored in plaintext (in `.workflow-data/snapshots/` or the `workflow_snapshots` table) and are not authenticated, so only enable this where snapshot storage is as trusted as your deployment.
+- A restored run sees `process.env` as of the current invocation, the same as a full replay.
+- Snapshots are deleted after the run reaches a terminal state. world-local and world-postgres have no separate retention for them, so a snapshot of a run that ends without any invocation observing it (for example, one cancelled externally) stays until you remove it.
+
+### `WORKFLOW_SNAPSHOT_ALLOW_UNENCRYPTED`
+
+- Default: disabled
+- Set `1` or `true` on the workflow handler to let the QuickJS engine persist VM snapshots for runs without an encryption key. See [`WORKFLOW_SNAPSHOT_THRESHOLD`](#workflow_snapshot_threshold) for what that stores.
+
 ## Dynamic workflows
 
 ### `WORKFLOW_EXPERIMENTAL_DYNAMIC_WORKFLOWS`
@@ -259,6 +284,7 @@ For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPL
 - Default: automatic
 - Forces the write-side codec to `zstd` or `gzip`.
 - Invalid values are ignored. Automatic mode prefers `zstd` when the current Node.js runtime supports it, otherwise it falls back to `gzip`.
+- Writes for a run on another deployment (for example `resumeHook()` reaching a run that started before the project moved to a newer Node.js version) use `zstd` only when that run's deployment runs Node.js 22.15+ (or 23.8+), and `gzip` otherwise, since older Node.js versions cannot decode `zstd`. Runs created before `@workflow/core` recorded the Node.js version always receive `gzip`. Setting this to `zstd` does not override that check.
 
 ### `WORKFLOW_TRACE_MODE`
 
@@ -290,7 +316,7 @@ For example, a workflow can run a 10-minute inline step even with `WORKFLOW_REPL
 
 Node's own modules do less than the client they replace, so enabling this drops the per-call-site tuning the Worlds configure:
 
-- Event-log requests lose HTTP/2, so concurrent reads and writes no longer share one connection, and the enlarged HTTP/2 receive windows no longer apply. This is the largest difference, and it slows down replays that read a big event log. It does not apply to event writes on the opt-in [WebSocket events transport](/docs/configuration/worlds#workflow_events_transport), which takes neither transport.
+- Event-log requests lose HTTP/2, so concurrent reads and writes no longer share one connection, and the enlarged HTTP/2 receive windows no longer apply. This is the largest difference, and it slows down replays that read a big event log. It does not apply to event writes on the [WebSocket events transport](/docs/configuration/worlds#workflow_events_transport), which is the default and takes neither transport.
 - Requests lose their transport-level retry. Failures still surface to the layers above, which retry event writes and redeliver queue messages, so nothing is silently dropped, but a failure that a same-connection retry would have hidden now costs a full redelivery.
 - Stream close loses its retry of retriable server errors. A transient failure at close can leave a stream marked closing until the run expires, where it would previously have resolved on the retry.