workflow 4.2.0-beta.76 → 4.2.0-beta.77

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

@@ -82,12 +82,49 @@ Without `--decrypt`, encrypted fields display as `🔒 Encrypted` placeholders.
 
 ## Custom World Implementations
 
-The core runtime encrypts data automatically when the `World` implementation provides a `getEncryptionKeyForRun()` method. This method receives the run ID and returns the raw encryption key bytes.
+The core runtime encrypts data automatically when the `World` implementation provides a `getEncryptionKeyForRun()` method. The core runtime can call this method in two forms:
+
+{/* @skip-typecheck - interface signature, not runnable code */}
+```typescript
+getEncryptionKeyForRun?(run: WorkflowRun): Promise<Uint8Array | undefined>;
+getEncryptionKeyForRun?(
+  runId: string,
+  context?: Record<string, unknown>
+): Promise<Uint8Array | undefined>;
+```
+
+Use `getEncryptionKeyForRun(run)` when the run entity already exists. Use `getEncryptionKeyForRun(runId, context?)` in runtime paths like `start()` where the run has not been created yet but the world may still need context such as `deploymentId`.
 
 To add encryption support to a custom `World`:
 
-1. Implement `getEncryptionKeyForRun(runId: string)` on your `World` class
+1. Implement `getEncryptionKeyForRun()` on your `World` class, handling both call shapes
 2. Return the raw 32-byte key as a `Uint8Array` — the core runtime uses it for AES-256-GCM operations
 3. Ensure the same key is returned for the same run ID across invocations (for decryption during replay)
 
+```typescript
+import type { WorkflowRun, World } from "@workflow/world";
+
+export const getEncryptionKeyForRun: World["getEncryptionKeyForRun"] = async (
+  run,
+  context
+) => {
+  const runId = typeof run === "string" ? run : run.runId;
+  const deploymentId =
+    typeof run === "string"
+      ? (context?.deploymentId as string | undefined)
+      : run.deploymentId;
+
+  return await lookupRunKey(runId, deploymentId);
+};
+
+async function lookupRunKey(
+  runId: string,
+  deploymentId?: string
+): Promise<Uint8Array | undefined> {
+  // Look up or derive the encryption key for this run
+  // Return undefined to skip encryption
+  return new Uint8Array(32);
+}
+```
+
 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.

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

@@ -127,7 +127,7 @@ flowchart TD
 
 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.
 
-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`. This causes the hook's promise to reject with a `WorkflowRuntimeError`, failing the workflow gracefully. 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 that is already in use by another active hook, a `hook_conflict` event is recorded instead of `hook_created`. This causes the hook's 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.
 
@@ -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. The hook is not created, and the workflow will fail with a `WorkflowRuntimeError` when the hook is awaited. |
+| `hook_conflict` | Records that hook creation failed because the token is already in use by another active hook. The hook is not created, and awaiting the hook will reject 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. |
 
@@ -241,6 +241,23 @@ This correlation enables:
 - Building timelines of entity lifecycle transitions
 - Debugging by tracing the complete history of any entity
 
+### Request ID Correlation
+
+Some `World` implementations also attach a `requestId` to events for platform-log correlation. This is different from `correlationId`:
+
+- `correlationId` links together events for the same entity lifecycle
+- `requestId` tells you which inbound platform request created or updated the event
+
+On Vercel, `requestId` is the platform request ID when available. Other worlds are not expected to provide a `requestId`.
+
+```json
+{
+  "eventType": "step_started",
+  "correlationId": "step_01JQEXAMPLE1234567890",
+  "requestId": "iad1::abc123-1712345678901-xyz987"
+}
+```
+
 ## Entity IDs
 
 All entities in the Workflow SDK use a consistent ID format: a 4-character prefix followed by an underscore and a [ULID](https://github.com/ulid/spec) (Universally Unique Lexicographically Sortable Identifier).

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

@@ -261,6 +261,35 @@ class MyFrameworkBuilder extends BaseBuilder {
 
 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";
+
+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 */}
@@ -346,22 +375,50 @@ In the future, the Workflow SDK will emit more routes under the `.well-known/wor
 
 ## Security
 
