workflow 5.0.0-beta.34 → 5.0.0-beta.36

package/docs/getting-started/react-router/v7.mdx

@@ -0,0 +1,237 @@
+---
+title: React Router v7
+description: Add durable workflows to a React Router v7 framework-mode app using Nitro v3.
+type: guide
+summary: Enable the Vite Environment API and configure React Router v7, Nitro v3, and Workflow SDK.
+prerequisites:
+  - /docs/getting-started/react-router
+related:
+  - /docs/getting-started/nitro
+  - /docs/foundations/workflows-and-steps
+---
+
+This guide starts with an existing React Router v7 framework-mode app. It is verified with v7.18.1; if your config does not recognize `v8_viteEnvironmentApi`, update to the latest v7 release.
+
+<Steps>
+
+<Step>
+
+## Install Nitro and Workflow SDK
+
+<Tabs items={["npm", "pnpm", "bun", "yarn"]} defaultValue="pnpm">
+
+<Tab value="npm">
+
+```bash
+npm install nitro workflow
+```
+
+</Tab>
+
+<Tab value="pnpm">
+
+```bash
+pnpm add nitro workflow
+```
+
+</Tab>
+
+<Tab value="bun">
+
+```bash
+bun add nitro workflow
+```
+
+</Tab>
+
+<Tab value="yarn">
+
+```bash
+yarn add nitro workflow
+```
+
+</Tab>
+
+</Tabs>
+
+This integration requires Nitro v3.
+
+</Step>
+
+<Step>
+
+## Enable the Vite Environment API
+
+React Router v7 keeps the Vite Environment API behind a future flag. Enable the required flag and set an explicit build directory:
+
+```typescript title="react-router.config.ts" lineNumbers
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  ssr: true,
+  buildDirectory: "build", // [!code highlight]
+  future: {
+    v8_viteEnvironmentApi: true, // [!code highlight]
+  },
+} satisfies Config;
+```
+
+</Step>
+
+<Step>
+
+## Create the React Router server handler
+
+Create `server/ssr.ts`:
+
+```typescript title="server/ssr.ts" lineNumbers
+import { createRequestHandler } from "react-router";
+
+export default {
+  fetch: createRequestHandler(
+    () => import("virtual:react-router/server-build"),
+    import.meta.env.MODE,
+  ),
+};
+```
+
+This adapts React Router's generated server build to the Fetch API handler Nitro expects.
+
+</Step>
+
+<Step>
+
+## Configure Vite
+
+Update `vite.config.ts`:
+
+```typescript title="vite.config.ts" lineNumbers
+import { reactRouter } from "@react-router/dev/vite";
+import { nitro } from "nitro/vite";
+import { defineConfig } from "vite";
+import { workflow } from "workflow/vite";
+import reactRouterConfig from "./react-router.config";
+
+export default defineConfig({
+  plugins: [
+    reactRouter(),
+    nitro({
+      serverDir: "./server",
+      output: {
+        dir: reactRouterConfig.buildDirectory,
+        serverDir: `${reactRouterConfig.buildDirectory}/server`,
+        publicDir: `${reactRouterConfig.buildDirectory}/client`,
+      },
+    }),
+    workflow({ dirs: ["workflows"] }),
+  ],
+  environments: {
+    ssr: {
+      build: {
+        rollupOptions: {
+          input: "./server/ssr.ts",
+        },
+      },
+    },
+  },
+});
+```
+
+Keep `dirs: ["workflows"]` so subsequent builds do not scan generated files under `build`. Place `reactRouter()` before `nitro()` in the plugin array.
+
+</Step>
+
+<Step>
+
+## Create a workflow
+
+Create `workflows/greeting.ts`:
+
+```typescript title="workflows/greeting.ts" lineNumbers
+export async function greetingWorkflow(name: string) {
+  "use workflow";
+
+  return greet(name);
+}
+
+async function greet(name: string) {
+  "use step";
+
+  return `Hello, ${name}!`;
+}
+```
+
+</Step>
+
+<Step>
+
+## Start the workflow from a Nitro route
+
+Create `server/routes/api/greeting.post.ts`:
+
+```typescript title="server/routes/api/greeting.post.ts" lineNumbers
+import { defineHandler } from "nitro";
+import { start } from "workflow/api";
+import { greetingWorkflow } from "../../../workflows/greeting";
+
+export default defineHandler(async (event) => {
+  const { name } = (await event.req.json()) as { name: string };
+  const run = await start(greetingWorkflow, [name]);
+
+  return { runId: run.runId };
+});
+```
+
+React Router continues to handle your application routes. Nitro handles this server route at `POST /api/greeting`, as well as Workflow SDK's internal routes.
+
+</Step>
+
+<Step>
+
+## Run the app
+
+Start the development server:
+
+```bash
+pnpm vite dev
+```
+
+Then start a workflow:
+
+```bash
+curl -X POST \
+  -H "content-type: application/json" \
+  -d '{"name":"Workflow"}' \
+  http://localhost:3000/api/greeting
+```
+
+Build and start the production server:
+
+```bash
+pnpm vite build
+node ./build/server/index.mjs
+```
+
+You can inspect local runs with `pnpm workflow web`.
+
+</Step>
+
+</Steps>
+
+## Troubleshooting
+
+### Vite reports an invalid SSR input or `path.replace is not a function`
+
+Set `future.v8_viteEnvironmentApi` to `true` in `react-router.config.ts`.
+
+### React Router pages return 404
+
+Check that the `ssr` environment input points to `./server/ssr.ts`.
+
+### A second build tries to compile files under `build/server`
+
+Use `workflow({ dirs: ["workflows"] })`, remove the existing `build` directory once, and rebuild.
+
+### `vite build` finishes output but does not exit
+
+Use `workflow@5.0.0-beta.33` or later with Nitro v3.

