workflow 5.0.0-beta.9 → 5.0.1

package/docs/worlds/local.mdx

@@ -0,0 +1,129 @@
+---
+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-configuration workflow development on your machine.
+prerequisites:
+  - /docs/deploying
+related:
+  - /worlds/postgres
+  - /worlds/vercel
+---
+
+The Local World is bundled with `workflow` and used automatically during local development. It requires no installation or configuration.
+
+To explicitly use the Local World in any environment, set this environment variable:
+
+```bash
+WORKFLOW_TARGET_WORLD=local
+```
+
+## Observability
+
+The Workflow CLI uses the Local World by default. Run these commands inside your workflow project to view 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 requires no configuration, but you can customize its behavior through environment variables or programmatically through `createWorld()`.
+
+### `WORKFLOW_LOCAL_DATA_DIR`
+
+Directory for storing workflow data as JSON files. Default: `.workflow-data/`
+
+### `PORT`
+
+The application dev server port. Used to deliver workflow queue messages to the combined flow route. 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_RUN_STATUS_POLL_INTERVAL_MS`
+
+How often a wait for a terminal run status re-reads the run file, in milliseconds. Default: `100`.
+
+`await run.returnValue` asks the World to wait for the run to finish. When the run and the caller share a process (the usual development server case), an in-process signal resolves the wait as soon as the run ends, and this interval never comes into play. The interval covers activity the signal cannot detect, primarily a second process awaiting a run over the same data directory, so it is set far below Workflow's own polling interval.
+
+### `WORKFLOW_LOCAL_HEADERS_TIMEOUT_MS`
+
+Maximum time in milliseconds to wait for a local queue handler to begin responding before redelivering the durable message. Default: `0` (no deadline).
+
+A delivery executes inline steps before the handler responds, so a deadline shorter than your longest step redelivers a healthy delivery while it is still running and executes the same step again. Set this only if you would rather a hung handler be redelivered, and set it above the longest inline work you expect.
+
+### `WORKFLOW_LOCAL_BODY_TIMEOUT_MS`
+
+Maximum gap in milliseconds between response body chunks from a local queue handler before redelivering the durable message. Default: `0` (no deadline). The same caution as `WORKFLOW_LOCAL_HEADERS_TIMEOUT_MS` applies.
+
+### `WORKFLOW_NODE_HTTP`
+
+Whether queue deliveries go out through Node's built-in `node:http` and `node:https` modules instead of the HTTP client library this World normally uses. Default: disabled. Set to `1` to switch to Node's modules. Socket pooling, keep-alive, and both timeouts above apply either way. See [`WORKFLOW_NODE_HTTP`](/docs/configuration/runtime-tuning#workflow_node_http) for what else changes.
+
+### `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_LOCAL_HOOK_RETENTION_LIMIT_DAYS`
+
+Maximum [`experimental_minRetention`](/docs/api-reference/workflow/create-hook#keep-a-token-unavailable-after-the-run-ends) accepted by the Local World, in days. Default: `30`. Set this to the same limit as your production World so oversized values fail during local development.
+
+### `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
+
+Group-commit window, in milliseconds, for the leading chunk of an idle stream. Default: `0` (dispatch immediately). A positive value holds the first chunk up to that long to collect a group, trading first-chunk latency for fewer requests. Chunks arriving while a request is in flight always coalesce into the next group regardless.
+
+### 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, // WORKFLOW_STREAM_FLUSH_INTERVAL_MS, if set, overrides this
+});
+```
+
+```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**: Workflow messages, including queued step invocations, do not persist across server restarts.
+- **Filesystem storage**: Data is stored in local JSON files.
+- **Single instance**: The Local World cannot handle distributed deployments.
+- **No authentication**: The Local World is suitable only for local development.
+
+For production deployments, use the [Vercel World](/worlds/vercel), which handles execution, persistence, multi-tenancy, scale, observability, and security for you on Vercel, or check out the [Postgres World](/worlds/postgres) - a tested reference implementation that implements the complete World spec and can be used to deploy workflows anywhere.

package/docs/worlds/meta.json

@@ -0,0 +1,10 @@
+{
+  "title": "Worlds",
+  "pages": [
+    "local",
+    "vercel",
+    "postgres",
+    "building-a-world",
+    "upgrading-to-v5"
+  ]
+}

package/docs/worlds/postgres.mdx

