workflow 4.2.0-beta.70 → 4.2.0-beta.72

package/docs/foundations/serialization.mdx

@@ -56,6 +56,10 @@ These types have special handling and are explained in detail in the sections be
 - `ReadableStream<Serializable>`
 - `WritableStream<Serializable>`
 
+**Custom Classes:**
+
+- Class instances that implement [`WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE`](#custom-class-serialization)
+
 ## Streaming
 
 `ReadableStream` and `WritableStream` are supported as serializable types with special handling. These streams can be passed between workflow and step functions while maintaining their streaming capabilities.
@@ -121,6 +125,213 @@ export async function fetch(...args: Parameters<typeof globalThis.fetch>) {
 
 This allows you to make HTTP requests directly in workflow functions while maintaining deterministic replay behavior through automatic caching.
 
+## Custom Class Serialization
+
+By default, custom class instances cannot be serialized because the serialization system doesn't know how to reconstruct them. You can make your classes serializable by implementing two static methods using special symbols from the `@workflow/serde` package.
+
+### Basic Example
+
+{/* @expect-error:2351 */}
+
+```typescript title="workflows/custom-class.ts" lineNumbers
+import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde"; // [!code highlight]
+
+class Point {
+  constructor(
+    public x: number,
+    public y: number
+  ) {}
+
+  // Define how to serialize an instance to plain data
+  static [WORKFLOW_SERIALIZE](instance: Point) { // [!code highlight]
+    return { x: instance.x, y: instance.y }; // [!code highlight]
+  } // [!code highlight]
+
+  // Define how to reconstruct an instance from plain data
+  static [WORKFLOW_DESERIALIZE](data: { x: number; y: number }) { // [!code highlight]
+    return new Point(data.x, data.y); // [!code highlight]
+  } // [!code highlight]
+}
+```
+
+Once you've implemented these methods, instances of your class can be passed between workflow and step functions:
+
+{/* @expect-error:2351 */}
+
+```typescript title="workflows/geometry.ts" lineNumbers
+import { Point } from "./custom-class";
+
+export async function geometryWorkflow() {
+  "use workflow";
+
+  const point = new Point(10, 20);
+  // Point is serialized automatically
+  const doubled = await doublePoint(point); // [!code highlight]
+
+  console.log(doubled.x, doubled.y); // 20, 40
+  return doubled;
+}
+
+async function doublePoint(point: Point) {
+  "use step";
+  // Returns a new Point instance
+  return new Point(point.x * 2, point.y * 2); // [!code highlight]
+}
+```
+
+### How It Works
+
+1. **`WORKFLOW_SERIALIZE`**: A static method that receives a class instance and returns serializable data (primitives, plain objects, arrays, etc.)
+
+2. **`WORKFLOW_DESERIALIZE`**: A static method that receives the serialized data and returns a new class instance
+
+3. **Automatic Registration**: The SWC compiler plugin automatically detects classes that implement these symbols and registers them for serialization
+
+### Requirements
+
+<Callout type="warn">
+Both methods must be implemented as **static** methods on the class. Instance methods are not supported.
+</Callout>
+
+- The data returned by `WORKFLOW_SERIALIZE` must itself be serializable (see [Supported Serializable Types](#supported-serializable-types))
+- Both symbols must be implemented together - a class with only one will not be serializable
+
+<Callout type="warn">
+The `WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE` methods run inside the workflow context and are subject to the same constraints as `"use workflow"` functions. This means:
+- No Node.js-specific APIs (like `fs`, `path`, `crypto`, etc.)
+- No non-deterministic operations (like `Math.random()` or `Date.now()`)
+- No external network calls
+
+Keep these methods simple and focused on data transformation only.
+</Callout>
+
+### Complex Example
+
+A class that uses Node.js APIs or other non-deterministic operations cannot be used directly inside a workflow function. The recommended approach is to make the class workflow-compatible by adding `"use step"` to its instance methods. The SWC compiler will strip the method bodies from the workflow bundle and replace them with proxy functions that invoke the method as a step — with full Node.js runtime access. The `this` context (the class instance) is automatically serialized and deserialized across the workflow/step boundary.
+
+This requires the class to implement `WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE`, so that the instance can be passed to the step execution context.
+
+{/* @expect-error:2351 */}
+
+```typescript title="workflows/order.ts" lineNumbers
+import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde"; // [!code highlight]
+import { db } from "../lib/db";
+
+class Order {
+  constructor(
+    public id: string,
+    public items: Map<string, number>,
+    public createdAt: Date
+  ) {}
+
+  // Custom serialization — data must be serializable types
+  static [WORKFLOW_SERIALIZE](instance: Order) { // [!code highlight]
+    return { // [!code highlight]
+      id: instance.id, // [!code highlight]
+      items: instance.items, // Map is serializable // [!code highlight]
+      createdAt: instance.createdAt, // Date is serializable // [!code highlight]
+    }; // [!code highlight]
+  } // [!code highlight]
+
+  static [WORKFLOW_DESERIALIZE](data: { // [!code highlight]
+    id: string; // [!code highlight]
+    items: Map<string, number>; // [!code highlight]
+    createdAt: Date; // [!code highlight]
+  }) { // [!code highlight]
+    return new Order(data.id, data.items, data.createdAt); // [!code highlight]
+  } // [!code highlight]
+
+  // Methods without "use step" run in the workflow context
+  // and must follow the same constraints as workflow functions
+  total(): number {
+    let sum = 0;
+    for (const quantity of this.items.values()) {
+      sum += quantity;
+    }
+    return sum;
+  }
+
+  // Instance methods with "use step" run as step functions
+  // with full Node.js access — `this` is automatically serialized
+  async save(): Promise<void> {
+    "use step"; // [!code highlight]
+    await db.orders.insert({ // [!code highlight]
+      id: this.id, // [!code highlight]
+      items: Object.fromEntries(this.items), // [!code highlight]
+      createdAt: this.createdAt, // [!code highlight]
+    }); // [!code highlight]
+  }
+
+  async sendConfirmation(email: string): Promise<string> {
+    "use step"; // [!code highlight]
+    const res = await fetch("https://api.example.com/email", { // [!code highlight]
+      method: "POST", // [!code highlight]
+      body: JSON.stringify({ // [!code highlight]
+        to: email, // [!code highlight]
+        orderId: this.id, // [!code highlight]
+        itemCount: this.items.size, // [!code highlight]
+      }), // [!code highlight]
+    }); // [!code highlight]
+    const { messageId } = await res.json();
+    return messageId;
+  }
+}
+```
+
+The class can then be used naturally inside a workflow function. Instance methods marked with `"use step"` are each executed as a step — with automatic caching, retry semantics, and full Node.js runtime access. Methods _without_ `"use step"` run directly in the workflow context, so they must follow the same constraints as workflow functions:
+
+{/* @expect-error:2693 */}
+
+```typescript title="workflows/process-order.ts" lineNumbers
+export async function processOrderWorkflow(
+  orderId: string,
+  items: Map<string, number>,
+  email: string
+) {
+  "use workflow";
+
+  const order = new Order(orderId, items, new Date()); // [!code highlight]
+
+  // Runs in the workflow context — no "use step" needed
+  const itemCount = order.total(); // [!code highlight]
+
+  // Each "use step" instance method call runs as a separate step
+  await order.save(); // [!code highlight]
+  const messageId = await order.sendConfirmation(email); // [!code highlight]
+
+  return { orderId, itemCount, messageId };
+}
+```
+
+Note that [pass-by-value semantics](#pass-by-value-semantics) also apply to the `this` context of `"use step"` instance methods. Modifying instance properties inside a step method will not affect the original instance in the workflow. If you need to update instance state, return `this` from the step method and re-assign the variable in the workflow:
+
+{/* @expect-error:2351 */}
+
+```typescript title="workflows/order.ts" lineNumbers
+export class Order {
+  // ...
+
+  async addItem(name: string, quantity: number): Promise<Order> {
+    "use step";
+    this.items.set(name, quantity);
+    return this; // [!code highlight]
+  }
+}
+```
+
+{/* @expect-error:2693,2552,2304 */}
+
+```typescript title="workflows/process-order.ts" lineNumbers
+export async function processOrderWorkflow() {
+  "use workflow";
+
+  let order = new Order(orderId, items, new Date());
+
+  // Re-assign to capture the updated instance
+  order = await order.addItem("Widget", 3); // [!code highlight]
+}
+```
+
 ## Pass-by-Value Semantics
 
 **Parameters are passed by value, not by reference.** Steps receive deserialized copies of data. Mutations inside a step won't affect the original in the workflow.

package/docs/foundations/streaming.mdx

@@ -87,6 +87,22 @@ export async function GET(
 
 This allows clients to reconnect and continue receiving data from where they left off, rather than restarting from the beginning.
 
+`startIndex` also supports **negative values** to read relative to the end of the stream. For example, `startIndex: -5` starts 5 chunks before the current end. This is useful when you want to show the most recent output without reading the entire stream history.
+
+On an active (not-yet-closed) stream, the negative index resolves relative to the chunk count at connection time; any chunks written afterward are still delivered normally.
+
+{/* @skip-typecheck: incomplete code sample */}
+```typescript
+// Read only the last 10 chunks
+const stream = run.getReadable({ startIndex: -10 });
+```
+
+If the absolute value exceeds the total number of chunks, reading starts from the beginning (the value is clamped to 0).
+
+<Callout type="warn">
+Because streams are live and continue receiving chunks, negative `startIndex` values resolve to different absolute positions on each call. Accurate pagination over a live stream requires cursor-based access, which is not yet supported. Keep this in mind when building clients that paginate over stream data.
+</Callout>
+
 ## Streams as Data Types
 
 [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) and [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) are standard Web Streams API types that Workflow DevKit makes serializable. These are not custom types - they follow the web standard - but Workflow DevKit adds the ability to pass them between functions while maintaining their streaming capabilities.
@@ -164,6 +180,8 @@ Workflow functions must be deterministic to support replay. Since streams bypass
 For more on determinism and replay, see [Workflows and Steps](/docs/foundations/workflows-and-steps).
 
 ```typescript title="workflows/bad-example.ts" lineNumbers
+import { getWritable } from "workflow";
+
 export async function badWorkflow() {
   "use workflow";
 
@@ -176,6 +194,8 @@ export async function badWorkflow() {
 ```
 
 ```typescript title="workflows/good-example.ts" lineNumbers
+import { getWritable } from "workflow";
+
 export async function goodWorkflow() {
   "use workflow";
 
@@ -501,6 +521,8 @@ If a lock is not released, the step function's HTTP request cannot terminate. Ev
 **Close streams when done:**
 
 ```typescript lineNumbers
+import { getWritable } from "workflow";
+
 async function finalizeStream() {
   "use step";
 

package/docs/getting-started/index.mdx

@@ -63,11 +63,11 @@ import { Next, Nitro, SvelteKit, Nuxt, Hono, Bun, AstroDark, AstroLight, TanStac
         <span className="font-medium">SvelteKit</span>
      </div>
     </Card>
-    <Card href="/docs/getting-started/nestjs">
+    <Card className="opacity-50">
       <div className="flex flex-col items-center justify-center gap-2">
-        <Nest className="size-16" />
+        <Nest className="size-16 dark:invert grayscale" />
         <span className="font-medium">NestJS</span>
-        <Badge variant="secondary">Experimental</Badge>
+        <Badge variant="secondary">Coming soon</Badge>
       </div>
     </Card>
     <Card className="opacity-50">

package/docs/getting-started/meta.json

@@ -0,0 +1,15 @@
+{
+  "title": "Getting Started",
+  "pages": [
+    "next",
+    "astro",
+    "express",
+    "fastify",
+    "hono",
+    "nitro",
+    "nuxt",
+    "sveltekit",
+    "vite"
+  ],
+  "defaultOpen": true
+}

package/docs/getting-started/nestjs.mdx

@@ -11,6 +11,10 @@ related:
 
 This guide will walk through setting up your first workflow in a NestJS app. Along the way, you'll learn more about the concepts that are fundamental to using the development kit in your own projects.
 
+<Callout>
+NestJS integration is experimental and not yet supported for deployment to Vercel.
+</Callout>
+
 ---
 
 <Steps>
@@ -323,14 +327,6 @@ WorkflowModule.forRoot({
 });
 ```
 
-## Deploying to production
-
-Workflow DevKit apps currently work best when deployed to [Vercel](https://vercel.com/home) and needs no special configuration.
-
-<FluidComputeCallout />
-
-Check the [Deploying](/docs/deploying) section to learn how your workflows can be deployed elsewhere.
-
 ## Next Steps
 
 - Learn more about the [Foundations](/docs/foundations).

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

@@ -0,0 +1,93 @@
+---
+title: Encryption
+description: Learn how Workflow DevKit encrypts user data end-to-end in the event log.
+type: conceptual
+summary: Understand how workflow and step data is encrypted at rest.
+prerequisites:
+  - /docs/how-it-works/event-sourcing
+related:
+  - /docs/observability
+  - /docs/deploying/world/vercel-world
+---
+
+<Callout>
+This guide explains how Workflow DevKit 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.
+</Callout>
+
+Workflow DevKit 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.
+
+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.
+
+## 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`
+
+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
+
+### 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](/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.
+
+### 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 same plaintext produces different ciphertext each time due to the random nonce
+
+## 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.
+
+### 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.
+
+### CLI
+
+Add the `--decrypt` flag to any `inspect` command:
+
+```bash
+# Inspect a specific run
+npx workflow inspect run <run-id> --decrypt
+
+# Inspect a specific step
+npx workflow inspect step <step-id> --run <run-id> --decrypt
+
+# List events for a run
+npx workflow inspect events --run <run-id> --decrypt
+
+# Inspect a specific stream
+npx workflow inspect stream <stream-id> --run <run-id> --decrypt
+```
+
+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.
+
+To add encryption support to a custom `World`:
+
+1. Implement `getEncryptionKeyForRun(runId: string)` on your `World` class
+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)
+
+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/meta.json

@@ -4,7 +4,8 @@
     "understanding-directives",
     "code-transform",
     "framework-integrations",
-    "event-sourcing"
+    "event-sourcing",
+    "encryption"
   ],
   "defaultOpen": false
 }

package/docs/observability/index.mdx

@@ -7,6 +7,7 @@ prerequisites:
   - /docs/foundations
 related:
   - /docs/how-it-works/event-sourcing
+  - /docs/how-it-works/encryption
 ---
 
 Workflow DevKit provides powerful tools to inspect, monitor, and debug your workflows through the CLI and Web UI. These tools allow you to inspect workflow runs, steps, webhooks, [events](/docs/how-it-works/event-sourcing), and stream output.
@@ -60,3 +61,5 @@ To inspect workflows running on Vercel, ensure you're logged in to the Vercel CL
 # Inspect workflows running on Vercel
 npx workflow inspect runs --backend vercel
 ```
+
+When deployed to Vercel, workflow data is [encrypted end-to-end](/docs/how-it-works/encryption). Encrypted fields display as locked placeholders until you choose to decrypt them using the **Decrypt** button in the web UI or the `--decrypt` flag in the CLI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "4.2.0-beta.70",
+  "version": "4.2.0-beta.72",
   "description": "Workflow DevKit - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -37,6 +37,7 @@
       "workflow": "./dist/api-workflow.js",
       "default": "./dist/api.js"
     },
+    "./errors": "./dist/internal/errors.js",
     "./internal/errors": "./dist/internal/errors.js",
     "./internal/builtins": "./dist/internal/builtins.js",
     "./internal/private": "./dist/internal/private.js",
@@ -48,21 +49,26 @@
     "./astro": "./dist/astro.js",
     "./vite": "./dist/vite.js",
     "./nest": "./dist/nest.js",
-    "./runtime": "./dist/runtime.js"
+    "./runtime": "./dist/runtime.js",
+    "./observability": {
+      "types": "./dist/observability.d.ts",
+      "default": "./dist/observability.js"
+    }
   },
   "dependencies": {
     "ms": "2.1.3",
-    "@workflow/astro": "4.0.0-beta.44",
-    "@workflow/cli": "4.2.0-beta.70",
-    "@workflow/core": "4.2.0-beta.70",
-    "@workflow/errors": "4.1.0-beta.18",
+    "@workflow/astro": "4.0.0-beta.46",
+    "@workflow/cli": "4.2.0-beta.72",
+    "@workflow/core": "4.2.0-beta.72",
+    "@workflow/errors": "4.1.0-beta.19",
     "@workflow/typescript-plugin": "4.0.1-beta.5",
-    "@workflow/next": "4.0.1-beta.66",
-    "@workflow/nest": "0.0.0-beta.19",
-    "@workflow/nitro": "4.0.1-beta.65",
-    "@workflow/nuxt": "4.0.1-beta.54",
-    "@workflow/sveltekit": "4.0.0-beta.59",
-    "@workflow/rollup": "4.0.0-beta.27"
+    "@workflow/utils": "4.1.0-beta.13",
+    "@workflow/next": "4.0.1-beta.68",
+    "@workflow/nest": "0.0.0-beta.21",
+    "@workflow/nitro": "4.0.1-beta.67",
+    "@workflow/nuxt": "4.0.1-beta.56",
+    "@workflow/sveltekit": "4.0.0-beta.61",
+    "@workflow/rollup": "4.0.0-beta.29"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",