workflow 5.0.0-beta.9 → 5.0.0

package/docs/worlds/upgrading-to-v5.mdx

@@ -0,0 +1,162 @@
+---
+title: Upgrading a World to v5
+description: Port a custom World implementation from the v4 spec to v5, including the interface delta, the contract changes, and the new event ID allocation rules.
+type: guide
+summary: What changed in the World spec between v4 and v5, and how to update a custom World.
+prerequisites:
+  - /worlds/building-a-world
+related:
+  - /docs/whats-new
+  - /worlds/building-a-world
+  - /worlds/postgres
+  - /worlds/vercel
+---
+
+This page is for people who implement the `World` interface themselves, or who maintain a build integration that compiles workflow files. It covers what changed between the v4 and v5 spec, which of those changes break an existing implementation, and what new surface is worth adopting.
+
+Three things are required to be a v5 World: the [interface changes](#interface-changes), the [contract changes](#contract-changes), and [event ID allocation](#event-id-allocation). The last one is the largest piece of work and the only one that is not visible from the type signatures. Everything under [new optional surface](#new-optional-surface) can wait.
+
+If your application runs on the [Vercel](/worlds/vercel), [Local](/worlds/local), or [Postgres](/worlds/postgres) World, you need nothing from this page. Those implementations ship with the SDK and are already on the v5 spec. For the application-facing changes, see [What's new in v5](/docs/whats-new).
+
+The fastest way to start is to install the World migration skill and hand the job to an agent:
+
+```bash
+npx skills add https://github.com/vercel/workflow --skill migrating-world-v4-to-v5
+```
+
+<CopyPrompt text="Upgrade this custom Workflow SDK World from the v4 spec to v5 using the migrating-world-v4-to-v5 skill. Start with event ID allocation, which is required and is not visible from the type signatures, then apply the interface and contract changes. Wire up the @workflow/world-testing conformance suite and report its output, along with anything the skill flags as a decision rather than an edit." />
+
+This is a different skill from `migrating-workflow-v4-to-v5`, which upgrades the application code. If the same repository does both, run the application one first.
+
+If you would rather work from the diff directly:
+
+<CopyPrompt text="My app uses a custom Workflow SDK World. Help me upgrade it from the v4 World spec to v5. Clone https://github.com/vercel/workflow and, on the main branch, study packages/world (the World interface and types) plus the first-party implementations in packages/world-vercel and packages/world-postgres. Run git diff stable...workflow@<the 5.x version I am upgrading to> -- packages/world packages/world-vercel packages/world-postgres (release tags are named like workflow@5.0.0; fall back to main if the tag does not exist) to see exactly what changed since the 4.x line, and use those diffs to identify the spec and implementation changes. Then port the same changes into my custom World and verify it by running a workflow end to end against it. Pay particular attention to event id allocation, which is required and is not visible from the type signatures: a v5 World assigns each event a dense, 1-based slot within its run, must settle races on a slot in the store rather than in process, and must never reject a create for a taken slot. It advances to the next free slot and returns the events it skipped." />
+
+We're working on bringing back World compatibility tests and reporting on the [Worlds page](/worlds), to make it easier to see which Workflow versions each World is compatible with.
+
+## Spec versions
+
+A World declares the protocol version it speaks on `specVersion`, and that number is stamped on every run it creates. Declare `SPEC_VERSION_CURRENT` from `@workflow/world`, not a literal:
+
+{/* @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,
+    // ...
+  };
+}
+```
+
+In v4 the runtime required that number to equal its own current version exactly. In v5 it checks the declaration against a range, `[SPEC_VERSION_CURRENT, SPEC_VERSION_MAX_SUPPORTED]`, before it creates or replays anything, and refuses a World outside it with an error naming both the range and what your World declared.
+
+The two bounds are the same version today, so exactly one is accepted. That is a consequence of [event ID allocation](#event-id-allocation) being a requirement rather than an option: a World declaring anything lower allocates IDs the runtime cannot read positions out of, and admitting it would only move the failure from startup into the middle of a run. The check is written as a range because the constants answer different questions and come apart while a version bump is staged. The ceiling rises when the runtime learns to read the next version, and the floor rises when that version becomes the one Worlds stamp.
+
+Using the constant is what keeps the check passing across upgrades. It moves with the `@workflow/world` version your package resolves, so a bump raises your declaration and the runtime's floor together, while a hard-coded number leaves your World a version behind the next bump and gets it rejected by the runtime it ships alongside. This is worth re-checking if you followed earlier guidance: `SPEC_VERSION_SUPPORTS_SLOT_IDENTITY` names the version that introduced slot-numbered IDs and is equal to `SPEC_VERSION_CURRENT` today, but declaring it pins you to a literal by another name. `@workflow/world-vercel` declared it and now declares the current version instead. Keep `@workflow/world` in the same release channel as the `workflow` version your users install.
+
+Runs carry a spec version too, and a run keeps the version it was created under for its whole life. Read the stamped version off the run rather than assuming every run matches what your World declares today. Bumping the constant does not reach runs already in your store: their version is persisted, every version test in the runtime is a lower bound, and a run's event ID scheme is resolved from what is stored.
+
+## Interface changes
+
+These break an existing v4 implementation. Each one is a signature or module-shape change your World has to follow.
+
+| Change | What to do |
+| --- | --- |
+| `getWorld()` and `createWorld()` are async | `await getWorld()`. This already worked in 4.x, so it is safe to write before upgrading. See [`getWorld`](/docs/api-reference/workflow-runtime/get-world). |
+| Stream methods moved to `world.streams.*`, with `runId` first | `writeToStream(name, runId, chunk)` becomes `streams.write(runId, name, chunk)`; likewise `writeToStreamMulti` → `streams.writeMulti`, `closeStream` → `streams.close`, `readFromStream` → `streams.get`, `getStreamChunks` → `streams.getChunks`, `listStreamsByRunId` → `streams.list`. |
+| `world.steps.get()` requires `runId` | The first argument is no longer `string \| undefined`. Pass the run ID that owns the step. |
+| `events.listByCorrelationId()` requires `runId` | A correlation ID identifies a step, hook, or wait within its run, not across runs, so the lookup is scoped to one run. Pass the run that owns the correlation ID. The same applies to `analytics.events.listByCorrelationId()`. A World that paginates by event ID also needs the scope in its cursor comparison because two runs can hold the same correlation ID. |
+| `createLocalWorld()` and `createVercelWorld()` removed | Export a `createWorld()` factory from your package instead, matching the first-party Worlds. The arguments are unchanged. |
+| Worlds are injected into host bundles at build time | Selection is static rather than resolved dynamically at runtime. Verify your World still resolves after the upgrade, and that its module graph survives bundling. |
+| `@workflow/world-local` stream chunks moved | Chunks live at `streams/chunks/<streamName>/`. Files written in the old flat layout are not read back, so local development state from 4.x can be deleted. Only relevant if your World inherited that layout. |
+
+## Contract changes
+
+These do not change any signature, so an implementation ported by types alone will compile and then behave incorrectly.
+
+**Suspension and dispatch.** The asymmetric `{ timeoutSeconds }` wait-return contract is gone. A wait is now an ordinary queue continuation with `delaySeconds`, and a suspension dispatches its waits and its steps as one parallel batch. A queue that assumed one message per suspension needs to handle the batch.
+
+**Step queue topics are retired.** The `'step'` queue kind no longer exists. Queued steps travel on the workflow topic, carrying `stepId` and `stepName` in the payload, and execute in the combined flow handler. A World that provisioned separate `__wkf_step_*` topics can drop them.
+
+**Capabilities fail closed.** The optional `capabilities` object advertises behavior the runtime otherwise assumes is absent. An unadvertised capability costs performance, never correctness, so a partial World stays correct while it catches up. The reverse is not true: advertising something you do not enforce removes a guard the runtime was relying on. Only set a flag once the behavior is implemented.
+
+**A stale replay no longer has to be refused.** v5 shipped with a `preconditionGuard` capability for a World that rejected an event creation whose snapshot was behind the log. It is gone, and nothing replaced it: allocating positions at the commit means a reader's log is a prefix rather than a prefix with a hole, replay is deterministic on a prefix, and a write reports the events it was pushed past. As a result, a stale replay costs a merge instead of a rejection. If you implemented the guard, you can delete it. `PreconditionFailedError` and the runtime's handling of it remain for a World that allocates positions away from the commit (see [Event ID allocation](#event-id-allocation)); no World in the SDK throws it.
+
+**Replay reads the event log with `resolveData: 'skip-step-inputs'`.** A World may leave `input` out of `step_created` and `step_started` events for this value, and must otherwise treat it as `'all'`. A World that tests `resolveData === 'all'`, or validates against `['none', 'all']`, strips step results or rejects the read, and every replay fails. Test for `'none'` instead, or map with `entityResolveData()` from `@workflow/world`. `@workflow/world-testing` covers this case.
+
+**Event creation can return a delta.** `events.create()` may return events alongside the one it created, in `events` with a matching `cursor` and `hasMore`. The runtime uses this to skip a follow-up `events.list` round trip on `run_started`, on step-terminal writes that carried a `sinceCursor`, and on `hook_received` writes that carried `preloadEvents`. All three are advisory: a World that returns only the created event stays correct and pays one more round trip.
+
+## Event ID allocation
+
+This is the largest change for a World implementation, and it is required.
+
+In v4 an event ID was a ULID your World minted however it liked. In v5 an event ID is its **slot**: `evnt_` followed by the event's 1-based position in that run's log, zero-padded to 26 characters, so a run's first event is `evnt_00000000000000000000000001`. Format one with `slotToEventId()` from `@workflow/world`.
+
+There is no capability to declare and no fallback path. The runtime reads a position out of every ID it loads and fails the run when it cannot. A World whose IDs are not positions will pass a type check and start runs, but it cannot replay a single workflow. The first replay fails with `Event id is not slot-numbered`.
+
+The scheme exists for what a reader can conclude from a log it just fetched: positions are dense, so a truncated log is distinguishable from a complete one by its length alone. The runtime relies on that, and it fails a run with [`CORRUPTED_EVENT_LOG`](/docs/errors/corrupted-event-log) rather than replay across a hole, so four rules bind an implementation:
+
+- **Uniqueness.** Settle a race for a position where the store settles it, with a unique constraint on `(runId, eventId)` or a conditional write, not by reading the maximum in your own process and adding one.
+- **Density.** Positions run from 1 with no holes. A writer that loses a race re-derives its position from the store instead of incrementing a local number, which would leave a permanent hole.
+- **Bump and report.** `events.create()` params carry `eventCount`, so the expected position is `eventCount + 1`. When it is taken, do not reject the write: commit at the next free position and return the events you skipped on the success response. A stale count is the normal case for a parallel fan-out, and rejecting it would serialize writes the runtime deliberately issues concurrently.
+- **Allocate at the commit.** Take the position in the same operation that appends the event, not earlier. This is what makes a reader's log a prefix of the run's log rather than a prefix with a hole in it: nothing can land behind a position a reader has already passed. A World that mints a position in a request handler and commits later breaks the property every replay depends on, and is the only kind that still has a use for a stale-write rejection.
+
+[Event ID Allocation](/worlds/building-a-world#event-id-allocation) carries the full rules, and [Event IDs](/docs/how-it-works/event-sourcing#event-ids) covers what the format means for anything that reads an ID back.
+
+One consequence is specific to an upgrade, and it is the thing to plan around.
+
+<Callout type="warn">
+  **Runs already in your store cannot be replayed by the new code.** A ULID-numbered run is not readable as positions, and the runtime refuses it rather than guessing, so there is no mixed-scheme mode and no per-run fallback. Drain those runs on your 4.x build before deploying a v5 World, or accept that the ones still in flight will fail. On a platform such as Vercel, where a run executes on the deployment that created it, this resolves itself: those runs finish on the build that started them and never meet the new code. Anywhere a single deployment serves every run, sequencing matters.
+</Callout>
+
+## New optional surface
+
+None of this is required. Each entry is a hook the runtime uses if your World provides it, and routes around if it does not.
+
+| Member | What it buys |
+| --- | --- |
+| `capabilities` | Advertises `hookRetention.active`, `hookResumeDedup`, `hookForceClaim`, `deploymentAffinity`, `maxConcurrency`, and `dynamicWorkflowCode`. See the contract note above about failing closed. Event ID allocation is *not* in here: it is a requirement, not a capability. |
+| `analytics` | A metadata-only read namespace for observability surfaces. Payload-bearing reads stay on `runs`, `steps`, `events`, and `hooks`. |
+| `runs.experimentalSetAttributes` | Backs `setAttributes()` from application code. Without it, run attributes are unavailable. |
+| `runs.cancelMany` | Bulk cancellation: up to 500 unique run IDs per request (`BULK_CANCEL_MAX_RUN_IDS`), an optional `cancelReason` of at most 512 characters, and a per-run outcome for every ID. Without it, the runtime falls back to bounded-concurrency individual cancels. |
+| `getRuntimeDeadline()` | The absolute time the current invocation will be terminated. The runtime derives its inline replay budget from this, so a host with a long function timeout gets more work per invocation. Without it, the budget is a flat two minutes. See [`WORKFLOW_V2_TIMEOUT_MS`](/docs/configuration/runtime-tuning#workflow_v2_timeout_ms). |
+| `getEnvironment()` | The environment your World's writes are attributed to. Must be synchronous, side-effect free, and match what the backend will actually apply. A wrong answer is worse than `undefined`, because callers use it to detect cross-environment mismatches. Worlds with a single tenant should omit it. |
+| `createRunId(options)` | Mints the bare run ID; the core adds the `wrun_` prefix. Return a valid ULID. You may embed World-specific metadata in it, as `@workflow/world-vercel` does with a region identifier. Read only the option keys you recognize and ignore the rest. |
+| `describeRun(run)` | World-specific display fields for observability surfaces. |
+| `getEncryptionKeyForRun()` | Returns a ready-to-use 32-byte AES-256 key. Without it, data is stored unencrypted. Two overloads: pass the `WorkflowRun` when you have it, or a `runId` plus opaque World context when the entity is not available locally. |
+| `resolveLatestDeploymentId()` | Resolves `deploymentId: 'latest'`. Only meaningful for Worlds where deployment routing exists. |
+| `close()` | Releases connection pools and listeners so CLI commands and short-lived processes can exit without `process.exit()`. |
+| `streams.streamFlushIntervalMs` | Sets the stream flush window. The v5 default is `0`, so the first chunk flushes immediately; set a value to coalesce writes again. |
+| Hook token retention | `Hook.tokenRetentionUntil` marks the earliest time a token may become available after its run ends. Keep the owning run readable at least that long, and honor `hook_disposed` as an immediate release. Declare `capabilities.hookRetention.active` only once this is implemented, since the runtime otherwise rejects retained hooks before registration. |
+| Hook resume dedup | `resumeHook()` writes `hook_received` and dispatches the queue message in parallel when the backend collapses concurrent writes carrying the same `(runId, resumeId)` onto one committed event. Declare `capabilities.hookResumeDedup` only if you enforce that constraint **and** `events.list()` returns the committed event's top-level `resumeId`. A World that omits either guarantee must leave the flag unset, which keeps the sequential path. See [Durable hook resume](/docs/changelog/lazy-hook-resume). |
+| Hook token takeover | Backs [`createHook({ experimental_force: true })`](/docs/api-reference/workflow/create-hook#take-over-a-token-another-run-holds). When a forced `hook_created` names a token another live run holds, append `hook_disposed` with `forceClaimedBy: { runId, hookId }` to the holder's log and refuse later `hook_received` writes to it, then re-point the token to the claimer and record `Hook.claimedFrom`. Refuse the takeover with an ordinary `hook_conflict` carrying `forceRefusedReason: 'victim-spec-version'` when the holder was stamped below spec version 8, and answer a `hook_received` refused by a takeover with `HookForceClaimedError` so `resumeHook()` can follow the token. Declare `capabilities.hookForceClaim` only once you give these guarantees. Without it, the runtime fails a forced `createHook()` at registration. |
+
+## If you also maintain a build integration
+
+Compiling workflow files changed independently of the storage contract.
+
+| Change | What to do |
+| --- | --- |
+| The `client` SWC transform mode was removed | It merged into `step` mode. Integrations passing `mode: 'client'` pass `mode: 'step'`. |
+| `stepEntrypoint` removed from `workflow/runtime` | Steps execute through the combined workflow handler the framework integrations generate. Custom hosts use `getWorldHandlers()`. |
+| Step, workflow and webhook bundles are ESM | Generated output moved from CJS to ESM, with a `createRequire` banner for CJS dependencies. The VM-executed workflow bundle stays CJS. The CLI's standalone output is renamed to match: `flow.mjs`, `webhook.mjs`, and `__step_registrations.mjs` in place of `flow.js`, `webhook.js`, and `step.js`. Consumers import the namespace rather than a default. |
+| `workflow/internal/private` and `@workflow/core/private` removed | These were never public API. The compiler no longer emits imports from them, so regenerate build output rather than importing them yourself. |
+| Duplicate step or workflow IDs fail the build | 4.x resolved collisions across non-exported workspace files last-write-wins. A build integration that derived IDs from a partial path may now produce build failures. |
+
+## Verifying the upgrade
+
+Run a workflow end to end against your World, not just the type checker. The contract changes above compile cleanly and fail at runtime.
+
+The cases worth covering explicitly:
+
+- A run that suspends on a step and one that suspends on a wait, to exercise the batched dispatch.
+- A parallel fan-out, so concurrent `events.create()` calls race on the same position or the same precondition.
+- A hook resumed after its run has already progressed, and a hook whose token is retained past the end of its run.
+- A stream written and read back, including a stream closed before the reader attaches.
+- A run created under an older spec version, if your World has any, read back by the new code.
+
+`@workflow/world-testing` is the shared suite the first-party Worlds run, and it now covers event ID allocation directly: `numbers events by position` fails a World whose IDs do not decode to slots, whose run is not dense from 1, or whose IDs are not in canonical form. A World padding to a different width sorts its own log incorrectly past ten events. Run it against your World before the end-to-end cases above; it turns the failure that would otherwise appear on a first replay into one line of test output.
+
+The first-party implementations in `packages/world-local` and `packages/world-postgres` are the reference for everything else, and their test suites are the closest thing to full conformance while the compatibility tests are being rebuilt.

package/docs/worlds/vercel.mdx

@@ -0,0 +1,345 @@
+---
+title: Vercel World
+description: Fully managed World for Vercel deployments with automatic storage, queuing, and authentication.
+type: integration
+summary: Deploy workflows to Vercel with fully managed storage, queuing, and authentication.
+prerequisites:
+  - /docs/deploying
+related:
+  - /docs/how-it-works/encryption
+  - /worlds/local
+  - /worlds/postgres
+---
+
+The Vercel World is a fully managed workflow backend for applications deployed on Vercel. It provides scalable storage, distributed queuing, and automatic authentication without configuration.
+
+When you deploy to Vercel, workflows automatically use the Vercel World without requiring setup.
+
+## Usage
+
+Deploy your application to Vercel:
+
+```bash
+vercel deploy
+```
+
+Vercel automatically:
+
+- Selects the Vercel World backend
+- Configures authentication using OIDC tokens
+- Provisions storage and queuing infrastructure
+- Isolates data per environment (production, preview, development)
+
+<FluidComputeCallout />
+
+## System environment variables
+
+Workflow recognizes a Vercel deployment by `VERCEL_DEPLOYMENT_ID`. Vercel exposes that variable, along with the rest of its [system environment variables](https://vercel.com/docs/environment-variables/system-environment-variables), only when the project opts in. Check this before your first deployment:
+
+1. Open your project in the [Vercel dashboard](https://vercel.com/dashboard).
+2. Go to **Settings**, then **Environment Variables**.
+3. Select the **Enable access to System Environment Variables** checkbox.
+4. Redeploy. The setting applies to new deployments; it does not change deployments that already exist.
+
+`VERCEL_DEPLOYMENT_ID` is available at both build time and runtime, and Workflow reads it in both. The build uses it to decide whether to emit Vercel Function output, including the queue-triggered flow handler, or local development output. The runtime uses it to [select the World](/docs/configuration/worlds#workflow_target_world).
+
+<Callout type="warn">
+  With the checkbox cleared, a Vercel deployment is indistinguishable from a
+  non-Vercel environment as far as Workflow is concerned: the build emits local
+  output and, unless `WORKFLOW_TARGET_WORLD` is set, the runtime selects the
+  [Local World](/worlds/local), which stores workflow state on the filesystem.
+  A deployment's filesystem is read-only, so with this default selection,
+  every run fails before its first step.
+</Callout>
+
+### Diagnosing a missing deployment ID
+
+With no `WORKFLOW_TARGET_WORLD` override, nothing in the deployment announces the wrong World, so the failure is easy to mistake for a bug in the SDK:
+
+- Runs fail with the Local World reporting that it cannot create its data directory, naming a filesystem code such as `EROFS`.
+- No runs appear in the Vercel dashboard, because none were ever created in the Vercel World.
+- The SDK's "the local (filesystem) world is running inside a Vercel deployment" warning does **not** appear. That check keys off `VERCEL_DEPLOYMENT_ID` as well, so the same missing variable hides it.
+
+To confirm, log `process.env.VERCEL_DEPLOYMENT_ID` from a deployed function. If it is undefined (as is `VERCEL`), the setting is off.
+
+Setting `WORKFLOW_TARGET_WORLD=vercel` is not a workaround. The Vercel World needs the deployment ID itself, to address queue messages to the deployment that created each run and to derive that deployment's encryption keys, so it fails with an error naming the missing `VERCEL_DEPLOYMENT_ID`. Enable the checkbox and redeploy.
+
+## Vercel platform documentation
+
+For complete details on pricing, usage limits, and included allotments on Vercel, see the official Vercel documentation:
+
+- **[Vercel Workflow](https://vercel.com/docs/workflows)**: Pricing details, concepts, and observability for Workflow on Vercel
+- **[Vercel limits](https://vercel.com/docs/limits)**: Platform-wide limits, including Workflow-specific constraints
+- **[Vercel Hobby plan](https://vercel.com/docs/plans/hobby)**: Free-tier included usage for Workflow and other resources
+
+For self-hosted deployments, use the [Postgres World](/worlds/postgres). For local development, use the [Local World](/worlds/local).
+
+## Per-run limits
+
+The Vercel World caps how large a single run can get. It caps the run's [event log](/docs/how-it-works/event-sourcing), and separately caps how many steps one run may create; see [Workflow run limits](https://vercel.com/docs/workflows/pricing#workflow-run-limits) for the current values. A run that exhausts its event budget fails with `MAX_EVENTS_EXCEEDED` and cannot be continued.
+
+Treat both caps as backstops, not budgets. Replay cost grows with the log, so a run slows down well before it fails. We recommend splitting a run into [child workflows](/cookbook/advanced/child-workflows) once a run would grow past a few thousand events. Size for that recommendation rather than for the cap.
+
+Vercel raises the per-run event and step limits on request, so an unusually large run that genuinely cannot be split is worth raising with support rather than working around.
+
+## Multi-region
+
+The Vercel World runs in every [Vercel Function region](https://vercel.com/docs/regions). Each workflow run is pinned to a single region at creation time. Its stored state, queue dispatch, and streams are all served from that region without cross-region round trips on the hot path. When your application is deployed in the run's region, as described below, step execution is also region-local.
+
+<Callout type="info">
+  Multi-region requires `workflow` version **5.0.0** or later. The 4.x
+  release line does not support region pinning. Runs created by 4.x always
+  live in `iad1`.
+</Callout>
+
+### Automatic region pinning
+
+No configuration is needed. A run is pinned to the region of the function that creates it:
+
+- Deploy your app to a single region (via [`regions`](https://vercel.com/docs/project-configuration/vercel-json#regions) in `vercel.json` or the project settings), and every run lives there.
+- Deploy to multiple regions for a globally distributed audience, and each run is pinned to the region that served the user who triggered it. Workflow data and streaming stay close to that user.
+
+### Explicit region selection
+
+To pin a specific run somewhere else, pass the `region` option to [`start()`](/docs/api-reference/workflow-api/start):
+
+```typescript
+import { start } from "workflow/api";
+import { myWorkflow } from "@/workflows/my-workflow";
+
+const run = await start(myWorkflow, [input], { region: "sfo1" });
+```
+
+<Callout type="warn">
+  The `region` option controls where the run's **data is stored** and where
+  its **queue messages are dispatched from**. It does not deploy your code
+  there. Your workflow and step functions execute in the regions your
+  application is deployed to. For execution to actually happen in the
+  specified region, your app must be deployed there through
+  [`regions`](https://vercel.com/docs/project-configuration/vercel-json#regions) in
+  `vercel.json` or the Function Regions setting in your project settings.
+  If it isn't, the run's data lives in the requested region but its steps
+  execute in the nearest region your app is deployed to.
+</Callout>
+
+### Good to know
+
+- Reads, hook resumes, and stream consumers can come from anywhere. The platform routes them to the run's region automatically.
+- Runs created by 4.x SDKs, including runs that existed before you upgraded, live in `iad1` and are unaffected by an upgrade. There is no migration.
+- **Hook tokens are currently stored in `iad1`** for every run, regardless of the run's region. The token-to-run mapping that powers [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token) and [`resumeHook()`](/docs/api-reference/workflow-api/resume-hook) lives there so tokens without region information can always be resolved. Hook *payloads* are not affected. A received payload is recorded on the run's event log, which lives in the run's region like all other run data. This token placement may become a project-level setting in the future.
+
+## Limitations
+
+- **No run migration**: A run's region is fixed at creation. Existing runs cannot be moved to a different region.
+- **Hook minimum retention**: [`experimental_minRetention`](/docs/api-reference/workflow/create-hook#keep-a-token-unavailable-after-the-run-ends) cannot exceed 30 days.
+
+## Observability
+
+Workflow observability is built into the Vercel dashboard on your project page. It respects your existing authentication and project permission settings.
+
+The Vercel World implements the optional [`world.analytics`](/docs/api-reference/workflow-runtime/world/analytics) interface, backed by the same observability data pipeline as the dashboard. Two behaviors are specific to this implementation. Listings scan faster when bounded with a `startTime`/`endTime` window, and your plan's observability lookback caps the queryable window. Requesting an older window fails with `observability-upgrade-required`, and responses include `pageInfo` with the current and maximum lookback so tools can size date ranges.
+
+The `workflow` CLI commands open a browser window deeplinked to the Vercel dashboard:
+
+```bash
+# List workflow runs (opens Vercel dashboard)
+npx workflow inspect runs --backend vercel
+
+# Launch the web UI (opens Vercel dashboard)
+npx workflow web --backend vercel
+```
+
+The CLI automatically retrieves authentication from the Vercel CLI (`vercel login`) and infers project/team IDs from your local Vercel project linking.
+
+To use the local observability UI instead of the Vercel dashboard:
+
+```bash
+npx workflow web --backend vercel --localUi
+```
+
+To override the automatic configuration:
+
+```bash
+npx workflow inspect runs \
+  --backend vercel \
+  --env production \
+  --project my-project \
+  --team my-team \
+  --authToken <your-token>
+```
+
+Learn more in the [Observability](/docs/observability) documentation.
+
+## Testing & compatibility
+
+<WorldTestingPerformance worldId="vercel" />
+
+## Configuration
+
+In a Vercel deployment, you do not configure the Vercel World yourself. The platform injects everything the runtime needs, including `VERCEL_DEPLOYMENT_ID`, `VERCEL_PROJECT_ID`, per-request OIDC tokens, and `VERCEL_DEPLOYMENT_KEY` for encryption.
+
+Do not set those platform-provided values yourself. You do have to leave [system environment variables](#system-environment-variables) enabled for the project, though: that setting is what makes `VERCEL_DEPLOYMENT_ID` available in the first place.
+
+Most users never need to set the `WORKFLOW_VERCEL_*` variables below. They are only overrides for tools running outside Vercel, such as your laptop or CI, when those tools need to inspect or test a remote Vercel Workflow project and cannot infer the project, team, token, or target environment automatically.
+
+For example, you might set them when running `workflow inspect runs --backend vercel` from CI without an interactive `vercel login`, or when running tests against a specific preview deployment. In normal local development, the CLI infers these values from your `.vercel` directory and Vercel CLI login. In a deployed Vercel function, these variables have no effect on runtime configuration, and the runtime warns if they are set there.
+
+### `WORKFLOW_VERCEL_ENV`
+
+The Vercel environment to target. Options: `production`, `preview`. Default: `production`.
+
+### `WORKFLOW_VERCEL_AUTH_TOKEN`
+
+Vercel API authentication token. Keep this secret in your environment, not in code. Falls back to `VERCEL_TOKEN`, then to your Vercel CLI login.
+
+### `WORKFLOW_VERCEL_PROJECT`
+
+Vercel project ID (`prj_...`).
+
+### `WORKFLOW_VERCEL_PROJECT_NAME`
+
+Vercel project name/slug, used for dashboard links.
+
+### `WORKFLOW_VERCEL_TEAM`
+
+Vercel team ID.
+
+### `WORKFLOW_VERCEL_BACKEND_URL`
+
+Custom base URL for the Vercel workflow API proxy. Default: `https://api.vercel.com/v1/workflow`.
+
+### `VERCEL_WORKFLOW_SERVER_URL`
+
+Custom workflow-server URL for direct runtime requests, or for the proxy to forward to via `WORKFLOW_VERCEL_BACKEND_URL`. Default: unset; normal deployments should not need this.
+
+### `WORKFLOW_SEQUENTIAL_REPLAYS`
+
+Set `WORKFLOW_SEQUENTIAL_REPLAYS=1` to guarantee that **at most one orchestrator (flow) invocation runs at a time per workflow run**. This behavior is off by default; without it, the runtime relies on idempotency and the event log to tolerate concurrent flow invocations of the same run.
+
+When enabled, each run's orchestrator messages are given their own queue topic and the flow trigger is configured with `maxConcurrency: 1`, so [Vercel Queues](https://vercel.com/docs/queues) processes replays for a given run strictly one at a time. Step executions (which ride the flow topic in the combined handler model) get a per-step topic, so steps keep full parallelism.
+
+<Callout type="warn">
+  This variable is read at **both build time and runtime**, so it must be set as a project-level environment variable that applies to your build and your deployed functions. Setting it for only one will produce an inconsistent configuration. The same applies to framework integrations that write their own queue trigger configuration instead of using `getWorkflowQueueTrigger()` from `@workflow/builders`: they only get the runtime half (per-run topics) unless they also emit `maxConcurrency: 1` on their flow trigger.
+</Callout>
+
+Because it routes each run's flow invocations through a dedicated `maxConcurrency: 1` queue topic, enabling this might lead to higher queue performance overhead.
+
+### `VERCEL_QUEUE_MAX_DELAY_SECONDS`
+
+Maximum delay, in seconds, that Workflow uses for one Vercel Queues continuation message when implementing `sleep()`. If a workflow sleeps longer than this, the runtime schedules another continuation message when the first one fires, repeating until the sleep's target time is reached. Default: `82800` (23 hours).
+
+Vercel Queues can delay messages for up to 7 days, capped by the message TTL. Because the default TTL is 24 hours, Workflow uses a 23-hour continuation hop to stay safely inside that default.
+
+### `WORKFLOW_REQUEST_TIMEOUT_MS`
+
+Per-request timeout, in milliseconds, for Vercel World HTTP calls to workflow-server. Default: `60000`. Clamped to `10000`-`120000`; a value outside that range is pulled into it and warns once.
+
+Below the floor the deadline starts canceling requests that would have succeeded, since a cold route or a large event page can take seconds, and a canceled request is redriven through the queue rather than making progress. The ceiling matches the longest a backend route holds a response. Requests that legitimately outlast it (stream reads and writes, event batches) opt out of the deadline entirely rather than relying on this value.
+
+### `WORKFLOW_MAX_CHUNKS_PER_REQUEST`
+
+Maximum stream chunks written in one Vercel World request. Larger batches are split across multiple requests. Default: `1000`. Minimum: `1`.
+
+### `WORKFLOW_STREAMS_TRANSPORT`
+
+Experimental stream-write transport capability. Default: `http`. Set `WORKFLOW_STREAMS_TRANSPORT=ws` to attempt `workflow-stream-ws/v1`. The server authoritatively accepts or declines every upgrade; a decline goes directly to HTTP for that writer lifetime. Reads remain HTTP and demand-driven.
+
+This setting does not own tenant rollout policy and does not infer server support from package versions. HTTP remains the compatibility path. The protocol route (`/websockets/v1`) is versioned independently from REST v2/v4 and persisted workflow `specVersion` values.
+
+Writes and close requests execute serially. The first operation waits up to 250 ms for an opted-in socket to open; this is an implementation-level measurement knob, not protocol semantics. If the budget expires, or the upgrade fails or is declined before acceptance, the writer uses HTTP without racing the same operation over both transports. After the socket accepts a write, a missing acknowledgement has an unknown outcome: the writer fails rather than replaying the write over HTTP and risking a duplicate append.
+
+Before routine authentication expiry or server max duration, the server sends a v1 `drain` control. The client stops sending, lets an already-admitted request receive its reply, and reconnects after the server closes with code 1001. Authentication drains re-resolve a fresh bearer. A request that was sent but receives no reply before close still has an unknown outcome and is never replayed.
+
+### `WORKFLOW_EVENTS_TRANSPORT`
+
+Opt-in WebSocket transport for workflow run events, which ships them to the Vercel World over one socket per run instead of one HTTP request each. Default: `http`.
+
+Set `WORKFLOW_EVENTS_TRANSPORT=ws` to opt in. Only that value (case-insensitive) enables the WebSocket — any other value, including unset, empty, or `http`, keeps HTTP — so a typo fails toward the default rather than enabling a transport nobody asked for.
+
+The setting is ignored when the World is configured with `projectConfig` and therefore routes through the `api-workflow` proxy: that endpoint is an HTTP-only REST gateway and does not forward a WebSocket upgrade, so events stay on HTTP. The fallback is silent, because the variable is typically set deployment-wide and a `projectConfig` World (such as the CLI) cannot act on it, and is reported once per process under `DEBUG=workflow:*`. `workflow.events.transport` on the per-write span records which transport actually carried a run.
+
+Tracing is unaffected by the choice. Each event write emits an `http POST` client span against the same `url.full`, regardless of which transport carries it. On the WebSocket path, the span is synthesized around the frame because no HTTP request is made. Attributes distinguish the transports:
+
+| Attribute | HTTP | WebSocket |
+| --- | --- | --- |
+| `workflow.events.transport` | `http` | `ws` |
+| `workflow.event.type` | the event type, e.g. `step_started` | same |
+| `network.protocol.name` | — | `websocket` |
+| `workflow.events.ws.url` | — | the socket the frame went over |
+| `workflow.events.ws.req_id` | — | per-connection request id, matching the server's log line |
+
+The WebSocket handshake is itself a span, `workflow.events.ws.connect`, so the cost of opening (or eagerly reopening) a connection is attributable rather than showing up as unexplained time inside the first write.
+
+### Programmatic configuration
+
+`createWorld()` accepts explicit API configuration. It does not read `WORKFLOW_VERCEL_*` automatically, so pass the environment values yourself when you want a configured World module:
+
+{/*@skip-typecheck: incomplete code sample*/}
+
+```typescript title="my-world.ts" lineNumbers
+import { createWorld } from "@workflow/world-vercel";
+
+export default createWorld({
+  token: process.env.WORKFLOW_VERCEL_AUTH_TOKEN,
+  projectConfig: {
+    projectId: "prj_...",
+    teamId: "team_...",
+    environment: "production",
+  },
+});
+```
+
+```bash title=".env"
+WORKFLOW_TARGET_WORLD="./my-world.ts"
+```
+
+## Versioning
+
+On Vercel, workflow runs are pegged to the deployment that started them. This means:
+
+- Existing workflow runs continue executing on their original deployment, even as new code is deployed
+- New workflow runs start on the latest deployment
+- Code changes won't break in-flight workflows
+
+This ensures long-running workflows complete reliably without being affected by subsequent deployments.
+
+For the full model, including rerunning on latest and explicit upgrade boundaries, see [Versioning](/docs/foundations/versioning).
+
+## Security
+
+### Consumer function security
+
+Workflow handler functions on Vercel are not accessible through public endpoints. During the build step, the Workflow SDK registers the combined flow handler as only reachable by [Vercel Queue](https://vercel.com/docs/queues), using the `experimentalTriggers` configuration in `.vc-config.json`:
+
+```json title=".vc-config.json (flow handler)"
+{
+  "experimentalTriggers": [
+    {
+      "type": "queue/v2beta",
+      "topic": "__wkf_workflow_*",
+      "consumer": "default",
+    }
+  ]
+}
+```
+
+Practically, this means:
+
+- You don't need to add authentication or authorization logic to workflow handlers
+- Unauthorized requests can never reach workflow or step execution
+- Only messages delivered through Vercel Queues can trigger execution
+- Handlers receive only a message ID that must be retrieved from Vercel's backend, making it impossible to craft custom payloads
+
+<Callout>
+  The Workflow SDK build step manages this configuration. If you are writing a custom integration, see [Framework integrations: Security](/docs/how-it-works/framework-integrations#security) for more details.
+</Callout>
+
+## How it works
+
+The Vercel World uses Vercel's infrastructure for workflow execution:
+
+- **Storage**: Workflow data is stored in Vercel's cloud with automatic replication and [end-to-end encryption](/docs/how-it-works/encryption)
+- **Queuing**: Steps are distributed across Vercel Functions through [Vercel Queues](https://vercel.com/docs/queues) with automatic retries and [consumer function security](#consumer-function-security)
+- **Authentication**: OIDC tokens provide secure, automatic authentication
+
+For more details, see the [Vercel Workflow documentation](https://vercel.com/docs/workflows).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workflow",
-  "version": "5.0.0-beta.9",
+  "version": "5.0.0",
   "description": "Workflow SDK - Build durable, resilient, and observable workflows",
   "main": "dist/typescript-plugin.cjs",
   "type": "module",
@@ -49,6 +49,8 @@
     "./astro": "./dist/astro.js",
     "./vite": "./dist/vite.js",
     "./nest": "./dist/nest.js",
+    "./nest/builder": "./dist/nest-builder.js",
+    "./nest/vercel-builder": "./dist/nest-vercel-builder.js",
     "./runtime": "./dist/runtime.js",
     "./observability": {
       "types": "./dist/observability.d.ts",
@@ -56,24 +58,25 @@
     }
   },
   "dependencies": {
+    "@workflow/astro": "5.0.0",
+    "@workflow/cli": "5.0.0",
+    "@workflow/core": "5.0.0",
+    "@workflow/errors": "5.0.0",
+    "@workflow/typescript-plugin": "5.0.0",
+    "@workflow/utils": "5.0.0",
     "ms": "2.1.3",
-    "@workflow/astro": "5.0.0-beta.9",
-    "@workflow/cli": "5.0.0-beta.9",
-    "@workflow/core": "5.0.0-beta.9",
-    "@workflow/errors": "5.0.0-beta.5",
-    "@workflow/typescript-plugin": "5.0.0-beta.4",
-    "@workflow/utils": "5.0.0-beta.3",
-    "@workflow/next": "5.0.0-beta.9",
-    "@workflow/nest": "5.0.0-beta.9",
-    "@workflow/nitro": "5.0.0-beta.9",
-    "@workflow/nuxt": "5.0.0-beta.9",
-    "@workflow/sveltekit": "5.0.0-beta.9",
-    "@workflow/rollup": "5.0.0-beta.9"
+    "@workflow/next": "5.0.0",
+    "@workflow/nest": "5.0.0",
+    "@workflow/nitro": "5.0.0",
+    "@workflow/nuxt": "5.0.0",
+    "@workflow/sveltekit": "5.0.0",
+    "@workflow/rollup": "5.0.0"
   },
   "devDependencies": {
     "@types/ms": "2.1.0",
     "@types/node": "22.19.0",
-    "@workflow/tsconfig": "5.0.0-beta.0"
+    "@workflow/tsconfig": "5.0.0",
+    "typescript": "^6.0.3"
   },
   "peerDependencies": {
     "@opentelemetry/api": "1"

package/docs/api-reference/workflow/experimental-set-attributes.mdx

@@ -1,63 +0,0 @@
----
-title: experimental_setAttributes
-description: Attach string metadata to workflow run for observability.
-type: reference
-summary: Use experimental_setAttributes inside a workflow or step function to set run attributes.
-prerequisites:
-  - /docs/foundations/workflows-and-steps
-related:
-  - /docs/observability/attributes
-  - /docs/api-reference/workflow/fatal-error
----
-
-Attaches string metadata to the current workflow run.
-
-<Callout>
-This API is experimental and may change before the stable attributes API is released.
-</Callout>
-
-```typescript lineNumbers
-import { experimental_setAttributes } from "workflow"
-
-export async function orderWorkflow(orderId: string) {
-  "use workflow"
-
-  await experimental_setAttributes({
-    phase: "received",
-    orderId,
-  })
-}
-```
-
-## API Signature
-
-### Parameters
-
-<TSDoc
-definition={`
-import { experimental_setAttributes } from "workflow";
-export default experimental_setAttributes;`}
-showSections={['parameters']}
-/>
-
-## Usage
-
-Call `experimental_setAttributes` from a `"use workflow"` function or a `"use step"` function. Calling it from plain application code is not supported because there is no active workflow run.
-
-Attribute values must be strings. Pass `undefined` to remove an attribute:
-
-```typescript lineNumbers
-import { experimental_setAttributes } from "workflow"
-
-export async function cleanupAttributes() {
-  "use workflow"
-
-  await experimental_setAttributes({ staleKey: undefined })
-}
-```
-
-Attribute keys must be 1-256 characters, values must be strings up to 256 bytes, and each run can have up to 64 attributes. Keys that start with `$` are reserved for framework and library code.
-
-Validation errors throw [`FatalError`](/docs/api-reference/workflow/fatal-error) and fail the run before an attribute write is attempted.
-
-When called from a workflow body, the write is recorded through an internal step. When called from a step body, the step posts the attributes directly to the World. Storage errors from step-body calls throw from `experimental_setAttributes`, so catch them inside the step if the write should be best-effort.