experimental-a2 0.17.0 → 0.18.0

package/docs/reference/01-api.mdx

@@ -1,2358 +0,0 @@
----
-title: API
-description: "The whole surface, small enough to read in one sitting: contract, server, session, reducer, and the React and HTTP helpers."
----
-
-## `experimental-a2`
-
-### `a2.contract(options)`
-
-```ts
-a2.contract(options: {
-  name: string
-  events: Record<string, StandardSchemaV1>
-  presence?: Record<string, StandardSchemaV1>
-  reducer?: { name: string; initialState: S; stateSchema?: StandardSchemaV1; fold: (state: S, event: Event) => S }
-}): Contract
-```
-
-Defines one kind of lifecycle: a name plus the events it understands. The name
-must be unique per app; it identifies the contract in storage and queue
-messages. The name may not contain the control character U+001F, and event
-types may not start with `a2.`, which A2 reserves for its own events, such as
-`a2.cleared`. The result is a plain,
-importable, **isomorphic** value: the server
-implements it, reducers derive from it, the browser types its pushes off it.
-See [Contracts and sessions](/concepts/contracts).
-
-`presence` is the optional second vocabulary: each key a field of one
-participant's ephemeral state, each value its schema. Presence fields are
-replicated last-writer-wins and never stored in the log; reducers cannot
-see them. See [Presence](/guides/presence).
-
-Schemas are [Standard Schema](https://standardschema.dev): Zod, Valibot,
-ArkType, anything that implements it. Validators must be synchronous
-(async ones are rejected here, at definition time), and the validated
-output is what's stored.
-
-### `contract.batch(...events)`
-
-Preserves the literal types in a heterogeneous handler-returned event array.
-It returns the same events as a readonly tuple; A2 validates them when the
-handler completes.
-
-### `reducer(options)`
-
-```ts
-reducer(options: {
-  contract: Contract
-  name: string                // identity; keys cached snapshots
-  initialState: S             // the seed (schema input, when stateSchema is set)
-  stateSchema?: StandardSchemaV1 // declares S, checks initialState, guards cached folds
-}): { fold(fn: (state: S, event: Event) => S): Reducer<S> }
-```
-
-Builds a separate reducer for server reads or for the contract's optional
-`reducer` field. The contract publishes only that selected reducer to clients.
-Inline definitions include `fold` directly. The standalone builder uses two steps: the first call
-fixes the state and event types, so `.fold()` receives fully concrete
-ones. Literal unions in your state survive, with zero annotations.
-
-The name is the reducer's identity; it keys cached snapshots, so rename it
-when the fold's logic changes. Two reducers never fight over a cache
-entry, and a rename (or a `stateSchema` mismatch, when present)
-invalidates, and the next read refolds from raw events. See
-[Reading state](/concepts/state).
-
-### `A2Error`
-
-The shared base for A2 failures, discriminated by `code`. The session
-client exposes its `A2ClientError` subclass. See
-[Errors](/reference/errors).
-
-### `idempotentId(...parts)`
-
-`idempotentId(...parts: string[]): Promise<string>` derives a stable UUIDv8
-from an ordered tuple of strings. It runs on the server and in the browser.
-
-```ts shared/request-id.ts
-import { idempotentId } from 'experimental-a2'
-
-export const id = await idempotentId('orders', 'shop-7', 'request-42')
-```
-
-Pass the result as an event's `id` when retries should converge on the same
-event. The same tuple produces the same ID across runtimes and A2 versions.
-String boundaries, order, and case matter; strings are not normalized.
-Empty strings and an empty tuple are valid inputs.
-
-Every argument has the same role. A prefix such as `'orders'` is a namespace
-by convention. Include enough context to distinguish operations across
-contracts and sessions, since event IDs are globally unique within a store.
-
-The helper performs no I/O. A2 preserves explicit IDs and keeps its automatic
-ID generation unchanged. Changing an existing application's ID recipe changes
-retry identity, so retries of previously committed requests need to retain
-their original IDs.
-
-### `SessionCleared`
-
-The marker a [clear](#sessionclearoptions) leaves in `session.stream()`: an
-`Event` whose `type` is `'a2.cleared'` and whose `payload` is `null`. It
-never reaches handlers or `history()`. Comparing `event.type` with that string
-narrows a stream item to `SessionCleared`. The session client handles the
-marker on its own, so this matters only when you read the server stream
-yourself.
-
-## `experimental-a2/server`
-
-### `handler(entry)`
-
-Define handlers inline in `createServer({ handlers })` for ordinary use.
-Use this helper when composing an existing handler.
-
-Accepts a handler function or an object with `handler` and optional `lane` and
-`abortOn`. Returns the object shape: a function becomes `{ handler: entry }`,
-and an object is returned unchanged. The original function and object types
-are preserved. Use it to compose an existing handler without branching on its
-shape.
-
-```ts server/composed-orders.ts
-import * as a2 from 'experimental-a2'
-import { createServer, handler, type HandlerContext } from 'experimental-a2/server'
-import { z } from 'zod'
-
-const orders = a2.contract({
-  name: 'composed-orders',
-  events: {
-    created: z.object({ shopId: z.string() }),
-    notified: z.object({ shopId: z.string() }),
-  },
-})
-
-const created = handler({
-  lane: 'orders',
-  handler: async (ctx: HandlerContext<typeof orders.events, 'created'>) => {
-    return orders.batch({ type: 'notified', payload: ctx.event.payload })
-  },
-})
-
-export const ordersServer = createServer({
-  contract: orders,
-  handlers: {
-    created: {
-      ...created,
-      handler: async (ctx) => {
-        const result = await created.handler(ctx)
-        // Your additional work goes here:
-        // await notifyShop(ctx.event.payload, { idempotencyKey: ctx.event.id })
-        return result
-      },
-    },
-  },
-})
-```
-
-Spreading the object preserves its `lane` and `abortOn`. Set either property
-after the spread to override it. Changing a built-in AI handler's lane can
-separate it from the handlers it coordinates with.
-
-Composition runs in one handler attempt. Work after the original function
-resolves still runs before its returned events commit. A thrown error fails
-the composed attempt; on retry, the wrapper and original handler can run again.
-For a new handler, annotate its context as above or pass an already typed
-function. `handler` does not bind a handler to a contract;
-`createServer({ handlers })` checks that it matches the contract.
-
-### `createServer(options)`
-
-```ts
-createServer(options: {
-  contract: Contract // the vocabulary this server implements
-  store?: A2Store    // default: sqlite in dev, memory in tests, required in prod
-  scheduler?: A2Scheduler
-  telemetry?: A2Telemetry // optional instrumentation; see experimental-a2/otel
-  presence?: { ttlMs?: number } // presence expiry policy; default 60s
-  handlers?: {
-    [type]:
-      | Handler
-      | {
-          abortOn?: AbortSpec
-          lane?: string | ((ctx: LaneContext) => string)
-          handler: Handler
-        }
-  }
-}): A2Server
-
-type Handler = (
-  ctx: Context,
-) => Promise<void | AppendInput | readonly AppendInput[]>
-```
-
-Implements a contract: binds the vocabulary to storage and reactions.
-Handlers are one table, complete at construction, so a handler can never
-be silently missing because the module that registered it wasn't
-imported. Compose across files by spreading objects into `handlers`
-(note: a duplicate key under spread silently last-wins).
-
-Handlers are concurrent by default. A2 starts every eligible event after its
-append commits. Add `lane` when events share a resource and must not overlap.
-Within one session, events with the same lane value run one at a time in log
-order. Different lanes and events without a lane run concurrently. A lane
-resolver receives `{ sessionId, event }`; A2 resolves and stores the value when
-the event is appended, so a later deployment cannot reinterpret pending work.
-For example, `lane: ({ event }) => event.payload.warehouseId` serializes work
-per warehouse while different warehouses continue concurrently.
-
-Handlers can return one event or an array. A2 marks the triggering event
-processed and appends the returned batch in one atomic store operation. Returned
-events do not exist when the handler throws. `ctx.session.append(name, ...events)`
-is different: it commits immediately, so its events may run while the current
-handler is still active unless a lane orders them.
-`ctx.session.schedule(name, timing, ...events)` waits for provider acceptance;
-its events append later and are not part of the parent completion transaction.
-
-Handlers are optional per event type. An event type without one settles in
-the append transaction with no dispatch attempt. If the session has no older
-pending handler work, A2 starts no drain or scheduler arm. A server with no
-handlers is a durable event log with no reaction infrastructure. See
-[Events without handlers](/concepts/handlers#events-without-handlers).
-
-Server-only by construction: `experimental-a2/server` is the only entry point that
-can reach a store backend, and its exports map resolves to a loud error
-under the browser condition.
-
-`presence.ttlMs` sets how long a presence value survives without a
-refreshing set (default 60 seconds, as a positive integer of
-milliseconds). Expiry counts on the storage's own clock, never on the
-sender's stamp. The option is valid only on contracts that declare
-`presence`; anywhere else construction throws a `TypeError`.
-
-`abortOn` names the events that fire `ctx.signal` while a handler runs.
-an array matches by type; an object takes per-type predicates for
-targeted cancellation:
-
-```ts
-generate: {
-  abortOn: {
-    cancelled: (event, trigger, { attempt }) =>
-      event.payload.of === `${trigger.id}:${attempt}`,
-  },
-  handler: async (ctx) => { /* ... */ },
-}
-```
-
-The predicate's third argument contains the triggering event's durable
-`attempt`, so a cancellation can fence a specific recovered run.
-
-The context every handler receives:
-
-| Property      | Type                                                      |
-| ------------- | --------------------------------------------------------- |
-| `ctx.event`   | `Event`: the triggering event                             |
-| `ctx.attempt` | durable 1-based dispatch claim ordinal                    |
-| `ctx.session` | this session's `id`, `append`, `schedule`, `history`, `state`, `stream`, `setPresence` |
-| `ctx.signal`  | `AbortSignal`: fires on lease lapse (`CLAIM_EXPIRED`), proven supersession (`SUPERSEDED_ATTEMPT`), and matching `abortOn` events |
-
-`ctx.attempt` starts at `1` and increments on every durable claim. It may skip
-when a process dies before handler entry.
-
-`ctx.session.id` equals `ctx.event.sessionId`. Its `history`, `state`, and
-`stream` methods share the session surface returned by `server.session(id)`,
-with one causal default: `ctx.session.state(reducer)` folds through the
-triggering event's index. The same event sees the same state across concurrent
-appends and retries. Ask for `{ through: 'latest' }` when a handler intentionally
-needs the committed frontier captured when that read runs.
-
-The handler-local append is specialized:
-
-```ts
-ctx.session.append(name: string, ...events: AppendInput[]): Promise<Event[]>
-```
-
-The name is an idempotency key scoped to the triggering event for events whose
-`id` is omitted. A2 derives each omitted id from the trigger id, name, and event
-position. The same name and generated-id batch returns the existing rows
-across retries. Changing that batch conflicts with those rows. An explicit
-event `id` wins over the generated id, which lets different triggering events
-converge on one fact. A root `server.session(id).append(...events)` takes no
-name.
-
-`ctx.session.schedule(name, timing, ...events)` includes the triggering event
-in its stable task identity. A relative delay is anchored to that event's
-durable `createdAt`, so a handler retry keeps the same delivery time. The call
-returns `Promise<void>` after the configured scheduler accepts the task.
-
-A latest state read and following append are not atomic. Concurrent appends and
-retries may move the frontier between them. A generic join should read with
-`{ through: 'latest' }`, use a monotone readiness predicate, and give its output
-a stable explicit event `id`, so every eligible attempt converges on the same
-append.
-
-### `server.fetch(request, options?)`
-
-```ts
-server.fetch(
-  request: Request,
-  options?: {
-    authorize?: (operation: A2Operation) => boolean | Promise<boolean>
-    upgradeWebSocket?: (
-      attach: (socket: A2Socket) => void,
-    ) => Response | Promise<Response>
-    multiplexWebSocket?: boolean
-  },
-): Promise<Response>
-
-type A2Operation =
-  | {
-      type: 'stream'
-      sessionId: string
-      startAfter: number
-      transport: 'http' | 'websocket'
-    }
-  | {
-      type: 'history'
-      sessionId: string
-      gte: number
-      lte: number
-      transport: 'http'
-    }
-  | {
-      type: 'push'
-      sessionId: string
-      events: readonly {
-        type: ContractEventType | string
-        payload: unknown
-        id?: string
-      }[]
-      presence?: {
-        participant: string
-        values: Readonly<Record<string, unknown>>
-        seen?: number
-        at?: number
-      }
-      transport: 'http' | 'websocket'
-    }
-```
-
-The bound Fetch API route for this server. An unprotected route can export it
-directly:
-
-```ts app/api/public-order-events/route.ts
-import { ordersServer } from '@/server/orders'
-
-export const GET = ordersServer.fetch
-export const POST = ordersServer.fetch
-```
-
-A plain GET streams one session over SSE, resumed after the `index` query
-parameter. A GET with `gte` and `lte` returns the closed history range as JSON
-and sets `a2-history-covered` to `true` when every requested index was returned.
-When the range includes the latest clear marker, it also sets `a2-clear-index`,
-and coverage counts only the requested indexes after that marker. A range
-entirely below the marker returns `[]`.
-POST accepts `{ sessionId, events, presence? }` and returns the appended events.
-Presence is inferred from the contract. A contract that declares presence
-streams it and accepts presence pushes automatically.
-
-`authorize` runs after the request or socket frame has been parsed, but before
-contract schema validation, presence validation, or I/O. Event names and
-presence field names are typed from the contract. Their unvalidated values stay
-`unknown`. Return `false` to deny the operation with `FORBIDDEN`. A thrown error
-becomes `STORE_UNAVAILABLE`, because authorization infrastructure failed rather
-than denied access. Operation objects, push events, event arrays, and presence
-patches are frozen. Authorize them, do not rewrite them.
-
-Authentication stays outside A2, where the route can read headers, cookies, and
-framework context. Capture the authenticated principal in `authorize`:
-
-```ts app/api/protected-order-events/route.ts
-import { ordersServer } from '@/server/orders'
-
-async function fetchOrders(request: Request): Promise<Response> {
-  // your authentication:
-  const user = { id: 'user-1' }
-  if (!user) return new Response(null, { status: 401 })
-
-  return ordersServer.fetch(request, {
-    authorize(operation) {
-      // your per-session and per-operation authorization:
-      // return canAccess(user, operation)
-      return true
-    },
-  })
-}
-
-export const GET = fetchOrders
-export const POST = fetchOrders
-```
-
-Direct `session.append`, handler appends, scheduled appends, and server-side
-`setPresence` bypass `authorize`. It is an ingress policy for this fetch call,
-not a global server policy.
-
-A GET with `Upgrade: websocket` uses `upgradeWebSocket`. Without that option it
-returns 426. The upgrade function receives an `attach` callback for the
-platform socket:
-
-```ts app/api/socket-order-events/route.ts
-import { experimental_upgradeWebSocket } from '@vercel/functions'
-import { ordersServer } from '@/server/orders'
-
-export const POST = ordersServer.fetch
-
-export function GET(request: Request): Promise<Response> {
-  return ordersServer.fetch(request, {
-    upgradeWebSocket: (attach) =>
-      experimental_upgradeWebSocket(attach, {
-        maxPayload: 4 * 1024 * 1024,
-      }),
-  })
-}
-```
-
-By default, the `sessionId` and `index` query parameters bind one session to the
-socket. A2 authorizes the stream before upgrading. Frames on that socket cannot
-select another session.
-
-Set `multiplexWebSocket: true` here and `multiplex: true` in the client's `ws`
-API to share one socket.
-Authenticate the physical WebSocket GET before calling `server.fetch`. Validate
-`Origin` too when browser cookies authenticate it; WebSocket handshakes do not
-use a CORS preflight. Use `authorize` for each session subscribe and each event
-or presence push. Only enable multiplexing when that request context may access
-every session accepted by `authorize`. A denied subscribe receives
-`unsubscribed` and does not affect other sessions. A denied event push receives
-a `FORBIDDEN` ack. Denied presence is silently dropped because it is
-fire-and-forget.
-
-SSE and WebSocket lifetimes use the platform's ambient invocation deadline.
-A2 also uses the platform's ambient `waitUntil` capability for background work.
-Neither capability is reordered or passed through `server.fetch` options.
-
-### `server.session(id)`
-
-```ts
-server.session(id: string): Session
-```
-
-A handle on one instance of the contract. The session is the unit of log
-ordering, lane keys, recovery, state, and live sync. Handler execution is
-concurrent unless events share a lane. Creating the handle does no I/O;
-nothing loads until you append, read, or stream.
-
-```ts
-const session = server.session('order-42')
-
-session.id
-session.append(...events)
-session.schedule('expire-order', { delay: '5d' }, {
-  type: 'expired',
-  payload: {},
-})
-session.history({ gte, lte })
-session.state(reducer)
-session.stream({ startAfter })
-```
-
-`session.id` is the id passed to `server.session(id)`. Root `append` takes only
-events. The handler-local form at `ctx.session.append` adds its required name
-before the events. Both root and handler sessions expose `schedule`.
-
-### `server.drain(sessionId)`
-
-```ts
-server.drain(sessionId: string): Promise<{ settled: boolean }>
-```
-
-Claims every currently eligible event and runs their handlers concurrently.
-`settled` means no actionable or live-claimed work remains. A dead-lettered
-event can leave later work in its lane blocked while other lanes continue.
-You'll rarely call this yourself; it is the primitive scheduler callbacks use.
-The public result stays this simple boolean.
-
-### `A2Store`
-
-Custom adapters implement these atomic drain methods:
-
-```ts
-// Custom server store adapter:
-type EventCause = {
-  index: number
-  attempt: number
-  batchSize?: number // present on named handler appends
-}
-
-type AppendEvent = {
-  type: string
-  payload: unknown
-  id?: string
-  cause?: EventCause
-  lane?: string
-  settled?: true // internal: no handler is registered for this event type
-}
-
-type ReturnedEvent = AppendEvent & { id: string }
-
-type StoredEvent = Event & {
-  cause: EventCause | null
-  lane: string | null
-  processedAt: Date | null
-  processedByAttempt: number | null
-  returnedEventIds: string[] | null
-  firstClaimedAt: Date | null
-  lastClaimedAt: Date | null
-  attemptCount: number
-  claimHolder: string | null
-  claimExpiresAt: Date | null
-  failureCount: number
-  lastFailedAt: Date | null
-  lastFailedAttempt: number | null
-  lastError: string | null
-  failedAt: Date | null
-  clearIndex?: number // on claimed events, once the session has been cleared
-}
-
-type StoreAppendResult = {
-  events: StoredEvent[]
-  hasPending: boolean
-}
-
-type StoreClaimAvailableResult =
-  | { outcome: 'claimed'; events: StoredEvent[] }
-  | { outcome: 'busy'; retryAt: Date }
-  | { outcome: 'settled' }
-
-type CompleteAttemptResult =
-  | { outcome: 'completed'; events: StoredEvent[] }
-  | { outcome: 'superseded' }
-
-interface A2Store {
-  append(
-    sessionId: string,
-    events: AppendEvent[],
-    options?: { originIndex?: number },
-  ): Promise<StoreAppendResult>
-
-  // optional together; required for session.clear()
-  clear?(options: {
-    sessionId: string
-    ifLastIndex?: number
-    cause?: EventCause
-  }): Promise<{ cleared: boolean; index: number; clearIndex: number }>
-  reclaim?(sessionId: string): Promise<{ deleted: number; done: boolean }>
-
-  claimAvailable(options: {
-    sessionId: string
-    holder: string
-    ttlMs: number
-    expiresAtMs?: number
-    excludeIndexes?: readonly number[]
-  }): Promise<StoreClaimAvailableResult>
-
-  renewClaims(options: {
-    sessionId: string
-    holder: string
-    claims: readonly { index: number; attempt: number }[]
-    ttlMs: number
-    expiresAtMs?: number
-  }): Promise<{ renewed: number[]; superseded: number[] }>
-
-  completeAttempt(options: {
-    sessionId: string
-    index: number
-    attempt: number
-    events: ReturnedEvent[]
-  }): Promise<CompleteAttemptResult>
-
-  failAttempt(options: {
-    sessionId: string
-    index: number
-    attempt: number
-    error: string
-    maxFailures: number
-  }): Promise<{
-    outcome: 'failed' | 'dead_lettered' | 'superseded'
-    failureCount: number
-  }>
-}
-```
-
-| Method | Atomic effect |
-| --- | --- |
-| `append` | Write a consecutive batch. Events carrying core's internal `settled` flag receive `processedAt` in the same transaction, with no dispatch attempt. An event carrying `cause` is fenced by attempt currency: it commits only while `cause.attempt` is still the parent's latest attempt and the parent is not dead-lettered, throwing `SUPERSEDED_ATTEMPT` otherwise (the check serializes against a concurrent claim; the idempotent-replay path runs first). |
-| `claimAvailable` | Claim every eligible event. All unlaned events are independent; only the lowest-index unfinished event in each lane is eligible. A claim records its holder, expiry, timestamps, and next `attemptCount`. |
-| `renewClaims` | Extend the listed live claims still owned by the holder. `renewed` lists the claims that remain owned; `superseded` lists the claims whose event's `attemptCount` passed the listed attempt. An expired claim no successor took appears in neither: it may still complete. Renewal never revives an expired claim. |
-| `completeAttempt` | Fence on the current attempt, mark the parent processed, store its exact ordered `returnedEventIds`, and append the returned batch in the same transaction. A same-attempt retry returns the committed children; a stale attempt returns `superseded`. |
-| `failAttempt` | Record one current caught failure, clear its claim, and dead-letter at `maxFailures`. A repeated failure acknowledgment is idempotent; stale attempts return `superseded`. |
-| `clear` | Serialized with `append`. Check `ifLastIndex` against the head and the latest marker, and append a settled clear marker at the next index, touching no existing rows. A `cause` is fenced like a handler append. |
-| `reclaim` | Delete one bounded batch of rows below the latest clear marker, with their bookkeeping, event-id records, lane pointers, and cached state. Report how many rows went and `done` when nothing is left. Never wait on a lock that other methods hold. |
-
-A store that supports clearing treats every event at or below the latest clear
-marker as superseded, whether or not its row still exists. `claimAvailable`
-never claims it, lane readiness at append and at completion ignores it (a
-dead-lettered lane head stops blocking), `renewClaims` reports it in
-`superseded`, `completeAttempt` and `failAttempt` return `superseded`, and an
-`append` whose `cause` names it throws `SUPERSEDED_ATTEMPT`. An `append` whose
-`originIndex` is at or below the marker throws `SESSION_CLEARED`. Reads start
-at the marker, `readState` returns its index as `clearIndex`, and claimed
-events carry it as `clearIndex`. In `append` and `completeAttempt`, an event id
-whose row is below this session's marker is free to reuse. Each check belongs
-inside the operation's existing atomic step. Without `clear` and `reclaim`,
-`session.clear()` and `session.schedule.clear()` throw a `TypeError` before
-writing anything.
-
-`attemptCount` counts claims, including abandoned ones. `failureCount` counts
-caught failures and dead-letters at ten. See
-[Durability](/concepts/durability#one-event-many-attempts) for the recovery
-model. `cause` identifies the event and handler attempt whose
-`ctx.session.append` or return value first persisted the child. A null cause
-means a top-level event.
-`lane` is the session-scoped serialized group resolved before append.
-`returnedEventIds` makes a lost completion
-acknowledgment recoverable without accepting a partial child batch. Lifecycle
-timestamps are adapter clock values for their atomic store operations, not exact
-database commit times.
-Built-in adapters persist these fields inside their existing atomic operations,
-with no extra backend round trip.
-
-### `A2Scheduler`
-
-Custom scheduler adapters implement two methods:
-
-| Method | Effect |
-| --- | --- |
-| `schedule(task: SchedulerTask): Promise<void>` | put one versioned task on durable delivery infrastructure |
-| `handler(...servers)` | return the route that receives drain, append, and clear tasks |
-
-Application routes call `scheduler.handler(...servers)` on the configured
-adapter. The handler requires at least one drainable server and rejects
-duplicate contract names synchronously.
-
-`SchedulerTask` is `SchedulerDrainTask | SchedulerAppendTask |
-SchedulerClearTask`. These task types, plus `ScheduledEvent`, are exported
-from `experimental-a2/server`.
-
-| Task | Fields |
-| --- | --- |
-| `SchedulerDrainTask` | `version: 1`, `kind: 'drain'`, `contract`, `sessionId`, required epoch-ms `dueAt` |
-| `SchedulerAppendTask` | `version: 1`, `kind: 'append'`, stable `id`, `contract`, `sessionId`, required epoch-ms `dueAt`, readonly `events`, optional `originIndex` |
-| `SchedulerClearTask` | `version: 1`, `kind: 'clear'`, stable `id`, `contract`, `sessionId`, required epoch-ms `dueAt`, `ifLastIndex` |
-| `ScheduledEvent` | fixed `id`, `type`, and JSON `payload` |
-
-Drain tasks wake pending work and carry no application payload. Append tasks
-carry the events for `session.schedule`; `originIndex` is the scheduling
-handler's event, absent for root schedules. Clear tasks carry the condition
-for `session.schedule.clear`.
-
-Custom adapters deliver an authenticated, normalized append or clear task
-through the server helpers:
-
-```ts custom-scheduler.ts
-import {
-  deliverSchedulerAppend,
-  deliverSchedulerClear,
-  type DrainableServer,
-  type SchedulerAppendTask,
-  type SchedulerClearTask,
-} from 'experimental-a2/server'
-
-export async function deliver(
-  server: DrainableServer,
-  task: SchedulerAppendTask | SchedulerClearTask,
-) {
-  if (task.kind === 'clear') await deliverSchedulerClear(server, task)
-  else await deliverSchedulerAppend(server, task)
-}
-```
-
-Import both from `experimental-a2/server`. Each verifies the task and server
-contract match. `deliverSchedulerAppend` revalidates the carried event inputs
-and uses the ordinary top-level append path. The target server must have a
-scheduler. When the append leaves pending handler work, the helper resolves
-only after a recovery watchdog is durable; a send failure keeps the provider
-delivery retryable. A task whose `originIndex` was cleared resolves without
-appending.
-
-`deliverSchedulerClear` runs a conditional `clear({ ifLastIndex })` and
-resolves after its deletion finishes. A store failure rejects, so the provider
-redelivers and the retry finishes deleting. Authenticate the transport and
-validate the task envelope before calling either helper.
-
-## Session
-
-### `session.append(...events)`
-
-```ts
-session.append(
-  ...events: Array<{ type: string; payload: unknown; id?: string }>
-): Promise<Event[]>
-```
-
-The only way to move a session forward. Payloads are validated against
-the contract's schemas before anything is written. A multi-event append
-is atomic: all-or-nothing, consecutive positions, one transaction. Pass
-`id` to make an append idempotent across retries; re-sending an
-identical batch returns the original rows. (Events that arrived through
-`server.fetch`'s push lane are accepted directly.) See
-[Durability](/concepts/durability).
-
-After the write, A2 dispatches only event types with registered handlers.
-Other event types are already settled by the append itself. An unhandled
-append still starts session healing when older handled work is pending. The
-store reports that session-wide pending state as part of the atomic append, so
-this decision needs no follow-up read.
-
-### `session.append.dispatch(...events)`
-
-```ts
-session.append.dispatch(
-  ...events: Array<{ type: string; payload: unknown; id?: string }>
-): Promise<Event[]>
-```
-
-Commits the same atomic batch, but sends pending work directly to configured
-scheduler instead of starting an inline drain. The call awaits acceptance of an
-immediate scheduler message. It throws before writing if the server has no
-scheduler adapter.
-
-If the queue send fails, the events are already durable. Give them explicit
-IDs and retry the same dispatch safely. A batch that leaves no pending handler
-work does not send a scheduler message. Dispatch chooses how this append wakes
-the session; it does not reserve events for one worker. A drain that is already
-active may still claim newly eligible work first.
-
-`dispatch` exists only on a server session's top-level append. Handler-scoped
-`ctx.session.append(name, ...events)` already runs inside an active drain and
-does not expose `dispatch`. Its immediate children and atomically returned
-children become eligible in that drain.
-
-### `session.schedule(name, timing, ...events)`
-
-`schedule` returns `Promise<void>` and is available on both root and handler
-sessions. `name` must be non-empty. At least one event is required.
-`ScheduleDelay`, `ScheduleTiming`, and `SessionSchedule` are exported from
-`experimental-a2/server`.
-
-| Timing | Meaning |
-| --- | --- |
-| `{ delay: '30s' }` | relative delay with unit `ms`, `s`, `m`, `h`, or `d` |
-| `{ at: Date }` | absolute delivery time |
-
-The template type checks the unit suffix. At runtime, the delay number must be
-an unsigned base-10 decimal without leading zeros, finite, and greater than
-zero. `0s`, signs, exponent notation, malformed durations, invalid dates, and
-objects containing both timing fields are rejected. A root relative delay
-starts from that call's wall clock. A handler relative delay starts from the
-triggering event's durable `createdAt`, so retries preserve its delivery time.
-Use `{ at }` when a retried root call needs one target time. The requested
-target is the earliest useful delivery time. Adapters encode provider timing
-in whole-second slots. An already-due target is sent immediately.
-
-The stable task id derives from the contract, session, and name. Handler tasks
-also include the triggering event id. Omitted event ids derive from that task
-id and event position; explicit ids win. Reuse a name only for an identical
-timing and event batch. Provider deduplication is an optimization. Stable event
-ids make later duplicate deliveries converge in the store.
-
-A2 snapshots payloads into plain JSON trees, then validates the event schemas
-before sending. Encode dates as ISO strings and custom classes as plain data;
-values such as `undefined`, bigint, functions, symbols, cycles, accessors, and
-non-plain prototypes are rejected. The promise resolves after provider
-acceptance, not after append. Shared object references become independent JSON
-values. The task carries the snapshotted JSON schema input. At delivery, the
-ordinary top-level append validates that input, so a schema
-transform produces the stored payload from the original input. The events have
-`cause: null` and enter normal handlers, lanes, state, and streams.
-
-A task scheduled from a handler belongs to its triggering event's lifetime. If
-the session is cleared before delivery, the task is acknowledged without
-appending. Once a session has been cleared, handler task ids also include the
-clear, so a trigger id reused in the new lifetime schedules a new task. A root
-task has no triggering event, so its events join whichever lifetime exists when
-it is delivered, and its name identifies one task across lifetimes. Put
-something from the new lifetime in the name when you schedule again after a
-clear.
-
-There is no cancellation, reschedule, cron, or timer-listing API. See
-[Timers and delays](/guides/timers) for stale-timer guards, provider limits,
-and deployment compatibility.
-
-### `session.clear(options?)`
-
-```ts
-session.clear(options?: { ifLastIndex?: number }): Promise<{
-  cleared: boolean
-  index: number
-}>
-```
-
-End the session's current lifetime. One atomic step checks the condition and
-appends a reserved clear marker at the next index. The session id stays usable
-and indexes never restart. `ifLastIndex` is a non-negative safe integer; the
-first matching rule decides:
-
-| When | Result |
-| --- | --- |
-| the latest marker is at `ifLastIndex + 1` | `{ cleared: true, index }`, a retry of that clear |
-| `ifLastIndex` is given and is not the head | `{ cleared: false, index }`, nothing changes |
-| the head is `0` or already a clear marker | `{ cleared: true, index }`, nothing changes |
-| otherwise | `{ cleared: true, index }`, the new marker |
-
-`index` is always the head after the call. Every event at or below the marker
-is superseded: it is never dispatched again and never blocks its lane, its
-running handler's appends throw `SUPERSEDED_ATTEMPT`, and that handler's state
-reads never fold the new lifetime: they throw `SESSION_CLEARED`, except that
-after a clear from another instance, a read bounded at its own event may return
-that event's state from memory until the handler's `ctx.signal` aborts. Pushes and appends after the marker start the
-new lifetime.
-
-`clear()` then deletes the old events, their bookkeeping and event-id records,
-and cached state below the marker in short batches, and resolves when they are
-gone. Other work on the session keeps running between batches. If deletion
-fails, the call rejects with the session already cleared; any later clear of
-the session, including a retry, finishes the deletion. There is no background
-sweep. Event ids from the old lifetime can be used again. Presence is not
-cleared.
-
-On `ctx.session`, the clear is fenced like the handler's appends and ends the
-handler's own attempt: `ctx.signal` aborts with `SUPERSEDED_ATTEMPT` and
-returned events are discarded. Its deletion keeps running under the platform's
-`waitUntil`. All built-in stores support clearing. See
-[Clearing a session](/concepts/contracts#clearing-a-session).
-
-### `session.schedule.clear(name, options)`
-
-```ts
-session.schedule.clear(
-  name: string,
-  options: ({ delay: ScheduleDelay } | { at: Date }) & {
-    ifLastIndex: number
-  },
-): Promise<void>
-```
-
-Publish a conditional clear to the configured scheduler. `name` is non-empty
-and `ifLastIndex` is required. Timing has the same meaning and provider limits
-as `session.schedule`. The task id derives from the contract, session, name,
-and condition, plus the triggering event id and any earlier clear inside a
-handler; reuse a name only for the same timing. The promise resolves after
-provider acceptance.
-
-Delivery runs `clear({ ifLastIndex })` and acknowledges after the deletion
-finishes. A stale or duplicate delivery changes nothing. No event is appended.
-Indexes never repeat, so a condition from an older lifetime never matches a
-newer one. Clear tasks, appends, and recovery drains all use the Vercel
-scheduler's `deploymentId` setting.
-
-`ifLastIndex: ctx.event.index` matches only while the handler's event is still
-the head. The handler's own appends and returned events move the head, so a
-handler that writes should use the index of its last `ctx.session.append`
-instead. Actor handlers always commit state, so they can't use the trigger's
-index. A delay short enough to deliver while the handler is still running can
-match before those writes land; the clear then ends the handler's attempt and
-discards its returned events.
-
-Each delivery attempt resumes the deletion where the last one stopped. Vercel
-Queues redelivers until retention ends. QStash retries one message up to its
-`retries` budget; a deletion that outlasts every retry leaves the message in
-QStash's dead-letter queue with the rest of the old history still invisible,
-and any later clear of the session finishes it.
-
-### `session.history()`
-
-```ts
-session.history(options?: { gte?: number; lte?: number }): Promise<Event[]>
-```
-
-Raw events from the session, oldest first. `gte` and `lte` are inclusive event
-indexes; omit a bound to leave that end of the log open.
-Bounds are non-negative safe integers. `lte: 0` returns `[]`; `gte > lte` throws.
-After a clear, history starts after the marker. The marker itself is not
-returned.
-
-Redis reads a fixed committed range in pages of at most 256 events, with up to
-sixteen page reads in flight. Public history omits dispatch metadata. PostgreSQL
-uses one indexed range query selecting only public event columns. Custom store
-adapters can implement `readHistory(sessionId, options)` with the same exclusive
-`afterIndex` and inclusive `throughIndex` bounds as `read()`. A2 falls back to
-`read()` when that capability is absent.
-
-### `session.state(reducer, options?)`
-
-```ts
-session.state(
-  reducer: Reducer<S>,
-  options?: { through?: number | 'latest' },
-): Promise<{ state: S; index: number; clearIndex?: number }>
-```
-
-The log folded through one committed prefix. `index` is its exact boundary,
-an append-order cursor rather than a handler-settlement marker. Hand it to the
-client to resume there. Snapshot write-back uses platform `waitUntil`; this
-read never dispatches handlers or waits for pending work.
-
-On a root session from `server.session(id)`, omitting `through` reads the latest
-committed frontier. On the handler-scoped `ctx.session`, omitting it reads
-through `ctx.event.index`. That boundary is inclusive and stable across retries.
-Use `{ through: 'latest' }` inside a handler only when later committed events
-are intentionally part of the decision. A numeric `through` is an inclusive,
-non-negative safe integer; `through: 0` returns the reducer's initial state.
-
-Once a session has been cleared, the result includes `clearIndex`, the latest
-marker, and state folds from there. Forward the whole result when hydrating a
-client. A positive `through` below `clearIndex` throws `SESSION_CLEARED`, and
-`through: 0` returns the seed without `clearIndex`. On
-`ctx.session`, every state read throws it once the triggering event has been
-cleared, including `{ through: 'latest' }`. Handler `history()` and `stream()`
-are not fenced.
-
-The default handler read and numeric handler reads automatically retain their
-exact folded checkpoint while the triggering event is unfinished. Completion
-or dead-lettering releases the reference and collects the checkpoint when no
-other unfinished handler uses it. There are no retention options. Handler
-`{ through: 'latest' }` reads and all root reads do not retain history.
-
-If the latest snapshot is ahead of a numeric boundary, A2 can use the greatest
-eligible retained checkpoint. A root historical read never creates retention
-or writes a stale checkpoint behind the latest snapshot; it folds from the log
-when no eligible checkpoint exists.
-
-Operational snapshot-read failures preserve existing A2 errors; other errors
-become `STORE_UNAVAILABLE` with the original error as the cause. They do not retry through individual
-reads or raw history. Cache misses and `stateSchema` rejection still rebuild
-from the log. Snapshot write-back remains background work; failures are reported
-through `a2.snapshot` telemetry or the default console sink, without failing the
-completed read or attaching snapshot contents.
-
-### `session.stream(options?)`
-
-```ts
-session.stream(options?: { startAfter?: number }): AsyncIterable<Event | SessionCleared>
-session.stream(options: {
-  startAfter?: number
-  presence: true
-}): AsyncIterable<Event | SessionCleared | PresencePatch | PresenceSnapshot>
-```
-
-A live feed of the session's events. `startAfter` is a non-negative safe integer;
-`startAfter: 20` begins with event 21.
-Server-side only; `server.fetch` exposes it over SSE and WebSocket. Subscribing
-never dispatches handlers.
-
-A clear arrives in order as a `SessionCleared` marker, whose `type` is
-`'a2.cleared'`. A stream that opens below the
-latest marker begins with it. A stream that is already running delivers the
-log in order, so events from before the clear can arrive ahead of the marker.
-Reset when the marker arrives. Clearing never closes a stream.
-
-With `presence: true`, the feed yields one `PresenceSnapshot` first:
-`{ snapshot }`, the current pruned map with each field's own `value`,
-`seen`, and `at` stamp. Live presence patches then interleave with
-events. The stream response sends both as named SSE frames, so clients
-that don't know them skip them. The return type widens only under the
-literal `presence: true`; without it, existing consumers keep
-`AsyncIterable<Event>`. The option itself exists only on sessions of
-contracts that declare `presence`; elsewhere it is a type error, not a
-runtime throw. A `PresencePatch` is `{ participant, values, seen, at }`
-with `values` typed by the contract's presence schemas (`null` marks a
-cleared field).
-
-### `session.setPresence(patch)`
-
-```ts
-session.setPresence(patch: {
-  participant: string
-  values: { [field]: payload | null } // partial; null clears a field
-  seen?: number
-  at?: number // the sender's LWW stamp, epoch ms; receipt time when absent
-}): Promise<void>
-```
-
-Validates each field against the contract's `presence` schemas, then
-broadcasts. Last writer wins per participant per field, ordered by
-`at`, the sender's stamp in epoch milliseconds (the browser client
-stamps its sends automatically). When `at` is absent, receipt time
-stands in: a stampless caller is a single writer, so receipt order is
-its send order. No log row, no
-dispatch, no scheduler arm; `history()` and `state()` never see it. A
-bad payload throws `INVALID_PAYLOAD`; an unknown field throws
-`UNKNOWN_PRESENCE_FIELD`; a non-finite or negative `at` throws a
-`TypeError`. `seen` is the sender's stream frontier, the
-stamp view code uses to reconcile presence against the fold (see
-[Presence](/guides/presence#reconciling-the-planes-seen)). Values expire
-by backend TTL when a participant goes silent (default 60 seconds; set
-`createServer({ presence: { ttlMs } })` to change it). Expiry counts on
-the storage clock, not the sender stamp, so a hostile stamp can only
-vandalize its own field and still expires on schedule.
-
-The patch is structurally the `presence` sibling of the push envelope;
-`server.fetch`'s push lane forwards it whole to `session.setPresence(presence)`.
-The API mirrors the wire.
-
-The handler-scoped form `ctx.session.setPresence(...)` is the same
-operation; `seen` defaults to the triggering event's `index`.
-
-### `session.presence()`
-
-```ts
-session.presence(): Promise<{
-  [participant: string]: {
-    [field: string]: { value: unknown; seen: number; at: Date }
-  }
-}>
-```
-
-The current presence map, expired values pruned. A point-in-time read
-for server renders; live consumers use `stream({ presence: true })`.
-Each entry's `at` is the sender's stamp for when the value was set,
-the last-writer-wins comparator; how long a value stays painted is
-still view logic, decided at render time.
-
-## Event
-
-```ts
-type Event = {
-  id: string
-  type: string
-  payload: unknown // typed by the contract's schema for `type`
-  index: number // position in the session's log, from 1
-  sessionId: string
-  createdAt: Date
-}
-```
-
-## `experimental-a2/react`
-
-### `createReact(options)`
-
-```ts
-createReact(options: {
-  client: A2Client          // bind a shared client: api + contract + session identity
-}): { SessionProvider, useSession }
-
-// or, bind the contract and supply api through the Provider:
-createReact(options: {
-  contract: Contract       // requires a public reducer
-}): { SessionProvider, useSession }
-```
-
-A factory, like `createContext`: call it once in a `'use client'`
-module, export the bound pair. Server components import
-`SessionProvider` from that module as a client reference; client
-components import `useSession` from the same file. See
-[Live UI](/guides/react#bind-react-once).
-
-`createReact({ contract })` is also supported for provider-bound clients. Use a
-shared `A2Client` when code outside the provider needs to push before a route
-transition and the destination should adopt the same optimistic session.
-
-### `<SessionProvider>`
-
-| Prop            | What it is                                             |
-| --------------- | ------------------------------------------------------ |
-| `sessionId`     | which session to subscribe to                          |
-| `initial`       | optional snapshot or Promise of a snapshot; `null` means bootstrap |
-| `initialEvents` | optional earlier raw events for a history UI           |
-| `participant`   | overrides the client's `participant`; one of the two is required to call `setPresence` |
-
-Supplies scope and optional initial data. Mounted enabled hooks own
-connection leases and reconnect from the last streamed event. `participant` binds at the session's
-first resolution; a changed provider prop is ignored for the session's
-runtime lifetime.
-
-`initial` carries the complete state/index snapshot, plus `clearIndex` when
-the session has been cleared.
-For a new session, the stream starts after `initial.index`, including events
-appended between the server render and the connection. `initialEvents` only preloads the raw
-`events` feed for a UI that needs entries from before that frontier. It does
-not affect state hydration or stream resumption. Later snapshots advance
-state while preserving the stream's resume position, so delayed events
-still enter the feed without folding into state again.
-
-`initial` accepts `InitialSnapshot<S>`: `StateSnapshot<S> | null | undefined |
-Promise<StateSnapshot<S> | null | undefined>`. The type is exported from
-`experimental-a2` and `experimental-a2/client`. A cold session waits for a
-supplied Promise before connecting. A snapshot result seeds state; `null`
-or `undefined` selects subscription bootstrap. Rejection pauses cold startup
-and reports through `connection.error`; supply a new Promise, snapshot, or
-`null` to resume. A warm session keeps its current state and connection.
-The Provider itself does not suspend. Keep Promise identity stable.
-
-### `useSession(options?)`
-
-```ts
-const { state, hydrated, push, reconnect, events, index, loadHistory, history, connection } = useSession()
-```
-
-`state` has the reducer's client state type. A supplied snapshot seeds the
-first render. Otherwise it displays `reducer.initialState`, through the client
-projection when present, until a snapshot replaces it atomically. Without a
-supplied snapshot, the server sends one first on the same subscription.
-Bootstrap errors and retries use `connection`.
-`hydrated` is a boolean shared with `session.getSnapshot()`. It is `false`
-while only the reducer seed is available and becomes `true` when an initial
-snapshot or bootstrap is applied, even for an empty state at index 0.
-It stays `true` while cached state survives reconnects, disabled hooks, or a
-failed replacement preload. It does not imply a live connection or fresh data.
-The hook accepts `sessionId`, `client`, `participant`, `initial`, `enabled`, and
-`suspend` options; scope defaults come from its Provider and bound client.
-`suspend` defaults to `false`. With `true`, React `use()` reads the supplied
-`initial` Promise, using the nearest Suspense and Error boundaries. Automatic
-subscription bootstrap never suspends, including when the Promise resolves
-to `null` or `undefined`. The default renders the reducer seed while a cold
-initial Promise is pending. `enabled` controls connection ownership independently.
-
-`state` starts from that snapshot and folds live events through the
-shared reducer. `events` is the raw event feed: observed, explicitly
-seeded, or backscrolled. Unless `initialEvents` seeds earlier entries or
-`loadHistory` fetches them, it begins after `initial.index`. `index` is
-the latest server-confirmed state index, the `lastSeenIndex` for
-[cancellation](/guides/cancellation).
-
-`loadHistory({ before?, limit? })` backscrolls: it fetches a bounded
-slice of the log from below the frontier (the same route, `gte`/`lte`
-query parameters) and merges it into `events`, deduped, ordered, and
-shared across every handle of the session. It resolves with the events
-in the requested range. Defaults walk backward 50 at a time from the
-oldest loaded event; `before` is an exclusive upper bound. After a
-newer snapshot hydrates the session, default paging still continues from
-the oldest loaded event. Pass an explicit `before` to read another range.
-It never touches `state` or the optimistic overlay. Calls
-serialize per session and already-loaded ranges are not refetched.
-`history` is the progress: `{ loading, complete, oldestLoaded }`, where
-`complete` means the feed reaches index 1, or the first event after the latest
-clear (or the log is empty). The `ws` api has no history lane; there `loadHistory`
-throws a `TypeError`.
-
-When a clear reaches the session, `state` resets to the reducer's initial
-state and `events` drops everything at or below the marker. Unconfirmed pushes
-stay in the overlay and apply to the reset state. A push acked below the marker
-was cleared with it: it leaves the overlay and its `confirmed` resolves.
-
-`presence` is the replicated ephemeral map,
-`Record<participantId, { [field]: { value, seen, at } }>`, including
-this client. `setPresence(values)` is fire-and-forget: validated
-locally, merged into the local map immediately, coalesced on the wire
-to a fixed cadence (a leading send immediately, then at most one
-merged send per interval; later values win per field), stamped with
-the frontier at send time as `seen`. Parallel sends are safe: merges
-are last-writer-wins by `at`, and the client's stamps are monotonic
-per session (wall-seeded, guarded so overlapping sends can never
-invert). No ack, no `confirmed`, no retry.
-
-Both members exist only when the contract declares `presence`; their
-value and field types come from its schemas, through the reducer, with
-no type arguments (the reducer is the client's typed handle on the
-contract; it still never folds presence). `setPresence` requires a
-`participant`: the client's default, or the provider's override. See
-[Presence](/guides/presence).
-
-`push` appends optimistically: validated locally, rolled back on
-rejection, retried for `STORE_UNAVAILABLE` and transport failures. Awaiting it gives the
-server ack; the same result carries `confirmed`, a lazy promise for
-the later moment when the live stream has delivered the batch back and
-the view shows server truth:
-
-```ts
-const t0 = performance.now()
-const result = push({ type: 'created', payload })
-await result // the server ack: push→ack latency
-await result.confirmed // the stream round-trip: ack→stream latency
-const roundtripMs = performance.now() - t0
-```
-
-Overlapping calls through the same session client update the view
-immediately, then enter the transport in invocation order. Each call waits
-only for the previous call's ack or final rejection, not for `confirmed`.
-Other session IDs and clients remain concurrent; they converge on the log's
-durable order.
-
-A rejected push rejects both promises with the same `A2ClientError`;
-`confirmed` is materialized only when accessed, so ignoring it costs
-nothing. It also reads as intent: `await push(...).confirmed` is
-"continue once this is server truth".
-
-`session.reconnect(): void` immediately restarts a leased subscription,
-including one paused by the reconnection policy,
-from its current cursor. It preserves state, pending writes, and leases, and
-does nothing without an active lease. The React `useSession()` result exposes
-the same `reconnect` function. Use it after a custom REST mutation; it requests
-a restart rather than returning a promise for catch-up completion. A
-multiplexed WebSocket keeps its physical socket and other session lanes;
-a single-session WebSocket replaces its socket.
-
-`connection` is a discriminated union; impossible states are
-unrepresentable (an `error` only exists while disconnected):
-
-```ts
-// in a client module:
-import type { A2ClientError } from 'experimental-a2/client'
-
-type Connection =
-  | { status: 'idle' }
-  | { status: 'connecting'; reconnects: number; error: A2ClientError | null }
-  | { status: 'paused'; reconnects: number; error: A2ClientError | null }
-  | { status: 'live'; reconnects: number }
-  | { status: 'closed' }
-```
-
-"Reconnecting…" is `status === 'connecting' && reconnects > 0`. And
-it's honest about silence: the server heartbeats the stream (`: ping`
-every 15s), and a client that hears nothing for two beats treats the
-connection as dead (aborts it and reconnects), so `live` means bytes
-are actually flowing, not "the socket hasn't errored yet". See
-[Live UI](/guides/react).
-
-### `useSession(client, sessionId, options?)`
-
-```ts
-useSession(client: A2Client, sessionId: string, options?: {
-  participant?: string // overrides the client's participant
-  initial?: InitialSnapshot<S>
-  enabled?: boolean
-  suspend?: boolean
-}): UseSessionResult
-```
-
-The standalone, provider-less hook. It returns the same result shape
-as the bound hook, for apps whose components reach sessions ad hoc (a
-sidebar of channel sessions, a user session read from a menu). The
-handle is identity-mapped: every hook and provider mounting the same
-session shares one runtime. The stream is refcounted: the first mount
-connects, the last unmount closes (StrictMode-safe).
-
-`initial` accepts the result of `session.state(reducer)` or its Promise. Pass it
-whole: its `clearIndex` lets a cached client drop history from before a clear
-it never streamed. The automatic snapshot carries it too. Without it,
-the subscription obtains a snapshot automatically. To defer automatic I/O,
-pass `enabled: false`. Disabled hooks keep observing cached state; other
-owners continue normally. Explicit pushes can still acquire a connection.
-For deliberate full replay, supply `{ state: reducer.initialState, index: 0 }`.
-See [Live UI](/guides/react).
-
-## `experimental-a2/ai`
-
-The isomorphic AI protocol: event schemas, the `AIState` reducer, pure input
-builders, and `agentContract()` for extending both. It has a peer dependency on
-AI SDK v7, used as types only here.
-
-### `agentContract(options)`
-
-```ts
-agentContract<M extends UIMessage = UIMessage>(options: {
-  name: string
-  events?: Record<string, StandardSchemaV1>
-  messageSchema?: StandardSchemaV1<M>
-  reducer?: {
-    name: string // snapshot identity: rename it when fold changes
-    initialState: X // its keys may not shadow AIState's
-    fold: (state: X, event: ContractEvent) => X
-  }
-}): Contract<Events, {}, AgentReducer<M, Events, X>>
-```
-
-A core contract carrying the built-in AI protocol plus `events`, with a reducer
-that folds `AIState` and, with `reducer`, your application state beside it.
-The session's state is `AIState<M> & X`. Share it when a client needs
-application events or state: serve it with `agent({ contract })` and use it
-with [`useAgent({ api, id, contract })`](#useagentoptions). Otherwise
-`agent({ name })` builds one on the server and clients use the built-in
-protocol.
-
-Built-in event names cannot be replaced by `options.events`. `messageSchema`
-validates a narrower `UIMessage` type in message payloads; the explicit type
-argument types messages without one. `reducer.fold` sees `X` and every event,
-never the transcript; it runs after the AI fold on the server and in every
-client, so optimistic display carries through. A key of `initialState` that
-`AIState` also has throws a `TypeError` and fails to typecheck. The reducer name
-is `AI_STATE_REDUCER` (`a2.ai.state.v26`) without `reducer`, and
-`${reducer.name}+a2.ai.state.v26` with one, so checkpoints advance when either
-fold changes. `AgentReducer` types that name, which is what lets
-[`createAgentClient()`](#createagentclientoptions) accept a plain
-`agentContract()`, and carries `X` to `agent()`'s resolvers.
-
-### `TranscriptMessage<M>`
-
-```ts
-type TranscriptMessage<M extends UIMessage> = Omit<M, 'parts'> & {
-  parts: Array<M['parts'][number] | CompactionPart>
-}
-```
-
-The message type of `AIState<M>['messages']` and `deriveUIMessages()`: your
-message type with the [compaction part](#iscompactionpartpart) added, so
-`isCompactionPart()` narrows even when `M` declares its own data parts.
-
-### `AIMessageOf<Events>`
-
-The `UIMessage` type a contract's `ai.message.created` schema carries, such as
-`AIMessageOf<typeof contract.events>`. It falls back to `UIMessage`. `agent()`
-uses it to type messages for any contract carrying the AI protocol.
-
-### `handlerContext(contract?)`
-
-Reads the durable A2 handler context ambient to the current tool
-execution. Tools are plain AI SDK `tool()` definitions; A2 passes their
-options through to the AI SDK without interpreting them and runs each
-local `execute` inside an ambient context scope. Call
-`handlerContext()` anywhere below `execute`, including awaited helpers and
-async iteration. A call outside any tool execution throws a `TypeError`.
-Without an argument, the context is typed for the built-in protocol. Pass a
-shared `agentContract()` to type application events; A2 verifies it against the
-executing agent and throws a `TypeError` on a mismatch.
-
-The returned `AgentToolContext<D>` supplies the current A2 handler's `event`,
-`attempt`, `session`, and `signal`. Local tools execute the explicit
-`ai.tool.execution.requested` work event. Its payload contains the admitted
-`call`, `generation`, `turnId`, and execution `version`. Calls such as
-`ctx.session.schedule()` use the scheduler of the agent executing the tool.
-
-The context is runtime capability, not event data. A2 creates it for the
-current attempt, never persists it, and never sends it to the model or a
-provider-executed tool. Each retry reads that attempt's fresh context.
-Model-phase tool options (`contextSchema`, dynamic descriptions,
-`needsApproval` predicates, input lifecycle callbacks) are the AI SDK's
-own; A2 forwards them untouched, and durable execution passes no AI SDK
-`context` option. `needsApproval` and `generation.toolApproval`
-predicates run during the model step and are re-evaluated on recovery
-for the same durable tool call, so keep them deterministic over the tool
-input. Model-phase hooks see tool definitions without local `execute`
-functions.
-
-### `inputs`
-
-Pure typed inputs for `append()` and `push()`. The `useAgent()` actions build
-the browser ones:
-
-| Input | Events |
-| --- | --- |
-| `inputs.message(message, { generate? })` | queues input; `generate: false` records passive context at admission |
-| `inputs.seed(message)` | queues passive context; non-user roles require a trusted append |
-| `inputs.approval(response)` | answers a pending tool approval |
-| `inputs.input(response)` | answers a pending application input |
-| `inputs.requestInput(request)` | requests application input from trusted server code |
-| `inputs.retry(options)` | retries a failed response |
-| `inputs.stop({ turnId, lastSeenIndex? })` | ends the observed turn and advances when admission is open |
-| `inputs.steer({ turnId, message, lastSeenIndex? })` | puts the new input first for a handoff after the observed turn's current step |
-| `inputs.queue.edit({ message })` | changes a pending input; its ID stays fixed |
-| `inputs.queue.move({ inputId, beforeId })` | moves pending input before an ID; `null` means the end |
-| `inputs.queue.remove({ inputId })` | removes pending input; its submission stays in the log |
-| `inputs.queue.sendNow({ inputId, turnId, lastSeenIndex? })` | promotes an existing queued input for a handoff after the current step; preserves pause |
-| `inputs.pause({ when: 'now' \| 'after-turn' })` | pauses execution now or inbox admission after the turn |
-| `inputs.resume()` | resumes retained work, then inbox admission |
-| `inputs.toolResult(result)` | records a deferred provider-executed tool result from trusted server code |
-| `inputs.interrupt(options)` | interrupts a specific generation/request owner |
-
-Edits are last-write-wins in session log order and preserve the pending message's
-identity and role. They require no revision or confirmation before another edit.
-Admission freezes the message; subsequent edits return `not-pending`.
-
-All builders emit `ai.control.requested`. Persistence and application are
-separate: `ai.control.decided` returns `{ commandId, outcome, reason? }` through
-the existing stream. Outcomes are `applied` or `rejected`. Rejection reasons
-include `not-pending`, `role-mismatch`, `stale-turn`, `not-found`,
-`not-user-input`, and `closed`.
-`state.receipt` holds the latest user receipt.
-
-Steering validates and prioritizes new input even if the observed turn has
-finished. A matching active turn finishes its current model response and tool
-batch, then yields before another model step. Running local workers and deferred
-provider results settle first; unanswered human approval/input waits can be
-closed at that point. Pause stays closed. Otherwise the input starts when idle
-or waits first behind a different active turn. The priority change is atomic;
-the later handoff and new work are committed atomically at the step boundary.
-Steer and Send now do not use `lastSeenIndex` to cut output.
-
-Queue removal leaves the original submission in the log, so replay does not recreate the input.
-Send now preserves the queued input ID and latest accepted content. It requires
-an observed `turnId` (or null for idle), preserves pause, and only accepts
-user-role input. It promotes passive user input to generation. Missing targets
-and stale turns reject before any queue change.
-
-`state.inbox` contains `paused` and ordered `items`. Each item contains
-`{ id, message, generate, afterStepOf? }`. The optional turn ID
-`afterStepOf` records the observed steering turn while that item remains queued;
-a matching active turn hands off after its current step.
-Removal cancels it and admission consumes it. `state.active` is null or contains
-`{ turnId, input, phase }`; admission freezes `input`. On the server, pending
-inputs are absent from `messages` and model context. The `paused` status and the `pausing`/`paused`
-active phases represent retained work. Resume uses a fresh model request and
-execution version. Tools without terminal outcomes can retry; their stable
-`toolCallId` supports external idempotency.
-
-`inputs` deliberately has no session lifecycle methods. Append explicit
-`ai.session.created` and `ai.session.closed` events from trusted server code
-when an application uses them. Message, seed, and steering builders set the event ID to the input message ID.
-The two IDs must match for all new-input commands. Caller command/input IDs must
-be nonempty and cannot use the reserved `a2.ai:` prefix. Identical events replay;
-conflicting ID reuse rejects before append under core deduplication rules. IDs
-are unique across the store, including different contracts and sessions.
-Approval, input-response, and retry builders use stable interaction IDs.
-Other commands use IDs assigned by `push()` or `append()`; transport retries
-preserve those IDs. Browser
-ingress accepts user messages, approval and input responses, interruptions,
-and explicit retries. Only built-in server handlers append generation requests
-and AI lifecycle events. `inputs.requestInput()`, `inputs.toolResult()`, and non-user messages built
-with `inputs.seed()` are for trusted server appends.
-
-`inputs.message(message, { generate: false })` is valid browser input. It admits
-the user message to `AIState.messages` without starting a model turn. The next
-user message that allows generation includes passive user messages before it
-in model context. Passive user messages after that trigger wait for a later
-generating message. Omitting the option preserves the default scheduling
-behavior. `inputs.seed()` writes
-the same passive flag. Trusted assistant and system seeds are context, not user
-queue cutpoints. The server never schedules them, regardless of the `generate`
-field. Model output is generation progress rather than another
-`ai.message.created` fact, so an assistant response cannot recursively start a
-new turn.
-
-Approval and input request/response payloads require the active
-`requestId` and `generationId`. Clients copy both from the pending request, which prevents a
-delayed response from satisfying a newer model step.
-
-`ai.retry.requested` carries `{ messageId, responseMessageId, retryId }`.
-`retryId` identifies one user action. The server converts the fact into an
-`ai.generation.requested` whose reason is `retry`.
-Retry reruns the failed model call while retaining earlier completed model steps,
-their tool results, and committed compactions, including steps completed after
-the latest compaction.
-The failed model call's uncommitted step is removed from the active prompt and
-response. Conversation forks and edit-and-resend flows for admitted messages are
-application-owned.
-
-A2-generated requests, generations, assistant responses, worker jobs, reports,
-and lifecycle events have fixed-length deterministic IDs in the reserved
-`a2.ai:` namespace. An assistant message's ID equals its initial model-request
-event ID. Control state keeps no lifetime input/response-ID registry. IDs are opaque;
-ownership is carried by event fields. `ai.generation.requested` requires
-`responseMessageId`; a tool continuation also requires `sourceGenerationId`.
-
-`ai.generation.failed` sets `stepLimit: true` when `maxSteps` rejects a
-continuation before another model step starts.
-
-`ai.message.interrupted` carries either `{ messageId, requestId, reason?,
-lastSeenIndex? }` or `{ messageId, generationId, reason?, lastSeenIndex? }`.
-Exactly one owner ID is required. Clients copy `requestId` from
-`activeRequestId` before generation start and switch to the observed
-`activeGeneration.generationId` after start. A request-owned interruption
-remains valid if that same request starts before the append commits. A delayed
-interruption for an older owner is a projection and cancellation no-op.
-The message and owner IDs are validated as one pair. If either ID does not
-identify that same response owner, the interruption is stale and is a no-op.
-
-An accepted interruption terminally fences its request or generation. Later
-generation, tool, approval, input, and compaction events remain in raw history
-but cannot alter `AIState`, satisfy pending work, or reactivate the response.
-Completed tool results at or before `lastSeenIndex` remain completed. A final
-tool result that races an ordinary generation failure remains authoritative in
-either commit order, while the generation stays failed.
-
-Interruption and failure projections discard tool parts still in
-`input-streaming`. These argument drafts are not completed tool calls and do not
-enter later model prompts. Raw progress remains in the log. Available inputs,
-approval-waiting calls, and completed results retain their existing terminal
-handling.
-
-### `reasoningLevels`
-
-```ts
-type ReasoningLevel = 'provider-default' | 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
-const reasoningLevels: readonly ReasoningLevel[]
-```
-
-Every `ReasoningLevel`, in order, for pickers. A `model` option returns one in
-[`ModelSettings`](#modelsettings).
-
-### `isCompactionPart(part)`
-
-```ts
-isCompactionPart(part: { type: string }): part is CompactionPart
-
-type CompactionPart = {
-  type: 'data-a2-compaction'
-  id: string // the compacting generation's ID
-  data: {
-    status: 'running' | 'completed' | 'failed' | 'interrupted'
-    inputTokens?: number
-    thresholdTokens?: number
-    summary?: string
-    usage?: LanguageModelUsage
-  }
-}
-```
-
-The transcript part that marks a compaction. When `ai.compaction.requested`
-folds, the reducer appends it to the active response, between the steps
-before it and the model step it compacted for; a compaction before the first
-step creates the response with this part. The part counts toward that step's
-recovery base, so Stop cutoffs, failures, and retries of the step keep it.
-`ai.compaction.completed` settles it in place with the summary and usage. A
-running compaction whose generation ends first becomes `interrupted` (Stop,
-Pause now, or session close) or `failed` (failure). A pending Stop previews it
-as `interrupted` on the client. A superseded worker attempt's part is removed,
-and its replacement compacts again if it needs to. AI SDK
-`convertToModelMessages()` skips data parts by default, and model context never
-contains it.
-
-### `events` and `createEvents(options?)`
-
-The built-in Standard Schema definitions. Use `events` for the default AI SDK
-`UIMessage`; use `createEvents({ messageSchema })` to validate a more specific
-message type. Both are isomorphic.
-
-### Optimistic AI client state
-
-Every client folding an AI reducer exposes `state.messages`, `state.inbox`, and
-`state.starting` with pending send, edit, move, remove, Send now, steer, pause,
-resume, and Stop commands applied for display. This includes contracts with
-application state from `agentContract({ reducer })`. Idle, unpaused
-sends appear in the conversation immediately. A generating input occupies the
-optimistic turn, so subsequent sends queue. Busy or paused sessions queue new
-sends. `starting` indicates a speculative turn awaiting acceptance; it does not
-indicate model execution. Confirmed turns take precedence during reconciliation.
-Steering inputs, and Send now inputs targeting an active turn, appear in
-`state.messages` after the current response and are omitted from the client
-inbox. This display survives receipt and hydration, including while paused.
-They remain pending server inputs until admission and do not enter the model
-prompt early. Multiple steering inputs follow inbox admission order.
-
-New active turn identities come from accepted control decisions. A pending Stop
-for that turn clears the displayed `state.active`, generation, and pending
-approvals/inputs, and previews an idle status (or paused when the inbox is paused). With
-`lastSeenIndex`, its retained generation projection freezes at the observed
-frontier. The preview lasts through the request echo until the controller's
-decision; rejected requests restore the confirmed active turn and output.
-Server reads and reducer folds retain confirmed messages and inbox entries;
-`state.starting` is false there. Custom reducers that call `reduceAIState()` or
-nest the AI fold do not inherit the client display behavior. Repeat editing and
-Send now remain available while earlier edits are pending. Later local edits
-stay visible through earlier commands' acknowledgments and receipts.
-
-The pending-command ledger survives request echo and retires on the matching
-`ai.control.decided` receipt or session close. Failed pushes roll back through
-the client's existing optimistic overlay. This display adds no I/O and does not
-read raw history.
-
-### `AIState`
-
-The AI reducer's `initialState`, `fold`, server `session.state()`, and client
-snapshots all use `AIState`. Keep state and its log index together when
-hydrating; do not fold already-seen history twice. `messages` holds
-[`TranscriptMessage<M>`](#transcriptmessagem) values. Model context has its own
-built-in fold and schema, which carries the contract's application state.
-
-Persistence encoding is internal. Tool inputs, outputs, and provider metadata
-live in message parts; the tool activity list retains only identity and status.
-No event or tool payload is truncated. `AIState`
-contains `inbox`, `active`, `starting`, the latest command `receipt`, session lifecycle,
-messages, generation status, pending approvals
-and input, tool activity, compaction, usage, the last error, and
-`activeRequestId`, `activeRequestReason`, `activeRequestSourceGenerationId`, `activeResponseMessageId`,
-`responseOwners: Record<string, { generationId: string; requestId: string; attempt: number }>`, and terminal request and
-generation ownership fences.
-`activeRequestId` is the server-authorized generation request and fences
-delayed requests before their generation starts. `activeResponseMessageId`
-identifies the requested response until `activeGeneration` exists.
-`activeProjection` holds the indexed generation frontier while a generation is
-active, after a generation step completes while its response waits on tool,
-approval, or input barriers, while paused, and after a generation fails while it awaits retry
-or interruption. Response completion, interruption, supersession, retry, or a
-later generation clears or replaces it. `responseOwners` keeps the
-latest generation owner for each response message, so late events from a
-superseded owner cannot alter the projection. `terminalRequestIds` and
-`terminalGenerations` preserve accepted completion, failure, interruption,
-and supersession fences across snapshots and recovery. They are optional
-snapshot-compatible fields with the shapes `Record<string, true>` and
-`Record<string, 'completed' | 'failed' | 'interrupted' | 'superseded'>`.
-The active projection also stores its prompt boundary and a serializable stream
-cursor for open text, reasoning, and tool-input parts. Ordered progress applies
-only its new chunks. `activeProjection.batches` stores indexed batches as
-`{ length, tail, blocks }`: a bounded tail and shared completed blocks. Appending
-ordered progress does not copy the full retained batch list. The blocks are
-ordinary JSON with logarithmic nesting depth, so checkpoints can be serialized
-and cloned. Retained batches support exact interruption cutoffs and out-of-order
-reconstruction. The cursor and blocks share the active projection's lifetime.
-Checkpoint size and serialization cost still grow with retained progress.
-Tool-input deltas update `input-streaming` parts with best-effort partial JSON
-for display. The state stays `input-streaming` until a completed input arrives;
-partial parsing does not authorize execution or change interruption handling.
-Application events are ignored by the AI fold.
-
-### `deriveUIMessages(history)` and `reduceAIState(state, event)`
-
-`deriveUIMessages()` folds a raw A2 event history directly into
-`TranscriptMessage<M>[]`, AI SDK messages that include compaction parts. `reduceAIState()` is the event-at-a-time form used by the
-standard reducer. Both synchronously project the same chunk-only protocol.
-
-## `experimental-a2/ai/server`
-
-### `agent(options)`
-
-```ts
-agent({
-  name: string, // or contract: agentContract(...), never both
-  events?, messageSchema?, // with name: server-only application events
-  model: LanguageModel | ModelSettings | (context => LanguageModel | ModelSettings),
-  tools?,
-  instructions?,
-  generation?,
-  maxSteps?,
-  messageMetadata?,
-  generate?,
-  compaction?,
-  progress?,
-  toolLane?: string, // run local tool executions one at a time on this lane
-  handlers?, // application event handlers
-  store?, scheduler?, telemetry?,
-}): Agent<Events, State, Name> // an A2Server
-```
-
-Serves an AI agent as one ordinary A2 server: the built-in protocol, its model
-and tool handlers, and A2's store, scheduler, and telemetry. Pass `name` for the
-built-in protocol (with optional server-only `events` and `messageSchema`), or a
-shared `agentContract()` as `contract` when clients fold application state.
-Any other contract throws a `TypeError` and fails to typecheck; a fully custom
-contract is core A2, served by `createServer()`. Messages are typed by the
-contract's `ai.message.created` schema through
-[`AIMessageOf`](#aimessageofevents).
-The result is an `A2Server` with `fetch`, `session(id)`, `drain()`, and
-`contract`. `typeof` it types `useAgent()` and
-`createAgentClient()` through a type-only import; `Name` is its reducer name,
-which decides whether the contract-free client accepts it.
-
-A2 runs one AI SDK `streamText()` model step per durable generation, persists
-its `UIMessageChunk`s once in durable progress batches, projects messages
-synchronously, extracts tool and approval lifecycle events, executes local
-tools, and records completion, usage, interruption, and failure. `model`
-accepts an AI SDK model string or provider model, or
-[`ModelSettings`](#modelsettings) to choose its reasoning level and speed with
-it. `model`, `instructions`, and `generation` can be values or per-generation
-async resolvers. A resolver that throws, or returns an invalid value, fails the
-turn once with its message, like a provider error, instead of retrying; the
-attempt's `ai.generation.started` omits `model` when the model never resolved.
-`retry()` runs the step again. Store failures (`A2Error`) still retry durably.
-
-`fetch` accepts reads and pushes of public AI controls:
-`ai.control.requested` commands other than the server-authored
-`request-input` and `tool-result`, with
-`send`, `edit`, and `steer` limited to user messages. With a `contract`, it also
-accepts the contract's application events, like any A2 server; `events` passed
-with `name` stay server-only, since no client can push them. Every other pushed
-event answers `400`. `fetch(request, { authorize })` adds per-operation policy on
-top, such as who may push which application event. `handlers` handles application events; naming an
-event the agent handles itself throws a `TypeError` at construction.
-
-The agent's `telemetry` instruments both Core and AI operations in the same
-active trace. See the [span catalogue](#the-span-catalogue).
-
-`generation` contains per-step settings such as `temperature`,
-`maxOutputTokens`, `topP`, provider options, and tool approval policy. A2 owns
-the one-step stop condition, local tool execution, and continuation. Responses
-have no step limit by default. Set `maxSteps` to a positive integer to limit one
-complete assistant response. Support for individual model settings depends on
-the selected model and provider. `generation` excludes `stopWhen`, tool
-execution callbacks, tool callers, sandbox execution, and the tool approval
-secret. Everything else, including `toolsContext`, passes through to the AI SDK
-untouched. A local tool reads its durable context with `handlerContext()` when
-its handler executes. Model-step timeouts remain available; tool-execution
-timeouts are not.
-
-A `generation` resolver receives `{ event, messages, state, session, signal }`
-and returns `AgentGenerationSettings` or a promise. It runs once per attempt
-before compaction and model dispatch; its settings also govern tool approvals
-and automatic-compaction compatibility. Static settings are validated at
-construction, resolved settings before use. Failures and cancellation follow
-model resolution.
-
-`messageMetadata(context)` synchronously maps each default AI SDK stream part
-to the metadata type of the agent's `UIMessage`. It receives the same context
-as `generate(context)`, plus the current `TextStreamPart` as `part`; its
-`generation` is the settings the default generator sends, with A2's Gateway
-defaults applied. Metadata returned for standard `start` and `finish` parts is
-recorded with generation progress and shallow-merged onto the projected
-assistant message. Use the `finish` part's `totalUsage` to retain final token
-usage. A custom `generate` function owns its metadata chunks and does not use
-this mapper.
-
-`generate(context)` optionally replaces the default AI SDK generation. It
-receives the resolver context, `{ event, messages, state, session, signal }`,
-plus the step's `generationId`, `modelMessages`, and the resolved `model`,
-`instructions`, `tools`, and `generation` settings. `messages` and
-`modelMessages` reflect this step's compaction. Its stream writes the assistant
-message `event.payload.responseMessageId`. It returns exactly one model step as
-a `ReadableStream<UIMessageChunk>`. A2 continues to own tool execution,
-continuation, and the durable lifecycle around that stream.
-
-Generation requests use one durable lane, so model calls for a session do not
-overlap. Queued-turn policy also waits to schedule a later user message until
-the active assistant response, including its complete tool loop, reaches a
-terminal event. The policy matters in addition to lane FIFO because a tool
-continuation may be appended after the later user message. A generation
-failure keeps later messages queued until the failed response is explicitly
-retried or interrupted.
-
-Independent authorized tool handlers run concurrently without a fixed
-concurrency limit. `toolLane` names a lane for every local tool execution, so
-they run one at a time in admission order; model steps keep their own lane. A private coordinator reducer tracks generation closure,
-cancellation, calls, approvals, and terminal results for the active response.
-Completed responses do not accumulate in its state. Its
-`ctx.session.state(coordinator, { through: 'latest' })` reads the durable
-snapshot plus log tail because these joins intentionally observe concurrent
-tool results. Process memory is not authoritative. Concurrent join checks return
-the same deterministic continuation event, so they use `ctx.session.append()`
-and storage deduplicates the race.
-
-Tool results and generation completion have no fixed relative order. The
-continuation predicate needs both the closed model step and every required
-terminal result.
-
-Single-owner terminal events use returned-event causality. They commit
-atomically with parent completion and receive the parent's durable cause.
-Many-owner joins and preliminary streaming outputs use immediate idempotent
-appends. Provider calls and external tool side effects are at least once and
-require their own idempotency. Approved provider-executed calls may satisfy the
-join from the approval response. Provider tools with declared deferred-result
-support wait for their provider result instead of a local executor. An
-authenticated provider callback appends the terminal `ai.tool.result` through
-the trusted server session API; `fetch` rejects it from browsers.
-
-`compaction` defaults to automatic for supported Gateway requests. It accepts
-`false` to disable compaction and discovery, `{ thresholdTokens?, instructions? }`
-to override automatic behavior, or the existing custom
-`{ shouldCompact(context), compact(context) }` policy. It also accepts a
-resolver `(context: AgentResolverContext) => CompactionOptions | Promise<CompactionOptions>`.
-The resolver runs once per generation and returns a valid policy or `false`.
-It can await application reducers through `context.session.state(reducer)`, whose
-default boundary is the captured prompt frontier. Model, instruction, compaction,
-metadata, and custom-generation contexts expose state access and omit raw history.
-Callbacks receive prompt messages and the triggering `event`, without an
-`execution` argument. Model, instruction, and generation-setting resolvers receive
-`{ event, messages, state, session, signal }`, where `state` is the contract's
-application state (from `agentContract({ reducer })`, `{}` without one) as of the
-captured snapshot; it rides in the model-context checkpoint, so it costs no
-read. Compaction, metadata, and custom-generation callbacks receive the same
-context plus `modelMessages`, including committed summaries. The contract's reducer continues to expose the full
-transcript. `context.session.state()` returns its `AIState` directly, paired
-with its log index for hydration.
-Static options are validated at construction; resolved options are validated
-before that generation starts. Each session uses its own resolved value. `thresholdTokens` is an
-optional positive safe integer. `instructions` adds to A2's internal summary
-prompt without replacing the agent's instructions.
-
-Without an explicit threshold, the first generation batches a metadata request
-into its existing start write. An independent handler reads the public Gateway
-catalog and records that session/model's limits. It does not delay model dispatch.
-The default threshold is 75% of the context window, lowered for a larger configured
-output allowance. A pending or unavailable lookup leaves the threshold unknown;
-the first request proceeds, and provider context-limit errors fail normally.
-`state.modelMetadata` retains each model's pending, resolved, or unavailable state.
-Pending also covers exhausted handler retries; no new request is added per turn.
-The catalog has a shared one-hour process cache and a five-second fetch timeout.
-
-Direct/custom providers, fallback model lists, and custom generators need explicit
-compaction configuration. Provider-executed tools, structured output, and forced
-tool choices skip implicit compaction and reject explicit automatic policies.
-Custom policies remain available for these configurations.
-
-The raw input estimate uses serialized bytes of messages, tools, and instructions,
-excluding provider options on messages and content parts. These options still reach
-the model unchanged. It is not a provider tokenizer. A preceding same-model
-completion anchors later growth to reported input usage, correcting both overestimates
-and underestimates. A smaller prompt, retry, compaction, or model change stops
-that calibration.
-
-Completed generations record the raw `inputTokenEstimate` beside usage.
-Automatic `ai.compaction.requested` events also record the pre-compaction
-`inputTokenEstimate`, the calibrated `inputTokens` used for the decision, and
-`thresholdTokens`. Custom-policy requests omit these diagnostics. They add no
-model calls or database round trips.
-
-The built-in summary adds one model request and preserves the request prefix for
-caching. It does not invoke application generation callbacks, transforms, or tool
-hooks. Both custom policy callbacks and `generate` receive `modelMessages`, the
-model-ready prompt including summaries, alongside typed UI `messages`.
-
-Built-in summaries remain separate from application-typed messages. The
-transcript marks each compaction with a
-[`data-a2-compaction` part](#iscompactionpartpart), and
-`state.compaction?.status === 'running'` reports current activity. The
-conversation in `state.messages` remains intact. Model execution
-uses a separate context checkpoint; existing compactions do not require a
-transcript read. Successful compaction is permanent, including across failure,
-interruption, retry, and recovery. Retry reruns the failed step from the latest
-committed context. Compaction defers while tool exchanges or A2-owned tool work
-remain unsettled, checked with one fresh coordinator state read on each candidate.
-Unresolved dead-lettered tool work also defers compaction until repair and
-settlement or session closure. `progress` controls durable batching. By
-default each batch is written as soon as the previous one finishes, so a slow
-model's chunks are written one at a time and chunks that arrive during a write
-share the next batch, up to `maxChunks` (128). `maxDelayMs` (default 0) lets a
-batch keep collecting chunks for up to that long after the previous write;
-boundary chunks and `maxChunks` write sooner. Raising it trades token latency
-for fewer progress events.
-
-This entry point is server-only and resolves to a throwing browser stub.
-
-### `ModelSettings`
-
-```ts
-type ModelSettings = {
-  model: LanguageModel
-  reasoning?: ReasoningLevel
-  speed?: 'fast' | 'standard'
-}
-```
-
-A model with its reasoning level and speed, which a `model` option or resolver
-returns to choose all three together. `reasoning` becomes the AI SDK
-`reasoning` call option. `speed: 'fast'` sets `providerOptions.gateway.speed`
-to prefer AI Gateway's faster tier when the model offers one, and `'standard'`
-removes a configured speed. Both override the same settings in `generation`.
-[`reasoningLevels`](#reasoninglevels) lists the levels.
-
-### `runWithHandlerContext(ctx, fn)`
-
-The testing seam for context-reading tools: runs `fn` with `ctx`
-installed as the ambient handler context, so a tool's `execute` can be
-called directly in tests. Inside `fn`, `handlerContext()` returns `ctx`
-with or without a contract argument.
-
-See [Durable AI agents](/guides/ai-agents) for the protocol and complete
-examples.
-
-## `experimental-a2/ai/client`
-
-### `createAgentClient(options)`
-
-```ts
-createAgentClient<typeof agent>(options: {
-  api: ClientApi
-  gcTime?: number
-  participant?: string
-  reconnect?, fetch?, webSocket?, // as createClient
-}): AgentClient // an A2Client over the built-in AI protocol
-```
-
-A contract-free client for an `agent()` route. It accepts only agents whose
-reducer carries the built-in name (`typeof AI_STATE_REDUCER`): `agent({ name })`
-or `agent({ contract })` with an `agentContract()` that has no `reducer`. The AI protocol and its
-`AIState` reducer are library code, and the type argument, taken from a
-type-only import of the server module, types messages. Use it for pushes
-outside React, such as a first message sent before navigating, and pass it to
-`useAgent({ client })` so the hook shares its sessions. It pushes the built-in
-AI controls only. Agents built from an extended `agentContract()` use
-`createClient({ contract })` instead, so the client folds the same state.
-
-## `experimental-a2/ai/react`
-
-### `useAgent(options)`
-
-```ts
-useAgent<typeof agent>(options: {
-  id: string
-  initial?: InitialSnapshot<AIState>
-  participant?: string
-} & ({ api: string } | { client: AgentClient })): UseAgentResult
-
-useAgent(options: {
-  id: string
-  initial?: InitialSnapshot<State>
-  participant?: string
-} & (
-  | { api: string; contract: Contract } // a shared agentContract(), imported for real
-  | { client: A2Client } // createClient({ contract, api })
-)): UseAgentResult
-```
-
-One agent session in React: its live optimistic `AIState` and actions that
-fill in protocol identities. With `api`, the hook keeps one shared client per
-route for the page's lifetime, reading `globalThis.fetch` on each request; with
-`client`, it uses yours, for a custom `fetch`, headers, or `gcTime`. Both forms
-accept only agents whose reducer carries the built-in name, like
-`createAgentClient()`. With `contract`, it folds the contract's application
-state too, keeping one client per contract and route; `state` is
-`AIState & X` and `push` accepts the contract's events. Pass that contract's
-`createClient({ contract, api })` as `client` instead to share it with pushes
-outside React, such as a first message sent before navigating. A custom
-contract, one not built by `agentContract()`, uses core A2's `useSession()` and
-`inputs` directly. Keep one options form per call site;
-the form must not change between renders.
-
-The result is the session result (`state`, `index`, `connection`, `push`,
-`events`, `hydrated`, `reconnect`, `loadHistory`, `history`) plus:
-
-| Member | Does |
-| --- | --- |
-| `messages` | `state.messages` |
-| `status` | `state.status` |
-| `indicator` | `'starting'`, `'thinking'`, `'compacting'`, or `null` |
-| `sendMessage(message, { generate? })` | queues a string (one text part) or a `UIMessage` |
-| `steer(message)` | steers the active turn after its current step, or sends when idle |
-| `stop()` | stops the active turn at the rendered frontier |
-| `approve(approval)`, `deny(approval, { reason? })` | answers a pending approval |
-| `respond(input, value)` | answers a pending application input |
-| `retry()` | retries the failed response with a fresh `retryId` |
-| `pause({ when })`, `resume()` | pauses and resumes |
-| `queue.edit(message)`, `queue.move({ inputId, beforeId })`, `queue.remove(inputId)`, `queue.sendNow(inputId)` | edits the inbox |
-
-Every action returns a `PushResult`, like `push()`: it resolves to the
-persisted command events and rejects when the push fails, and `.confirmed`
-resolves when the stream delivers them back. Each event's `id` is the
-`commandId` of its `ai.control.decided` receipt. Actions read identities from
-the state of the render that created them, so `stop()` and `queue.sendNow()`
-carry the frontier the user saw. An action with nothing to address, such as
-`stop()` without an active turn or `retry()` without a failed one, resolves to
-an empty array. Actions are rebuilt on every render; their identity is not
-stable.
-
-`indicator` is `starting` for an optimistic turn awaiting acceptance,
-`compacting` while a summary runs, `thinking` while the current model step has
-no visible part (reasoning and step boundaries do not count), and `null`
-otherwise.
-
-## `experimental-a2/client`
-
-```ts
-createClient(options: {
-  contract: Contract // requires a public reducer
-  api: ClientApi
-  gcTime?: number // idle session lifetime; 5 minutes by default
-  participant?: string // default presence identity for every session
-  reconnect?: (failure: {
-    sessionId: string
-    error: A2ClientError | null
-    attempt: number
-  }) => number | false
-}): A2Client
-
-type ClientApi =
-  | SessionUrl // one route: GET SSE stream + POST push
-  | { type: 'http'; push: SessionUrl; stream: SessionUrl }
-  | { type: 'ws'; url: SessionUrl; multiplex?: false }
-  | { type: 'ws'; url: string; multiplex: true }
-
-type SessionUrl = string | ((sessionId: string) => string)
-```
-
-`reconnect` runs after a failed connection or a stream ending, including a
-clean end with `error: null`. Return the delay in milliseconds before the next
-attempt, or `false` to pause automatic reconnection. Delays must be finite,
-non-negative, and at most 2,147,483,647 ms. The callback is synchronous; a
-throw or invalid result pauses the connection with an `A2ClientError`.
-
-`attempt` starts at 1 for the first retry. It counts consecutive attempts
-per session and resets when the stream becomes live or `session.reconnect()`
-explicitly restarts it. It is separate from the lifetime `reconnects` count.
-Without a callback, A2 retries indefinitely with delays starting at 500 ms,
-doubling up to five seconds. The callback does not run for an explicit
-restart, an idle-stream refresh, or a caller closing the stream.
-
-While paused, `connection.status` is `paused` and its last error remains
-available. State, hydration, optimistic writes, and connection leases remain
-intact. Another consumer taking a lease does not resume a paused stream.
-Call `session.reconnect()` to resume immediately with a fresh attempt count.
-Releasing the last lease still closes the stream. A later first lease starts
-a new connection. Push retries are independent of this policy; a push does
-not resume a paused stream. An acknowledged push's `confirmed` promise waits
-until the stream delivers through the acknowledged index. A bootstrap
-snapshot, or a stream that starts after a supplied initial index, delivers
-through that index. Hydration does not otherwise confirm an unobserved
-acknowledgement. A push never waits for bootstrap. An HTTP push does not
-wait for a pending initial Promise either; a WebSocket push rides its
-connection, which opens once that Promise settles.
-Resumption preserves the stream's own position, even when
-hydration has advanced state while paused.
-
-A `SessionUrl` function runs for each HTTP request or WebSocket connection.
-Use it for session-specific paths. A2 still adds its `sessionId` and read-bound
-query parameters. The function does not authorize that ID. Bind any path scope
-or URL token to `operation.sessionId` in `authorize`; keep URL tokens short-lived
-because URLs can appear in infrastructure logs. A multiplexed WebSocket URL is
-a string because its connection carries more than one session.
-
-The framework-agnostic session client `experimental-a2/react` is built on: the SSE
-subscription with frontier resume and reconnection, the optimistic push
-queue with ack/rollback, and the local fold. `client.session(id, {
-initial?, initialEvents?, participant? })` returns a
-handle with `getSnapshot()`/`subscribe()` (the `useSyncExternalStore`
-contract), `push()`, `loadHistory()`, `connect()`, `reconnect()`, and `close()`.
-`connect()` takes a lease on the live stream and returns its release:
-leases refcount per handle (the first connects, releasing the last
-closes, releasing twice is a no-op), so independent consumers of one
-identity-mapped handle never fight over the stream. `close()` is the
-hard stop: it drops every outstanding lease and closes now; a later
-`connect()` starts fresh.
-Snapshots carry `state`, `events`, `index`, `history`, and `connection`
-(the same fields `useSession` exposes), and `push` returns the same
-ack-then-`confirmed` result. On contracts that declare `presence` the handle also carries
-`setPresence()` and snapshots carry the `presence` map, exactly like
-the hook; `participant` is the identity `setPresence` sends under:
-stated once on `createClient` as the default for every handle, or per
-session as the override. Use
-it directly from any other framework, or none.
-
-Within one `A2Client`, repeated `session(id)` calls return the same live
-handle. A later call with a further server-rendered frontier advances the
-handle and does not drop pending optimistic events; a stale render cannot move
-it backward. Optional `initialEvents` seed earlier raw events for history UIs
-and merge into that feed. They do not affect the folded state or stream
-frontier. Idle handles are evicted after `gcTime`. This memory layer is
-separate from `experimental-a2/cache-indexeddb`: memory preserves identity
-across route transitions, while IndexedDB preserves the replica across reloads.
-
-`initial` accepts the same `InitialSnapshot<S>` as React. A pending Promise
-delays cold connection startup, including a connection acquired by `push`.
-An HTTP push is sent without waiting; a WebSocket push waits for that
-connection. It does not start another request. Replacing the source or calling `close()`
-invalidates its pending result and any deferred adoption behind a write.
-Releasing the last connection lease does not cancel the caller's Promise;
-it can still seed cached data without reopening transport. Idle eviction
-detaches A2's listener. Repeating the same Promise within that cached runtime
-does not restart cancelled work.
-
-## `experimental-a2/cache-indexeddb`
-
-```ts
-indexedDb(): A2ClientCache
-```
-
-A browser-side cache for `SessionProvider`: the session's events
-(immutable; writes are idempotent by index), a folded snapshot
-(invalidated by a reducer rename), and the pending-push queue.
-`cache.clear(sessionId?)` is the logout story. Create instances in client
-code; they're live objects, not serializable props. See
-[Local-first](/guides/local-first).
-
-## `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.
-
-### The span catalogue
-
-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 |
-| 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 measure elapsed time, including 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. Summing spans or subtracting summed children
-does not yield exclusive Core/AI overhead. Model and application I/O is included;
-inspect its child spans for detail.
-
-Attributes arrive in two waves: **at start** (passed to `span()`) and
-**mid-span** (via `handle.setAttribute`; outcomes and counts aren't
-known until 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.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 remain; `stalled` means a caught failure needs a later retry.
-A dead-lettered event blocks only later events in its lane. Other lanes remain
-eligible.
-
-A failing handler marks its `a2.event` span with the exception and
-error status; `a2.event.outcome = dead_lettered` is the attribute to
-alert on. `superseded` means a stale completion or failure did not change the
-log.
-`A2Telemetry` is a one-method interface; anything with
-`span(name, attributes, fn)` works;
-`otel()` is simply the adapter A2 ships. This catalogue is a contract:
-renames and additions are breaking for dashboards, and are called out in the
-package's `CHANGELOG.md`.
-
-## `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` is passed to the Queue SDK unchanged and applies to every task,
-including recovery watchdogs. Omit it to use `VERCEL_DEPLOYMENT_ID`, pass a
-deployment ID to target that deployment, or pass `null` for deploymentless
-delivery. Publishing and consuming clients must use the same deployment scope.
-The same 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 deployment is
-promoted. Deploymentless delivery lets Vercel choose an eligible consumer; it
-does not select the latest production deployment. Every eligible consumer must
-use `deploymentId: null` and remain compatible with pending tasks and session
-work.
-
-The adapter retains every task for seven days and accepts delays through six
-days, leaving the final day for delivery and retries. `transport` and `clock`
-are advanced injection seams for tests and custom delivery. An injected
-transport receives the topic, an exact `SchedulerTask`, and send options.
-`deploymentId` configures the built-in Queue SDK client only; an injected
-transport owns its provider configuration.
-
-## `experimental-a2/scheduler-qstash`
-
-`qstash(options?)` returns an `A2Scheduler` backed by QStash HTTP delivery.
-Vercel Queues remains the recommended default on Vercel. Use QStash when you
-want 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 |
-
-`headers` adds static headers to every callback delivery, including recovery
-successors. A2 validates and snapshots the record when `qstash()` runs, then
-asks QStash to redact every configured value from its dashboard and API. QStash
-still receives, stores, and delivers the original values. Header names are
-case-insensitive. Provider-owned `Upstash-*` headers, `Content-Type*`, HTTP
-framing headers, and A2's managed Vercel identity headers are reserved.
-
-`client` accepts the structural `publishJSON(...)` part of a configured
-`@upstash/qstash` `Client`. A2 still creates the `Receiver` lazily from the
-signing-key options. `client` cannot be combined with `token` or `transport`.
-Use it to configure the QStash API endpoint, publish-request retry policy, or
-telemetry. Use A2's `headers` option for callback credentials. Client-global
-callback headers and redaction are outside A2's merge contract. The injected
-client receives raw callback credentials, including an automatic preview
-identity, and must honor the per-publish redaction request.
-
-`transport` and `clock` are advanced injection seams for tests and custom
-delivery. A `QStashTransport` implements `publish(request)` and
-`verify(request)`. Publish requests contain the callback `url`, a complete
-`SchedulerTask` body, optional callback `headers`, optional `redact.header`
-names, optional Unix-seconds `notBefore`, and a deterministic
-`deduplicationId`. Store-outage successors add provider-private generation
-metadata to that body. Custom transports must preserve the body, deliver every
-header, and apply every redaction request. An explicit `retries` value is
-forwarded; omission lets QStash use its provider default. Verify requests
-contain the signature, raw body, exact callback URL, and optional Upstash
-region.
-
-An explicit `url` always wins. Otherwise, Vercel production resolves to
-`https://${VERCEL_PROJECT_PRODUCTION_URL}/api/a2/scheduler` and preview resolves
-to `https://${VERCEL_BRANCH_URL}/api/a2/scheduler`. Outside those deployments,
-a runtime that exposes `process.env` and is not in `NODE_ENV=production`
-resolves to `http://localhost:${PORT ?? 3000}/api/a2/scheduler` and passes
-`devMode: true` to the SDK client and receiver. `QSTASH_DEV` is not required.
-`PORT` must be an integer from 1 through 65535. `QSTASH_DEV_PORT` configures the
-local QStash server, not the application callback. Automatic startup requires
-`@upstash/qstash` 2.11.0 or newer in a Node.js runtime. The lazy transport
-starts it on the first publish or verification. The direct SDK override means
-`QSTASH_DEV=false` does not disable an inferred local route.
-
-A non-Vercel production runtime or a process-less runtime requires an explicit
-absolute URL. Pass one for a custom host or path, an application port not
-available through `PORT`, or Docker networking. An Edge runtime that exposes
-`process.env` can infer the local URL, but it must start the QStash development
-server separately. Outside production, an explicit URL does not override the
-SDK's development mode, so `QSTASH_DEV` and manually supplied `QSTASH_URL` plus
-credentials retain their SDK-defined behavior. A2 passes `devMode: false` in
-production. The inferred Vercel hosts are moving aliases, so pending tasks can
-reach later deployments on the same production or branch URL.
-
-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)
-```
-
-The route must be reachable by the selected QStash server after any platform
-edge authentication. The development server calls localhost directly. The
-adapter reads its raw body once and verifies `Upstash-Signature`, the exact URL,
-and `Upstash-Region` before it parses the delivery or touches a server. Missing
-or invalid signatures return 401, so ordinary unsigned traffic cannot execute
-scheduler work. A signed malformed envelope returns 489 with
-`Upstash-NonRetryable-Error: true`. The same non-retryable response applies
-when the declared or streamed body exceeds `maxBodyBytes`. Before an initial
-publish, the adapter checks the normalized task with enough reserved room for
-its largest possible private store-outage lineage. Append and clear tasks
-reserve a maximum safe-integer generation. Drain tasks also reserve their actual root
-`dueAt`. Store-outage successors check their actual body. The adapter therefore
-cannot initially accept a task that would exceed the same limit solely when
-lineage is added. Raise the option to match a larger paid-plan payload limit
-when needed. Keep one value across every deployment that can receive this
-callback URL. A lower value deployed while older tasks remain can return a
-non-retryable 489 for a task accepted by the previous value.
-
-For an inferred Vercel preview callback, the adapter reads the current
-invocation's `x-vercel-oidc-token` for each publish. When it is a parseable JWT
-whose expiration remains at least 60 seconds after the task's first due time,
-the adapter supplies it as `x-vercel-trusted-oidc-idp-token` and requests QStash
-header redaction. A matching Vercel Trusted Sources rule can then admit the
-first delivery. QStash receives the credential even though its dashboard and
-API redact it.
-
-This is opportunistic, not durable. Missing, malformed, and near-expiry tokens
-fall back to an ordinary publish, preserving public-preview behavior. An
-explicit `url` opts out. Inferred production and local callbacks never forward
-the token. QStash stores the static header and reuses it on retries, so delayed
-tasks and retries can outlive it. Use an explicit automation bypass or public
-ingress when every protected delivery must remain authorized. Applications can
-supply a dedicated bypass through `headers`; A2 requests redaction for its
-value, but pending messages retain the captured credential after rotation. A
-delivery-time Vercel relay remains a separate application architecture that
-requires a Trusted Sources rule, strict target allowlisting, and a versioned
-routing envelope. QStash signature verification remains mandatory after the
-edge-access check.
-
-Settled deliveries return 200. Busy deliveries await a durable successor
-watchdog before returning 200. Stalled deliveries publish a fresh successor
-before returning 200, which resets the per-message retry budget. A retryable
-store outage also hands drain, append, and clear tasks to a fresh successor
-before acknowledging. Store-outage successors wait 30 seconds, then multiply the delay
-by four for each signed generation, capped at one day. Their generation keeps
-increasing after the cap so each handoff has a new deduplication id. Drain
-lineage includes the first failing task's `dueAt`, contract, and session.
-Append and clear lineage includes the task id, contract, and session. Duplicate delivery of one
-generation therefore publishes the same successor key without merging a later
-drain episode. Append tasks otherwise return 200 after their ordinary fixed-id
-append succeeds and any recovery watchdog for pending handler work is durable.
-Clear tasks return 200 after their conditional clear and its deletion finish.
-Unknown contracts, missing scheduler configuration, schema failures, and
-successor publish failures keep the current delivery retryable. Delivery is at
-least once, so handler side effects still need idempotency keys.
-
-The adapter leaves `retries` unset by default so QStash applies its provider
-default. An explicit non-negative value is passed through. Every delivery
-attempt is billable. A prolonged outage in which QStash cannot reach the
-callback still requires DLQ monitoring and redrive because no running callback
-can publish a successor. QStash's
-documented 10-minute deduplication window can reduce duplicate watchdogs but is
-not part of A2's correctness model. Stable scheduled-event ids also make timer
-redelivery safe after that window. One-shot delays are currently capped at 7
-days on free plans and 1 year on usage-based plans, with no fixed maximum on
-fixed plans. Leave at least one second of margin at a plan maximum because
-`notBefore` uses whole Unix seconds. The adapter carries both recovery watchdogs and
-`session.schedule` tasks.
-
-The built-in QStash and Vercel adapters preserve the original provider error
-from a rejected send. A recognized definite 4xx status or error is terminal
-except for 408, 409, 425, and 429. Those statuses, 5xx responses, network
-failures, and errors with no recognized status remain retryable. The Vercel
-adapter also recognizes the SDK's name-only `BadRequestError`,
-`UnauthorizedError`, and `ForbiddenError` as terminal. Its 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.
-
-## Entry points
-
-| Entry point          | Ships                              | Peer dependency |
-| -------------------- | ---------------------------------- | --------------- |
-| `experimental-a2`                 | `contract`, `A2Error`: isomorphic core    | none     |
-| `experimental-a2/server`          | `createServer`: implement a contract      | none     |
-| `experimental-a2/client`          | `createClient`: framework-agnostic session client | none |
-| `experimental-a2/react`           | `createReact`                      | `react`         |
-| `experimental-a2/ai`              | `agentContract`, `handlerContext`, `inputs`, and the AI reducer: isomorphic | `ai` |
-| `experimental-a2/ai/server`       | `agent`: the AI SDK runner as an A2 server | `ai`           |
-| `experimental-a2/ai/client`       | `createAgentClient`: contract-free agent client | `ai`   |
-| `experimental-a2/ai/react`        | `useAgent`                         | `ai`, `react`   |
-| `experimental-a2/store-postgres`    | `postgres`: Postgres store backend   | `pg` (or inject a client) |
-| `experimental-a2/store-redis`       | `redis`: Redis Streams store backend, push-native streaming | `ioredis` (or inject a client) |
-| `experimental-a2/store-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/cache-indexeddb` | `indexedDb` browser cache          | none            |
-| `experimental-a2/otel`            | `otel` telemetry adapter           | `@opentelemetry/api` |
-
-Core `experimental-a2` imports none of the backends, enforced by a browser-bundle
-test in CI, not just convention. Importing `experimental-a2/store-postgres` is what
-pulls in Postgres, never `experimental-a2` itself, and never your client bundle.