@workflow/core 5.0.0-beta.43 → 5.0.0-beta.44

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

@@ -1,5 +1,5 @@
 ---
-title: How the Directives Work
+title: How the directives work
 description: Deep dive into the internals of how Workflow SDK directives transform your code.
 type: conceptual
 summary: Learn how the compiler transforms directive-annotated code into three execution modes.
@@ -10,16 +10,15 @@ related:
 ---
 
 <Callout>
-This is an advanced guide that dives into internals of the Workflow SDK directive and is not required reading to use workflows. To simply use the Workflow SDK, check out the [getting started](/docs/getting-started) guides for your framework.
+This advanced guide covers the internals of Workflow SDK directives. To start using Workflow SDK, see the [getting started](/docs/getting-started) guide for your framework.
 </Callout>
 
-Workflows use special directives to mark code for transformation by the Workflow SDK compiler. This page explains how `"use workflow"` and `"use step"` directives work, what transformations are applied, and why they're necessary for durable execution.
+Workflows use special directives to mark code for transformation by the Workflow SDK compiler. The `"use workflow"` and `"use step"` directives apply the transformations required for durable execution.
 
-## Directives Overview
+## Directives overview
 
 Workflows use two directives to mark functions for special handling:
 
-{/* @skip-typecheck: incomplete code sample */}
 ```typescript
 export async function handleUserSignup(email: string) {
   "use workflow"; // [!code highlight]
@@ -44,7 +43,7 @@ async function createUser(email: string) {
 
 These directives trigger the `@workflow/swc-plugin` compiler to transform your code in different ways depending on the execution context.
 
-## The Three Transformation Modes
+## The three transformation modes
 
 The compiler operates in three distinct modes, transforming the same source code differently for each execution context:
 
@@ -52,39 +51,47 @@ The compiler operates in three distinct modes, transforming the same source code
 flowchart LR
     A["Source Code<br/>with directives"] --> B["Step Mode"]
     A --> C["Workflow Mode"]
-    A --> D["Client Mode"]
+    A --> D["Detect Mode"]
     B --> E["Step registration bundle"]
+    B --> G["Your App Code<br/>(Enables `start`)"]
     C --> F["Workflow bundle"]
     E --> H["Combined flow handler"]
     F --> H
-    D --> G["Your App Code<br/>(Enables `start`)"]
+    D --> I["Build manifest<br/>(discovery)"]
 ```
 
-### Comparison Table
+### Comparison table
 
 | Mode     | Used In    | Purpose                        | Runtime role | Required? |
 |----------|------------|--------------------------------|--------------|-----------|
-| Step     | Build time | Registers executable step functions | Imported by the combined flow handler | Yes |
+| Step     | Build time + your app code | Registers executable step functions; gives app code workflow IDs for `start()` | Imported by the combined flow handler, and applied to application code by the framework loader | 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* |
+| Detect   | Build time | Discovers workflows, steps, and serialization classes without transforming code | Feeds the build's discovery phase and manifest | Yes (build-internal) |
 
-\* 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.
+<Callout type="info">
+  Earlier releases had a separate **client mode** for application code. In 5.0 it merged into step mode, which produces the same app-code behavior (workflow functions throw on direct calls and carry `workflowId` for `start()`) while also registering step functions. Build integrations that passed `mode: "client"` now pass `mode: "step"`.
+</Callout>
 
-## Detailed Transformation Examples
+## Detailed transformation examples
 
-<Tabs items={["Step Mode", "Workflow Mode", "Client Mode"]}>
+<Tabs items={["Step Mode", "Workflow Mode", "Detect Mode"]}>
 <Tab value="Step Mode">
 
-**Step Mode** creates a registration bundle that the combined flow handler imports. It is not an HTTP route.
+**Step Mode** creates the registration bundle that the combined flow handler imports (it is not an HTTP route), and is also the transform framework loaders apply to your application code.
 
 **Input:**
 
-{/* @skip-typecheck: incomplete code sample */}
 ```typescript
 export async function createUser(email: string) {
   "use step";
   return { id: crypto.randomUUID(), email };
 }
+
+export async function handleUserSignup(email: string) {
+  "use workflow";
+  const user = await createUser(email);
+  return { userId: user.id };
+}
 ```
 
 **Output:**
