workflow 4.2.0-beta.71 → 4.2.0-beta.72

package/docs/api-reference/workflow-errors/step-not-registered-error.mdx

@@ -0,0 +1,56 @@
+---
+title: StepNotRegisteredError
+description: Thrown when a step function is not registered in the current deployment.
+type: reference
+summary: Catch StepNotRegisteredError when a step function cannot be found during execution.
+related:
+  - /docs/errors/step-not-registered
+  - /docs/api-reference/workflow-errors/workflow-not-registered-error
+---
+
+`StepNotRegisteredError` is thrown when the runtime tries to execute a step function that is not registered in the current deployment. This is an infrastructure error — not a user code error. It typically indicates a build or bundling issue that caused the step to not be included in the deployment.
+
+When this error occurs, the step fails (like a `FatalError`) and control is passed back to the workflow function, which can handle the failure gracefully.
+
+```typescript lineNumbers
+import { StepNotRegisteredError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (StepNotRegisteredError.is(error)) { // [!code highlight]
+  console.error("Step not registered:", error.stepName);
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface StepNotRegisteredError {
+  /** The name of the step function that was not found. */
+  stepName: string;
+  /** The error message. */
+  message: string;
+}
+export default StepNotRegisteredError;`}
+/>
+
+### Static Methods
+
+#### `StepNotRegisteredError.is(value)`
+
+Type-safe check for `StepNotRegisteredError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+<Callout>
+The `.is()` method works in server-side Node.js code (API routes, middleware, hooks). Inside `"use workflow"` functions, step errors arrive deserialized from the event log and won't be actual `StepNotRegisteredError` instances — use `error.message` matching instead. See the [troubleshooting page](/docs/errors/step-not-registered) for workflow-side error handling examples.
+</Callout>
+
+```typescript
+import { StepNotRegisteredError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (StepNotRegisteredError.is(error)) {
+  // error is typed as StepNotRegisteredError
+}
+```

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

@@ -0,0 +1,62 @@
+---
+title: ThrottleError
+description: Thrown when a request is rate-limited by the workflow backend.
+type: reference
+summary: Catch ThrottleError when a workflow storage operation is rate-limited (HTTP 429).
+related:
+  - /docs/api-reference/workflow-errors/workflow-world-error
+  - /docs/api-reference/workflow-errors/too-early-error
+---
+
+`ThrottleError` is thrown when a request to the workflow backend is rate-limited. It corresponds to HTTP 429 Too Many Requests semantics.
+
+The `retryAfter` property contains the number of seconds to wait before retrying.
+
+<Callout>
+The Workflow runtime handles this error automatically by backing off and retrying. You will only encounter it when interacting with world storage APIs directly.
+</Callout>
+
+```typescript lineNumbers
+import { ThrottleError } 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 (ThrottleError.is(error)) { // [!code highlight]
+    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface ThrottleError {
+  /** The number of seconds to wait before retrying. Present when the server sends a Retry-After header. */
+  retryAfter?: number;
+  /** The error message. */
+  message: string;
+}
+export default ThrottleError;`}
+/>
+
+### Static Methods
+
+#### `ThrottleError.is(value)`
+
+Type-safe check for `ThrottleError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { ThrottleError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (ThrottleError.is(error)) {
+  // error is typed as ThrottleError
+}
+```

package/docs/api-reference/workflow-errors/too-early-error.mdx

@@ -0,0 +1,62 @@
+---
+title: TooEarlyError
+description: Thrown when a request is made before the system is ready to process it.
+type: reference
+summary: Catch TooEarlyError when a world operation is attempted before the system is ready.
+related:
+  - /docs/api-reference/workflow-errors/workflow-world-error
+  - /docs/api-reference/workflow-errors/throttle-error
+---
+
+`TooEarlyError` is thrown by world implementations when a request is made before the system is ready to process it. It corresponds to HTTP 425 Too Early semantics.
+
+The `retryAfter` property contains the number of seconds to wait before retrying.
+
+<Callout>
+The Workflow runtime handles this error automatically by retrying after the specified delay. You will only encounter it when interacting with world storage APIs directly.
+</Callout>
+
+```typescript lineNumbers
+import { TooEarlyError } 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 (TooEarlyError.is(error)) { // [!code highlight]
+    console.log(`Retry after ${error.retryAfter} seconds`);
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface TooEarlyError {
+  /** Delay in seconds before the operation can be retried. Present when the server sends a Retry-After header. */
+  retryAfter?: number;
+  /** The error message. */
+  message: string;
+}
+export default TooEarlyError;`}
+/>
+
+### Static Methods
+
+#### `TooEarlyError.is(value)`
+
+Type-safe check for `TooEarlyError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { TooEarlyError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (TooEarlyError.is(error)) {
+  // error is typed as TooEarlyError
+}
+```

package/docs/api-reference/workflow-errors/workflow-not-registered-error.mdx

@@ -0,0 +1,57 @@
+---
+title: WorkflowNotRegisteredError
+description: Thrown when a workflow function is not registered in the current deployment.
+type: reference
+summary: Catch WorkflowNotRegisteredError when a workflow function cannot be found during execution.
+related:
+  - /docs/errors/workflow-not-registered
+  - /docs/api-reference/workflow-errors/step-not-registered-error
+---
+
+`WorkflowNotRegisteredError` is thrown when the runtime tries to execute a workflow function that is not registered in the current deployment. This is an infrastructure error — not a user code error. It typically means a run was started against a deployment that does not have this workflow (e.g., the workflow was renamed or moved), or there was a build/bundling issue.
+
+When this error occurs, the run fails with a `RUNTIME_ERROR` error code.
+
+```typescript lineNumbers
+import { WorkflowNotRegisteredError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowNotRegisteredError.is(error)) { // [!code highlight]
+  console.error("Workflow not registered:", error.workflowName);
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowNotRegisteredError {
+  /** The name of the workflow function that was not found. */
+  workflowName: string;
+  /** The error message. */
+  message: string;
+}
+export default WorkflowNotRegisteredError;`}
+/>
+
+### Static Methods
+
+#### `WorkflowNotRegisteredError.is(value)`
+
+Type-safe check for `WorkflowNotRegisteredError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+<Callout>
+The `.is()` method works in server-side Node.js code (API routes, middleware). When checking the error from `run.returnValue`, use `WorkflowRunFailedError.is()` and inspect `error.cause` — the underlying error is deserialized from the event log.
+</Callout>
+
+```typescript
+import { WorkflowNotRegisteredError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowNotRegisteredError.is(error)) {
+  // error is typed as WorkflowNotRegisteredError
+}
+```
+

package/docs/api-reference/workflow-errors/workflow-run-cancelled-error.mdx

@@ -0,0 +1,56 @@
+---
+title: WorkflowRunCancelledError
+description: Thrown when awaiting the return value of a cancelled workflow run.
+type: reference
+summary: Catch WorkflowRunCancelledError when awaiting run.returnValue on a run that was cancelled.
+related:
+  - /docs/api-reference/workflow-errors/workflow-run-failed-error
+  - /docs/api-reference/workflow-errors/workflow-run-not-found-error
+---
+
+`WorkflowRunCancelledError` is thrown when awaiting `run.returnValue` on a workflow run that was explicitly cancelled via `run.cancel()`. Cancelled runs do not produce a return value.
+
+You can check for cancellation before awaiting by inspecting `run.status`.
+
+```typescript lineNumbers
+import { WorkflowRunCancelledError } from "workflow/errors"
+declare const run: { status: Promise<string>; returnValue: Promise<any> }; // @setup
+
+try {
+  const result = await run.returnValue;
+} catch (error) {
+  if (WorkflowRunCancelledError.is(error)) { // [!code highlight]
+    console.log(`Run ${error.runId} was cancelled`);
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowRunCancelledError {
+  /** The ID of the cancelled run. */
+  runId: string;
+  /** The error message. */
+  message: string;
+}
+export default WorkflowRunCancelledError;`}
+/>
+
+### Static Methods
+
+#### `WorkflowRunCancelledError.is(value)`
+
+Type-safe check for `WorkflowRunCancelledError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { WorkflowRunCancelledError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowRunCancelledError.is(error)) {
+  // error is typed as WorkflowRunCancelledError
+}
+```

package/docs/api-reference/workflow-errors/workflow-run-failed-error.mdx

@@ -0,0 +1,62 @@
+---
+title: WorkflowRunFailedError
+description: Thrown when awaiting the return value of a failed workflow run.
+type: reference
+summary: Catch WorkflowRunFailedError when awaiting run.returnValue on a run that encountered a fatal error.
+related:
+  - /docs/api-reference/workflow/fatal-error
+  - /docs/api-reference/workflow-errors/workflow-run-cancelled-error
+  - /docs/api-reference/workflow-errors/workflow-run-not-found-error
+---
+
+`WorkflowRunFailedError` is thrown when awaiting `run.returnValue` on a workflow run whose status is `'failed'`. This indicates that the workflow encountered a fatal error during execution and cannot produce a return value.
+
+The `cause` property contains the underlying error with its message, stack trace, and optional error code.
+
+```typescript lineNumbers
+import { WorkflowRunFailedError } from "workflow/errors"
+declare const run: { status: Promise<string>; returnValue: Promise<any> }; // @setup
+
+try {
+  const result = await run.returnValue;
+} catch (error) {
+  if (WorkflowRunFailedError.is(error)) { // [!code highlight]
+    console.error(`Run ${error.runId} failed:`, error.cause.message);
+    if (error.cause.code) {
+      console.error("Error code:", error.cause.code);
+    }
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowRunFailedError {
+  /** The ID of the failed run. */
+  runId: string;
+  /** The underlying error that caused the failure. */
+  cause: Error & { code?: string };
+  /** The error message. */
+  message: string;
+}
+export default WorkflowRunFailedError;`}
+/>
+
+### Static Methods
+
+#### `WorkflowRunFailedError.is(value)`
+
+Type-safe check for `WorkflowRunFailedError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { WorkflowRunFailedError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowRunFailedError.is(error)) {
+  // error is typed as WorkflowRunFailedError
+}
+```

package/docs/api-reference/workflow-errors/workflow-run-not-found-error.mdx

@@ -0,0 +1,56 @@
+---
+title: WorkflowRunNotFoundError
+description: Thrown when operating on a workflow run that does not exist.
+type: reference
+summary: Catch WorkflowRunNotFoundError when performing operations on a non-existent workflow run.
+related:
+  - /docs/api-reference/workflow-errors/workflow-run-failed-error
+  - /docs/api-reference/workflow-errors/workflow-run-cancelled-error
+---
+
+`WorkflowRunNotFoundError` is thrown when performing operations on a workflow run that does not exist. This includes calling methods like `run.status`, `run.cancel()`, or awaiting `run.returnValue` on a run whose ID does not match any known workflow run.
+
+Note that `getRun(id)` itself is synchronous and will not throw — the error is raised when subsequent operations on the run object discover the run is missing.
+
+```typescript lineNumbers
+import { WorkflowRunNotFoundError } from "workflow/errors"
+declare const run: { status: Promise<string>; returnValue: Promise<any> }; // @setup
+
+try {
+  const status = await run.status;
+} catch (error) {
+  if (WorkflowRunNotFoundError.is(error)) { // [!code highlight]
+    console.error(`Run ${error.runId} does not exist`);
+  }
+}
+```
+
+## API Signature
+
+### Properties
+
+<TSDoc
+definition={`
+interface WorkflowRunNotFoundError {
+  /** The ID of the run that was not found. */
+  runId: string;
+  /** The error message. */
+  message: string;
+}
+export default WorkflowRunNotFoundError;`}
+/>
+
+### Static Methods
+
+#### `WorkflowRunNotFoundError.is(value)`
+
+Type-safe check for `WorkflowRunNotFoundError` instances. Preferred over `instanceof` because it works across module boundaries and VM contexts.
+
+```typescript
+import { WorkflowRunNotFoundError } from "workflow/errors"
+declare const error: unknown; // @setup
+
+if (WorkflowRunNotFoundError.is(error)) {
+  // error is typed as WorkflowRunNotFoundError
+}
+```

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/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/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) };
+  }
+}
+```