workflow 5.0.0-beta.35 → 5.0.0-beta.37

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

@@ -1,251 +0,0 @@
----
-title: Building a World
-description: Implement the World interface to run workflows on any custom infrastructure.
-type: guide
-summary: Build a custom World adapter to run workflows on your own infrastructure.
-prerequisites:
-  - /docs/deploying
-  - /docs/foundations/workflows-and-steps
-related:
-  - /docs/deploying/world/local-world
-  - /docs/deploying/world/postgres-world
-  - /docs/deploying/world/vercel-world
----
-
-A **World** is the abstraction that allows workflows to run on any infrastructure. It handles workflow storage, step execution queuing, and data streaming. This guide explains the World interface and how to implement your own.
-
-<Callout>
-  Before building a custom World, check the [Worlds Ecosystem](/worlds) page — there may already be a community implementation for your infrastructure.
-</Callout>
-
-<Callout type="info">
-  **Reference Implementation:** The [Postgres World source code](https://github.com/vercel/workflow/tree/main/packages/world-postgres) is a production-ready example of how to implement the World interface with a database backend and graphile-worker for queuing.
-</Callout>
-
-## What is a World?
-
-A World connects workflows to the infrastructure that powers them. The World interface abstracts three core responsibilities:
-
-1. **Storage** — Persisting workflow runs, steps, hooks, and the event log
-2. **Queue** — Enqueuing and processing workflow and step invocations
-3. **Streamer** — Managing real-time data streams between workflows and clients
-
-{/* @skip-typecheck - interface definition, not runnable code */}
-```typescript
-interface World extends Storage, Queue, Streamer {
-  start?(): Promise<void>;
-  close?(): Promise<void>;
-  getEncryptionKeyForRun?(run: WorkflowRun): Promise<Uint8Array | undefined>;
-  getEncryptionKeyForRun?(runId: string, context?: Record<string, unknown>): Promise<Uint8Array | undefined>;
-}
-```
-
-The optional `start()` method initializes background tasks (for example, queue polling). The optional `close()` method releases resources like connection pools and listeners. The optional `getEncryptionKeyForRun()` method returns the AES-256 key used to encrypt data for a run; if it is not implemented, encryption is disabled.
-
-## The Event Log Model
-
-Workflow storage is built on an **append-only event log**. All state changes happen through events — you never modify runs, steps, or hooks directly. Instead, you create events that update the materialized state.
-
-Events fall into three categories: run lifecycle events, step lifecycle events, and hook lifecycle events. See the [Event Sourcing](/docs/how-it-works/event-sourcing) documentation for a complete list of event types and their semantics.
-
-## Storage Interface
-
-The Storage interface provides read access to materialized entities and write access through events:
-
-{/* @skip-typecheck - interface definition, not runnable code */}
-```typescript
-interface Storage {
-  runs: {
-    get(id: string, params?: GetWorkflowRunParams): Promise<WorkflowRun>;
-    list(params?: ListWorkflowRunsParams): Promise<PaginatedResponse<WorkflowRun>>;
-  };
-
-  steps: {
-    get(runId: string | undefined, stepId: string, params?: GetStepParams): Promise<Step>;
-    list(params: ListWorkflowRunStepsParams): Promise<PaginatedResponse<Step>>;
-  };
-
-  events: {
-    // Create a new workflow run (runId may be client-provided or null for server generation)
-    create(runId: string | null, data: RunCreatedEventRequest, params?: CreateEventParams): Promise<EventResult>;
-    
-    // Create an event for an existing run
-    create(runId: string, data: CreateEventRequest, params?: CreateEventParams): Promise<EventResult>;
-    
-    list(params: ListEventsParams): Promise<PaginatedResponse<Event>>;
-    listByCorrelationId(params: ListEventsByCorrelationIdParams): Promise<PaginatedResponse<Event>>;
-  };
-
-  hooks: {
-    get(hookId: string, params?: GetHookParams): Promise<Hook>;
-    getByToken(token: string, params?: GetHookParams): Promise<Hook>;
-    list(params: ListHooksParams): Promise<PaginatedResponse<Hook>>;
-  };
-}
-```
-
-### Key Implementation Details
-
-**Event Creation:** When `events.create()` is called, your implementation must:
-1. Persist the event to the event log
-2. Atomically update the affected entity (run, step, or hook)
-3. Return both the created event and the updated entity
-
-**Run Creation:** For `run_created` events, the `runId` parameter may be a client-provided string or `null`. When `null`, your World generates and returns a new `runId`.
-
-**Hook Tokens:** Hook tokens must be unique. If a `hook_created` event conflicts with an existing token, return a `hook_conflict` event instead and include the active hook owner's run ID as `eventData.conflictingRunId`.
-
-**Automatic Hook Disposal:** When a workflow reaches a terminal state (`completed`, `failed`, or `cancelled`), automatically dispose of all associated hooks to release tokens for reuse.
-
-## Queue Interface
-
-The Queue interface handles asynchronous execution of workflows and steps:
-
-{/* @skip-typecheck - interface definition, not runnable code */}
-```typescript
-interface Queue {
-  getDeploymentId(): Promise<string>;
-
-  queue(
-    queueName: ValidQueueName,
-    message: QueuePayload,
-    opts?: QueueOptions
-  ): Promise<{ messageId: MessageId }>;
-
-  createQueueHandler(
-    queueNamePrefix: QueuePrefix,
-    handler: (message: unknown, meta: { attempt: number; queueName: ValidQueueName; messageId: MessageId }) => Promise<void | { timeoutSeconds: number }>
-  ): (req: Request) => Promise<Response>;
-}
-```
-
-### Queue Names
-
-Queue names follow a specific pattern:
-- `__wkf_workflow_<name>` — For workflow invocations
-- `__wkf_step_<name>` — For step invocations
-
-### Message Payloads
-
-Two types of messages flow through queues:
-
-**Workflow Invocations:**
-{/* @skip-typecheck - interface definition, not runnable code */}
-```typescript
-interface WorkflowInvokePayload {
-  runId: string;
-  traceCarrier?: Record<string, string>;  // OpenTelemetry context
-  requestedAt?: Date;
-}
-```
-
-**Step Invocations:**
-{/* @skip-typecheck - interface definition, not runnable code */}
-```typescript
-interface StepInvokePayload {
-  workflowName: string;
-  workflowRunId: string;
-  workflowStartedAt: number;
-  stepId: string;
-  traceCarrier?: Record<string, string>;
-  requestedAt?: Date;
-}
-```
-
-### Implementation Considerations
-
-- Messages must be delivered at-least-once
-- Support configurable retry policies
-- Track attempt counts for observability
-- Implement idempotency using the `idempotencyKey` option when provided
-
-## Streamer Interface
-
-The Streamer interface enables real-time data streaming:
-
-{/* @skip-typecheck - interface definition, not runnable code */}
-```typescript
-interface Streamer {
-  streamFlushIntervalMs?: number;
-
-  streams: {
-    write(
-      runId: string,
-      name: string,
-      chunk: string | Uint8Array
-    ): Promise<void>;
-
-    writeMulti?(
-      runId: string,
-      name: string,
-      chunks: (string | Uint8Array)[]
-    ): Promise<void>;
-
-    close(runId: string, name: string): Promise<void>;
-
-    get(
-      runId: string,
-      name: string,
-      startIndex?: number
-    ): Promise<ReadableStream<Uint8Array>>;
-
-    list(runId: string): Promise<string[]>;
-
-    /** Paginated snapshot of stream chunks. */
-    getChunks(
-      runId: string,
-      name: 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. */
-    getInfo(
-      runId: string,
-      name: string
-    ): Promise<{ tailIndex: number; done: boolean }>;
-  };
-}
-```
-
-Streams are identified by a combination of `runId` and `name`. Each workflow run can have multiple named streams.
-`writeMulti()` is an optional optimization for batching multiple writes.
-
-`getChunks` returns a paginated snapshot of currently available chunks (unlike `get` which returns a live `ReadableStream` that waits for new chunks). `getInfo` 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:
-
-- **[Local World](https://github.com/vercel/workflow/tree/main/packages/world-local)** — Filesystem-based, great for understanding the basics
-- **[Postgres World](https://github.com/vercel/workflow/tree/main/packages/world-postgres)** — Database-backed with graphile-worker for queuing
-
-## Testing Your World
-
-Workflow SDK includes an E2E test suite that validates World implementations. Once your World is published to npm:
-
-1. Add your world to [`worlds-manifest.json`](https://github.com/vercel/workflow/blob/main/worlds-manifest.json)
-2. Open a PR to the Workflow repository
-3. CI will automatically run the E2E test suite against your implementation
-
-Your world will then appear on the [Worlds Ecosystem](/worlds) page with its compatibility status and performance benchmarks.
-
-## Publishing Your World
-
-1. **Package your World** — Export a default World instance from your package
-2. **Publish to npm** — Publish your package to npm
-3. **Add to the manifest** — Submit a PR adding your world to [`worlds-manifest.json`](https://github.com/vercel/workflow/blob/main/worlds-manifest.json)
-4. **Document configuration** — Clearly document any required environment variables
-
-```json
-// worlds-manifest.json entry
-{
-  "package": "your-world-package",
-  "repository": "https://github.com/you/your-world",
-  "docs": "https://github.com/you/your-world#readme"
-}
-```

package/docs/deploying/meta.json

@@ -1,4 +0,0 @@
-{
-  "title": "Deploying",
-  "pages": ["...deploying", "world", "building-a-world"]
-}

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

@@ -1,105 +0,0 @@
----
-title: Local World
-description: Zero-config world bundled with Workflow for local development. No external services required.
-type: integration
-summary: Set up the Local World for zero-config workflow development on your machine.
-prerequisites:
-  - /docs/deploying
-related:
-  - /docs/deploying/world/postgres-world
-  - /docs/deploying/world/vercel-world
----
-
-The Local World is bundled with `workflow` and used automatically during local development. No installation or configuration required.
-
-To explicitly use the local world in any environment, set the environment variable:
-
-```bash
-WORKFLOW_TARGET_WORLD=local
-```
-
-## Observability
-
-The `workflow` CLI uses the local world by default. Running these commands inside your workflow project will show your local development workflows:
-
-```bash
-# List recent workflow runs
-npx workflow inspect runs
-
-# Launch the web UI
-npx workflow web
-```
-
-Learn more in the [Observability](/docs/observability) documentation.
-
-## Testing & Compatibility
-
-<WorldTestingPerformance worldId="local" />
-
-## Configuration
-
-The local world works with zero configuration, but you can customize behavior through environment variables or programmatically via `createWorld()`.
-
-### `WORKFLOW_LOCAL_DATA_DIR`
-
-Directory for storing workflow data as JSON files. Default: `.workflow-data/`
-
-### `PORT`
-
-The application dev server port. Used to enqueue steps and workflows. Default: auto-detected
-
-### `WORKFLOW_LOCAL_BASE_URL`
-
-Full base URL override for HTTPS or custom hostnames. Default: `http://localhost:{port}`
-
-Port resolution priority: `baseUrl` > `port` > `PORT` > auto-detected
-
-### `WORKFLOW_LOCAL_QUEUE_CONCURRENCY`
-
-Maximum number of concurrent queue message handlers. Default: `1000`
-
-### `WORKFLOW_LOCAL_QUEUE_MAX_VISIBILITY`
-
-Maximum number of seconds a local queue message can stay hidden before the handler rechecks the run. Default: unlimited.
-
-### `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS`
-
-Whether pending and running runs found in the data directory are re-enqueued when the world starts. Set to `0` or `false` to skip recovery and leave stale runs untouched. Default: `true`
-
-### `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
-
-Flush interval, in milliseconds, for buffered stream writes. Default: `10`.
-
-### Programmatic configuration
-
-Options passed to `createWorld()` take precedence over the environment variables above. Export the configured World from a module and point `WORKFLOW_TARGET_WORLD` at that module:
-
-```typescript title="my-world.ts" lineNumbers
-import { createWorld } from "@workflow/world-local";
-
-export default createWorld({
-  dataDir: "./custom-workflow-data",
-  port: 5173,
-  // baseUrl overrides port if set
-  baseUrl: "https://local.example.com:3000",
-  recoverActiveRuns: true, // overrides WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS
-  streamFlushIntervalMs: 10, // overrides WORKFLOW_STREAM_FLUSH_INTERVAL_MS
-});
-```
-
-```bash title=".env"
-WORKFLOW_TARGET_WORLD="./my-world.ts"
-```
-
-`createWorld()` also accepts `tag`, which scopes local storage files to a suffix. It is mainly used by test harnesses that share one `.workflow-data` directory.
-
-## Limitations
-
-The local world is designed for development, not production:
-
-- **In-memory queue** - Steps are queued in memory and do not persist across server restarts
-- **Filesystem storage** - Data is stored in local JSON files
-- **Single instance** - Cannot handle distributed deployments
-- **No authentication** - Suitable only for local development
-
-For production deployments, use the [Vercel World](/worlds/vercel) or [Postgres World](/worlds/postgres).

package/docs/deploying/world/meta.json

@@ -1,4 +0,0 @@
-{
-  "title": "Worlds",
-  "pages": ["local-world", "vercel-world", "postgres-world"]
-}

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

@@ -1,288 +0,0 @@
----
-title: Postgres World
-description: Production-ready, self-hosted world using PostgreSQL for storage and graphile-worker for job processing.
-type: integration
-summary: Deploy workflows to your own infrastructure using PostgreSQL and graphile-worker.
-prerequisites:
-  - /docs/deploying
-related:
-  - /docs/deploying/world/local-world
-  - /docs/deploying/world/vercel-world
----
-
-The Postgres World is a production-ready backend for self-hosted deployments. It uses PostgreSQL for durable storage and [graphile-worker](https://github.com/graphile/worker) for reliable job processing.
-
-Use the Postgres World when you need to deploy workflows on your own infrastructure outside of Vercel - such as a Docker container, Kubernetes cluster, or any cloud that supports long-running servers.
-
-## Installation
-
-Install the Postgres World package in your workflow project:
-
-```package-install
-@workflow/world-postgres
-```
-
-<Callout type="info">
-Use the same release channel for `workflow` and `@workflow/world-postgres`. If
-your app uses a beta or other prerelease Workflow version, install the matching
-prerelease Postgres World package, such as
-`npm install @workflow/world-postgres@beta`. Mismatched versions fail before
-starting a run with an error that says the runtime requires a World with a
-matching spec version.
-</Callout>
-
-Configure the required environment variables to use the world and point it to your PostgreSQL database:
-
-```bash title=".env"
-WORKFLOW_TARGET_WORLD="@workflow/world-postgres"
-WORKFLOW_POSTGRES_URL="postgres://user:password@host:5432/database"
-```
-
-Run the migration script to create the necessary tables in your database. Ensure `WORKFLOW_POSTGRES_URL` or `DATABASE_URL` is set when running this command:
-
-<Tabs items={["npm", "pnpm", "Yarn", "Bun"]}>
-
-<Tab value="npm">
-
-```bash
-npx --package=@workflow/world-postgres bootstrap
-```
-
-</Tab>
-
-<Tab value="pnpm">
-
-```bash
-pnpm dlx --package @workflow/world-postgres bootstrap
-```
-
-</Tab>
-
-<Tab value="Yarn">
-
-```bash
-yarn dlx --package @workflow/world-postgres bootstrap
-```
-
-</Tab>
-
-<Tab value="Bun">
-
-```bash
-bunx --package @workflow/world-postgres bootstrap
-```
-
-</Tab>
-
-</Tabs>
-
-<Callout type="info">
-The migration is idempotent and can safely be run as a post-deployment lifecycle script.
-</Callout>
-
-## Starting the World
-
-To subscribe to the graphile-worker queue, your workflow app needs to start the world on server start. Here are examples for a few frameworks:
-
-<Tabs items={["Next.js", "SvelteKit", "Nitro"]}>
-
-<Tab value="Next.js">
-
-Create an `instrumentation.ts` file in your project root:
-
-```ts title="instrumentation.ts" lineNumbers
-export async function register() {
-  if (process.env.NEXT_RUNTIME !== "edge") {
-    const { getWorld } = await import("workflow/runtime");
-    const world = await getWorld();
-    await world.start?.();
-  }
-}
-```
-
-<Callout type="info">
-Learn more about [Next.js Instrumentation](https://nextjs.org/docs/app/guides/instrumentation).
-</Callout>
-
-</Tab>
-
-<Tab value="SvelteKit">
-
-Create a `src/hooks.server.ts` file:
-
-```ts title="src/hooks.server.ts" lineNumbers
-import type { ServerInit } from "@sveltejs/kit";
-
-export const init: ServerInit = async () => {
-  const { getWorld } = await import("workflow/runtime");
-  const world = await getWorld();
-  await world.start?.();
-};
-```
-
-<Callout type="info">
-Learn more about [SvelteKit Hooks](https://svelte.dev/docs/kit/hooks).
-</Callout>
-
-</Tab>
-
-<Tab value="Nitro">
-
-Create a plugin to start the world on server initialization:
-
-```ts title="plugins/start-pg-world.ts" lineNumbers
-import { defineNitroPlugin } from "nitro/~internal/runtime/plugin";
-
-export default defineNitroPlugin(async () => {
-  const { getWorld } = await import("workflow/runtime");
-  const world = await getWorld();
-  await world.start?.();
-});
-```
-
-Register the plugin in your config:
-
-```ts title="nitro.config.ts"
-import { defineNitroConfig } from "nitropack";
-
-export default defineNitroConfig({
-  modules: ["workflow/nitro"],
-  plugins: ["plugins/start-pg-world.ts"],
-});
-```
-
-<Callout type="info">
-Learn more about [Nitro Plugins](https://v3.nitro.build/docs/plugins).
-</Callout>
-
-</Tab>
-
-</Tabs>
-
-<Callout type="info">
-The Postgres World requires a long-lived worker process that polls the database for jobs. This does not work on serverless environments. For Vercel deployments, use the [Vercel World](/worlds/vercel) instead.
-</Callout>
-
-## Observability
-
-Use the `workflow` CLI to inspect workflows stored in PostgreSQL:
-
-```bash
-# Set your database URL
-export WORKFLOW_POSTGRES_URL="postgres://user:password@host:5432/database"
-
-# List workflow runs
-npx workflow inspect runs --backend @workflow/world-postgres
-
-# Launch the web UI
-npx workflow web --backend @workflow/world-postgres
-```
-
-If `WORKFLOW_POSTGRES_URL` is not set, the CLI defaults to `postgres://world:world@localhost:5432/world`.
-
-Learn more in the [Observability](/docs/observability) documentation.
-
-## Testing & Compatibility
-
-<WorldTestingPerformance worldId="postgres" />
-
-## Configuration
-
-All configuration options can be set via environment variables or programmatically via `createWorld()`.
-
-### `WORKFLOW_POSTGRES_URL`
-
-PostgreSQL connection string used by the runtime World.
-
-Precedence: `WORKFLOW_POSTGRES_URL` > `DATABASE_URL` > `postgres://world:world@localhost:5432/world`
-
-The `bootstrap` migration command uses the same precedence.
-
-### `WORKFLOW_POSTGRES_JOB_PREFIX`
-
-Prefix for graphile-worker queue job names. Useful when sharing a database between multiple applications. Default: `workflow_`
-
-### `WORKFLOW_POSTGRES_WORKER_CONCURRENCY`
-
-Number of concurrent workers polling for jobs. Default: `50`.
-
-This value also bounds how many parent→child workflow polls can be in flight simultaneously. Every `await childRun.returnValue` inside a workflow holds a worker slot until the child run terminates — if you expect recursive or highly-fanned-out parent/child workflows, raise this ceiling above the peak number of concurrent polls. With the default of 50, the included `fibonacciWorkflow` e2e test (fib(6), ~24 concurrent polls at peak) passes; deeper recursion or larger fanouts need a correspondingly larger setting.
-
-### `WORKFLOW_POSTGRES_MAX_POOL_SIZE`
-
-Maximum size of the internal `pg.Pool` used when `createWorld()` constructs the pool. Default: the `pg` default (`10`).
-
-For higher worker concurrency, Graphile Worker recommends setting `maxPoolSize` to `10` or `queueConcurrency + 2`, whichever is larger.
-
-### `WORKFLOW_QUEUE_NAMESPACE`
-
-Queue topic namespace shared by build output and the Postgres World. Default: unset.
-
-For example, `custom` changes the queue topic prefixes from `__wkf_workflow_` and `__wkf_step_` to `__custom_wkf_workflow_` and `__custom_wkf_step_`. The value must be lowercase alphanumeric and start with a letter.
-
-### `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
-
-Flush interval, in milliseconds, for buffered stream writes. Default: `10`.
-
-### Programmatic configuration
-
-{/*@skip-typecheck: incomplete code sample*/}
-
-```typescript title="my-world.ts" lineNumbers
-import { createWorld } from "@workflow/world-postgres";
-
-export default createWorld({
-  connectionString:
-    process.env.WORKFLOW_POSTGRES_URL ?? process.env.DATABASE_URL!,
-  jobPrefix: "myapp_",
-  namespace: "myapp",
-  queueConcurrency: 50,
-  maxPoolSize: 52, // overrides WORKFLOW_POSTGRES_MAX_POOL_SIZE
-  streamFlushIntervalMs: 10,
-});
-```
-
-Options passed to `createWorld()` take precedence over the environment variables above. Export the World from a module and point `WORKFLOW_TARGET_WORLD` at that module:
-
-You can also pass an existing `pg.Pool` as `pool` instead of a connection string.
-
-```bash title=".env"
-WORKFLOW_TARGET_WORLD="./my-world.ts"
-```
-
-## How It Works
-
-The Postgres World uses PostgreSQL as a durable backend:
-
-- **Storage** - Workflow runs, events, steps, and hooks are stored in PostgreSQL tables
-- **Job Queue** - [graphile-worker](https://github.com/graphile/worker) handles reliable job processing with retries
-- **Streaming** - PostgreSQL NOTIFY/LISTEN enables real-time event distribution
-
-This architecture ensures workflows survive application restarts with all state reliably persisted. For implementation details, see the [source code](https://github.com/vercel/workflow/tree/main/packages/world-postgres).
-
-## Deployment
-
-Deploy your application to any cloud that supports long-running servers:
-
-- Docker containers
-- Kubernetes clusters
-- Virtual machines
-- Platform-as-a-Service providers (Railway, Render, Fly.io, etc.)
-
-Ensure your deployment has:
-
-1. Network access to your PostgreSQL database
-2. Environment variables configured correctly
-3. The `start()` function called on server initialization
-
-<Callout type="info">
-The Postgres World is not compatible with Vercel deployments. On Vercel, workflows automatically use the [Vercel World](/worlds/vercel) with zero configuration.
-</Callout>
-
-## Limitations
-
-- **Requires long-running process** - Must call `start()` on server initialization; not compatible with serverless platforms
-- **PostgreSQL infrastructure** - Requires a PostgreSQL database (self-hosted or managed)
-- **Not compatible with Vercel** - Use the [Vercel World](/worlds/vercel) for Vercel deployments
-
-For local development, use the [Local World](/worlds/local) which requires no external services.