workflow 4.2.0-beta.71 → 4.2.0-beta.73

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/deploying/world/postgres-world.mdx

@@ -160,6 +160,12 @@ Prefix for graphile-worker queue job names. Useful when sharing a database betwe
 
 Number of concurrent workers polling for jobs. Default: `10`
 
+### `WORKFLOW_POSTGRES_MAX_POOL_SIZE`
+
+Maximum size of the internal `pg.Pool` used when `createWorld()` constructs the pool. Default: `10`
+
+For higher worker concurrency, Graphile Worker recommends setting `maxPoolSize` to `10` or `queueConcurrency + 2`, whichever is larger.
+
 ### Programmatic configuration
 
 {/* @skip-typecheck: incomplete code sample */}
@@ -170,6 +176,7 @@ const world = createWorld({
   connectionString: "postgres://user:password@host:5432/database",
   jobPrefix: "myapp_",
   queueConcurrency: 20,
+  maxPoolSize: 20, // overrides WORKFLOW_POSTGRES_MAX_POOL_SIZE
 });
 ```
 

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