package/docs/getting-started/react-router/v8.mdx

@@ -0,0 +1,232 @@
+---
+title: React Router v8
+description: Add durable workflows to a React Router v8 framework-mode app using Nitro v3.
+type: guide
+summary: Configure React Router v8, Nitro v3, and Workflow SDK in one Vite build.
+prerequisites:
+  - /docs/getting-started/react-router
+related:
+  - /docs/getting-started/nitro
+  - /docs/foundations/workflows-and-steps
+---
+
+This guide starts with an existing React Router v8 framework-mode app.
+
+<Steps>
+
+<Step>
+
+## Install Nitro and Workflow SDK
+
+<Tabs items={["npm", "pnpm", "bun", "yarn"]} defaultValue="pnpm">
+
+<Tab value="npm">
+
+```bash
+npm install nitro workflow
+```
+
+</Tab>
+
+<Tab value="pnpm">
+
+```bash
+pnpm add nitro workflow
+```
+
+</Tab>
+
+<Tab value="bun">
+
+```bash
+bun add nitro workflow
+```
+
+</Tab>
+
+<Tab value="yarn">
+
+```bash
+yarn add nitro workflow
+```
+
+</Tab>
+
+</Tabs>
+
+This integration requires Nitro v3.
+
+</Step>
+
+<Step>
+
+## Use a shared build directory
+
+Set an explicit build directory in your React Router config:
+
+```typescript title="react-router.config.ts" lineNumbers
+import type { Config } from "@react-router/dev/config";
+
+export default {
+  ssr: true,
+  buildDirectory: "build", // [!code highlight]
+} satisfies Config;
+```
+
+React Router will place browser assets in `build/client`. Nitro will place the runnable server in `build/server`.
+
+</Step>
+
+<Step>
+
+## Create the React Router server handler
+
+Create `server/ssr.ts`:
+
+```typescript title="server/ssr.ts" lineNumbers
+import { createRequestHandler } from "react-router";
+
+export default {
+  fetch: createRequestHandler(
+    () => import("virtual:react-router/server-build"),
+    import.meta.env.MODE,
+  ),
+};
+```
+
+This adapts React Router's generated server build to the Fetch API handler Nitro expects.
+
+</Step>
+
+<Step>
+
+## Configure Vite
+
+Update `vite.config.ts`:
+
+```typescript title="vite.config.ts" lineNumbers
+import { reactRouter } from "@react-router/dev/vite";
+import { nitro } from "nitro/vite";
+import { defineConfig } from "vite";
+import { workflow } from "workflow/vite";
+import reactRouterConfig from "./react-router.config";
+
+export default defineConfig({
+  plugins: [
+    reactRouter(),
+    nitro({
+      serverDir: "./server",
+      output: {
+        dir: reactRouterConfig.buildDirectory,
+        serverDir: `${reactRouterConfig.buildDirectory}/server`,
+        publicDir: `${reactRouterConfig.buildDirectory}/client`,
+      },
+    }),
+    workflow({ dirs: ["workflows"] }),
+  ],
+  environments: {
+    ssr: {
+      build: {
+        rollupOptions: {
+          input: "./server/ssr.ts",
+        },
+      },
+    },
+  },
+});
+```
+
+Keep `dirs: ["workflows"]` so subsequent builds do not scan generated files under `build`. Place `reactRouter()` before `nitro()` in the plugin array.
+
+</Step>
+
+<Step>
+
+## Create a workflow
+
+Create `workflows/greeting.ts`:
+
+```typescript title="workflows/greeting.ts" lineNumbers
+export async function greetingWorkflow(name: string) {
+  "use workflow";
+
+  return greet(name);
+}
+
+async function greet(name: string) {
+  "use step";
+
+  return `Hello, ${name}!`;
+}
+```
+
+</Step>
+
+<Step>
+
+## Start the workflow from a Nitro route
+
+Create `server/routes/api/greeting.post.ts`:
+
+```typescript title="server/routes/api/greeting.post.ts" lineNumbers
+import { defineHandler } from "nitro";
+import { start } from "workflow/api";
+import { greetingWorkflow } from "../../../workflows/greeting";
+
+export default defineHandler(async (event) => {
+  const { name } = (await event.req.json()) as { name: string };
+  const run = await start(greetingWorkflow, [name]);
+
+  return { runId: run.runId };
+});
+```
+
+React Router continues to handle your application routes. Nitro handles this server route at `POST /api/greeting`, as well as Workflow SDK's internal routes.
+
+</Step>
+
+<Step>
+
+## Run the app
+
+Start the development server:
+
+```bash
+pnpm vite dev
+```
+
+Then start a workflow:
+
+```bash
+curl -X POST \
+  -H "content-type: application/json" \
+  -d '{"name":"Workflow"}' \
+  http://localhost:3000/api/greeting
+```
+
+Build and start the production server:
+
+```bash
+pnpm vite build
+node ./build/server/index.mjs
+```
+
+You can inspect local runs with `pnpm workflow web`.
+
+</Step>
+
+</Steps>
+
+## Troubleshooting
+
+### React Router pages return 404
+
+Check that the `ssr` environment input points to `./server/ssr.ts`.
+
+### A second build tries to compile files under `build/server`
+
+Use `workflow({ dirs: ["workflows"] })`, remove the existing `build` directory once, and rebuild.
+
+### `vite build` finishes output but does not exit
+
+Use `workflow@5.0.0-beta.33` or later with Nitro v3.