-**How are these HTTP endpoints secured?**
+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)"
+{
+  "experimentalTriggers": [
+    {
+      "type": "queue/v2beta",
+      "topic": "__wkf_step_*",
+      "consumer": "default",
+      "retryAfterSeconds": 5,
+      "initialDelaySeconds": 0
+    }
+  ]
+}
+```
+
+
+Two queue topics are created per deployment:
 
-Security is handled by the **world abstraction** you're using:
+| 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. The `STEP_QUEUE_TRIGGER` and `WORKFLOW_QUEUE_TRIGGER` constants are exported from `@workflow/builders` for this purpose:
+
+```typescript
+import { STEP_QUEUE_TRIGGER, WORKFLOW_QUEUE_TRIGGER } from "@workflow/builders";
+```
 
-**Vercel (`@workflow/world-vercel`):**
 
-- Vercel Queue will support private invoke, making routes inaccessible from the public internet
-- Handlers receive only a message ID that must be retrieved from Vercel's backend
-- Impossible to craft custom payloads without valid queue-issued message IDs
+### Custom implementations
 
-**Custom implementations:**
+For self-hosted or non-Vercel deployments, you are responsible for securing the handler endpoints:
 
-- Implement authentication via framework middleware
-- Use API keys, JWT validation, or other auth schemes
-- Network-level security (VPCs, private networks, firewall rules)
-- Rate limiting and request validation
+- **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](/docs/deploying/building-a-world).
 

package/docs/observability/index.mdx

@@ -18,7 +18,7 @@ Workflow SDK provides powerful tools to inspect, monitor, and debug your workflo
 npx workflow
 ```
 
-The CLI comes pre-installed with the Workflow SDK and registers the `workflow` command. If the `workflow` package is not already installed, `npx workflow` will install it globally, or use the local installed version if available.
+The CLI comes pre-installed with the Workflow SDK and registers the `workflow` command. If the `workflow` package is not already installed, `npx workflow` will download and run the CLI temporarily, or use the local installed version if available.
 
 Get started inspecting your local workflows:
 

package/docs/testing/index.mdx

@@ -371,7 +371,7 @@ Or use the CLI to inspect runs in the terminal:
 npx workflow inspect runs
 
 # Inspect a specific run
-npx workflow inspect runs <run-id>
+npx workflow inspect run <run-id>
 ```
 
 The Web UI shows each step, its inputs and outputs, retry attempts, hook state, and timing. This is especially useful for diagnosing issues with hooks that were not resumed, steps that failed unexpectedly, or workflows that timed out.

package/docs/testing/server-based.mdx

@@ -48,8 +48,24 @@ import type { ChildProcess } from "node:child_process";
 let server: ChildProcess | null = null;
 const PORT = "4000";
 
+function emitSetupLog(event: string, fields: Record<string, unknown> = {}) {
+  console.log(
+    JSON.stringify({
+      scope: "workflow-server-test",
+      event,
+      port: PORT,
+      ...fields,
+    })
+  );
+}
+
 export async function setup() { // [!code highlight]
-  console.log("Starting server for workflow execution...");
+  const stdout: string[] = [];
+  const stderr: string[] = [];
+
+  emitSetupLog("server_starting", {
+    command: `npx nitro dev --port ${PORT}`,
+  });
 
   server = spawn("npx", ["nitro", "dev", "--port", PORT], {
     stdio: "pipe",
@@ -57,13 +73,14 @@ export async function setup() { // [!code highlight]
     env: process.env,
   });
 
-  // Wait for the server to be ready
   const ready = await new Promise<boolean>((resolve) => {
     const timeout = setTimeout(() => resolve(false), 15_000);
 
     server?.stdout?.on("data", (data) => {
       const output = data.toString();
-      console.log("[server]", output);
+      stdout.push(output);
+      emitSetupLog("server_stdout", { message: output.trim() });
+
       if (output.includes("listening") || output.includes("ready")) {
         clearTimeout(timeout);
         resolve(true);
@@ -71,40 +88,66 @@ export async function setup() { // [!code highlight]
     });
 
     server?.stderr?.on("data", (data) => {
-      console.error("[server]", data.toString());
+      const output = data.toString();
+      stderr.push(output);
+      emitSetupLog("server_stderr", { message: output.trim() });
     });
 
     server?.on("error", (error) => {
-      console.error("Failed to start server:", error);
+      emitSetupLog("server_process_error", {
+        name: error.name,
+        message: error.message,
+      });
       clearTimeout(timeout);
       resolve(false);
     });
+
+    server?.on("exit", (code, signal) => {
+      emitSetupLog("server_exit", { code, signal });
+    });
   });
 
   if (!ready) {
-    throw new Error("Server failed to start within 15 seconds");
+    const recentStdout = stdout.join("").trim().slice(-2000);
+    const recentStderr = stderr.join("").trim().slice(-2000);
+
+    throw new Error(
+      [
+        "Server failed to start within 15 seconds.",
+        `Command: npx nitro dev --port ${PORT}`,
+        `WORKFLOW_LOCAL_BASE_URL: http://localhost:${PORT}`,
+        `Recent stdout:\n${recentStdout || "(empty)"}`,
+        `Recent stderr:\n${recentStderr || "(empty)"}`,
+      ].join("\n\n")
+    );
   }
 
