workflow 4.2.0-beta.70 → 4.2.0-beta.71

package/dist/internal/builtins.d.ts

@@ -3,7 +3,7 @@
  * similar to "stdlib" except that are not meant to be imported by users, but are instead "just available"
  * alongside user defined steps. They are used internally by the runtime
  */
-export declare function __builtin_response_array_buffer(res: Response): Promise<ArrayBuffer>;
-export declare function __builtin_response_json(res: Response): Promise<unknown>;
-export declare function __builtin_response_text(res: Response): Promise<string>;
+export declare function __builtin_response_array_buffer(this: Request | Response): Promise<ArrayBuffer>;
+export declare function __builtin_response_json(this: Request | Response): Promise<unknown>;
+export declare function __builtin_response_text(this: Request | Response): Promise<string>;
 //# sourceMappingURL=builtins.d.ts.map

package/dist/internal/builtins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../src/internal/builtins.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wBAAsB,+BAA+B,CAAC,GAAG,EAAE,QAAQ,wBAGlE;AAED,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,QAAQ,oBAG1D;AAED,wBAAsB,uBAAuB,CAAC,GAAG,EAAE,QAAQ,mBAG1D"}
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../src/internal/builtins.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wBAAsB,+BAA+B,CACnD,IAAI,EAAE,OAAO,GAAG,QAAQ,wBAIzB;AAED,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,oBAGrE;AAED,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,mBAGrE"}

package/dist/internal/builtins.js

@@ -3,16 +3,16 @@
  * similar to "stdlib" except that are not meant to be imported by users, but are instead "just available"
  * alongside user defined steps. They are used internally by the runtime
  */