package/docs/getting-started/sveltekit.mdx

@@ -245,7 +245,7 @@ Check the [Deploying](/docs/deploying) section to learn how your workflows can b
 If you see this error:
 
 ```
-'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+'start' received an invalid workflow function. Ensure the Workflow SDK is configured correctly and the function includes a 'use workflow' directive.
 ```
 
 Check both of these first:

package/docs/getting-started/vite.mdx

@@ -245,7 +245,7 @@ Check the [Deploying](/docs/deploying) section to learn how your workflows can b
 If you see this error:
 
 ```
-'start' received an invalid workflow function. Ensure the Workflow Development Kit is configured correctly and the function includes a 'use workflow' directive.
+'start' received an invalid workflow function. Ensure the Workflow SDK is configured correctly and the function includes a 'use workflow' directive.
 ```
 
 Check both of these first:

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

@@ -7,7 +7,7 @@ prerequisites:
   - /docs/how-it-works/event-sourcing
 related:
   - /docs/observability
-  - /docs/deploying/world/vercel-world
+  - /worlds/vercel
 ---
 
 <Callout>
@@ -38,7 +38,7 @@ Metadata such as workflow names, step names, entity IDs, timestamps, and lifecyc
 
 Each workflow run is encrypted with its own unique key, provided by the `World` implementation via `getEncryptionKeyForRun()`. How the key is generated and stored is up to the `World`.
 