@@ -0,0 +1,428 @@
+---
+title: Postgres World
+description: Self-hosted reference 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:
+  - /worlds/local
+  - /worlds/vercel
+---
+
+The Postgres World is a self-hosted backend that uses PostgreSQL for durable storage and [graphile-worker](https://github.com/graphile/worker) for reliable job processing.
+
+Use the Postgres World to deploy workflows on your own infrastructure outside Vercel, such as a Docker container, Kubernetes cluster, or any cloud that supports long-running servers.
+
+<Callout type="warn">
+  The Postgres World is a **reference implementation**: it implements the
+  complete World spec and is tested, but it is not optimized for scale, speed,
+  or security, and it ships with **no authentication** on the workflow HTTP
+  routes. For production use-cases we recommend cloning it and adapting it to
+  your persistence, network stack, scale, and security requirements. If you
+  deploy it as is, you must restrict those routes yourself. Read
+  [Security](#security) first.
+</Callout>
+
+## Installation
+
+Install the Postgres World package in your workflow project:
+
+```package-install
+@workflow/world-postgres
+```
+
+<Callout type="info">
+Keep `workflow` and `@workflow/world-postgres` on the same major version and release
+cycle. If your app uses a prerelease Workflow version, install the matching prerelease Postgres
+World package. Mismatched versions fail before starting a run with an error that names the
+spec versions the runtime supports and the one the World declares.
+</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
+
+### Experimental invocation delivery
+
+Set `WORKFLOW_POSTGRES_INVOKE=1`, or pass `enableInvoke: true` to the Postgres
+World's factory, to send hook inputs to the run's executor and wait for its
+response. Invocation is off by default. Apply the migrations and upgrade
+producers and workers together before enabling it.
+
+The executor validates the hook input and writes its event before responding.
+Workflow user code can consume the event later. The World stores inputs and
+responses in `workflow.workflow_invocations`. Inserting an input and enqueueing
+a workflow execution job share one transaction. Retries also enqueue an execution
+job, including when a retained response already exists, so committed events can
+be replayed after a runner failure.
+
+With the default job prefix, Graphile uses `workflow_flows_executor` for workflow
+execution and `workflow_flows` for step jobs and health checks. Execution jobs
+use a named queue per run, `workflow_flows:<runId>:executor`. Graphile permits
+one active job on each named queue across workers. Other runs, steps, and health
+checks can run concurrently. `queueConcurrency` limits total active jobs per
+worker process and defaults to 50. A custom job prefix replaces `workflow_` in
+these names.
+
+The HTTP receiver checks each execution request against its active Graphile job
+before processing pending inputs. Updated workers and receivers move legacy
+orchestration requests to the run's named queue. Before acknowledging an execution
+job, the World finishes any input already being processed and replays newly
+committed events. These entry checks do not stop an old handler from writing
+after its job is reclaimed.
+
+The caller receives a stored return value or a restored Workflow error. Terminal
+errors are retained as outcomes; transient or unrecognized failures leave inputs
+pending for Graphile to retry. Migration 0022 preserves the meaning of responses
+stored by earlier previews. Failure to store or read a response leaves the
+processing outcome unknown. Durable resume identities deduplicate the hook event
+when response storage must be retried.
+
+A shared `LISTEN/NOTIFY` connection signals changes to pending inputs and
+responses. Notifications contain identifiers, and readers fetch data from the
+table. Use a session-capable connection for `LISTEN`. Readers fall back to polling
+at 1s intervals if notifications fail, and connection retries use a 1s backoff.
+Notification failure and recovery are logged once per transition without
+payloads or connection details.
+
+The response-wait timeout defaults to 30s and can be set with `timeoutMs`. Encoded
+inputs and outcomes are limited to 1 MiB each. A timeout does not cancel
+processing. `$retention: 0` purges invocation data and prevents late writes from
+restoring it. Callers whose result has expired receive a 410 error with code
+`INVOCATION_DATA_EXPIRED`, even if the hook event committed earlier.
+
+Automatic cleanup of other results, stopping writes from reclaimed handlers, and
+routing requests across incompatible worker versions remain unimplemented.
+
+### Server startup
+
+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:
+
+<Callout type="warn">
+This step is specific to worlds that run a background worker, such as Postgres
+World. Worlds whose queue delivers work over HTTP, including the Vercel World,
+have no worker to subscribe, so `start()` does nothing there while the import
+still adds overhead. Pulling in `workflow/runtime` from a server-startup hook puts
+the whole runtime into the cold-start path before the first request is served.
+</Callout>
+
+<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
+
+You can set all configuration options through environment variables or programmatically through `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` end-to-end test (`fib(6)`, about 24 concurrent polls at peak) passes; deeper recursion or larger fanouts need a correspondingly larger setting.
+
+### `WORKFLOW_POSTGRES_POLL_INTERVAL_MS`
+
+Milliseconds between idle job fetches per worker. Each worker polls on its own, so an idle process runs about `queueConcurrency × 1000 / pollInterval` fetches per second. Default: `500`.
+
+### `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_POSTGRES_APPLICATION_MANAGED_SHUTDOWN`
+
+Set to `1` when the application or framework coordinates shutdown and awaits `world.close()` before closing its workflow HTTP server and any caller-owned pool. Default: unset (`false`).
+
+### `WORKFLOW_POSTGRES_RUN_STATUS_POLL_INTERVAL_MS`
+
+How often a wait for a terminal run status re-reads the run, in milliseconds. Default: `1000`.
+
+`await run.returnValue` asks the World to wait for the run to finish, and the Postgres World parks that wait on a `NOTIFY` issued by the run-terminal write. This interval is only the backstop: it bounds how long a lost notification can go unnoticed, so lowering it costs a query per waiting run per interval and buys nothing while notifications are arriving.
+
+### `WORKFLOW_POSTGRES_HEADERS_TIMEOUT_MS`
+
+Maximum time in milliseconds a queue delivery waits for the workflow handler to begin responding before the delivery is failed and Graphile Worker redelivers the message. Default: `0` (no deadline).
+
+A delivery executes the workflow body inline, so the handler responds only once that work is done. A deadline shorter than your longest inline step declares a healthy delivery crashed and redelivers it while the original is still running, executing the same steps twice. Set this only if you would rather a hung handler be redelivered than hold its worker slot until the process restarts, and set it above the longest inline work you expect.
+
+### `WORKFLOW_POSTGRES_BODY_TIMEOUT_MS`
+
+Maximum gap in milliseconds between response body chunks from the workflow handler before the delivery is failed and redelivered. Default: `0` (no deadline). The same caution as `WORKFLOW_POSTGRES_HEADERS_TIMEOUT_MS` applies.
+
+### `WORKFLOW_POSTGRES_HOOK_RETENTION_LIMIT_DAYS`
+
+Maximum [`experimental_minRetention`](/docs/api-reference/workflow/create-hook#keep-a-token-unavailable-after-the-run-ends) accepted by the Postgres World, in days. Default: `30`. Set this to the same limit as your production World so oversized values fail during development.
+
+### `WORKFLOW_QUEUE_NAMESPACE`
+
+Queue topic namespace shared by build output and the Postgres World. Default: unset.
+
+For example, `custom` changes the queue topic prefix from `__wkf_workflow_` to `__custom_wkf_workflow_`. The value must be lowercase alphanumeric and start with a letter.
+
+### `WORKFLOW_STREAM_FLUSH_INTERVAL_MS`
+
+Group-commit window, in milliseconds, for the leading chunk of an idle stream. Default: `0` (dispatch immediately). A positive value holds the first chunk up to that long to collect a group, trading first-chunk latency for fewer requests. Chunks arriving while a request is in flight always coalesce into the next group regardless.
+
+### 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"
+```
+
+### Application-managed shutdown
+
+Graphile Worker responds automatically when the application is asked to shut down. If your application or framework already coordinates a broader shutdown sequence, set `WORKFLOW_POSTGRES_APPLICATION_MANAGED_SHUTDOWN=1` when selecting the package directly with `WORKFLOW_TARGET_WORLD`, or set `applicationManagedShutdown: true` in a programmatic World. Use the application's normal shutdown hook. This prevents Graphile Worker's default handler from terminating the process as soon as its queue stops. The hook must handle cleanup errors and await resources in this order:
+
+1. `world.close()`
+2. The workflow HTTP server
+3. Any caller-owned `pg.Pool`
+
+Closing the world stops new queue claims and waits for active jobs. After Graphile Worker's grace period, a pending workflow HTTP request is aborted. Graphile Worker unlocks that same row through its normal failure handling. The already-claimed delivery consumes a Graphile attempt and is retried only if its attempt budget remains; a one-attempt or final-attempt job is not retried. The shutdown handler does not insert a successor row. Because a client abort does not prove the server handler stopped, workflow and step handlers must tolerate at-least-once execution.
+
+## 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).
+
+## Security
+
+Unlike the [Vercel World](/worlds/vercel), which authenticates and [encrypts](/docs/how-it-works/encryption) workflow traffic automatically, the Postgres World does **not** automatically authenticate requests that drive workflow execution. Adding that is your responsibility and should be in place before an app using this World is used in production and reachable by untrusted clients. We also recommend [enabling encryption](/docs/how-it-works/encryption#custom-world-implementations).
+
+### Protect the queue route
+
+`POST /.well-known/workflow/v1/flow` is where the worker delivers workflow orchestration and queued step invocations. It is mounted in your application like any other route, so it is publicly reachable by default, and it accepts any request whose headers and body are well-formed: there is no signature, shared secret, or caller check. Anyone who can reach it can forge or replay a workflow or step invocation, including steps your application would only reach after its own gating. Restrict it before you expose the app.
+
+The other routes under `/.well-known/workflow/v1/` differ:
+
+- `webhook/:token`, created by [`createWebhook()`](/docs/api-reference/workflow/create-webhook), is authorized by the token in the URL and nothing else. Use [`createHook()`](/docs/api-reference/workflow/create-hook) behind your own authenticated route and [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) when you need more than that.
+- `manifest.json` responds with `404` unless the app was built with `WORKFLOW_PUBLIC_MANIFEST=1`. That variable is read at build time, so unsetting it in the runtime environment of an already-built deployment does not withdraw the manifest. Leave it unset outside of testing, because the manifest lists your workflow and step names.
+
+### Bringing your own auth
+
+Workflow does not prescribe an auth mechanism for self-hosted Worlds, so restrict the flow route at the network edge rather than inside the application:
+
+- **Keep the flow route unreachable from outside.** By default the worker delivers to a loopback address (`http://localhost:{PORT}`, or `WORKFLOW_LOCAL_BASE_URL` when set), so in the common single-process topology nothing outside the container needs to reach it. Blocking external requests to `/.well-known/workflow/v1/flow` at your ingress, reverse proxy, or firewall costs you nothing, because loopback delivery never traverses that layer. Do not block the whole `/.well-known/workflow/` prefix if you use [`createWebhook()`](/docs/api-reference/workflow/create-webhook): its `webhook/:token` route sits under the same prefix and has to stay reachable by whoever calls it.
+- **Authenticate at the proxy when the routes must cross hosts.** If your web tier and workers are separate deployments, require mTLS or a shared-secret header at the proxy in front of the application, and strip any client-supplied copy of that header at the edge.
+- **Do not gate these paths in framework middleware.** The [Next.js setup guide](/docs/getting-started/next) tells you to exclude `/.well-known/workflow/*` from your proxy matcher, because a handler that consumes the internal request body breaks execution. Adding the paths back in order to gate them reintroduces that failure mode.
+- **Do not expect the World to present a credential.** It does not sign its delivery requests or attach a secret to them, so an in-application check that requires one will reject the World's own deliveries.
+
+### Data at rest
+
+The Postgres World does not currently implement `getEncryptionKeyForRun()`, so it does not participate in Workflow's [end-to-end encryption](/docs/how-it-works/encryption): workflow and step inputs and return values, hook payloads and metadata, and stream chunks are all stored in your database in readable form. A World derived from this one can opt in by implementing that one method; see [Custom World implementations](/docs/how-it-works/encryption#custom-world-implementations). Until then, protect the database, its credentials, and its backups accordingly.
+
+The [observability UI](/docs/observability) has no authentication of its own either. If you self-host `@workflow/web` against your Postgres database, put it behind your own auth layer, because everyone who can reach it can read every run.
+
+## Deployment
+
+Deploy your application to any cloud that supports long-running servers:
+
+- Docker containers
+- Kubernetes clusters
+- Virtual machines
+- Platform-as-a-service (PaaS) providers, such as Railway, Render, and Fly.io
+
+Ensure your deployment has:
+
+- Network access to your PostgreSQL database
+- Environment variables configured correctly
+- The `start()` function called on server initialization
+- `/.well-known/workflow/v1/flow` restricted so untrusted clients cannot reach it (see [Security](#security))
+
+<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
+
+- **Reference implementation**: Tested and implements the complete World spec, but is not optimized for scale, speed, or security; a production deployment typically clones it and adapts it, or runs workers in separate processes with a more robust queuing system
+- **No built-in authentication**: The workflow HTTP routes accept any request that reaches them; you must restrict them yourself (see [Security](#security))
+- **No encryption**: Workflow and step data is stored unencrypted; the World does not currently implement [end-to-end encryption](/docs/how-it-works/encryption)
+- **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.