experimental-a2 0.19.0 → 0.20.0

package/docs/01-quickstart.mdx

@@ -60,7 +60,7 @@ export const ordersServer = createServer({
 
 Development needs no database setup: events go to SQLite at `.a2/dev.db` and
 survive restarts. Tests get an in-memory store. Production needs an explicit
-store; see [Production](/server/production).
+store; see [Stores](/stores/overview).
 
 ## 4. Append the first event
 
@@ -169,11 +169,14 @@ You have a validated write path, a handler, a log you can read, and a view
 folded from it. The rest of these docs apply the same two moves, append an
 event and react to it, to timers, cancellation, live UIs, and production.
 
-<CardGroup cols={2}>
+<CardGroup cols={3}>
   <Card title="Handlers" href="/server/handlers" icon="file">
     Context, chaining, and re-runs.
   </Card>
-  <Card title="Production" href="/server/production" icon="rocket">
-    A store, a scheduler, dead letters.
+  <Card title="Stores" href="/stores/overview" icon="rocket">
+    Where sessions live in production.
+  </Card>
+  <Card title="Schedulers" href="/schedulers/overview" icon="clock">
+    Retries and timers on a queue.
   </Card>
 </CardGroup>

package/docs/actors/01-introduction.mdx

@@ -57,7 +57,7 @@ handler's first lines and throw `NonRetriableError` on bad shapes.
 
 `actor` also accepts `createServer`'s `store`, `scheduler`, and
 `telemetry` options, with the same development default store; see
-[Production](/server/production). A protocol can also declare
+[Stores](/stores/overview) and [Schedulers](/schedulers/overview). A protocol can also declare
 [`presence`](/actors/routes#presence).
 
 ## Call it

package/docs/actors/meta.ts

@@ -1 +1 @@
-export default { order: 6 }
+export default { order: 8 }

package/docs/agents/02-tools.mdx

@@ -81,7 +81,7 @@ for the event payload.
 
 This tool schedules a reminder as a new user message. `ctx.session` belongs to
 the executing agent, so `schedule()` uses that agent's scheduler: add
-`setReminder` to its `tools` and configure a [scheduler](/server/production).
+`setReminder` to its `tools` and configure a [scheduler](/schedulers/overview).
 Naming the timer after `toolCallId` and the message after the triggering
 event's ID makes a retry converge on the same timer and message, even if a
 provider reuses tool-call IDs. The six-day maximum is Vercel Queues'

package/docs/agents/03-conversations.mdx

@@ -393,7 +393,7 @@ retries, and so does one where A2 itself fails while or just after the tool
 runs. Every other tool uses the default, `'rerun'`. See
 [`agent()`](/reference/ai#agentoptions) for the exact cases.
 
-Configure a [production scheduler](/server/production) as for any A2 server. It
+Configure a [production scheduler](/schedulers/overview) as for any A2 server. It
 recovers an incomplete generation after the original serverless invocation
 disappears.
 

package/docs/agents/meta.ts

@@ -1 +1 @@
-export default { order: 5 }
+export default { order: 7 }

package/docs/client/meta.ts

@@ -1 +1 @@
-export default { order: 4 }
+export default { order: 6 }

package/docs/contract/03-sessions.mdx

@@ -70,7 +70,7 @@ authorize your own route before calling it.
 
 ### Scheduling a clear
 
-With a [scheduler](/server/production) configured, a handler can schedule a
+With a [scheduler](/schedulers/overview) configured, a handler can schedule a
 clear. This one clears an idle cart a day after its last activity:
 
 ```ts server/carts.ts

package/docs/index.mdx

@@ -156,7 +156,7 @@ from the log.
   <Card title="Timers" href="/server/timers" icon="clock">
     Schedule an event for later.
   </Card>
-  <Card title="Production" href="/server/production" icon="rocket">
+  <Card title="Production" href="/stores/overview" icon="rocket">
     A store and a scheduler.
   </Card>
 </CardGroup>
@@ -212,7 +212,7 @@ A durable store backend, such as Postgres or Redis. Add a queue-backed scheduler
 when the contract has handlers or calls `session.schedule`. A history-only
 contract with no timers needs no reaction infrastructure. Development needs
 neither: SQLite appears under `.a2/` and state survives restarts. See
-[Production](/server/production).
+[Stores](/stores/overview) and [Schedulers](/schedulers/overview).
 
 </details>
 

package/docs/reference/01-core.mdx

@@ -17,15 +17,15 @@ description: "Every entry point, and the isomorphic `experimental-a2` core: cont
 | `experimental-a2/ai/pi` | `pi`: the Pi harness for `agent()` | `ai`, `@earendil-works/pi-coding-agent`, `@earendil-works/pi-ai` |
 | `experimental-a2/ai/client` | `createAgentClient`: contract-free agent client | `ai` |
 | `experimental-a2/ai/react` | `useAgent` | `ai`, `react` |
-| [`experimental-a2/store-postgres`](/reference/adapters#experimental-a2store-postgres) | `postgres`: Postgres store backend | `pg` (or inject a client) |
-| [`experimental-a2/store-redis`](/reference/adapters#experimental-a2store-redis) | `redis`: Redis Streams store backend, push-native streaming | `ioredis` (or inject a client) |
-| [`experimental-a2/store-redis-http`](/reference/adapters#experimental-a2store-redis-http) | `redisHttp`: the same Redis store over provider REST APIs (Upstash) | none |
-| `experimental-a2/store-sqlite` | SQLite store backend | none |
-| `experimental-a2/store-memory` | in-memory store backend | none |
-| `experimental-a2/scheduler-vercel` | `vercelQueues`: recovery and timers | `@vercel/queue` |
-| `experimental-a2/scheduler-qstash` | `qstash`: signed recovery and timers | `@upstash/qstash` |
+| [`experimental-a2/store-postgres`](/stores/postgres) | `postgres`: Postgres store backend | `pg` (or inject a client) |
+| [`experimental-a2/store-redis`](/stores/redis) | `redis`: Redis Streams store backend, push-native streaming | `ioredis` (or inject a client) |
+| [`experimental-a2/store-redis-http`](/stores/redis-http) | `redisHttp`: the same Redis store over provider REST APIs (Upstash) | none |
+| [`experimental-a2/store-sqlite`](/stores/sqlite) | SQLite store backend | none |
+| [`experimental-a2/store-memory`](/stores/memory) | in-memory store backend | none |
+| [`experimental-a2/scheduler-vercel`](/schedulers/vercel-queues) | `vercelQueues`: recovery and timers | `@vercel/queue` |
+| [`experimental-a2/scheduler-qstash`](/schedulers/qstash) | `qstash`: signed recovery and timers | `@upstash/qstash` |
 | `experimental-a2/cache-indexeddb` | `indexedDb` browser cache | none |
-| `experimental-a2/otel` | `otel` telemetry adapter | `@opentelemetry/api` |
+| [`experimental-a2/otel`](/reference/telemetry) | `otel` telemetry adapter | `@opentelemetry/api` |
 
 `experimental-a2` imports none of the backends, and a browser-bundle test in CI
 enforces it. Importing a backend's entry point, such as

package/docs/reference/02-server.mdx

@@ -438,7 +438,7 @@ Custom scheduler adapters implement two methods:
 
 Application routes call `scheduler.handler(...servers)` on the configured
 adapter. See
-[Production](/server/production#2-add-a-scheduler-for-handlers-and-timers).
+[Schedulers](/schedulers/overview).
 
 `SchedulerTask` is `SchedulerDrainTask | SchedulerAppendTask |
 SchedulerClearTask`. These task types, plus `ScheduledEvent`, are exported
@@ -522,7 +522,7 @@ session.append.dispatch(
 
 Commits the same atomic batch, then sends pending work to the configured
 scheduler instead of starting an inline drain. See
-[Dispatch in a fresh invocation](/server/production#dispatch-in-a-fresh-invocation).
+[Dispatch in a fresh invocation](/schedulers/overview#dispatch-in-a-fresh-invocation).
 
 - Awaits acceptance of an immediate scheduler message. A batch that leaves no
   pending handler work sends none.
@@ -681,7 +681,7 @@ type DeadLetter = Event & {
 ```
 
 The session's dead-lettered events, oldest first, each with why it failed. See
-[When an event dead-letters](/server/production#3-when-an-event-dead-letters).
+[Resolve a dead letter](/server/handlers#resolve-a-dead-letter).
 
 - `failureCount` counts the attempts that spent its budget: caught failures,
   and attempts that ended before they finished. `attemptCount` counts every

package/docs/reference/04-ai.mdx

@@ -362,7 +362,7 @@ stub.
 | `toolLane` | one lane for every local tool execution, one at a time in admission order; model steps keep their own lane |
 | `toolRecovery` | `'rerun'` (default) or `'report'` per tool, the harness's own tools included |
 | `handlers` | application event handlers; naming an event the agent handles throws a `TypeError` |
-| `store`, `scheduler`, `telemetry` | as for any A2 server; `telemetry` covers Core and AI in one trace ([span catalogue](/reference/adapters#the-span-catalogue)) |
+| `store`, `scheduler`, `telemetry` | as for any A2 server; `telemetry` covers Core and AI in one trace ([span catalogue](/reference/telemetry#the-span-catalogue)) |
 
 **Contracts.** A contract not built by `agentContract()` throws a `TypeError`
 and fails to typecheck (serve custom contracts with `createServer()`). Messages
@@ -601,6 +601,14 @@ call. Replay grows with the response, roughly 0.1 to 0.5 seconds for one of 80
 to 200 tool calls. When libfx can't take a checkpoint, A2 replays from an
 earlier one.
 
+FX's model calls carry the same [AI Gateway](#agentoptions) defaults as the
+AI SDK harness: `caching: 'auto'`, under any Gateway options FX sets itself,
+and the session's stable `x-session-affinity` header in place of FX's own,
+which changes every time A2 rebuilds the kernel. A2 leaves every other byte of
+the request as FX wrote it, so it adds caching only where FX's own options come
+last in the request, as libfx writes them; otherwise the request goes
+unchanged.
+
 Credentials come from `AI_GATEWAY_API_KEY`, or Vercel's OIDC token on Vercel.
 This entry point is server-only.
 

package/docs/reference/05-telemetry.mdx

@@ -0,0 +1,132 @@
+---
+title: Telemetry
+description: "Trace A2 with OpenTelemetry, and the spans it reports."
+---
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { otel } from 'experimental-a2/otel'
+import { orders } from '@/contracts'
+
+export const ordersServer = createServer({
+  contract: orders,
+  telemetry: otel(),
+  // ...store, scheduler, and handlers
+})
+```
+
+With any OpenTelemetry 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, and `a2.event.outcome = dead_lettered` is the attribute to alert on.
+Agent servers add `a2.ai.*` spans.
+
+## `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. `A2Telemetry` is a one-method interface:
+anything with `span(name, attributes, fn)` works, and `otel()` is the adapter
+A2 ships.
+
+## 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` \| `failed`          |
+| `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. `failed` appears only on
+  scheduler deliveries: the drain threw after arming its successor watchdog,
+  the span records the error, and that successor retries the session.
+- 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.

package/docs/reference/06-errors.mdx

@@ -44,7 +44,7 @@ export async function POST(req: Request) {
 | `SESSION_CLEARED` | a state read reaches below the latest clear, a handler reads state past a clear of its event, or an actor call is cleared before it receives its answer | no |
 | `CLAIM_EXPIRED` | never thrown; only the `ctx.signal` abort reason when the attempt's lease lapsed without renewal (assumed loss, decided locally, not proof) | no |
 | `STORE_UNAVAILABLE` | the store backend failed; nothing was written. The original error is the `cause` | **yes** |
-| `STORE_NOT_CONFIGURED` | production boots with no `store` configured (during `next build` page collection, deferred to first use) | no |
+| `STORE_NOT_CONFIGURED` | production boots with no `store` configured (during `next build` page collection, deferred to first use), a store's optional peer dependency is missing, or a Postgres database lacks A2's tables at the version the release needs (or the notification triggers `listenConnectionString` uses). The message names the fix | no |
 
 Retrying an *identical* batch is not `PARTIAL_DUPLICATE_BATCH`: it's an
 idempotent success that returns the previously appended events. A failing

package/docs/reference/meta.ts

@@ -1 +1 @@
-export default { order: 7 }
+export default { order: 9 }

package/docs/schedulers/01-overview.mdx

@@ -0,0 +1,112 @@
+---
+title: Overview
+description: A clock for handler retries and timers.
+---
+
+```ts server/orders.ts
+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: {
+    /* ... */
+  },
+})
+```
+
+```ts app/api/a2/scheduler/route.ts
+import { billingServer, ordersServer, scheduler } from '@/server'
+
+export const POST = scheduler.handler(ordersServer, billingServer)
+```
+
+A scheduler wakes sessions on a clock. It retries a handler that failed or
+whose process died, and it delivers [timers](/server/timers), whose delays must
+fit the [provider's limit](/server/timers#provider-limits). Share one
+scheduler across your servers and mount its route once, with every server it
+delivers to. `scheduler.handler(...)` checks those servers when the module
+loads, so a bad route fails at startup.
+
+| Scheduler | Use it for |
+| --- | --- |
+| [Vercel Queues](/schedulers/vercel-queues) | Apps on Vercel (recommended) |
+| [QStash](/schedulers/qstash) | A stable public URL, called from separate infrastructure |
+
+## Without a scheduler
+
+If no event type has a handler and nothing calls `session.schedule`, skip it.
+Events settle as they're appended, with no queue messages. That's a complete
+production setup for history, reducers, and live sync.
+
+With handlers but no scheduler, a session only wakes on a top-level append or
+an explicit `server.drain()`. Reads never wake it, so a session nobody writes
+to stays stuck. That's fine for internal tools that can heal on the next
+write. For production, add a scheduler.
+
+## More than one scheduler
+
+Servers with different scheduler instances need separate routes, even from the
+same adapter. Give each QStash instance its own `url`, and each Vercel Queues
+instance its own `topic` and trigger.
+
+## Dispatch in a fresh invocation
+
+`append` starts handlers in the same request and uses the scheduler as a
+watchdog. `append.dispatch` stores the event and hands its handlers 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 needs a scheduler and waits for the queue to accept the message. If that
+send fails, the event may already be stored; its explicit `id` makes a retry
+safe.
+
+## Deploys and rollbacks
+
+Queued work can reach a different deployment than the one that sent it. Keep
+event schemas compatible across deployments. Each adapter's page explains
+where its tasks go: [Vercel Queues](/schedulers/vercel-queues#deployments) and
+[QStash](/schedulers/qstash#deployments).
+
+:::warning
+Don't roll back to an A2 version without timer delivery while scheduled tasks
+are outstanding. An old route can acknowledge a scheduled append without
+writing its events. Rolling back past scheduled clears fails too: an old
+Vercel Queues route keeps failing the clear until retention ends, and an old
+QStash route moves it to QStash's dead-letter queue. Roll forward, or wait for
+those tasks to deliver first.
+:::
+
+## Send errors
+
+When a provider rejects a send, both adapters keep the provider's original
+error.
+
+- **Terminal:** a definite 4xx status or error, except 408, 409, 425, and 429.
+  The Vercel adapter also treats the SDK's `BadRequestError`,
+  `UnauthorizedError`, and `ForbiddenError` as terminal.
+- **Retryable:** 408, 409, 425, 429, 5xx, network failures, and errors with no
+  recognized status.
+- Vercel Queues' duplicate-message error counts as success.
+
+A2's durable AI tools use this classification. Direct `session.schedule()`
+calls still reject with the original error.

package/docs/schedulers/02-vercel-queues.mdx

@@ -0,0 +1,87 @@
+---
+title: Vercel Queues
+description: The recommended scheduler on Vercel.
+---
+
+```ts server/orders.ts
+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: {
+    /* ... */
+  },
+})
+```
+
+```ts app/api/a2/scheduler/route.ts
+import { ordersServer, scheduler } from '@/server'
+
+export const POST = scheduler.handler(ordersServer)
+```
+
+```json vercel.json
+{
+  "functions": {
+    "app/api/a2/scheduler/route.ts": {
+      "experimentalTriggers": [
+        {
+          "type": "queue/v2beta",
+          "topic": "a2"
+        }
+      ]
+    }
+  }
+}
+```
+
+```package-install
+npm i @vercel/queue
+```
+
+The trigger is required. It connects the route to Vercel Queues and makes the
+function private, so only the queue can call it. Don't also expose the route
+publicly or wrap it in your own authentication.
+
+Messages are kept for seven days (Vercel Queues' default is 24 hours, and
+seven days is its maximum), so timers can be scheduled up to seven days out. A
+longer delay goes out as asked, and Vercel Queues refuses it.
+
+A drain delivery is acknowledged once its session settles or a later watchdog
+for it is stored, including when the drain fails after storing that watchdog.
+A drain that fails before then stays unacknowledged, so Vercel Queues
+redelivers it.
+
+## Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `topic` | `'a2'` | must match the trigger's `topic`, and `[A-Za-z0-9_-]+` |
+| `deploymentId` | `VERCEL_DEPLOYMENT_ID` | which deployment receives tasks; see below |
+| `transport`, `clock` | the `@vercel/queue` client, the system clock | test seams for custom delivery |
+
+An injected `transport` receives the topic, the task, and send options, and
+owns its own provider configuration; `deploymentId` only configures the
+built-in client.
+
+## Deployments
+
+`deploymentId` applies to every task: retries, timers, and scheduled clears.
+Leave it out to deliver to the deployment that sent the task, pass an ID to
+target one deployment, or pass `null` to let Vercel pick. Every deployment that
+sends or receives must use the same setting.
+
+- **Tasks stay with their deployment.** Promoting a new deployment doesn't move
+  them, so older deployments keep receiving their own work until it's done or
+  expires. Upgrading doesn't fix an older deployment's route.
+- **`null` doesn't mean latest.** Vercel picks any eligible deployment, so every
+  one of them must use `deploymentId: null` and handle pending tasks.
+- **Changing the setting doesn't move queued tasks.** Keep the old deployments
+  running until those tasks finish.

package/docs/schedulers/03-qstash.mdx

@@ -0,0 +1,123 @@
+---
+title: QStash
+description: Signed HTTP delivery from Upstash, to a stable public URL.
+---
+
+```ts server/orders.ts
+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: {
+    /* ... */
+  },
+})
+```
+
+```ts app/api/a2/scheduler/route.ts
+import { ordersServer, scheduler } from '@/server'
+
+export const POST = scheduler.handler(ordersServer)
+```
+
+```package-install
+npm i @upstash/qstash
+```
+
+Set `QSTASH_TOKEN`, `QSTASH_CURRENT_SIGNING_KEY`, and
+`QSTASH_NEXT_SIGNING_KEY`. In development you need none of them: A2 starts
+QStash's local server on the first publish. It needs `@upstash/qstash` 2.11.0
+or newer.
+
+The route checks `Upstash-Signature` before it touches the store and answers
+unsigned requests with 401. Delivery is at least once, so handler side effects
+need idempotency keys.
+
+## Callback URL
+
+QStash calls `/api/a2/scheduler`. An explicit `url` always wins; otherwise A2
+infers it:
+
+- **Vercel production:** `https://${VERCEL_PROJECT_PRODUCTION_URL}/api/a2/scheduler`.
+- **Vercel preview:** `https://${VERCEL_BRANCH_URL}/api/a2/scheduler`.
+- **Locally:** `http://localhost:${PORT ?? 3000}/api/a2/scheduler`, against
+  QStash's development server. `PORT` must be an integer from 1 through 65535.
+
+Pass `url` for anything else: production outside Vercel, a custom path or
+host, Docker networking, or a runtime without `process.env`. With an explicit
+`url` outside production, A2 doesn't start the development server: set
+`QSTASH_DEV`, or `QSTASH_URL` and credentials, yourself. An Edge runtime infers
+the local URL but must also start the development server itself.
+
+## Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `url` | inferred, see above | the callback URL |
+| `token` | `QSTASH_TOKEN` | |
+| `currentSigningKey` | `QSTASH_CURRENT_SIGNING_KEY` | |
+| `nextSigningKey` | `QSTASH_NEXT_SIGNING_KEY` | |
+| `headers` | none | static headers on every callback |
+| `client` | a lazy `@upstash/qstash` client | your own configured client |
+| `retries` | QStash's default | retries per delivery; every attempt is billed |
+| `maxBodyBytes` | `1_048_576` (1 MiB) | the largest task A2 sends or accepts |
+| `transport`, `clock` | the `@upstash/qstash` client and receiver, the system clock | test seams for custom delivery |
+
+- **`headers`** are checked and copied when `qstash()` runs. A2 asks QStash to
+  redact every value from its dashboard and API, but QStash still stores and
+  delivers them. Names are case-insensitive. `Upstash-*`, `Content-Type`, HTTP
+  framing headers, and A2's Vercel identity headers are reserved.
+- **`client`** is the `publishJSON(...)` part of a configured `Client`, for its
+  endpoint, retry policy, or telemetry. It can't be combined with `token` or
+  `transport`. It receives callback credentials unredacted and must apply each
+  publish's redaction. Put callback credentials in `headers`, not on the
+  client.
+- **`maxBodyBytes`**: A2 reserves room for a task's retry metadata before the
+  first publish, so an accepted task never outgrows the limit. Raise it for a
+  larger paid-plan limit, and keep one value on every deployment that receives
+  the URL.
+- **`transport`** implements `publish(request)` and `verify(request)`. It must
+  keep the body, deliver every header, and apply every redaction.
+
+## How delivery works
+
+- The route returns 200 once a task is done, or once its follow-up is queued,
+  so each retry gets a fresh message and retry budget. That includes a drain
+  that fails after queueing its follow-up.
+- If the store is down (`STORE_UNAVAILABLE`) or not set up yet
+  (`STORE_NOT_CONFIGURED`, such as Postgres before its tables exist) before a
+  drain queues its follow-up, or during an append or clear task, the task moves
+  to a new message: 30 seconds later, four times longer each time, up to one
+  day.
+- A signed but malformed task, or one over `maxBodyBytes`, returns 489 with
+  `Upstash-NonRetryable-Error: true`. Unknown contracts, missing
+  configuration, and other failures return an error, so QStash retries.
+- If QStash can't reach the route at all, nothing queues a follow-up: watch
+  QStash's dead-letter queue and redrive from it.
+- Delays are capped by your plan: 7 days on free plans and 1 year on
+  usage-based plans, with no fixed cap on fixed plans. Leave a second of
+  margin at the cap.
+
+## Protected previews
+
+For an inferred preview URL, each publish forwards the invocation's Vercel
+OIDC token as `x-vercel-trusted-oidc-idp-token`, redacted, so a Vercel Trusted
+Sources rule can let the first delivery through. This is best effort: a
+missing or expiring token falls back to a plain publish, and retries reuse the
+stored token, which may have expired. When every protected delivery must get
+through, pass an automation bypass in `headers` instead. Signature checks still
+apply after Vercel's.
+
+## Deployments
+
+Inferred production and preview URLs are moving aliases, so a pending task can
+reach a later deployment. Keep tasks and event schemas compatible across
+deployments, and keep the same `maxBodyBytes` on all of them: a lower value
+rejects tasks that an earlier deployment accepted.

package/docs/schedulers/meta.ts

@@ -0,0 +1 @@
+export default { order: 5 }