-For example, the [Vercel World](/docs/deploying/world/vercel-world) provides unique keys per run and execution environment, ensuring that a given run can only decrypt data from that run itself.
+For example, the [Vercel World](/worlds/vercel) provides unique keys per run and execution environment, ensuring that a given run can only decrypt data from that run itself.
 
 ### Encryption Algorithm
 
@@ -127,4 +127,4 @@ async function lookupRunKey(
 }
 ```
 
-The [Vercel World](/docs/deploying/world/vercel-world) implementation uses HKDF derivation from a deployment-scoped key, but any consistent key management scheme will work.
+The [Vercel World](/worlds/vercel) implementation uses HKDF derivation from a deployment-scoped key, but any consistent key management scheme will work.

package/docs/how-it-works/event-sourcing.mdx

@@ -121,15 +121,15 @@ flowchart TD
 
 **Hook states:**
 
-- `active`: Ready to receive payloads (hook exists in storage)
-- `disposed`: No longer accepting payloads (hook is deleted from storage)
+- `active`: Ready to receive payloads
+- `disposed`: No longer accepting payloads
 - `conflicted`: Hook creation failed because the token is already in use by another workflow
 
-Unlike other entities, hooks don't have a `status` field—the states above are conceptual. An "active" hook is one that exists in storage, while "disposed" means the hook has been deleted. When a `hook_disposed` event is created, the hook record is removed rather than updated.
+Unlike other entities, hooks don't have a `status` field—the states above are conceptual. When a `hook_disposed` event is created, the hook record is removed rather than updated.
 
-While a hook is active, its token is reserved and cannot be used by other workflows. If a workflow attempts to create a hook with a token that is already in use by another active hook, a `hook_conflict` event is recorded instead of `hook_created`. Current worlds include the token and the run ID that currently owns it, though older persisted events or world implementations may only include the token. This causes `hook.getConflict()` to resolve with the conflicting run and the hook's payload promise to reject with a `HookConflictError`, which you can detect with `HookConflictError.is(error)`. See the [hook-conflict error](/docs/errors/hook-conflict) documentation for more details.
+While a hook is active, its token is reserved and cannot be used by other workflows. If a workflow attempts to create a hook with a token reserved by another run — either by an active hook or by `experimental_minRetention` after its run ended — a `hook_conflict` event is recorded instead of `hook_created`. Current worlds include the token and the run ID that owns it, though older persisted events or world implementations may only include the token. This causes `hook.getConflict()` to resolve with the conflicting run and the hook's payload promise to reject with a `HookConflictError`, which you can detect with `HookConflictError.is(error)`. See the [hook-conflict error](/docs/errors/hook-conflict) documentation for more details.
 
-When a hook is disposed (either explicitly or when its workflow completes), the token is released and can be claimed by future workflows. Hooks are automatically disposed when a workflow reaches a terminal state (`completed`, `failed`, or `cancelled`). The `hook_disposed` event is only needed for explicit disposal before workflow completion.
+When a workflow ends, its Hooks can no longer be resumed. They are normally removed and their tokens become available again. With `experimental_minRetention`, a Hook remains readable and its token remains unavailable until retention ends. A `hook_disposed` event removes the Hook and makes its token available immediately.
 
 See [Hooks & Webhooks](/docs/foundations/hooks) for more on how hooks and webhooks work.
 
@@ -188,7 +188,7 @@ Events are categorized by the entity type they affect. Each event contains metad
 | Event | Description |
 |-------|-------------|
 | `hook_created` | Creates a new hook in `active` state. Contains the hook token and optional metadata. |
-| `hook_conflict` | Records that hook creation failed because the token is already in use by another active hook. Contains the token and, for current worlds, the active hook owner's run ID. The hook is not created: `hook.getConflict()` resolves with the conflicting run, and awaiting the hook payload rejects with a `HookConflictError`. |
+| `hook_conflict` | Records that hook creation failed because another run owns the token. Contains the token and, for current worlds, the owner's run ID. The hook is not created: `hook.getConflict()` resolves with the conflicting run, and awaiting the hook payload rejects with a `HookConflictError`. |
 | `hook_received` | Records that a payload was delivered to the hook. The hook remains `active` and can receive more payloads. |
 | `hook_disposed` | Deletes the hook from storage (conceptually transitioning to `disposed` state). The token is released for reuse by future workflows. |
 

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

@@ -6,7 +6,7 @@ summary: Build a custom framework integration using the Workflow SDK compiler an
 prerequisites:
   - /docs/foundations/workflows-and-steps
 related:
-  - /docs/deploying/building-a-world
+  - /worlds/building-a-world
 ---
 
 <Callout>
@@ -414,7 +414,7 @@ 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`, or `WORKFLOW_SAFE_MODE=1` when the specific variable is unset — 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 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.
 
 
 ### Custom implementations