@@ -99,18 +106,25 @@ export async function createUser(email: string) {
     __wf_reg.set(__wf_id, __wf_fn); // [!code highlight]
     __wf_fn.stepId = __wf_id; // [!code highlight]
 })(createUser, "step//workflows/user.js//createUser"); // [!code highlight]
+
+export async function handleUserSignup(email: string) {
+  throw new Error("You attempted to execute ..."); // [!code highlight]
+}
+handleUserSignup.workflowId = "workflow//workflows/user.js//handleUserSignup"; // [!code highlight]
 ```
 
 **What happens:**
 
 - The `"use step"` directive is removed
-- The function body is kept completely intact (no transformation)
-- The function is registered with the runtime via an inline IIFE (no imports needed)
+- Step function bodies are kept completely intact (no transformation)
+- Each step function is registered with the runtime via an inline IIFE (no imports needed)
 - Step functions run with full Node.js/Deno/Bun access
+- Workflow function bodies are **replaced** with an error throw, and a `workflowId` property is attached. Launch workflow functions with [`start()`](/docs/api-reference/workflow-api/start) instead of calling them directly. The ID identifies the workflow to `start()`
+- A dead-code-elimination pass removes code reachable only from the replaced workflow bodies
 
-**Why no transformation?** Step functions execute in your main runtime with full access to Node.js APIs, file system, databases, etc. They don't need any special handling—they just run normally.
+**Why no step transformation?** Step functions execute in your main runtime with full access to Node.js APIs, the file system, databases, and other resources. They run normally without special handling.
 
-**ID Format:** Step IDs follow the pattern `step//{filepath}//{functionName}`, where the filepath is relative to your project root.
+**ID format:** Step IDs follow the pattern `step//{filepath}//{functionName}`, where the file path is relative to your project root.
 
 </Tab>
 <Tab value="Workflow Mode">