-  await delay(2_000); // Allow full initialization
+  await delay(2_000);
 
-  // Point the workflow runtime at the local server
   process.env.WORKFLOW_LOCAL_BASE_URL = `http://localhost:${PORT}`; // [!code highlight]
 
-  console.log("Server ready for workflow execution");
+  emitSetupLog("server_ready", {
+    baseUrl: process.env.WORKFLOW_LOCAL_BASE_URL,
+  });
 }
 
 export async function teardown() { // [!code highlight]
-  if (server) {
-    console.log("Stopping server...");
-    server.kill("SIGTERM");
-    await delay(1_000);
-    if (!server.killed) {
-      server.kill("SIGKILL");
-    }
+  if (!server) return;
+
+  emitSetupLog("server_stopping");
+
+  server.kill("SIGTERM");
+  await delay(1_000);
+
+  if (!server.killed) {
+    emitSetupLog("server_force_kill");
+    server.kill("SIGKILL");
   }
 }
 ```
 
+These JSON log lines are intentional. They give CI jobs, local tooling, and agents stable events to watch for (`server_starting`, `server_stdout`, `server_stderr`, `server_ready`, `server_exit`), and the thrown timeout error includes the command, expected `WORKFLOW_LOCAL_BASE_URL`, and buffered stdout/stderr so a failed setup is actionable without interactive debugging.
+
 The setup script sets `WORKFLOW_LOCAL_BASE_URL` so the workflow runtime sends step execution requests to the running server.
 
 <Callout type="info">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "4.2.0-beta.76",
+  "version": "4.2.0-beta.77",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -57,18 +57,18 @@
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "4.0.0-beta.50",
-    "@workflow/cli": "4.2.0-beta.76",
-    "@workflow/core": "4.2.0-beta.76",
+    "@workflow/astro": "4.0.0-beta.51",
+    "@workflow/cli": "4.2.0-beta.77",
+    "@workflow/core": "4.2.0-beta.77",
     "@workflow/errors": "4.1.0-beta.20",
     "@workflow/typescript-plugin": "4.0.1-beta.5",
     "@workflow/utils": "4.1.0-beta.13",
-    "@workflow/next": "4.0.1-beta.72",
-    "@workflow/nest": "0.0.0-beta.25",
-    "@workflow/nitro": "4.0.1-beta.71",
-    "@workflow/nuxt": "4.0.1-beta.60",
-    "@workflow/sveltekit": "4.0.0-beta.65",
-    "@workflow/rollup": "4.0.0-beta.33"
+    "@workflow/next": "4.0.1-beta.73",
+    "@workflow/nest": "0.0.0-beta.26",
+    "@workflow/nitro": "4.0.1-beta.72",
+    "@workflow/nuxt": "4.0.1-beta.61",
+    "@workflow/sveltekit": "4.0.0-beta.66",
+    "@workflow/rollup": "4.0.0-beta.34"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",