@@ -425,7 +425,7 @@ For self-hosted or non-Vercel deployments, you are responsible for securing the
 - **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](/docs/deploying/building-a-world).
+Learn more about [building custom Worlds](/worlds/building-a-world).
 
 ## Testing Your Integration
 

package/docs/meta.json

@@ -9,7 +9,7 @@
     "testing",
     "deploying",
     "errors",
-    "migration-guides",
+    "comparisons",
     "configuration",
     "api-reference"
   ]

package/docs/observability/attributes.mdx

@@ -57,6 +57,15 @@ export async function cleanupAttributes() {
 
 Attribute keys must be 1-256 characters, values must be strings up to 256 bytes, and each run can have up to 64 attributes. Keys that start with `$` are reserved for framework and library code.
 
+## Reserved keys
+
+When `start()` is called from inside a running workflow or step, the new run is automatically tagged with two reserved attributes:
+
+- `$parentRunId`: the run that started it.
+- `$rootRunId`: the root of the chain. It is inherited, so every run in a daisy chain or fan-out shares one root id.
+
+Top-level runs (started outside any workflow or step) are not tagged.
+
 ## Viewing attributes
 
 The run details panel in the observability UI shows the run's current attributes as key-value rows. Reserved `$`-prefixed keys are marked with a badge and sorted after user keys:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.34",
+  "version": "5.0.0-beta.36",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -49,6 +49,8 @@
     "./astro": "./dist/astro.js",
     "./vite": "./dist/vite.js",
     "./nest": "./dist/nest.js",
+    "./nest/builder": "./dist/nest-builder.js",
+    "./nest/vercel-builder": "./dist/nest-vercel-builder.js",
     "./runtime": "./dist/runtime.js",
     "./observability": {
       "types": "./dist/observability.d.ts",
@@ -57,18 +59,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "5.0.0-beta.34",
-    "@workflow/cli": "5.0.0-beta.34",
-    "@workflow/core": "5.0.0-beta.34",
-    "@workflow/errors": "5.0.0-beta.10",
+    "@workflow/astro": "5.0.0-beta.36",
+    "@workflow/cli": "5.0.0-beta.36",
+    "@workflow/core": "5.0.0-beta.36",
     "@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.34",
-    "@workflow/nest": "5.0.0-beta.34",
-    "@workflow/nitro": "5.0.0-beta.34",
-    "@workflow/nuxt": "5.0.0-beta.34",
-    "@workflow/sveltekit": "5.0.0-beta.34",
-    "@workflow/rollup": "5.0.0-beta.34"
+    "@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"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",