@@ -119,7 +133,6 @@ export async function createUser(email: string) {
 
 **Input:**
 
-{/* @skip-typecheck: incomplete code sample */}
 ```typescript
 export async function createUser(email: string) {
   "use step";
@@ -151,7 +164,7 @@ handleUserSignup.workflowId = "workflow//workflows/user.js//handleUserSignup"; /
 **What happens:**
 
 - Step function bodies are **replaced** with calls to `globalThis[Symbol.for("WORKFLOW_USE_STEP")]`
-- Workflow function bodies remain **intact**—they execute deterministically during replay
+- Workflow function bodies remain **intact**, so they execute deterministically during replay
 - The workflow function gets a `workflowId` property for runtime identification
 - The `"use workflow"` directive is removed
 
@@ -159,14 +172,14 @@ handleUserSignup.workflowId = "workflow//workflows/user.js//handleUserSignup"; /
 
 1. Checks if the step has already been executed (in the event log)
 2. If yes: Returns the cached result
-3. If no: Triggers a suspension and enqueues the step for background execution
+3. If no: Suspends the replay and executes the step, usually inline in the same invocation. The runtime returns the run to the queue only when the invocation's inline budget is exhausted or its timeout approaches
 
-**ID Format:** Workflow IDs follow the pattern `workflow//{filepath}//{functionName}`. The `workflowId` property is attached to the function to allow [`start()`](/docs/api-reference/workflow-api/start) to work at runtime.
+**ID format:** Workflow IDs follow the pattern `workflow//{filepath}//{functionName}`. The `workflowId` property is attached to the function so [`start()`](/docs/api-reference/workflow-api/start) works at runtime.
 
 </Tab>
-<Tab value="Client Mode">
+<Tab value="Detect Mode">
 
-**Client Mode** transforms workflow functions in your application code to prevent direct execution.
+**Detect Mode** is a lightweight, non-transforming mode used during the build's discovery phase.
 
 **Input:**
 
@@ -183,35 +196,30 @@ export async function handleUserSignup(email: string) {
 
 {/* @skip-typecheck: incomplete code sample */}
 ```typescript
+/**__internal_workflows{"workflows":{"user.js":{"handleUserSignup":{"workflowId":"workflow//workflows/user.js//handleUserSignup"}}}}*/; // [!code highlight]
 export async function handleUserSignup(email: string) {
-  throw new Error("You attempted to execute ..."); // [!code highlight]
+  "use workflow";
+  const user = await createUser(email);
+  return { userId: user.id };
 }
-handleUserSignup.workflowId = "workflow//workflows/user.js//handleUserSignup"; // [!code highlight]
 ```
 
 **What happens:**
 
-- Workflow function bodies are **replaced** with an error throw
-- The `workflowId` property is added (same as workflow mode)
-- Step functions are not transformed in client mode
-
-**Why this transformation?** Workflow functions cannot be called directly from application code—they must be started using [`start()`](/docs/api-reference/workflow-api/start). The error prevents accidental direct execution while the `workflowId` property allows the `start()` function to identify which workflow to launch.
+- The code is **not modified**. Detect mode only walks the AST
+- Discovered workflows, steps, and custom-serialization classes are emitted as a JSON manifest comment
+- The build uses this to decide which files feed the step and workflow bundles
 
-The IDs are generated exactly like in workflow mode to ensure they can be directly referenced at runtime.
+**Why a separate mode?** The build system first runs a fast regular expression pre-scan to find candidate files containing directive-like strings. It then runs detect mode on those candidates to validate them at the abstract syntax tree (AST) level. The plugin eliminates false positives, such as a directive-like string inside a template literal, because it only recognizes genuine directive statements.
 
 <Callout type="info">
-  **Client mode is optional:** While recommended for better developer experience (automatic IDs and type safety), you can skip client mode and instead:
-  - Manually construct workflow IDs using the pattern `workflow//{filepath}//{functionName}`
-  - Use the workflow manifest file generated during build to lookup IDs
-  - Pass IDs directly to `start()` as strings
-
-  All framework integrations include client mode as a loader by default.
+  **Working without the app-code loader:** Frameworks apply the step-mode transform to application code by default, which is what gives `start(handleUserSignup)` its automatic IDs and type safety. If your setup can't run the loader, you can instead construct workflow IDs manually using the pattern `workflow//{filepath}//{functionName}`, look them up in the build manifest, and pass them to `start()` as strings.
 </Callout>
 
 </Tab>
 </Tabs>
 
-## Generated Files
+## Generated files
 
 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.
 
@@ -224,7 +232,7 @@ Contains all workflow functions transformed in **workflow mode**. This file is i
 All workflow code is bundled together and embedded as a string inside `flow.js`. When a workflow needs to execute, this bundled code is run inside a **Node.js VM** (virtual machine) to ensure:
 
 - **Determinism**: The same inputs always produce the same outputs
-- **Side-effect prevention**: Direct access to Node.js APIs, file system, network, etc. is blocked
+- **Side-effect prevention**: Direct access to Node.js APIs, the file system, the network, and other resources is blocked
 - **Sandboxed execution**: Workflow orchestration logic is isolated from the main runtime
 
 **Build-time validation:**
@@ -259,6 +267,10 @@ Contains all step functions transformed in **step mode**. The combined flow hand
 
 This module must not be exposed as an HTTP endpoint.
 
+<Callout type="info">
+  **Changed in 5.0:** In 4.x, the step bundle was served as its own HTTP route at `POST /.well-known/workflow/v1/step`, with step messages delivered on a separate `__wkf_step_*` queue topic. v5 merged both into the combined flow handler. The step bundle became a registration module imported by `flow.js`, and step messages arrive on the shared workflow queue. Use the version picker to see the old layout on the v4 version of this page.
+</Callout>
+
 ### `webhook.js`
 
 Contains webhook handling logic for delivering external data to running workflows via [`createWebhook()`](/docs/api-reference/workflow/create-webhook).
@@ -269,24 +281,24 @@ Contains webhook handling logic for delivering external data to running workflow
 - Validates tokens and routes data to the correct workflow run
 - Resumes workflow execution after webhook delivery
 
-**Note:** 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` or `webhook.mjs` handler.
+The webhook file structure varies by framework. Next.js generates `webhook/[token]/route.js` to use App Router's dynamic routing, while other frameworks generate a single `webhook.js` or `webhook.mjs` handler.
 
-## Why Three Modes?
+## Why three modes?
 
 The multi-mode transformation enables the Workflow SDK's durable execution model:
 
-1. **Step Mode** (required) - Bundles executable step functions that can access the full runtime
-2. **Workflow Mode** (required) - Creates orchestration logic that can replay from event logs
-3. **Client Mode** (optional) - Prevents direct execution and enables type-safe workflow references
+1. **Step mode** (required): Bundles executable step functions that can access the full runtime and serves as the application-code transform that prevents direct workflow execution and enables type-safe `start()` references
+2. **Workflow mode** (required): Creates orchestration logic that can replay from event logs
+3. **Detect mode** (build-internal): Discovers directive-marked functions for the build without changing the code
 
 This separation allows:
 
 - **Deterministic replay**: Workflows can be safely replayed from event logs without re-executing side effects
 - **Sandboxed orchestration**: Workflow logic runs in a controlled VM without direct runtime access
 - **Stateless execution**: Your compute can scale to zero and resume from any point in the workflow
-- **Type safety**: TypeScript works seamlessly with workflow references (when using client mode)
+- **Type safety**: TypeScript supports workflow references passed to `start()`
 
-## Determinism and Replay
+## Determinism and replay
 
 A key aspect of the transformation is maintaining **deterministic replay** for workflow functions.
 
@@ -296,7 +308,7 @@ A key aspect of the transformation is maintaining **deterministic replay** for w
 - No direct side effects (no API calls, no database writes, no file I/O)
 - Can use seeded random/time APIs provided by the VM (`Math.random()`, `Date.now()`, etc.)
 
-Because workflow functions are deterministic and have no side effects, they can be safely re-run multiple times to calculate what the next step should be. This is why workflow function bodies remain intact in workflow mode—they're pure orchestration logic.
+Because workflow functions are deterministic and have no side effects, they can be safely rerun multiple times to calculate the next step. Workflow function bodies remain intact in workflow mode because they're pure orchestration logic.
 
 **Step functions can be non-deterministic:**
 
@@ -306,7 +318,7 @@ Because workflow functions are deterministic and have no side effects, they can
 
 Learn more about [Workflows and Steps](/docs/foundations/workflows-and-steps).
 
-## ID Generation
+## ID generation
 
 The compiler generates stable IDs for workflows and steps based on file paths and function names:
 
@@ -328,15 +340,15 @@ The compiler generates stable IDs for workflows and steps based on file paths an
   Although IDs can change when files are moved or functions are renamed, Workflow SDK functions assume [atomic versioning](/docs/foundations/versioning) in the World. This means changing IDs won't break old workflows from running, but will prevent runs from being upgraded and will cause your workflow/step names to change in observability across deployments.
 </Callout>
 
-## Framework Integration
+## Framework integration
 
-These transformations are framework-agnostic—they output standard JavaScript that works anywhere.
+These transformations are framework-agnostic. They output standard JavaScript that works anywhere.
 
 **For users**: Your framework handles all transformations automatically. See the [Getting Started](/docs/getting-started) guide for your framework.
 
 **For framework authors**: Learn how to integrate these transformations into your framework in [Building Framework Integrations](/docs/how-it-works/framework-integrations).
 
-## Debugging Transformed Code
+## Debugging transformed code
 
 If you need to debug transformation issues, you can inspect the generated files:
 

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

@@ -11,54 +11,58 @@ related:
 ---
 
 <Callout>
-This guide explains how Workflow SDK encrypts user data in the event log. Understanding these details is not required to use workflows — encryption is automatic and requires no code changes. For getting started, see the [getting started](/docs/getting-started) guides for your framework.
+Workflow SDK automatically encrypts user data in the event log without requiring code changes. To start using workflows, see the [getting started](/docs/getting-started) guide for your framework.
 </Callout>
 
-Workflow SDK supports automatic end-to-end encryption of all user data before it is written to the event log. When a `World` implementation provides encryption support, it is safe to pass sensitive data — such as API keys, tokens, or user credentials — as workflow inputs, step arguments, and return values. The storage backend only ever sees ciphertext.
+Workflow SDK supports automatic end-to-end encryption of all user data before writing it to the event log. When a `World` implementation provides encryption support, you can pass sensitive data, such as API keys, tokens, or user credentials, as workflow inputs, step arguments, and return values. The storage backend only sees ciphertext.
 
-Encryption support varies by `World` implementation. See the [Worlds](/worlds) page to check which worlds support this feature. `World` implementations opt into encryption by providing a `getEncryptionKeyForRun()` method — the core runtime will use it automatically when present.
+Encryption support varies by `World` implementation. See the [Worlds](/worlds) page to check which Worlds support this feature. `World` implementations opt into encryption by providing a `getEncryptionKeyForRun()` method. The core runtime uses it automatically when present.
 
-## What Is Encrypted
+## What is encrypted
 
 All user data flowing through the event log is encrypted:
 
-- **Workflow inputs** — arguments passed when starting a workflow
-- **Workflow return values** — the final output of a workflow
-- **Step inputs** — arguments passed to step functions
-- **Step return values** — the result returned by step functions
-- **Hook metadata** — data attached when creating a hook
-- **Hook payloads** — data received by hooks and webhooks
-- **Stream data** — each frame in a `ReadableStream` or `WritableStream`
+- **Workflow inputs**: Arguments passed when starting a workflow
+- **Workflow return values**: The final output of a workflow
+- **Step inputs**: Arguments passed to step functions
+- **Step return values**: The result returned by step functions
+- **Hook metadata**: Data attached when creating a hook
+- **Hook payloads**: Data received by hooks and webhooks
+- **Stream data**: Each frame in a `ReadableStream` or `WritableStream`
 
 Metadata such as workflow names, step names, entity IDs, timestamps, and lifecycle states are **not** encrypted. This allows the observability tools to display run structure and timelines without requiring decryption.
 
-## How It Works
+## How it works
 
-### Key Management
+### Compression
+
+Payloads are compressed before encryption. A format prefix on the stored value records the compression codec (gzip, with zstd support in the format), and the inner payload keeps its own serialization format prefix after decompression. Repetitive payloads compress heavily. AI token streams average around 80% smaller, reducing storage and network transfer. Like encryption, compression is automatic and requires no code changes.
+
+### Key management
 
 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](/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
+### Encryption algorithm
 
 Data is encrypted using **AES-256-GCM** via the [Web Crypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API):
 
 - A random 12-byte nonce is generated for each encryption operation
-- The GCM authentication tag provides integrity verification — any tampering with the ciphertext is detected
+- The GCM authentication tag provides integrity verification and detects any ciphertext tampering
 - The same plaintext produces different ciphertext each time due to the random nonce
 
-## Decrypting Data
+## Decrypting data
 
 When viewing workflow runs through the observability tools, encrypted fields display as locked placeholders until you explicitly choose to decrypt them.
 
 ### Permissions
 
-Decryption access is controlled by the `World` implementation. On Vercel, decryption follows the same permissions model as project environment variables — if you don't have permission to view environment variable values for a project, you won't be able to decrypt workflow data either. Each decryption request is recorded in your [Vercel audit log](https://vercel.com/docs/audit-log), giving your team full visibility into when and by whom workflow data was accessed.
+The `World` implementation controls decryption access. On Vercel, decryption follows the same permissions model as project environment variables. If you don't have permission to view environment variable values for a project, you can't decrypt its workflow data. Vercel records each decryption request in your [Vercel audit log](https://vercel.com/docs/audit-log), so your team can see when someone accessed workflow data and who accessed it.
 
-### Web Dashboard
+### Web dashboard
 
-Click the **Decrypt** button in the run detail panel to decrypt all data fields. Decryption happens entirely in the browser via the Web Crypto API — the observability server retrieves the encryption key but never sees your plaintext data.
+Click the **Decrypt** button in the run detail panel to decrypt all data fields. Decryption happens entirely in the browser through the Web Crypto API. The observability server retrieves the encryption key but never sees your plaintext data.
 
 ### CLI
 
@@ -80,7 +84,7 @@ npx workflow inspect stream <stream-id> --run <run-id> --decrypt
 
 Without `--decrypt`, encrypted fields display as `🔒 Encrypted` placeholders.
 
-## Custom World Implementations
+## Custom World implementations
 
 The core runtime encrypts data automatically when the `World` implementation provides a `getEncryptionKeyForRun()` method. The core runtime can call this method in two forms:
 
@@ -98,7 +102,7 @@ Use `getEncryptionKeyForRun(run)` when the run entity already exists. Use `getEn
 To add encryption support to a custom `World`:
 
 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
+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