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

package/docs/api-reference/workflow-errors/workflow-world-error.mdx

@@ -0,0 +1,79 @@
+---
+title: WorkflowWorldError
+description: Base error for failures from workflow storage backends.
+type: reference
+summary: Catch WorkflowWorldError to handle any error originating from a workflow world (storage backend).
+related:
+  - /docs/api-reference/workflow-errors/entity-conflict-error
+  - /docs/api-reference/workflow-errors/run-expired-error
+  - /docs/api-reference/workflow-errors/too-early-error
+  - /docs/api-reference/workflow-errors/throttle-error
+---
+
+`WorkflowWorldError` is the base error class for failures originating from a workflow world (storage backend). World implementations (local, Postgres, Vercel) throw subclasses of this error when storage operations fail.
+
+You can use `instanceof WorkflowWorldError` to catch any world-related error regardless of the specific type. Note that the static `.is()` method only matches errors constructed directly as `WorkflowWorldError` — use the subclass-specific `.is()` methods (e.g. `EntityConflictError.is()`) to match specific error types.
+
+<Callout>
+Most world errors are handled automatically by the Workflow runtime. You will typically only encounter these errors when interacting with world storage APIs directly or when there are infrastructure-level issues.
+</Callout>
+
+```typescript lineNumbers
+import { WorkflowWorldError } from "workflow/errors"
+declare const world: { events: { create(...args: any[]): Promise<any> } }; // @setup
+declare const runId: string; // @setup
+declare const event: any; // @setup
+
+try {
+  await world.events.create(runId, event);
+} catch (error) {
+  if (error instanceof WorkflowWorldError) { // [!code highlight]
+    console.error("Storage backend error:", error.message);
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowWorldError {
+  /** HTTP status code from the world backend, if available. */
+  status?: number;
+  /** Machine-readable error code, if available. */
+  code?: string;
+  /** The URL that was requested, if available. */
+  url?: string;
+  /** Retry-After value in seconds, present on 429 and 425 responses. */
+  retryAfter?: number;
+  /** The error message. */
+  message: string;
+}
+export default WorkflowWorldError;`}
+/>
+
+### Static Methods
+
+#### `WorkflowWorldError.is(value)`
+
+Type-safe check that matches only errors constructed directly as `WorkflowWorldError`. Does not match subclasses like `EntityConflictError` — use `instanceof` to catch all world errors, or the subclass-specific `.is()` methods.
+
+```typescript
+import { WorkflowWorldError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowWorldError.is(error)) {
+  // error is typed as WorkflowWorldError (not subclasses)
+}
+```
+
+### Subclasses
+
+The following error types extend `WorkflowWorldError`:
+
+- [`EntityConflictError`](/docs/api-reference/workflow-errors/entity-conflict-error) — operation conflicts with entity state
+- [`RunExpiredError`](/docs/api-reference/workflow-errors/run-expired-error) — run has expired
+- [`TooEarlyError`](/docs/api-reference/workflow-errors/too-early-error) — request made before system is ready
+- [`ThrottleError`](/docs/api-reference/workflow-errors/throttle-error) — request was rate-limited

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/changelog/index.mdx

@@ -0,0 +1,15 @@
+---
+title: Changelog
+description: Latest updates and new features in Workflow DevKit.
+type: overview
+---
+
+# Changelog
+
+Stay up to date with the latest changes to Workflow DevKit.
+
+---
+
+## 2026
+
+- TBD

package/docs/changelog/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Changelog",
+  "pages": ["index", "eager-processing"],
+  "defaultOpen": false
+}

package/docs/deploying/building-a-world.mdx

@@ -180,11 +180,31 @@ interface Streamer {
   ): Promise<ReadableStream<Uint8Array>>;
 
   listStreamsByRunId(runId: string): Promise<string[]>;