-export async function __builtin_response_array_buffer(res) {
+export async function __builtin_response_array_buffer() {
     'use step';
-    return res.arrayBuffer();
+    return this.arrayBuffer();
 }
-export async function __builtin_response_json(res) {
+export async function __builtin_response_json() {
     'use step';
-    return res.json();
+    return this.json();
 }
-export async function __builtin_response_text(res) {
+export async function __builtin_response_text() {
     'use step';
-    return res.text();
+    return this.text();
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYnVpbHRpbnMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaW50ZXJuYWwvYnVpbHRpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7R0FJRztBQUVILE1BQU0sQ0FBQyxLQUFLLFVBQVUsK0JBQStCLENBQUMsR0FBYTtJQUNqRSxVQUFVLENBQUM7SUFDWCxPQUFPLEdBQUcsQ0FBQyxXQUFXLEVBQUUsQ0FBQztBQUMzQixDQUFDO0FBRUQsTUFBTSxDQUFDLEtBQUssVUFBVSx1QkFBdUIsQ0FBQyxHQUFhO0lBQ3pELFVBQVUsQ0FBQztJQUNYLE9BQU8sR0FBRyxDQUFDLElBQUksRUFBRSxDQUFDO0FBQ3BCLENBQUM7QUFFRCxNQUFNLENBQUMsS0FBSyxVQUFVLHVCQUF1QixDQUFDLEdBQWE7SUFDekQsVUFBVSxDQUFDO0lBQ1gsT0FBTyxHQUFHLENBQUMsSUFBSSxFQUFFLENBQUM7QUFDcEIsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYnVpbHRpbnMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvaW50ZXJuYWwvYnVpbHRpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7R0FJRztBQUVILE1BQU0sQ0FBQyxLQUFLLFVBQVUsK0JBQStCO0lBR25ELFVBQVUsQ0FBQztJQUNYLE9BQU8sSUFBSSxDQUFDLFdBQVcsRUFBRSxDQUFDO0FBQzVCLENBQUM7QUFFRCxNQUFNLENBQUMsS0FBSyxVQUFVLHVCQUF1QjtJQUMzQyxVQUFVLENBQUM7SUFDWCxPQUFPLElBQUksQ0FBQyxJQUFJLEVBQUUsQ0FBQztBQUNyQixDQUFDO0FBRUQsTUFBTSxDQUFDLEtBQUssVUFBVSx1QkFBdUI7SUFDM0MsVUFBVSxDQUFDO0lBQ1gsT0FBTyxJQUFJLENBQUMsSUFBSSxFQUFFLENBQUM7QUFDckIsQ0FBQyJ9

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

@@ -39,12 +39,12 @@ export async function chat(messages: UIMessage[]) {
 
   const agent = new DurableAgent({
     model: "bedrock/claude-haiku-4-5-20251001-v1",
-    system: FLIGHT_ASSISTANT_PROMPT,
+    instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
 
   await agent.stream({
-    messages: convertToModelMessages(messages), // [!code highlight] Full history from client
+    messages: await convertToModelMessages(messages), // [!code highlight] Full history from client
     writable,
   });
 }
@@ -171,7 +171,7 @@ export async function chat(initialMessages: UIMessage[]) {
 
   const { workflowRunId: runId } = getWorkflowMetadata();
   const writable = getWritable<UIMessageChunk>();
-  const messages: ModelMessage[] = convertToModelMessages(initialMessages);
+  const messages: ModelMessage[] = await convertToModelMessages(initialMessages);
 
   // Write markers for initial user messages (for replay) // [!code highlight]
   for (const msg of initialMessages) { // [!code highlight]
@@ -183,7 +183,7 @@ export async function chat(initialMessages: UIMessage[]) {
 
   const agent = new DurableAgent({
     model: "bedrock/claude-haiku-4-5-20251001-v1",
-    system: FLIGHT_ASSISTANT_PROMPT,
+    instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
 

package/docs/ai/defining-tools.mdx

@@ -25,7 +25,7 @@ When you tool needs access to the full message history, you can access it via th
 ```typescript title="tools.ts" lineNumbers
 async function getWeather(
   { city }: { city: string },
-  { messages, toolCallId }: { messages: LanguageModelV2Prompt, toolCallId: string }) { // [!code highlight]
+  { messages, toolCallId }: { messages: ModelMessage[], toolCallId: string }) { // [!code highlight]
   "use step";
   return `Weather in ${city} is sunny`;
 }

package/docs/ai/index.mdx

@@ -127,11 +127,11 @@ export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
   const agent = new Agent({ // [!code highlight]
     model: gateway("bedrock/claude-4-5-haiku-20251001-v1"),
-    system: FLIGHT_ASSISTANT_PROMPT,
+    instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
-  const modelMessages = convertToModelMessages(messages);
-  const stream = agent.stream({ messages: modelMessages }); // [!code highlight]
+  const modelMessages = await convertToModelMessages(messages);
+  const stream = await agent.stream({ messages: modelMessages }); // [!code highlight]
   return createUIMessageStreamResponse({
     stream: stream.toUIMessageStream(),
   });
@@ -273,7 +273,7 @@ export async function chatWorkflow(messages: ModelMessage[]) {
     // ELSE if using a custom provider, pass the provider call as an argument:
     model: openai("gpt-5.1"), // [!code highlight]
 
-    system: FLIGHT_ASSISTANT_PROMPT,
+    instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
 
@@ -304,7 +304,7 @@ import { chatWorkflow } from "@/workflows/chat/workflow";
 
 export async function POST(req: Request) {
   const { messages }: { messages: UIMessage[] } = await req.json();
-  const modelMessages = convertToModelMessages(messages);
+  const modelMessages = await convertToModelMessages(messages);
 
   const run = await start(chatWorkflow, [modelMessages]); // [!code highlight]
 

package/docs/ai/message-queueing.mdx

@@ -33,15 +33,15 @@ The `prepareStep` callback runs before each step in the agent loop. It receives
 
 ```typescript lineNumbers
 interface PrepareStepInfo {
-  model: string | (() => Promise<LanguageModelV2>);  // Current model
+  model: string | (() => Promise<LanguageModel>);    // Current model
   stepNumber: number;                                // 0-indexed step count
   steps: StepResult[];                               // Previous step results
-  messages: LanguageModelV2Prompt;                   // Messages to be sent
+  messages: ModelMessage[];                          // Messages to be sent
 }
 
 interface PrepareStepResult {
-  model?: string | (() => Promise<LanguageModelV2>); // Override model
-  messages?: LanguageModelV2Prompt;                  // Override messages
+  model?: string | (() => Promise<LanguageModel>);   // Override model
+  messages?: ModelMessage[];                         // Override messages
 }
 ```
 
@@ -65,7 +65,7 @@ export async function chat(initialMessages: ModelMessage[]) {
 
   const agent = new DurableAgent({
     model: "bedrock/claude-haiku-4-5-20251001-v1",
-    system: FLIGHT_ASSISTANT_PROMPT,
+    instructions: FLIGHT_ASSISTANT_PROMPT,
     tools: flightBookingTools,
   });
 
@@ -101,7 +101,7 @@ export async function chat(initialMessages: ModelMessage[]) {
 Messages sent via `chatMessageHook.resume()` accumulate in the queue and get injected before the next step, whether that's a tool call or another LLM request.
 
 <Callout type="info">
-The `prepareStep` callback receives messages in `LanguageModelV2Prompt` format (with content arrays), which is the internal format used by the AI SDK.
+The `prepareStep` callback receives messages in `ModelMessage[]` format (with content arrays), which is the internal format used by the AI SDK.
 </Callout>
 
 ## Combining with Multi-Turn Sessions

package/docs/api-reference/index.mdx

@@ -17,6 +17,9 @@ All the functions and primitives that come with Workflow DevKit by package.
     <Card title="workflow/next" href="/docs/api-reference/workflow-next">
         Next.js integration for Workflow DevKit that automatically configures bundling and runtime support.
     </Card>
+    <Card title="@workflow/serde" href="/docs/api-reference/workflow-serde">
+        Serialization symbols for custom class serialization in workflows.
+    </Card>
     <Card title="@workflow/ai" href="/docs/api-reference/workflow-ai">
         Helpers for integrating AI SDK for building AI-powered workflows.
     </Card>

package/docs/api-reference/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "API Reference",
-  "pages": ["...", "workflow-ai", "vitest"]
+  "pages": ["...", "workflow-serde", "workflow-ai", "vitest"]
 }

package/docs/api-reference/workflow-ai/durable-agent.mdx

@@ -34,7 +34,7 @@ async function myAgent() {
 
   const agent = new DurableAgent({
     model: "anthropic/claude-haiku-4.5",
-    system: "You are a helpful weather assistant.",
+    instructions: "You are a helpful weather assistant.",
     temperature: 0.7,
     tools: {
       getWeather: {
@@ -249,7 +249,7 @@ async function weatherAgentWorkflow(userQuery: string) {
         execute: getWeather,
       },
     },
-    system: "You are a helpful weather assistant. Always provide accurate weather information.",
+    instructions: "You are a helpful weather assistant. Always provide accurate weather information.",
   });
 
   await agent.stream({
@@ -446,7 +446,7 @@ async function agentWithPrepareStep(userMessage: string) {
 
   const agent = new DurableAgent({
     model: "openai/gpt-4.1-mini", // Default model
-    system: "You are a helpful assistant.",
+    instructions: "You are a helpful assistant.",
   });
 
   await agent.stream({
@@ -500,7 +500,7 @@ async function agentWithMessageQueue(initialMessage: string) {
 
   const agent = new DurableAgent({
     model: "anthropic/claude-haiku-4.5",
-    system: "You are a helpful assistant.",
+    instructions: "You are a helpful assistant.",
   });
 
   await agent.stream({
@@ -812,7 +812,7 @@ async function agentWithUIMessages(userMessage: string) {
 
   const agent = new DurableAgent({
     model: "anthropic/claude-haiku-4.5",
-    system: "You are a helpful assistant.",
+    instructions: "You are a helpful assistant.",
   });
 
   const result = await agent.stream({

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

@@ -76,3 +76,27 @@ const run = await start(myWorkflow, ["arg1", "arg2"], { // [!code highlight]
   deploymentId: "custom-deployment-id" // [!code highlight]
 }); // [!code highlight]
 ```
+
+### Using `deploymentId: "latest"`
+
+Set `deploymentId` to `"latest"` to automatically resolve the most recent deployment for the current environment. This is useful when you want to ensure a workflow run targets the latest deployed version of your application rather than the deployment that initiated the call.
+
+```typescript
+import { start } from "workflow/api";
+import { myWorkflow } from "./workflows/my-workflow";
+
+const run = await start(myWorkflow, ["arg1", "arg2"], { // [!code highlight]
+  deploymentId: "latest" // [!code highlight]
+}); // [!code highlight]
+```
+
+<Callout type="info">
+The `deploymentId` option is currently a Vercel-specific feature. The `"latest"` value resolves to the most recent deployment matching your current environment — the same production target for production deployments, or the same git branch for preview deployments.
+</Callout>
+
+<Callout type="warn">
+When using `deploymentId: "latest"`, the workflow run will execute on a potentially different deployment than the one calling `start()`. Be mindful of forward and backward compatibility:
+
+- **Workflow identity**: The workflow ID is derived from the function name and file path. If the latest deployment has renamed the workflow function or moved it to a different directory, the workflow ID will no longer match and the run will fail to start.
+- **Input and output compatibility**: The arguments passed to `start()` are serialized by the calling deployment but deserialized by the target deployment. Similarly, the workflow's return value is serialized by the target deployment but deserialized by the caller. If the workflow's expected arguments or return type have changed (e.g. added required fields, removed fields, or changed types), the run may fail or behave unexpectedly. Ensure that input and output schemas remain backward-compatible across deployments.
+</Callout>

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

@@ -0,0 +1,52 @@
+---
+title: "@workflow/serde"
+---
+
+Serialization symbols for custom class serialization in Workflow DevKit.
+
+## Installation
+
+```package-install
+npm i @workflow/serde
+```
+
+## Overview
+
+By default, Workflow DevKit can serialize standard JavaScript types like primitives, objects, arrays, `Date`, `Map`, `Set`, and more. However, custom class instances are not serializable by default because the serialization system doesn't know how to reconstruct them.
+
+The `@workflow/serde` package provides two symbols that allow you to define custom serialization and deserialization logic for your classes, enabling them to be passed between workflow and step functions.
+
+## Symbols
+
+<Cards>
+    <Card href="/docs/api-reference/workflow-serde/workflow-serialize" title="WORKFLOW_SERIALIZE">
+        Symbol for defining how to serialize a class instance to plain data.
+    </Card>
+    <Card href="/docs/api-reference/workflow-serde/workflow-deserialize" title="WORKFLOW_DESERIALIZE">
+        Symbol for defining how to reconstruct a class instance from plain data.
+    </Card>
+</Cards>
+
+## Quick Example
+
+{/* @expect-error:2351 */}
+
+```typescript lineNumbers
+import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde";
+
+class Point {
+  constructor(public x: number, public y: number) {}
+
+  static [WORKFLOW_SERIALIZE](instance: Point) {
+    return { x: instance.x, y: instance.y };
+  }
+
+  static [WORKFLOW_DESERIALIZE](data: { x: number; y: number }) {
+    return new Point(data.x, data.y);
+  }
+}
+```
+
+<Callout>
+For a complete guide on custom class serialization, see the [Serialization documentation](/docs/foundations/serialization#custom-class-serialization).
+</Callout>

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

@@ -0,0 +1,3 @@
+{
+  "pages": ["...", "workflow-serialize", "workflow-deserialize"]
+}

package/docs/api-reference/workflow-serde/workflow-deserialize.mdx

@@ -0,0 +1,70 @@
+---
+title: WORKFLOW_DESERIALIZE
+---
+
+A symbol used to define custom deserialization for user-defined class instances. The static method should accept serialized data and return a new class instance.
+
+## Usage
+
+{/* @expect-error:2351 */}
+
+```typescript lineNumbers
+import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde";
+
+class Point {
+  constructor(public x: number, public y: number) {}
+
+  static [WORKFLOW_SERIALIZE](instance: Point) {
+    return { x: instance.x, y: instance.y };
+  }
+
+  static [WORKFLOW_DESERIALIZE](data: { x: number; y: number }) {
+    return new Point(data.x, data.y);
+  }
+}
+```
+
+## API Signature
+
+{/* @skip-typecheck */}
+
+```typescript
+static [WORKFLOW_DESERIALIZE](data: SerializableData): T
+```
+
+### Parameters
+
+<TSDoc
+definition={`
+interface Parameters {
+  /**
+   * The serialized data to reconstruct into a class instance.
+   * This is the same data that was returned by WORKFLOW_SERIALIZE.
+   */
+  data: SerializableData;
+}
+export default Parameters;`}
+/>
+
+### Returns
+
+The method should return a new instance of the class, reconstructed from the serialized data.
+
+## Requirements
+
+<Callout type="warn">
+The method must be implemented as a **static** method on the class. Instance methods are not supported.
+</Callout>
+
+- Both `WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE` must be implemented together
+- The method receives the exact data that was returned by `WORKFLOW_SERIALIZE`
+- If `WORKFLOW_SERIALIZE` returns complex types (like `Map` or `Date`), they will be properly deserialized before being passed to this method
+
+<Callout type="warn">
+This method runs inside the workflow context and is subject to the same constraints as `"use workflow"` functions:
+- 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 this method simple and focused on reconstructing the instance from the provided data.
+</Callout>

package/docs/api-reference/workflow-serde/workflow-serialize.mdx

@@ -0,0 +1,75 @@
+---
+title: WORKFLOW_SERIALIZE
+---
+
+A symbol used to define custom serialization for user-defined class instances. The static method should accept an instance and return serializable data.
+
+## Usage
+
+{/* @expect-error:2351 */}
+
+```typescript lineNumbers
+import { WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from "@workflow/serde";
+
+class Point {
+  constructor(public x: number, public y: number) {}
+
+  static [WORKFLOW_SERIALIZE](instance: Point) {
+    return { x: instance.x, y: instance.y };
+  }
+
+  static [WORKFLOW_DESERIALIZE](data: { x: number; y: number }) {
+    return new Point(data.x, data.y);
+  }
+}
+```
+
+## API Signature
+
+{/* @skip-typecheck */}
+
+```typescript
+static [WORKFLOW_SERIALIZE](instance: T): SerializableData
+```
+
+### Parameters
+
+<TSDoc
+definition={`
+interface Parameters {
+  /**
+   * The class instance to serialize.
+   */
+  instance: T;
+}
+export default Parameters;`}
+/>
+
+### Returns
+
+The method should return serializable data. This can be:
+
+- Primitives (`string`, `number`, `boolean`, `null`, `undefined`, `bigint`)
+- Plain objects with serializable values
+- Arrays of serializable values
+- Built-in serializable types (`Date`, `Map`, `Set`, `RegExp`, `URL`, etc.)
+- Other custom classes that implement serialization
+
+## Requirements
+
+<Callout type="warn">
+The method must be implemented as a **static** method on the class. Instance methods are not supported.
+</Callout>
+
+- Both `WORKFLOW_SERIALIZE` and `WORKFLOW_DESERIALIZE` must be implemented together
+- The returned data must itself be serializable
+- The SWC compiler plugin automatically detects and registers classes that implement these symbols
+
+<Callout type="warn">
+This method runs inside the workflow context and is subject to the same constraints as `"use workflow"` functions:
+- 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 this method simple and focused on extracting data from the instance.
+</Callout>

package/docs/deploying/world/vercel-world.mdx

@@ -6,6 +6,7 @@ summary: Deploy workflows to Vercel with fully-managed storage, queuing, and aut
 prerequisites:
   - /docs/deploying
 related:
+  - /docs/how-it-works/encryption
   - /docs/deploying/world/local-world
   - /docs/deploying/world/postgres-world
 ---
@@ -125,7 +126,7 @@ This ensures long-running workflows complete reliably without being affected by
 
 The Vercel World uses Vercel's infrastructure for workflow execution:
 
-- **Storage** - Workflow data is stored in Vercel's cloud with automatic replication and encryption
+- **Storage** - Workflow data is stored in Vercel's cloud with automatic replication and [end-to-end encryption](/docs/how-it-works/encryption)
 - **Queuing** - Steps are distributed across serverless functions with automatic retries
 - **Authentication** - OIDC tokens provide secure, automatic authentication
 

package/docs/foundations/common-patterns.mdx

@@ -252,6 +252,10 @@ export async function processOrder(orderId: string) {
 
 With background execution, the parent workflow continues immediately after starting the child. The child workflow runs independently with its own event log and can be monitored separately using the returned `runId`.
 
+<Callout type="info">
+If you want the child workflow to run on the latest deployment rather than the current one, you can pass [`deploymentId: "latest"`](/docs/api-reference/workflow-api/start#using-deploymentid-latest) in the `start()` options. This is currently a Vercel-specific feature. Be aware that the child workflow's function name, file path, argument types, and return type must remain compatible across deployments — renaming the function or changing its location will change the workflow ID, and modifying expected inputs or outputs can cause serialization failures.
+</Callout>
+
 **Choose direct await when:**
 - The parent needs the child's result before continuing
 - You want a single, unified event log

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/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.71",
   "description": "Workflow DevKit - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -52,17 +52,17 @@
   },
   "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/astro": "4.0.0-beta.45",
+    "@workflow/cli": "4.2.0-beta.71",
+    "@workflow/core": "4.2.0-beta.71",
     "@workflow/errors": "4.1.0-beta.18",
     "@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/next": "4.0.1-beta.67",
+    "@workflow/nest": "0.0.0-beta.20",
+    "@workflow/nitro": "4.0.1-beta.66",
+    "@workflow/nuxt": "4.0.1-beta.55",
+    "@workflow/sveltekit": "4.0.0-beta.60",
+    "@workflow/rollup": "4.0.0-beta.28"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",