workflow 5.0.0-beta.9 → 5.0.0

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

@@ -0,0 +1,538 @@
+---
+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:
+  - /worlds/upgrading-to-v5
+  - /worlds/local
+  - /worlds/postgres
+  - /worlds/vercel
+---
+
+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 complete example of how to implement the World interface with a database backend and graphile-worker for queuing. It is not optimized for scale, speed, or security and should be used as a reference to fill in those gaps in a custom World. Please see the [Postgres World docs](/worlds/postgres) for what a self-hosted World has to gate itself.
+</Callout>
+
+<Callout type="info">
+  If you have a World on the 4.x spec, see [Upgrading a World to v5](/worlds/upgrading-to-v5) for the interface and contract changes.
+</Callout>
+
+## What is a World?
+
+A World connects workflows to the infrastructure that powers them. The World interface abstracts three core responsibilities:
+
+1. **Storage**: Persists workflow runs, steps, hooks, and the event log
+2. **Queue**: Enqueues and processes workflow and step invocations
+3. **Streamer**: Manages real-time data streams between workflows and clients
+
+{/* @skip-typecheck - interface definition, not runnable code */}
+```typescript
+interface WorldCapabilities {
+  hookRetention?: {
+    active: boolean;
+  };
+  maxConcurrency?: boolean;
+  hookForceClaim?: boolean;
+  dynamicWorkflowCode?: boolean;
+}
+
+interface World extends Storage, Queue, Streamer {
+  specVersion: number;
+  capabilities?: WorldCapabilities;
+  analytics?: Analytics;
+  start?(): Promise<void>;
+  close?(): Promise<void>;
+  getEncryptionKeyForRun?(run: WorkflowRun): Promise<Uint8Array | undefined>;
+  getEncryptionKeyForRun?(runId: string, context?: Record<string, unknown>): Promise<Uint8Array | undefined>;
+  createRunId?(options?: Readonly<Record<string, unknown>>): string;
+  describeRun?(run: Readonly<Record<string, unknown>>): Record<string, string | null> | null | Promise<Record<string, string | null> | null>;
+  processExitTriggersQueueRedelivery?: boolean;
+}
+```
+
+`specVersion` is required. See [Declaring the spec version](#declaring-the-spec-version).
+
+The optional `capabilities` object advertises additional behavior, and every capability **fails closed**. A missing member means "unsupported," and the runtime keeps its conservative behavior. Set `hookRetention.active` to `true` only when the World implements hook token retention. Set `maxConcurrency` only when the World's queue supports `maxConcurrency`-limited consumption, which `WORKFLOW_SEQUENTIAL_REPLAYS=1` uses. Set `hookForceClaim` only when the World implements [hook token takeover](/worlds/upgrading-to-v5#new-optional-surface). Without it, `createHook({ experimental_force: true })` fails the workflow when it registers the hook. Set `dynamicWorkflowCode` only when the World persists `dynamicWorkflowCode` from `run_created` (and from a `run_started` that creates the run), echoes it on the created run, and returns it from `runs.get` with `resolveData: 'all'`. Without it, `start()` refuses [dynamic workflows](/docs/advanced/dynamic-workflows). The code is sent inline unless the World also implements `uploadDynamicWorkflowCode` for large definitions.
+
+[Slot-numbered event IDs](#event-id-allocation) are a contract requirement rather than a capability, so there is no flag or fallback path.
+
+The remaining optional members:
+
+- `analytics` provides metadata-only listings of runs, steps, events, hooks, waits, and attributes for observability surfaces. `workflow inspect` and the local web UI read from it, including for attribute search. See [Analytics interface](#analytics-interface-optional).
+- `start()` initializes background tasks (for example, queue polling); `close()` releases resources like connection pools and listeners.
+- `getEncryptionKeyForRun()` returns the AES-256 key used to encrypt data for a run; if it is not implemented, encryption is disabled.
+- `createRunId()` mints the ID for a new run. Implementations may embed World-specific metadata as long as the result remains a valid ULID. This is how [multi-region placement](/worlds/vercel#multi-region) works. `@workflow/world-vercel` reads `options.region` from the `start()` options and embeds a region tag. When omitted, the runtime generates a standard monotonic ULID.
+- `describeRun()` returns world-specific display fields for a run (for example, a region decoded from its ID) that tooling like `workflow inspect` renders as extra columns. It must be cheap, tolerate missing fields, and never throw.
+- `processExitTriggersQueueRedelivery` tells the runtime how to handle an exhausted replay budget. When `true`, it exits and relies on queue redelivery. When `false` or absent, it attempts to write `run_failed` and returns.
+
+### Declaring the spec version
+
+`specVersion` is the protocol version your World implements, and the version stamped on every run it creates. Export `SPEC_VERSION_CURRENT` from `@workflow/world` rather than writing a number:
+
+{/* @skip-typecheck - partial World, the other members are elided */}
+```typescript
+import { SPEC_VERSION_CURRENT } from '@workflow/world';
+
+export function createWorld(): World {
+  return {
+    specVersion: SPEC_VERSION_CURRENT,
+    // ...
+  };
+}
+```
+
+The runtime checks this before it creates or replays anything and throws if the version is outside the range it supports, naming both the range and what your World declared. A version below the range means your World allocates event IDs the runtime cannot read positions out of; above it means your World speaks a protocol this runtime has not learned.
+
+Using the constant keeps that check passing across upgrades. It moves with the `@workflow/world` version your package resolves, so a spec bump raises your declaration and the runtime's requirement together. A hard-coded number leaves your World a version behind the next bump, and the runtime rejects it. Keep `@workflow/world` in the same release channel as the `workflow` version your users install.
+
+## The event log model
+
+Workflow storage uses an **append-only event log**. All state changes happen through events. Instead of modifying runs, steps, or hooks directly, 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>>;
+    // Optional: backs setAttributes(). Omitting it means run attributes are
+    // unsupported on this World. The SDK helper no-ops with a warning.
+    experimentalSetAttributes?(runId: string, changes: AttributeChange[], options?: { allowReservedAttributes?: boolean }): Promise<ExperimentalSetAttributesResult>;
+
+    // Optional: long poll for a terminal status (see below)
+    waitForTerminalStatus?(id: string, params?: WaitForTerminalRunStatusParams): Promise<WorkflowRun>;
+  };
+
+  steps: {
+    get(runId: string, 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`.
+
+**Event data resolution:** `events.list()` and `events.create()` accept `resolveData: 'skip-step-inputs'`, and the runtime replays with it. The World may leave `input` out of `step_created` and `step_started` events, and returns everything else as for `'all'`. Treat any value other than `'none'` as `'all'`, because a World that tests `resolveData === 'all'` strips step results and breaks every replay. Map the value with `entityResolveData()` from `@workflow/world` before passing it to an entity read.
+
+**Run listing:** `runs.list({ status })` accepts a single status or an array. With an array, return runs whose status matches any listed value, and return no runs for an empty array (the same semantics as SQL `IN ()`). Treat an omitted `status` as no filter.
+
+**Hook tokens:** Hook tokens must be unique. If a `hook_created` event conflicts with an active hook or a token still reserved after its run ended, return a `hook_conflict` event and include the owner's run ID as `eventData.conflictingRunId`.
+
+Keep the owning run available for at least as long as its token remains unavailable because conflicts return that run.
+
+**Automatic hook cleanup:** When a run ends, remove its live hooks. Make each token available unless its `tokenRetentionUntil` is still in the future. A `hook_disposed` event always makes the token available immediately.
+
+### Optional: waiting for a terminal run status
+
+`await run.returnValue` must determine when a run finishes. Without help, it rereads the run every second, so it reports a run that finishes just after a read up to 1s late. Implement `runs.waitForTerminalStatus(id, { timeoutMs, signal, resolveData })` so the runtime asks once and receives an answer when the run ends.
+
+The contract is deliberately forgiving, because "wait" means something different in every store:
+
+- Resolve as soon as the run's status is terminal, returning the same entity `get` returns.
+- Resolve no later than roughly `timeoutMs` with the latest snapshot, whatever its status. **A timeout is a normal return, never an error.** A run that is still running is a valid response, and the runtime asks again.
+- `timeoutMs` is an upper bound, not a lower one. You may return a nonterminal snapshot early, and the runtime paces its own retries.
+- Fail exactly like `get`. A missing run throws `WorkflowRunNotFoundError`.
+
+Choose a waiting mechanism that fits your store. The reference Worlds use a server-side long poll (`world-vercel` holds `GET /v2/runs/:runId/status` open), `LISTEN`/`NOTIFY` (`world-postgres`), and an in-process emitter over the run files (`world-local`), respectively. Treat the notification only as a *signal*, and reread the run before responding. Back the wait with a periodic reread so a lost notification increases latency instead of causing a hang until the budget expires.
+
+Omitting the method is supported. A store with no change notification, or a deterministic simulator such as `world-sim` where a real wait would stall a virtual clock, can leave it out. The runtime continues polling `get` at intervals, and no other behavior degrades. There is no capability to declare.
+
+### Event ID allocation
+
+<Callout type="warn">
+  **Required.** Your World assigns every event ID, and every ID must be a position in its run's log. The runtime reads a position from every ID it loads and fails the run when it cannot. A World whose IDs use another format, such as a ULID, UUID, or database sequence shared across runs, cannot replay a workflow. There is no capability flag or fallback path.
+</Callout>
+
+An ID is `evnt_` followed by the event's 1-based position in that run's log, zero-padded to 26 characters, so the run's first event is `evnt_00000000000000000000000001`. Use `slotToEventId()` from `@workflow/world` to format one.
+
+Two properties have to hold, and both are about what a reader can conclude from the log:
+
+- **Uniqueness.** Two writers racing to append must not both take a position. Settle it where the store settles it, with a unique constraint on `(runId, eventId)` or a conditional write, rather than reading the maximum and adding one in your own process.
+- **Density.** Positions run from 1 with no holes, which is what lets a reader tell a complete log from a truncated one by its length alone. A writer that loses a race must re-derive its position from the store and take the next free one. Incrementing a local number after a loss leaves a permanent hole, and the runtime treats a hole as a log it cannot safely replay across.
+
+Allocate the position **at the commit** in the same operation that appends the event. This makes a reader's log a *prefix* of the run's log rather than a prefix with a hole. Nothing can land behind a position that a reader has passed. Assigning a position earlier, such as in a request handler, and committing later breaks the property that every replay depends on. This is the one case where you may need [a stale-write rejection](#optional-rejecting-a-stale-write) to compensate.
+
+#### Optional: pre-assigned positions and `noop` sealing
+
+Spec version 7 supports one alternative to allocate-at-commit for Worlds whose stores make commit-time allocation a contention bottleneck. Assign positions from a per-run atomic counter **before** the commit, and restore density at read time. With preassignment, concurrent writers hold distinct positions and never race for one. However, a writer that claims a position and stops leaves a permanent hole. A World that allocates this way MUST **seal** provably abandoned positions by writing a `noop` event into them. The seal races the original writer at the same uniqueness fence, and losing that race means the real event landed successfully. The World MUST NOT return a page with an interior hole. Return the dense prefix below the hole, and let the caller's next page continue past it after the position resolves to an event or a seal.
+
+The runtime skips `noop` events during replay. It never delivers them to a consumer or uses them to advance the deterministic clock, so a sealed log replays identically to one whose writers filled the holes. `noop` isn't user-creatable and is never sent to `events.create()`. Only your read path may write one. Worlds that allocate at the commit, through a synchronous counter or unique-constraint append, maintain perfect density and don't need sealing. `world-local` and `world-postgres` never seal, and a World that allocates at the commit is spec 7 compliant without additional work.
+
+The version a World stamps comes from `mintedSpecVersion()`: 8 by default or the slot-identity version (6) when [`WORKFLOW_SEALED_LOG=0`](/docs/configuration/runtime-tuning#workflow_sealed_log) disables it. Declare `mintedSpecVersion()` instead of a literal so your World moves with the fleet. A runtime other than the one that created a spec 7 run may read it, so readers must understand `noop` before anything stamps 7 in that environment.
+
+`events.create()` params carry `eventCount`: how many events the writer held in the log it replayed from, which is the position it expects to land on minus one. Attempt `eventCount + 1`. When that position is taken, **do not reject the write**. Advance to the next free position, commit there, and return the events occupying the positions you skipped over on the success response, in `events` with a matching `cursor` and `hasMore`. The writer merges them into its own log and replays once, rather than paying a second round trip to discover it was behind. A caller with a stale count is the normal case for a fan-out, and rejecting it would serialize writes the runtime issues in parallel.
+
+Not every write carries `eventCount`, and a World is free to skip the report read for event types whose writer never holds a log to merge it into (the step executor's `step_started`, `step_retrying`, `step_completed`, and `step_failed`, and the run-terminal `run_completed`, `run_failed`, and `run_cancelled`). Which writes send `eventCount` or `sinceCursor`, and why, is tabulated in [Events returned on a write](/docs/how-it-works/event-sourcing#events-returned-on-a-write). When a write carries both, the `sinceCursor` delta is a superset of the report, so return the delta and skip the report.
+
+### Optional: rejecting a stale write
+
+A replay writes events derived from the event log it loaded, so a write made from an event log that no longer matches the store can commit events no correct replay would produce. Rejecting one means answering `events.create()` with a `PreconditionFailedError` when the run's log already holds more events than the caller's `eventCount` says it had loaded.
+
+No World in this repository does. Reporting is the better mechanism because it removes the need to reject, not only because it costs less. A reader's log is a prefix of the run's log rather than a prefix with a hole in it, replay is deterministic on a prefix, and the writer's next write brings back what it missed. A shorter log therefore means a run that has not caught up, never a run that will decide differently.
+
+Implement rejection when your store allocates positions outside the commit and cannot reliably report the skipped span. Refusing a stale write is then safer than accepting one out of order.
+
+Two rules make this safe:
+
+- **Only reject on evidence.** If your record of a run's events is incomplete, expired, or cannot answer the question, accept the creation. A rejection must always indicate a real discrepancy because the runtime responds by discarding a replay.
+- **Accept a creation that carries no `eventCount`.** It came from a caller with no loaded log that could be stale, such as a queued step body or out-of-band writer, rather than a caller claiming the log is empty.
+
+A rejection may include the events the caller was missing as `{ events, cursor }` on the error's `details`. Include them only when you can prove that the set fully accounts for the discrepancy, isn't truncated, and contains only events from the run being written. The runtime merges them directly into the replay's event log, so incorrect data is worse than no delta. Otherwise, omit them, and the runtime performs a full reload.
+
+The runtime handles a rejection wherever it arrives. It restarts the replay in-process from a corrected log and invokes a fresh replay after spending that budget. It never retries the rejected write as-is because a replay working from a corrected log derives different events. This behavior requires no declaration or capability.
+
+## Queue interface
+
+The Queue interface handles asynchronous workflow execution, including queued step work:
+
+{/* @skip-typecheck - interface definition, not runnable code */}
+```typescript
+interface Queue {
+  getDeploymentId(): Promise<string>;
+
+  queue(
+    queueName: ValidQueueName,
+    message: QueuePayload,
+    opts?: QueueOptions
+  ): Promise<{ messageId: MessageId | null }>;
+
+  // Optional. Omit it and the runtime publishes one message at a time.
+  queueBatch?(
+    queueName: ValidQueueName,
+    messages: readonly { message: QueuePayload; opts?: QueueOptions }[]
+  ): Promise<QueueBatchResult[]>;
+
+  // Optional request/response delivery, enabled with capabilities.invoke.
+  invoke?(runId: string, payload: unknown, options?: InvokeOptions): Promise<unknown>;
+
+  createQueueHandler(
+    queueNamePrefix: QueuePrefix,
+    handler: (message: unknown, meta: { attempt: number; queueName: ValidQueueName; messageId: MessageId }) => Promise<unknown>
+  ): (req: Request) => Promise<Response>;
+}
+```
+
+### Invocation delivery
+
+Implement the optional `invoke` method to send an input to a workflow runner and
+return the runner's response. Enable `capabilities.invoke` only when your World
+supports this operation.
+
+Your World must guarantee at most one active workflow runner per `runId` across
+all worker processes. Different runs may execute concurrently. A replacement
+runner can take over after the previous runner stops.
+
+Route inputs to the active runner, or start or resume the runner when none is
+active. Call the existing `createQueueHandler` callback with
+`{ runId, invoke: true, requestId, input }`. The callback validates the input,
+waits for required event writes, and returns a result. Deliver that result to the
+original caller. Support input processing while the runner awaits step work,
+without starting a second runner for the same run.
+
+`requestId` identifies the logical input across retries and is separate from a
+queue delivery ID. `InvokeOptions` accepts an `idempotencyKey` and a `timeoutMs`
+response-wait limit.
+
+Treat invocation return values as response data, including any `timeoutSeconds`
+property. Ordinary workflow wake results use `timeoutSeconds` to schedule another
+execution.
+
+You can transport results with `InvocationOutcome`, using `{ ok: true, value }`
+for success or `{ ok: false, error: SerializedWorkflowError }` for an error. The
+helpers in `@workflow/errors/invocation` capture handler results and restore
+errors with their known Workflow classes and diagnostic fields. Return the value
+or throw the restored error from `invoke()`.
+
+Keep failures to store or deliver a response distinct from handler errors. A
+transport failure leaves processing unknown, and a handler error may follow
+committed event writes. If your World advertises `hookResumeDedup`, enforce that
+capability when retrying a hook event whose response was lost.
+
+### Batched publishing
+
+`queueBatch` is optional. Implement it when your transport can accept several messages in one round trip, and the runtime will use it to dispatch a wide `Promise.all` fan-out. A fan-out otherwise costs one round trip per branch, paid before the first branch's step body runs, so it lands directly on time-to-first-step.
+
+Its contract differs from `queue` in one important way: **a message that fails is reported, not thrown.** Return one result per input message, in input order, where `error` is set on the entries that were rejected and `retryable` says whether republishing might succeed. Reject the promise only for a request-level failure, where you cannot say what happened to any individual message.
+
+The count must match: return exactly as many results as you were given messages. The runtime rejects the whole batch if it does not, because an omitted result is indistinguishable from a message that was never published, and treating it as success would strand that step with nothing reporting an error.
+
+{/* @skip-typecheck - interface definition, not runnable code */}
+```typescript
+type QueueBatchResult =
+  | { messageId: MessageId | null; error?: undefined }
+  | { messageId: null; error: string; retryable: boolean };
+```
+
+`messageId: null` with no `error` means accepted without an ID yet, exactly as for `queue`, so callers test `error === undefined` for success rather than a non-null `messageId`.
+
+Every message targets one logical `queueName`, but you may split the batch internally — by a transport cap, or by any per-message routing dimension you derive from the payload — as long as the returned order still matches the input. The runtime passes a distinct `idempotencyKey` per message, because its recovery for both a request-level failure and a retryable entry is to republish the whole batch.
+
+### Queue names
+
+Queue names follow a specific pattern:
+- `__wkf_workflow_<name>`: Used for workflow orchestration and queued step invocations
+
+### Message payloads
+
+Workflow orchestration and step execution use the same payload. `stepId` and `stepName` identify a queued step invocation:
+
+**Workflow Invocations:**
+{/* @skip-typecheck - interface definition, not runnable code */}
+```typescript
+interface WorkflowInvokePayload {
+  runId: string;
+  stepId?: string;
+  stepName?: string;
+  traceCarrier?: Record<string, string>;  // OpenTelemetry context
+  requestedAt?: Date;
+}
+```
+
+The SDK also sends an internal `HealthCheckPayload` through the same workflow queue.
+
+### 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
+- Honor the `delaySeconds` option. Waits (`sleep()`) are delivered as ordinary delayed continuations on the workflow queue, so a World that ignores `delaySeconds` redelivers immediately and causes every sleeping run to enter a busy loop
+- Optionally honor the `region` option, a routing hint naming the region a message should be dispatched in; Worlds without a regional dimension ignore it
+
+## 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. Use this information to resolve negative `startIndex` values into absolute positions.
+
+## Analytics interface (optional)
+
+The optional `analytics` namespace provides **metadata-only** access to runs and their related records. It is intended for observability and discovery surfaces such as dashboards, `workflow inspect`, and the local web UI. Implementations can optimize these queries independently of payload storage.
+
+Tooling detects whether this namespace is available. When `world.analytics` is available, tooling prefers it for listings and attribute search. Otherwise, it uses the Storage APIs. Among the first-party Worlds, only the [Vercel World](/worlds/vercel) currently implements it. The Local and Postgres Worlds leave it `undefined`.
+
+{/* @skip-typecheck - interface definition, not runnable code */}
+```typescript
+interface Analytics {
+  runs: {
+    get(runId: string): Promise<AnalyticsRun>;
+    list(params?: AnalyticsListRunsParams): Promise<PaginatedResponse<AnalyticsRun>>;
+  };
+  attributes: {
+    // Distinct attribute keys observed on runs in the window, with run
+    // counts and first/last-seen timestamps, ordered alphabetically.
+    list(params?: AnalyticsListAttributesParams): Promise<PaginatedResponse<AnalyticsAttributeKey>>;
+  };
+  steps: {
+    get(runId: string, stepId: string): Promise<AnalyticsStep>;
+    list(params: AnalyticsListRunScopedParams): Promise<PaginatedResponse<AnalyticsStep>>;
+  };
+  events: {
+    get(runId: string, eventId: string): Promise<AnalyticsEvent>;
+    list(params: AnalyticsListEventsParams): Promise<PaginatedResponse<AnalyticsEvent>>;
+    listByCorrelationId(params: AnalyticsListEventsByCorrelationIdParams): Promise<PaginatedResponse<AnalyticsEvent>>;
+  };
+  hooks: {
+    get(hookId: string, params?: { runId?: string }): Promise<AnalyticsHook>;
+    list(params: AnalyticsListHooksParams): Promise<PaginatedResponse<AnalyticsHook>>;
+  };
+  waits: {
+    get(runId: string, waitId: string): Promise<AnalyticsWait>;
+    list(params: AnalyticsListWaitsParams): Promise<PaginatedResponse<AnalyticsWait>>;
+  };
+}
+```
+
+If you implement this namespace, observe the following requirements:
+
+- **Metadata only.** Analytics responses must not include run inputs or outputs, step data, hook tokens, or other payload data. The `Analytics*` schemas exported by `@workflow/world` define the complete set of permitted fields. Payload retrieval remains exclusively available through the Storage APIs.
+- **Attribute filters use the latest value.** `runs.list({ attributes })` evaluates each filter against the run's most recently written value for that key. A request may contain up to eight key-value pairs. Reserved `$`-prefixed attributes are valid filters, although users cannot write them directly.
+- **Time boundaries must be paired.** `startTime` and `endTime` may either both be omitted or both be supplied. Responses may include `pageInfo` describing retention and the available query window. Implementations with retention limits should return this information so tooling can present valid date ranges.
+- **Results may be eventually consistent.** Analytics records may lag live workflow state. Consumers use this namespace for discovery and listing; Storage remains the authoritative interface for current workflow state and payload access.
+
+See the [Analytics API reference](/docs/api-reference/workflow-runtime/world/analytics) for per-method parameters, row shapes, and `pageInfo` semantics.
+
+## Process-wide state
+
+Hold state that must be process-wide on `globalThis`, not at module scope.
+
+A World is loaded in one of two ways, and only one of them gives your package a
+single module instance:
+
+- **Loaded at runtime.** `WORKFLOW_TARGET_WORLD=@your-org/world-foo` is resolved
+  with `require()` at runtime, so Node's module cache dedupes it and one process
+  holds one copy.
+- **Bundled.** The host application's bundler compiles your package into its
+  server build. Bundlers key module identity on `(resource, layer)`, and a
+  framework routinely builds several server layers. Next.js compiles
+  `instrument`, app-route, `ssr` and `edge` as separate module graphs. Your
+  package is then compiled into each one, so a single process holds several
+  copies of every one of your modules, each with its own module scope.
+
+The two built-in worlds are bundled. A custom world is not today, but that is a
+property of how it is loaded rather than of how it is written, and it can change
+under you. `@workflow/world-vercel` was external until it wasn't, and every
+module-scope variable in it silently became per-copy state.
+
+So a top-level `let` or a `const` holding a `Map` is not the singleton it looks
+like:
+
+```typescript
+// Wrong: one Map per copy. Writes from one part of the app are invisible to
+// another, and a mutex like this simply stops mutually excluding.
+const locks = new Map<string, Promise<void>>();
+```
+
+Reach for `globalThis` under a `Symbol.for()` key instead, so every copy shares
+one object:
+
+```typescript
+type WorldState = { locks: Map<string, Promise<void>> };
+
+const StateKey = Symbol.for('@your-org/world-foo//locks/v1');
+const store = globalThis as typeof globalThis &
+  Record<symbol, WorldState | undefined>;
+
+const state: WorldState = (store[StateKey] ??= { locks: new Map() });
+```
+
+Version the key. Two releases of your package can end up in one process, and a
+key without a version lets an older copy read a state object it does not
+understand.
+
+Inside this repository, `globalSingleton()` from `@workflow/utils` does exactly
+this and is what the first-party worlds use; the hand-rolled form above is
+written out so a world published outside this repository does not need the
+dependency. `scripts/lint/module-scope-state.mjs` accepts either.
+
+Better still, keep the state on the World instance your `createWorld()` returns.
+Connection pools, caches, and open channels are usually per-World rather than
+per-process, and instance state cannot be duplicated by a bundler. Reserve the
+global for the few things that are genuinely process-wide: ID generators whose
+sequence must not fork, and log-once latches.
+
+## Reference implementations
+
+Study these implementations for guidance:
+
+- **[Local World](https://github.com/vercel/workflow/tree/main/packages/world-local)**: A file-system-based implementation for understanding the basics
+- **[Postgres World](https://github.com/vercel/workflow/tree/main/packages/world-postgres)**: A database-backed implementation 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**: 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"
+}
+```