+
+  /** Paginated snapshot of stream chunks. */
+  getStreamChunks(
+    name: string,
+    runId: string,
+    options?: { limit?: number; cursor?: string }
+  ): Promise<{
+    data: { index: number; data: Uint8Array }[];
+    cursor: string | null;
+    hasMore: boolean;
+    done: boolean;
+  }>;
+
+  /** Lightweight metadata: tail index and completion flag. */
+  getStreamInfo(
+    name: string,
+    runId: string
+  ): Promise<{ tailIndex: number; done: boolean }>;
 }
 ```
 
 Streams are identified by a combination of `runId` and `name`. Each workflow run can have multiple named streams.
 
+`getStreamChunks` returns a paginated snapshot of currently available chunks (unlike `readFromStream` which returns a live `ReadableStream` that waits for new chunks). `getStreamInfo` returns the tail index (last chunk index, 0-based, or `-1` when empty) and whether the stream is complete — useful for resolving negative `startIndex` values into absolute positions.
+
 ## Reference Implementations
 
 Study these implementations for guidance:

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/errors/hook-conflict.mdx

@@ -46,6 +46,8 @@ export async function processPayment() {
 **Solution:** Use unique tokens that include the run ID or other unique identifiers.
 
 ```typescript lineNumbers
+import { createHook } from "workflow";
+
 export async function processPayment(orderId: string) {
   "use workflow";
 
@@ -60,6 +62,8 @@ export async function processPayment(orderId: string) {
 The safest approach is to let the Workflow runtime generate a unique token automatically:
 
 ```typescript lineNumbers
+import { createHook } from "workflow";
+
 export async function processPayment() {
   "use workflow";
 
@@ -71,10 +75,11 @@ export async function processPayment() {
 
 ## Handling Hook Conflicts in Your Workflow
 
-When a hook conflict occurs, awaiting the hook will throw a `WorkflowRuntimeError`. You can catch this error to handle the conflict gracefully:
+When a hook conflict occurs, awaiting the hook will throw a `HookConflictError`. You can catch this error to handle the conflict gracefully:
 
 ```typescript lineNumbers
-import { WorkflowRuntimeError } from "@workflow/errors";
+import { createHook } from "workflow";
+import { HookConflictError } from "@workflow/errors";
 
 export async function processPayment(orderId: string) {
   "use workflow";
@@ -85,8 +90,9 @@ export async function processPayment(orderId: string) {
     const payment = await hook; // [!code highlight]
     return { success: true, payment };
   } catch (error) {
-    if (error instanceof WorkflowRuntimeError && error.message.includes("hook-conflict")) { // [!code highlight]
+    if (HookConflictError.is(error)) { // [!code highlight]
       // Another workflow is already processing this order
+      console.log(`Conflicting token: ${error.token}`);
       return { success: false, reason: "duplicate-processing" };
     }
     throw error; // Re-throw other errors

package/docs/errors/index.mdx

@@ -37,6 +37,12 @@ Fix common mistakes when creating and executing workflows in the **Workflow DevK
     <Card href="/docs/errors/corrupted-event-log" title="corrupted-event-log">
         Learn how to handle corrupted or invalid event logs.
     </Card>
+    <Card href="/docs/errors/step-not-registered" title="step-not-registered">
+        Resolve step not registered errors caused by deployment mismatches.
+    </Card>
+    <Card href="/docs/errors/workflow-not-registered" title="workflow-not-registered">
+        Resolve workflow not registered errors caused by deployment mismatches.
+    </Card>
 </Cards>
 
 ## Learn More

package/docs/errors/step-not-registered.mdx

@@ -0,0 +1,66 @@
+---
+title: step-not-registered
+description: A step function is not registered in the current deployment.
+type: troubleshooting
+summary: Resolve step not registered errors caused by build issues.
+prerequisites:
+  - /docs/foundations/steps
+related:
+  - /docs/errors/workflow-not-registered
+  - /docs/api-reference/workflow-errors/step-not-registered-error
+---
+
+This error occurs when the Workflow runtime tries to execute a step function that is not registered in the current deployment. When this happens, the step fails (like a `FatalError`) and control is passed back to the workflow function, which can optionally handle the failure.
+
+## Error Message
+
+```
+Step "<stepName>" is not registered in the current deployment.
+This usually indicates a build or bundling issue that caused the step
+to not be included in the deployment.
+```
+
+## Why This Happens
+
+Workflow runs are pegged to a specific deployment, so this error is not caused by newer deployments overriding the running code. Instead, it means the step function was not included in the deployment's workflow bundle at build time.
+
+This is an **infrastructure error**, not a user code error.
+
+## Common Causes
+
+### Build tooling issue
+
+Something went wrong during the build process that caused the step function to not be included in the workflow bundle. Check your build logs for errors related to workflow bundling. Common issues include:
+
+- The step file is missing a valid `"use step"` directive
+- The step function is not exported from the workflow file
+- An esbuild or SWC plugin error silently excluded the step
+
+### Step removed from the codebase
+
+The step function was deleted or its `"use step"` directive was removed, but the workflow still references it. Ensure all steps referenced by your workflow are present in the codebase.
+
+## How to Resolve
+
+1. **Check your build logs:** Look for errors or warnings related to workflow bundling. Ensure the step file contains a valid `"use step"` directive and is properly exported.
+
+2. **Verify the step exists:** Confirm the step function is present in the workflow file and has the `"use step"` directive.
+
+3. **Handle it in your workflow:** Since the step fails like a `FatalError`, you can catch it in your workflow code:
+
+```typescript lineNumbers
+declare function processPayment(orderId: string): Promise<any>; // @setup
+
+export async function myWorkflow() {
+  "use workflow";
+
+  try {
+    const result = await processPayment("order-123");
+    return { success: true, result };
+  } catch (error) {
+    // Step failure (including not registered) is caught here
+    console.error("Step failed:", error);
+    return { success: false, error: String(error) };
+  }
+}
+```

package/docs/errors/webhook-invalid-respond-with-value.mdx

@@ -43,6 +43,8 @@ export async function webhookWorkflow() {
 **Solution:** Use `"manual"` or provide a `Response` object.
 
 ```typescript lineNumbers
+import { createWebhook } from "workflow";
+
 // Fixed - use "manual"
 export async function webhookWorkflow() {
   "use workflow";
@@ -74,6 +76,8 @@ export async function webhookWorkflow() {
 **Solution:** Create a proper `Response` object.
 
 ```typescript lineNumbers
+import { createWebhook } from "workflow";
+
 // Fixed - use Response constructor
 export async function webhookWorkflow() {
   "use workflow";
@@ -89,6 +93,8 @@ export async function webhookWorkflow() {
 ### Default Behavior (202 Response)
 
 ```typescript lineNumbers
+import { createWebhook } from "workflow";
+
 // Returns 202 Accepted automatically
 const webhook = await createWebhook();
 const request = await webhook;
@@ -98,6 +104,8 @@ const request = await webhook;
 ### Manual Response
 
 ```typescript lineNumbers
+import { createWebhook } from "workflow";
+
 // Manual response control
 const webhook = await createWebhook({
   respondWith: "manual",
@@ -120,6 +128,8 @@ await request.respondWith(
 ### Pre-defined Response
 
 ```typescript lineNumbers
+import { createWebhook } from "workflow";
+
 // Immediate response
 const webhook = await createWebhook({
   respondWith: new Response("Request received", { status: 200 }),

package/docs/errors/webhook-response-not-sent.mdx

@@ -49,6 +49,8 @@ export async function webhookWorkflow() {
 **Solution:** Always call `request.respondWith()` when using manual response mode.
 
 ```typescript lineNumbers
+import { createWebhook } from "workflow";
+
 // Fixed - response sent
 export async function webhookWorkflow() {
   "use workflow";
@@ -92,6 +94,8 @@ export async function webhookWorkflow() {
 **Solution:** Ensure all code paths send a response.
 
 ```typescript lineNumbers
+import { createWebhook } from "workflow";
+
 // Fixed - response sent in all branches
 export async function webhookWorkflow() {
   "use workflow";
@@ -135,6 +139,8 @@ export async function webhookWorkflow() {
 **Solution:** Use try-catch to handle errors and send appropriate responses.
 
 ```typescript lineNumbers
+import { createWebhook } from "workflow";
+
 // Fixed - error handling with response
 export async function webhookWorkflow() {
   "use workflow";
@@ -163,6 +169,8 @@ export async function webhookWorkflow() {
 If you don't need custom response control, consider using the default response mode which automatically returns a `202 Accepted` response:
 
 ```typescript lineNumbers
+import { createWebhook } from "workflow";
+
 // Automatic 202 response - no manual response needed
 export async function webhookWorkflow() {
   "use workflow";

package/docs/errors/workflow-not-registered.mdx

@@ -0,0 +1,64 @@
+---
+title: workflow-not-registered
+description: A workflow function is not registered in the current deployment.
+type: troubleshooting
+summary: Resolve workflow not registered errors caused by deployment targeting or build issues.
+prerequisites:
+  - /docs/foundations/starting-workflows
+related:
+  - /docs/errors/step-not-registered
+  - /docs/api-reference/workflow-errors/workflow-not-registered-error
+---
+
+This error occurs when the Workflow runtime tries to execute a workflow function that is not registered in the current deployment. When this happens, the run fails with a `RUNTIME_ERROR` error code.
+
+## Error Message
+
+```
+Workflow "<workflowName>" is not registered in the current deployment.
+This usually means a run was started against a deployment that does not
+have this workflow, or there was a build/bundling issue.
+```
+
+## Why This Happens
+
+This error means the deployment that received the workflow execution request does not have the specified workflow function in its bundle. This is an **infrastructure error**, not a user code error.
+
+## Common Causes
+
+### Run started against a deployment without the workflow
+
+A run was started (or restarted from the dashboard UI) targeting a deployment where the workflow was renamed, moved to a different file, or removed entirely.
+
+{/* @skip-typecheck: incomplete code sample */}
+```typescript lineNumbers title="workflows/order.ts (original)"
+export async function processOrder(orderId: string) {
+  "use workflow";
+  // workflow logic
+}
+```
+
+{/* @skip-typecheck: incomplete code sample */}
+```typescript lineNumbers title="workflows/order.ts (current deployment)"
+// Renamed from processOrder to handleOrder
+export async function handleOrder(orderId: string) { // [!code highlight]
+  "use workflow";
+  // workflow logic
+}
+```
+
+If a new run is started targeting the current deployment using the old name `processOrder`, the runtime will not find it.
+
+### Build tooling issue
+
+Something went wrong during the build process that caused the workflow function to not be included in the workflow bundle. Check your build logs for errors related to workflow bundling. Common issues include:
+
+- The workflow file is missing a valid `"use workflow"` directive
+- The workflow function is not exported from the workflow file
+- An esbuild or SWC plugin error silently excluded the workflow
+
+## How to Resolve
+
+1. **If the workflow was renamed or moved:** Deploy with the workflow restored to its original name and location, then retry the run. Alternatively, start a new run using the updated workflow name against the current deployment.
+
+2. **If it's a build issue:** Check your build logs for errors related to workflow bundling. Ensure the workflow file contains a valid `"use workflow"` directive and is properly exported.

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/errors-and-retries.mdx

@@ -139,6 +139,35 @@ callApi.maxRetries = 5; // Retry up to 5 times on failure (6 total attempts)
   step can run up to 4 times total (1 initial attempt + 3 retries).
 </Callout>
 
+## Error Codes
+
+When a workflow run fails, the error may include a `code` that classifies the failure. You can access it programmatically via the `Run` class:
+
+```typescript lineNumbers
+import { WorkflowRunFailedError } from "@workflow/errors";
+import { start } from "workflow/api";
+
+const run = await start(myWorkflow, [input]);
+
+try {
+  const result = await run.returnValue;
+} catch (err) {
+  if (WorkflowRunFailedError.is(err)) {
+    console.log(err.cause.code); // "USER_ERROR", "RUNTIME_ERROR", or undefined
+    console.log(err.cause.message); // The error message
+  }
+}
+```
+
+| Code | Meaning |
+| --- | --- |
+| `USER_ERROR` | An error thrown in your workflow or step code (including propagated step failures like `FatalError`) |
+| `RUNTIME_ERROR` | An internal runtime error such as a corrupted event log or missing data. If you see this, please [file an issue](https://github.com/vercel/workflow/issues) |
+
+<Callout type="info">
+  The error code is also available on the run entity via the CLI (`npx workflow inspect runs <runId>`) in the `error.code` field, and as an OTEL span attribute (`workflow.error.code`) for observability.
+</Callout>
+
 ## Rolling Back Failed Steps
 
 When a workflow fails partway through, it can leave the system in an inconsistent state.