experimental-a2 0.19.0 → 0.20.0

package/docs/reference/05-adapters.mdx

@@ -1,351 +0,0 @@
----
-title: Adapters
-description: "Stores, schedulers, and OpenTelemetry."
----
-
-## `experimental-a2/otel`
-
-```ts
-otel(options?: { tracer?: Tracer; tracerName?: string }): A2Telemetry
-```
-
-OpenTelemetry instrumentation for a server (`@opentelemetry/api` is a peer
-dependency). Pass it as `telemetry`. Spans nest through the active context, so
-the happy path lands in one trace: request → append → drain → each handler →
-the events those handlers append. `A2Telemetry` is a one-method interface:
-anything with `span(name, attributes, fn)` works, and `otel()` is the adapter
-A2 ships. See [Watch it in traces](/server/production#watch-it-in-traces).
-
-### The span catalogue
-
-This catalogue is a contract: renames and additions are breaking for
-dashboards and are called out in the package's `CHANGELOG.md`. All spans carry
-`a2.contract` and `a2.session_id`. Core spans describe the durable runtime;
-`a2.ai.*` spans describe the built-in AI handlers.
-
-| Layer | Span | Wraps |
-| ----- | ---- | ----- |
-| Core | `a2.append` | validation + the store write (one batch) |
-| Core | `a2.drain` | one drain pass, including concurrent handlers |
-| Core | `a2.event` | one claimed dispatch, including its handler and completion |
-| Core | `a2.claim` | one `claimAvailable` store operation |
-| Core | `a2.commit` | one `completeAttempt` or `failAttempt` store operation |
-| Core | `a2.state` | one `state()` read: snapshot-plus-tail load + reducer fold |
-| Core | `a2.snapshot` | one background batch of checkpoint writes |
-| Core | `a2.redrive` | one `session.redrive()`: the store operation and starting the session's wakeup |
-| AI | `a2.ai.control` | applying an input/work report/session-close decision and preparing its returned events |
-| AI | `a2.ai.generate` | one generation handler, including Core calls and model/SDK work |
-| AI | `a2.ai.context` | constructing model messages, including tool prompt reconstruction when uncached |
-| AI | `a2.ai.compaction` | automatic summarization or the custom compaction callback |
-| AI | `a2.ai.tool` | one durable tool handler, including application execution |
-| AI | `a2.ai.ack` | waiting for a persisted work report's canonical events and control receipt |
-
-Durations include nested work: `a2.event` contains its AI handler and later
-commit, AI handlers call Core, and `a2.state` includes reducer code.
-Acknowledgements overlap control processing, claims can cover several events,
-and snapshots run in the background, so summing spans, or subtracting summed
-children, does not yield exclusive Core or AI overhead. Model and application
-I/O is included; its child spans have the detail.
-
-Attributes arrive in two waves: **at start** (passed to `span()`) and
-**mid-span** (via `handle.setAttribute`, for outcomes and counts known only
-after the work ran). A recorder must merge both; the ones you alert on are all
-mid-span.
-
-| Attribute             | Span        | When  | Values                                                |
-| --------------------- | ----------- | ----- | ----------------------------------------------------- |
-| `a2.append.source`    | `a2.append` | start | `external` \| `handler`                                |
-| `a2.append.mode`      | `a2.append` | start | `inline` \| `dispatch`                                |
-| `a2.append.types`     | `a2.append` | start | comma-joined event types                              |
-| `a2.append.count`     | `a2.append` | start | batch size                                            |
-| `a2.append.armed`     | `a2.append` | mid   | `false` when the scheduler arm failed and this append degraded to append-driven healing |
-| `a2.drain.outcome`    | `a2.drain`  | mid   | `settled` \| `busy` \| `stalled`                      |
-| `a2.drain.processed`  | `a2.drain`  | mid   | events processed this pass                            |
-| `a2.claim.outcome` | `a2.claim` | mid | `claimed` \| `busy` \| `settled` |
-| `a2.claim.count` | `a2.claim` | mid | number of claimed events, or zero |
-| `a2.commit.operation` | `a2.commit` | start | `complete` \| `fail` |
-| `a2.commit.index` | `a2.commit` | start | event log position |
-| `a2.commit.attempt` | `a2.commit` | start | durable 1-based attempt ordinal |
-| `a2.commit.outcome` | `a2.commit` | mid | `completed` \| `failed` \| `dead_lettered` \| `superseded` |
-| `a2.event.type`       | `a2.event`  | start | the event's type                                      |
-| `a2.event.index`      | `a2.event`  | start | log position                                          |
-| `a2.event.id`         | `a2.event`  | start | event id                                              |
-| `a2.event.attempt`    | `a2.event`  | start | same durable 1-based ordinal as `ctx.attempt`          |
-| `a2.event.lane`       | `a2.event`  | start | stored lane value; absent for concurrent unlaned work  |
-| `a2.event.handled`    | `a2.event`  | start | normally `true`; `false` when a custom-adapter row has no handler |
-| `a2.event.outcome`    | `a2.event`  | mid   | `processed` \| `failed` \| `dead_lettered` \| `superseded` \| `surrendered` |
-| `a2.event.aborted`    | `a2.event`  | mid   | `true` when `abortOn` fired during the run            |
-| `a2.state.reducer`    | `a2.state`  | start | the reducer's name                                    |
-| `a2.state.snapshot`   | `a2.state`  | mid   | `hit` \| `miss` \| `rejected` (schema guard discarded it) \| `memory` (served from the server's in-memory state) |
-| `a2.state.folded`     | `a2.state`  | mid   | events folded past the snapshot                       |
-| `a2.state.index`      | `a2.state`  | mid   | the frontier the returned state reflects              |
-| `a2.snapshot.reducer` | `a2.snapshot` | start | the reducer's name                                  |
-| `a2.snapshot.index`   | `a2.snapshot` | start | greatest checkpoint index in the write batch       |
-| `a2.snapshot.count`   | `a2.snapshot` | start | number of checkpoints in the write batch           |
-| `a2.redrive.index` | `a2.redrive` | start | log position of the event being redriven |
-| `a2.redrive.action` | `a2.redrive` | start | `retry` \| `skip` |
-| `a2.redrive.redriven` | `a2.redrive` | mid | `true` when the event was dead-lettered and is now resolved |
-| `a2.redrive.armed` | `a2.redrive` | mid | `false` when the scheduler arm failed and the wakeup degraded to append-driven healing |
-| `a2.ai.control.type` | `a2.ai.control` | start | `ai.control.requested` \| `ai.work.reported` \| `ai.session.closed` |
-| `a2.ai.control.id` | `a2.ai.control` | start | triggering event id |
-| `a2.ai.control.attempt` | `a2.ai.control` | start | durable 1-based attempt ordinal |
-| `a2.ai.generate.request_id` | `a2.ai.generate` | start | generation request event id |
-| `a2.ai.generate.attempt` | `a2.ai.generate` | start | durable 1-based attempt ordinal |
-| `a2.ai.context.request_id` | `a2.ai.context` | start | generation request event id |
-| `a2.ai.context.phase` | `a2.ai.context` | start | `generation` \| `refresh` \| `tool` |
-| `a2.ai.compaction.request_id` | `a2.ai.compaction` | start | generation request event id |
-| `a2.ai.compaction.generation_id` | `a2.ai.compaction` | start | generation attempt id |
-| `a2.ai.compaction.policy` | `a2.ai.compaction` | start | `automatic` \| `custom` |
-| `a2.ai.tool.request_id` | `a2.ai.tool` | start | originating generation request event id |
-| `a2.ai.tool.call_id` | `a2.ai.tool` | start | tool call id |
-| `a2.ai.tool.name` | `a2.ai.tool` | start | tool name |
-| `a2.ai.tool.attempt` | `a2.ai.tool` | start | durable 1-based attempt ordinal |
-| `a2.ai.ack.request_id` | `a2.ai.ack` | start | reporting worker event id |
-| `a2.ai.ack.report_id` | `a2.ai.ack` | start | work report event id, matching the control span's id |
-
-- Drain outcomes: `settled` means nothing actionable is left; `busy` means live
-  per-event claims or a failed event's retry hold remain; `stalled` means a
-  caught failure in this drain needs a later retry.
-- A failing handler marks its `a2.event` span with the exception and error
-  status. Alert on `a2.event.outcome = dead_lettered`. A dead-lettered event
-  blocks only later events in its lane, until `session.redrive()` resolves it;
-  other lanes stay eligible.
-- `superseded` means a stale completion or failure did not change the log.
-
-## `experimental-a2/store-postgres`
-
-`postgres({ connectionString })` returns an `A2Store` on Postgres; pass
-`client` to inject your own pool. See [Postgres](/server/production#postgres)
-for setup.
-
-- Without `listenConnectionString`, a live stream polls with an adaptive
-  cadence: every 25ms while the session is producing events, backing off to
-  two seconds when it goes quiet. After a quiet period, an update from another
-  client can take up to the idle interval plus query latency to arrive.
-- A client's own `push()` refreshes its idle stream immediately from the
-  current cursor, even when the write and stream routes run in different
-  invocations. A WebSocket push wakes the attached stream without reopening
-  the socket.
-- With `listenConnectionString`, notifications arrive after commit, and a
-  reconnect catches up from the cursor. Native event and presence
-  subscriptions also reconcile every ten seconds.
-
-## `experimental-a2/store-redis`
-
-`redis({ url })` returns an `A2Store` that keeps each session as a Redis
-Stream; pass `client` to inject your own. See
-[Redis](/server/production#redis-recommended) for setup and per-command costs.
-
-- Every write publishes a wake-up, so live streams are push-driven, not
-  polled.
-- A wake-up is disposable: a safety re-read recovers a lost one within ten
-  seconds.
-
-## `experimental-a2/store-redis-http`
-
-`redisHttp({ url, token })` returns the same Redis store over `fetch`, for
-providers that expose only a REST API, such as Upstash. See
-[Redis](/server/production#redis-recommended) for setup and the trust warning.
-
-- Live events and presence use Upstash's HTTP `SUBSCRIBE` endpoint (SSE), with
-  the same URL and token. Each active channel holds one outbound HTTP
-  subscription per store instance, shared by its local viewers and closed when
-  the last viewer leaves.
-- Writes publish their wake-ups in the same Redis script as the append. A
-  rejected notification does not fail the applied write.
-- Idle event streams re-read every ten seconds to recover missed
-  notifications. Subscriptions reconnect on their own and catch up from the
-  event cursor.
-- After a reconnect, A2 re-reads the current presence fields and clears fields
-  deleted during the gap, so presence may repeat its latest values. Updates
-  received during that read take precedence.
-- If the subscribe endpoint answers 404, 405, or 501, events and presence use
-  adaptive polling instead, from 25ms to two seconds while idle.
-
-## `experimental-a2/scheduler-vercel`
-
-`vercelQueues(options?)` returns an `A2Scheduler` backed by Vercel Queues.
-
-```ts server/scheduler-vercel.ts
-import { vercelQueues } from 'experimental-a2/scheduler-vercel'
-
-export const scheduler = vercelQueues()
-```
-
-| Option | Type | Default |
-| --- | --- | --- |
-| `topic` | `string` matching `[A-Za-z0-9_-]+` | `'a2'` |
-| `deploymentId` | `string \| null` | `VERCEL_DEPLOYMENT_ID` |
-| `transport` | `QueueTransport` | lazy `@vercel/queue` client |
-| `clock` | `{ now(): Date }` | system clock |
-
-- `deploymentId` passes to the Queue SDK unchanged and applies to every task,
-  recovery watchdogs included. Omit it for `VERCEL_DEPLOYMENT_ID`, pass an ID
-  to target that deployment, or pass `null` for deploymentless delivery.
-  Publishing and consuming clients must use the same deployment scope.
-- One configured client handles sends, payload fetches, acknowledgements, and
-  visibility changes; callback contents never choose the client.
-- Pinned tasks stay with their target deployment after another is promoted.
-  Deploymentless delivery lets Vercel choose an eligible consumer, not the
-  latest production deployment; every eligible consumer must use
-  `deploymentId: null` and stay compatible with pending tasks and session work.
-- Tasks are retained for seven days, Vercel Queues' maximum. A delay goes out
-  as asked; Vercel Queues refuses one longer than the retention.
-- `transport` and `clock` are advanced injection seams for tests and custom
-  delivery. An injected transport receives the topic, an exact
-  `SchedulerTask`, and send options, and owns its provider configuration;
-  `deploymentId` configures only the built-in client.
-
-See [Vercel Queues](/server/production#vercel-queues-recommended).
-
-## `experimental-a2/scheduler-qstash`
-
-`qstash(options?)` returns an `A2Scheduler` backed by QStash HTTP delivery.
-Vercel Queues remains the recommended default on Vercel; use QStash for a
-scheduler that calls a stable public endpoint.
-
-```ts server/scheduler-qstash.ts
-import { qstash } from 'experimental-a2/scheduler-qstash'
-
-export const scheduler = qstash()
-```
-
-| Option | Type | Default |
-| --- | --- | --- |
-| `url` | `string` | conventional local or Vercel callback; required for process-less runtimes, other production, and custom routes |
-| `token` | `string` | `QSTASH_TOKEN` |
-| `currentSigningKey` | `string` | `QSTASH_CURRENT_SIGNING_KEY` |
-| `nextSigningKey` | `string` | `QSTASH_NEXT_SIGNING_KEY` |
-| `headers` | `Readonly<Record<string, string>>` | no additional callback headers |
-| `client` | `QStashPublishingClient` | lazy `@upstash/qstash` client |
-| `retries` | non-negative integer | the QStash provider default |
-| `maxBodyBytes` | positive integer | `1_048_576` (1 MiB) for callbacks and reserved outbound bodies |
-| `transport` | `QStashTransport` | lazy `@upstash/qstash` client and receiver |
-| `clock` | `{ now(): Date }` | system clock |
-
-Mount the application handler once and pass every server that shares the
-scheduler:
-
-```ts app/api/a2/scheduler/route.ts
-import { billingServer, ordersServer, scheduler } from '@/server'
-
-export const POST = scheduler.handler(ordersServer, billingServer)
-```
-
-**Callback URL.** An explicit `url` always wins. Otherwise:
-
-- Vercel production: `https://${VERCEL_PROJECT_PRODUCTION_URL}/api/a2/scheduler`.
-  Preview: `https://${VERCEL_BRANCH_URL}/api/a2/scheduler`. Both are moving
-  aliases, so pending tasks can reach later deployments on the same URL.
-- A runtime that exposes `process.env`, outside `NODE_ENV=production`:
-  `http://localhost:${PORT ?? 3000}/api/a2/scheduler`, with `devMode: true` on
-  the SDK client and receiver. `QSTASH_DEV` is not required, and
-  `QSTASH_DEV=false` does not disable it. `PORT` must be an integer from 1
-  through 65535; `QSTASH_DEV_PORT` configures the local QStash server, not the
-  callback.
-- Automatic local startup needs `@upstash/qstash` 2.11.0 or newer in Node.js;
-  the lazy transport starts it on the first publish or verification. An Edge
-  runtime that exposes `process.env` infers the local URL but must start the
-  development server separately.
-- Non-Vercel production, process-less runtimes, custom hosts or paths, ports
-  not available through `PORT`, and Docker networking need an explicit
-  absolute URL.
-- Outside production, an explicit URL leaves SDK development mode to
-  `QSTASH_DEV` or a manual `QSTASH_URL` plus credentials. In production, A2
-  passes `devMode: false`.
-
-**Options.**
-
-- `headers`: static headers on every callback delivery, recovery successors
-  included. Validated and snapshotted when `qstash()` runs; A2 asks QStash to
-  redact every value from its dashboard and API, but QStash still receives,
-  stores, and delivers them. Names are case-insensitive. Reserved:
-  provider-owned `Upstash-*`, `Content-Type*`, HTTP framing headers, and A2's
-  managed Vercel identity headers.
-- `client`: the structural `publishJSON(...)` part of a configured
-  `@upstash/qstash` `Client`, for its API endpoint, publish-request retry
-  policy, or telemetry. Not combinable with `token` or `transport`; A2 still
-  creates the `Receiver` lazily from the signing keys. Put callback credentials
-  in `headers`, since client-global callback headers and redaction are outside
-  A2's merge contract. The client receives raw callback credentials, including
-  an automatic preview identity, and must honor per-publish redaction.
-- `transport`, `clock`: advanced injection seams for tests and custom delivery.
-  A `QStashTransport` implements `publish(request)` and `verify(request)`.
-  Publish requests carry the callback `url`, a complete `SchedulerTask` body
-  (plus provider-private generation metadata for store-outage successors),
-  optional `headers` and `redact.header` names, an optional Unix-seconds
-  `notBefore`, and a deterministic `deduplicationId`; preserve the body,
-  deliver every header, and apply every redaction. Verify requests carry the
-  signature, raw body, exact callback URL, and optional Upstash region.
-- `retries`: omitted, QStash uses its provider default; an explicit value is
-  forwarded. Every delivery attempt is billable.
-- `maxBodyBytes`: the adapter reserves room for a task's largest possible
-  store-outage lineage before its initial publish, so an accepted task never
-  exceeds the limit later. Raise it for a larger paid-plan payload limit. Keep
-  one value across every deployment that receives this URL: a lower value can
-  return a non-retryable 489 for a task an older value accepted.
-
-**The route.**
-
-- Must be reachable by the selected QStash server after any platform edge
-  authentication; the development server calls localhost directly.
-- Reads the raw body once and verifies `Upstash-Signature`, the exact URL, and
-  `Upstash-Region` before parsing or touching a server. Missing or invalid
-  signatures return 401.
-- A signed malformed envelope, or a declared or streamed body over
-  `maxBodyBytes`, returns 489 with `Upstash-NonRetryable-Error: true`.
-- Returns 200 when settled; when busy or stalled, after a durable successor
-  watchdog exists, so each caught failure gets a fresh message and a fresh
-  per-message retry budget. Append tasks return 200 after their fixed-id append
-  succeeds and any recovery watchdog for pending handler work is durable; clear
-  tasks after their conditional clear and its deletion finish.
-- A retryable store outage hands drain, append, and clear tasks to a fresh
-  successor before acknowledging: 30 seconds, times four per signed
-  generation, capped at one day. The generation keeps increasing past the cap,
-  so each handoff gets a new deduplication id, and duplicate deliveries of one
-  generation publish the same successor.
-- Unknown contracts, missing scheduler configuration, schema failures, and
-  successor publish failures keep the delivery retryable.
-
-**Delivery.**
-
-- At least once, so handler side effects need idempotency keys. QStash's
-  documented 10-minute deduplication window can reduce duplicate watchdogs but
-  is not part of A2's correctness model; stable scheduled-event ids keep timer
-  redelivery safe after it.
-- During a prolonged outage where QStash cannot reach the callback, nothing
-  publishes a successor: monitor the DLQ and redrive.
-- One-shot delays are capped at 7 days on free plans and 1 year on usage-based
-  plans, with no fixed maximum on fixed plans. Leave one second of margin at a
-  plan maximum: `notBefore` uses whole Unix seconds.
-- Carries both recovery watchdogs and `session.schedule` tasks.
-
-**Protected previews.** For an inferred preview callback, each publish
-forwards the invocation's `x-vercel-oidc-token` as
-`x-vercel-trusted-oidc-idp-token`, with redaction requested, when it is a
-parseable JWT that expires at least 60 seconds after the task's first due time,
-so a matching Vercel Trusted Sources rule can admit the first delivery. QStash
-still receives it. This is opportunistic: missing, malformed, and near-expiry
-tokens fall back to an ordinary publish; an explicit `url` opts out; inferred
-production and local callbacks never forward it; and QStash reuses the stored
-header on retries, so delayed tasks and retries can outlive it. When every
-protected delivery must stay authorized, use an explicit automation bypass
-through `headers` (pending messages keep the captured value after rotation) or
-public ingress. Signature verification still applies after the edge-access
-check.
-
-See [QStash](/server/production#qstash).
-
-## Scheduler send errors
-
-Both built-in adapters preserve the original provider error from a rejected
-send.
-
-- Terminal: a recognized definite 4xx status or error, except 408, 409, 425,
-  and 429. The Vercel adapter also treats the SDK's name-only
-  `BadRequestError`, `UnauthorizedError`, and `ForbiddenError` as terminal.
-- Retryable: 408, 409, 425, 429, 5xx responses, network failures, and errors
-  with no recognized status.
-- The Vercel adapter's native duplicate-message error is success.
-- A2's durable AI tool execution uses this private classification. Direct
-  `session.schedule()` calls still reject with the original error object.

package/docs/server/05-production.mdx

@@ -1,323 +0,0 @@
----
-title: Production
-description: Choose a durable store, add a scheduler for recovery and timers, and know what to do when an event dead-letters.
----
-
-## 1. Choose a store
-
-```ts server/orders.ts
-import { createServer } from 'experimental-a2/server'
-import { redis } from 'experimental-a2/store-redis'
-import { orders } from '@/contracts'
-
-export const ordersServer = createServer({
-  contract: orders,
-  store: redis({ url: process.env.REDIS_URL }),
-  handlers: {
-    /* ... */
-  },
-})
-```
-
-| Entry point | Backend | Use it for |
-| --- | --- | --- |
-| `experimental-a2/store-redis` | Redis | Production (recommended) |
-| `experimental-a2/store-redis-http` | Redis over a REST API | Production |
-| `experimental-a2/store-postgres` | Postgres | Production |
-| `experimental-a2/store-sqlite` | SQLite | Development: the default, at `.a2/dev.db` |
-| `experimental-a2/store-memory` | In-memory | Tests: the default when `NODE_ENV=test` |
-
-When you omit `store`, development gets SQLite (state survives `next dev`
-restarts) and tests get memory. Production has no default, on purpose: the
-server throws `STORE_NOT_CONFIGURED` at startup rather than write events to a
-filesystem that evaporates.
-
-The store holds A2's session histories. It does not connect A2 to your
-application tables; see [Sessions and your database](/contract/sessions#sessions-and-your-database).
-
-### Redis (recommended)
-
-`redis({ url })` from `experimental-a2/store-redis` stores each session as a
-Redis Stream and streams push-natively, so connections scale with your
-processes, not your audience. `ioredis` is an optional peer dependency; pass
-`url` or inject a client. It works on single instances and non-cluster
-providers such as Upstash, where durability is on by default.
-
-On providers that bill per command, such as Upstash, appending an event with a
-handler and running it takes 24 commands, and an idle live stream takes 6 a
-minute. See
-[`experimental-a2/store-redis`](/reference/adapters#experimental-a2store-redis)
-for how live streams recover a lost wake-up.
-
-When only a REST API is available, `redisHttp({ url, token })` from
-`experimental-a2/store-redis-http` speaks the same storage over `fetch`, with
-no client dependency or extra setup. Live events and presence use Upstash's
-HTTP `SUBSCRIBE` endpoint with the same URL and token. If that endpoint answers
-404, 405, or 501, the store polls instead; other errors stay errors. See
-[`experimental-a2/store-redis-http`](/reference/adapters#experimental-a2store-redis-http)
-for its subscriptions, reconnects, and fallback.
-
-:::warning
-`redisHttp` live streams trust the messages on the store's `:notify`
-channels. Browsers never hold Redis credentials, so they can't reach those
-channels. The risk is a Redis credential that can publish but not write, such
-as a token another service uses: it could add or hide events in live views.
-Grant publish access only to credentials that can also write the store.
-:::
-
-### Postgres
-
-Any Postgres works: Neon, Supabase, RDS, or your own box, including
-transaction-mode poolers. `pg` is an optional peer dependency. Pass
-`connectionString`, or inject your own pool as `client`; an injected pool's
-platform lifecycle is yours to manage.
-
-Live streams poll by default, backing off when a session goes quiet. For
-native notifications, also pass `listenConnectionString`: a direct connection
-to the same database. It installs notification triggers on A2's event and
-presence tables, which stay installed and also cover writes from instances
-without the option. Stores in one runtime share a listener, but every
-serverless instance opens its own direct connection, so leave connection
-headroom. See
-[`experimental-a2/store-postgres`](/reference/adapters#experimental-a2store-postgres)
-for live-stream latency and recovery.
-
-## 2. Add a scheduler for handlers and timers
-
-The scheduler puts a clock on recovery and on [timers](/server/timers).
-Vercel Queues is the recommended default on Vercel. QStash delivers over HTTP
-from separate infrastructure. Either adapter carries recovery and
-`session.schedule` tasks through one route. Scheduled delays must fit the
-[provider's limit](/server/timers#provider-limits).
-
-### Vercel Queues (recommended)
-
-```ts
-// server/orders.ts, now with a scheduler:
-import { createServer } from 'experimental-a2/server'
-import { redis } from 'experimental-a2/store-redis'
-import { vercelQueues } from 'experimental-a2/scheduler-vercel'
-import { orders } from '@/contracts'
-
-export const scheduler = vercelQueues()
-
-export const ordersServer = createServer({
-  contract: orders,
-  store: redis({ url: process.env.REDIS_URL }),
-  scheduler,
-  handlers: {
-    /* ... */
-  },
-})
-```
-
-`@vercel/queue` is a peer dependency. Share one scheduler instance across
-servers, and mount its handler once with every server it may deliver to:
-
-```ts app/api/a2/scheduler/route.ts
-import { billingServer, ordersServer, scheduler } from '@/server'
-
-export const POST = scheduler.handler(ordersServer, billingServer)
-```
-
-`scheduler.handler(...)` checks its servers when the module loads: at least
-one drainable server, with unique contract names. A bad route fails at
-startup, or in a build that evaluates route modules.
-
-```json vercel.json
-{
-  "functions": {
-    "app/api/a2/scheduler/route.ts": {
-      "experimentalTriggers": [
-        {
-          "type": "queue/v2beta",
-          "topic": "a2"
-        }
-      ]
-    }
-  }
-}
-```
-
-The trigger is required. It connects the route to Vercel Queues and makes the
-function private, so only queue infrastructure can invoke it. Don't expose the
-callback as a public route or wrap it in a second authentication scheme.
-
-The adapter keeps messages for 7 days (Vercel Queues' default is 24 hours), so
-scheduled appends and clears can be up to 7 days out.
-
-### QStash
-
-```ts
-// server/orders.ts, with QStash instead:
-import { createServer } from 'experimental-a2/server'
-import { qstash } from 'experimental-a2/scheduler-qstash'
-import { redis } from 'experimental-a2/store-redis'
-import { orders } from '@/contracts'
-
-export const scheduler = qstash()
-
-export const ordersServer = createServer({
-  contract: orders,
-  store: redis({ url: process.env.REDIS_URL }),
-  scheduler,
-  handlers: {
-    /* ... */
-  },
-})
-```
-
-`@upstash/qstash` 2.11.0 or newer is a peer dependency. Mount
-`scheduler.handler(...)` in the same `app/api/a2/scheduler/route.ts`, and set
-`QSTASH_TOKEN`, `QSTASH_CURRENT_SIGNING_KEY`, and `QSTASH_NEXT_SIGNING_KEY`.
-
-- **Callback URL:** inferred from `PORT` locally, and from
-  `VERCEL_PROJECT_PRODUCTION_URL` or `VERCEL_BRANCH_URL` on Vercel. Pass `url`
-  anywhere else.
-- **Local development:** A2 starts QStash's development server on the first
-  publish or verification, with no QStash variables needed.
-- **Security:** the route verifies `Upstash-Signature` before touching the
-  store and answers unsigned traffic with 401. Behind Deployment Protection,
-  pass an automation bypass as a callback header.
-- **Outages:** delivery is at least once and A2 keeps recovery going, but when
-  QStash can't reach the route at all, redrive its DLQ.
-
-The [adapter reference](/reference/adapters#experimental-a2scheduler-qstash)
-covers the options, protected previews, Edge runtimes, and body limits.
-
-### More than one scheduler
-
-Servers with different scheduler instances need separate routes, even from the
-same adapter. Each extra QStash instance passes its own `url`. Each Vercel
-Queues instance needs its own `topic` and a matching `experimentalTriggers`
-entry.
-
-### Dispatch in a fresh invocation
-
-Ordinary `append` starts handlers inline and uses the scheduler as a watchdog.
-`append.dispatch` persists the input and hands the pending work straight to the
-queue instead:
-
-```ts app/api/imports/route.ts
-import { ordersServer } from '@/server'
-
-export async function POST(request: Request) {
-  const { orderId, shopId, items } = await request.json()
-  await ordersServer.session(orderId).append.dispatch({
-    id: `created:${orderId}`,
-    type: 'created',
-    payload: { shopId, items },
-  })
-  return Response.json({ accepted: true }, { status: 202 })
-}
-```
-
-It requires a scheduler. The call awaits the queue send and starts no inline
-drain. If the send fails, the event may already be durable; its explicit id
-makes the retry idempotent. Dispatch controls the wakeup, not which worker
-claims the event.
-
-### Running without a scheduler
-
-If no event type has a handler and nothing calls `session.schedule`, skip
-`scheduler`. Events settle in their append transaction, with no drains, claims,
-or queue messages. That's a complete production configuration: a durable event
-log for history, reducers, and live sync.
-
-With handlers, skipping it means the only wakeups are a top-level append or an
-explicit `server.drain()`. Reads never wake a session, so one nobody wakes
-stays stuck. That's fine for internal tools where "heals on the next write" is
-acceptable. For production, configure a scheduler.
-
-## 3. When an event dead-letters
-
-A [dead-lettered](/server/guarantees#when-a-handler-keeps-failing) event waits
-for you. List a session's dead letters, then resolve each one:
-
-```ts
-// anywhere on the server, behind your own operator checks:
-import { ordersServer } from '@/server'
-
-const order = ordersServer.session(orderId)
-const [dead] = await order.deadLetters()
-if (dead) {
-  // dead.lastError says why (null if every attempt timed out or crashed);
-  // deploy the handler fix first, then:
-  await order.redrive(dead.index, { action: 'retry' })
-}
-```
-
-- **Fix and retry.** `{ action: 'retry' }` runs the handler again with a fresh
-  ten-failure budget. Once it completes, its lane continues.
-- **Skip.** `{ action: 'skip' }` marks the event processed without running it,
-  accepting that its effects never happen. The next event in its lane runs.
-
-Each redrive is one atomic store operation, and it wakes the session the way an
-append does, so the lane resumes without another write. An event that isn't
-dead-lettered anymore is left alone: `redrive` reports `{ redriven: false }`.
-
-## 4. Deploy safely
-
-The Vercel adapter's `deploymentId` applies to every task: recovery, scheduled
-appends, and scheduled clears. Omit it to use the publishing deployment, pass
-a deployment ID to target one, or pass `null` for deploymentless delivery.
-Publishing and consuming clients must use the same scope.
-
-- **Pinned tasks stay put.** Promoting a new deployment doesn't move them;
-  older deployments keep receiving their own work until it is acknowledged or
-  expires. Upgrading doesn't repair an older deployment's callback handler.
-- **Deploymentless doesn't mean latest.** Vercel picks an eligible consumer,
-  not the latest production deployment. Every eligible consumer must use
-  `deploymentId: null` and stay compatible with pending tasks and session work.
-- **Changing the setting doesn't move queued tasks.** Keep consumers for the
-  original scope until those tasks finish.
-
-QStash's inferred production and branch URLs are moving aliases, so pending
-tasks can reach a later deployment. Keep task envelopes and event schemas
-compatible across deployments, and keep the same `maxBodyBytes` on every
-deployment that can receive the callback: lowering it mid-rollout can reject
-tasks the previous deployment accepted.
-
-:::warning
-Don't roll back to an A2 version without timer delivery while scheduled tasks
-are outstanding.
-An old route can acknowledge a new append task as a recovery message without
-writing its events. Rolling back past scheduled clears fails too: an old
-Vercel Queues route keeps failing a clear task until retention ends, and an
-old QStash route rejects it as non-retryable, moving it to QStash's
-dead-letter queue. Roll forward, or wait for those tasks to deliver or remove
-them through the provider first.
-:::
-
-## Watch it in traces
-
-```ts
-// server/orders.ts, with telemetry:
-import { createServer } from 'experimental-a2/server'
-import { otel } from 'experimental-a2/otel'
-import { orders } from '@/contracts'
-
-export const ordersServer = createServer({
-  contract: orders,
-  // ...store, scheduler, and handlers as above
-  telemetry: otel(),
-})
-```
-
-`telemetry` takes an instrumentation hook; `experimental-a2/otel` implements
-it over OpenTelemetry (`@opentelemetry/api` is a peer dependency). With any
-OTel setup registered (on Vercel, `@vercel/otel`), one trace shows the request,
-`a2.append`, the inline `a2.drain`, an `a2.event` span per handler, and the
-appends those handlers make. Failures mark their `a2.event` span,
-`a2.event.attempt` reports `ctx.attempt`, and `a2.event.outcome =
-dead_lettered` is the attribute to alert on. Agent servers add `a2.ai.*`
-spans. See the [span catalogue](/reference/adapters#the-span-catalogue).
-
-## Checklist
-
-| Piece               | Done when                                                            |
-| ------------------- | -------------------------------------------------------------------- |
-| Store               | `store: redis(...)` (or `postgres(...)`) on every server              |
-| Scheduler           | for servers with handlers or timers: one shared adapter, route, and provider config |
-| Idempotent handlers | external side effects take `event.id` as an idempotency key           |
-| Client split        | contracts/reducers isomorphic; only `experimental-a2/server` touches backends      |