experimental-a2 0.2.0 → 0.4.0

package/docs/reference/01-api.mdx

@@ -11,6 +11,7 @@ description: "The whole surface, small enough to read in one sitting: contract,
 a2.contract(options: {
   name: string
   events: Record<string, StandardSchemaV1>
+  presence?: Record<string, StandardSchemaV1>
 }): Contract
 ```
 
@@ -20,6 +21,11 @@ messages. 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
@@ -63,10 +69,11 @@ Everything A2 throws. One class, discriminated by `code`. See
 ```ts
 createServer(options: {
   contract: Contract // the vocabulary this server implements
-  log?: A2Log        // default: sqlite in dev, memory in tests, required in prod
-  recovery?: A2Recovery
+  store?: A2Store    // default: sqlite in dev, memory in tests, required in prod
+  scheduler?: A2Scheduler
   telemetry?: A2Telemetry // optional instrumentation; see experimental-a2/otel
   validatePush?: (context: PushValidationContext) => void | PromiseLike<void>
+  presence?: { ttlMs?: number } // presence expiry policy; default 60s
   handlers?: {
     [type]:
       | Handler
@@ -99,28 +106,42 @@ 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 log operation. Returned
+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 recovery arm. A server with no
+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 log backend, and its exports map resolves to a loud error
+can reach a store backend, and its exports map resolves to a loud error
 under the browser condition.
 
-`validatePush({ sessionId, events })` runs only when `events` came from
-`parsePushBody()`. It runs before contract schema validation and before the log
-append, so throwing rejects the complete push without writing anything. Direct
-trusted server appends and handler appends bypass it. `parsePushBody()` creates
+`validatePush(context)` runs only for input that came from `parsePushBody()`,
+once per plane. The events plane invokes it with `{ sessionId, events }` before
+contract schema validation and before the store append, so throwing rejects the
+complete push without writing anything. The presence plane invokes it with
+`{ sessionId, events: [], presence }`, the whole pushed patch with its
+participant, before field validation and the broadcast, so authorizing the
+participant id (and applying any size or cardinality policy) happens at the
+same seam. The patch arrives frozen: authorize, don't rewrite (a mutation
+attempt throws and fails the push). Direct trusted server appends, handler appends, and server-side
+`setPresence` bypass it. `parsePushBody()` creates
 the runtime provenance brand after reading the envelope; a caller-supplied
 field with the same name is ignored, and the brand is not stored in the log.
 
+`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:
@@ -144,8 +165,8 @@ The context every handler receives:
 | ------------- | --------------------------------------------------------- |
 | `ctx.event`   | `Event`: the triggering event                             |
 | `ctx.attempt` | durable 1-based dispatch claim ordinal                    |
-| `ctx.session` | this session's `id`, `append`, `history`, `state`, `stream` |
-| `ctx.signal`  | `AbortSignal`: active only with `abortOn`                 |
+| `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.
@@ -172,6 +193,11 @@ 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 state read and following append are not atomic. Concurrent appends and
 retries may move the frontier between them. A generic join should use a
 monotone readiness predicate and a stable explicit output event `id`, so every
@@ -193,14 +219,18 @@ const session = server.session('order-42')
 
 session.id
 session.append(...events)
-session.history()
+session.schedule('expire-order', { delay: '5d' }, {
+  type: 'expired',
+  payload: {},
+})
+session.history({ gte, lte })
 session.state(reducer)
-session.stream({ startAt })
+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.
+before the events. Both root and handler sessions expose `schedule`.
 
 ### `server.drain(sessionId)`
 
@@ -211,15 +241,15 @@ 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 recovery callbacks use.
+You'll rarely call this yourself; it is the primitive scheduler callbacks use.
 The public result stays this simple boolean.
 
-### `A2Log`
+### `A2Store`
 
 Custom adapters implement these atomic drain methods:
 
 ```ts
-// Custom server log adapter:
+// Custom server store adapter:
 type EventCause = {
   index: number
   attempt: number
@@ -255,12 +285,12 @@ type StoredEvent = Event & {
   failedAt: Date | null
 }
 
-type LogAppendResult = {
+type StoreAppendResult = {
   events: StoredEvent[]
   hasPending: boolean
 }
 
-type LogClaimAvailableResult =
+type StoreClaimAvailableResult =
   | { outcome: 'claimed'; events: StoredEvent[] }
   | { outcome: 'busy'; retryAt: Date }
   | { outcome: 'settled' }
@@ -269,11 +299,11 @@ type CompleteAttemptResult =
   | { outcome: 'completed'; events: StoredEvent[] }
   | { outcome: 'superseded' }
 
-interface A2Log {
+interface A2Store {
   append(
     sessionId: string,
     events: AppendEvent[],
-  ): Promise<LogAppendResult>
+  ): Promise<StoreAppendResult>
 
   claimAvailable(options: {
     sessionId: string
@@ -281,15 +311,15 @@ interface A2Log {
     ttlMs: number
     expiresAtMs?: number
     excludeIndexes?: readonly number[]
-  }): Promise<LogClaimAvailableResult>
+  }): Promise<StoreClaimAvailableResult>
 
   renewClaims(options: {
     sessionId: string
     holder: string
-    indexes: number[]
+    claims: readonly { index: number; attempt: number }[]
     ttlMs: number
     expiresAtMs?: number
-  }): Promise<number[]>
+  }): Promise<{ renewed: number[]; superseded: number[] }>
 
   completeAttempt(options: {
     sessionId: string
@@ -313,9 +343,9 @@ interface A2Log {
 
 | 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. |
+| `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. Expired, completed, failed, and superseded claims are omitted and cannot be revived. |
+| `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`. |
 
@@ -328,11 +358,62 @@ 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 log operations, not exact
+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 and append tasks |
+
+`handler` is the low-level adapter-author seam. Application routes call
+`schedulerHandler(...servers)` from `experimental-a2/http`, which derives the
+adapter from the servers and verifies their wiring before it delegates here.
+
+`SchedulerTask` is `SchedulerDrainTask | SchedulerAppendTask`. 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` |
+| `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`.
+
+Custom adapters deliver an authenticated, normalized append task through the
+server helper:
+
+```ts custom-scheduler.ts
+import {
+  deliverSchedulerAppend,
+  type DrainableServer,
+  type SchedulerAppendTask,
+} from 'experimental-a2/server'
+
+export async function deliver(
+  server: DrainableServer,
+  task: SchedulerAppendTask,
+) {
+  await deliverSchedulerAppend(server, task)
+}
+```
+
+Import `deliverSchedulerAppend` from `experimental-a2/server`. It verifies the
+task and server contract match, 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. Authenticate the transport and validate the task envelope before
+calling it.
+
 ## Session
 
 ### `session.append(...events)`
@@ -354,7 +435,7 @@ identical batch returns the original rows. (Events parsed by
 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
-log reports that session-wide pending state as part of the atomic append, so
+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)`
@@ -366,13 +447,13 @@ session.append.dispatch(
 ```
 
 Commits the same atomic batch, but sends pending work directly to configured
-recovery instead of starting an inline drain. The call awaits acceptance of an
-immediate recovery message. It throws before writing if the server has no
-recovery adapter.
+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 recovery message. Dispatch chooses how this append wakes
+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.
 
@@ -381,13 +462,57 @@ active may still claim newly eligible work first.
 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.
+
+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.history()`
 
 ```ts
-session.history(): Promise<Event[]>
+session.history(options?: { gte?: number; lte?: number }): Promise<Event[]>
 ```
 
-Every event in the session, oldest first. Always the raw log.
+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.
 
 ### `session.state(reducer)`
 
@@ -395,21 +520,89 @@ Every event in the session, oldest first. Always the raw log.
 session.state(reducer: Reducer<S>): Promise<{ state: S; index: number }>
 ```
 
-The log folded through a reducer. `index` is the position the state
-reflects. Hand it to the client to resume a stream from exactly there. The
-snapshot and event tail are one log operation; snapshot write-back runs in
-platform `waitUntil`. This read never dispatches handlers.
+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.
 
 ### `session.stream(options?)`
 
 ```ts
-session.stream(options?: { startAt?: number }): AsyncIterable<Event>
+session.stream(options?: { startAfter?: number }): AsyncIterable<Event>
+session.stream(options: {
+  startAfter?: number
+  presence: true
+}): AsyncIterable<Event | PresencePatch | PresenceSnapshot>
 ```
 
-A live feed of the session's events, starting after `startAt`.
+A live feed of the session's events. `startAfter` is a non-negative safe integer;
+`startAfter: 20` begins with event 21.
 Server-side only; expose it over SSE with `sseResponse`. Subscribing never
 dispatches handlers.
 
+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. `sseResponse` 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` object `parsePushBody` returns,
+so a push route forwards it whole: `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
@@ -456,23 +649,54 @@ transition and the destination should adopt the same optimistic session.
 | `sessionId`     | which session to subscribe to                          |
 | `initialState`  | server-rendered state                                  |
 | `initialIndex`  | the fold's frontier, where the stream resumes          |
-| `initialEvents` | optional server-rendered history through that frontier |
+| `initialEvents` | optional earlier raw events for a history UI           |
+| `participant`   | this client's presence identity; required to call `setPresence` |
 
 Opens the stream on mount, closes it on unmount, reconnects with
-backoff from the current frontier.
+backoff from the current frontier. `participant` binds at the session's
+first resolution; a changed provider prop is ignored for the session's
+runtime lifetime.
+
+`initialState` and `initialIndex` are the complete server-to-client handoff.
+The stream resumes after `initialIndex`, 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.
 
 ### `useSession()`
 
 ```ts
-const { state, push, events, index, connection } = useSession()
+const { state, push, events, index, connection, presence, setPresence } =
+  useSession()
 ```
 
-`state` folds live events through the shared reducer, `events` is the
-raw observed feed, and `index` is the stream frontier, the
-`lastSeenIndex` for [cancellation](/guides/cancellation).
+`state` starts from the initial snapshot and folds live events through the
+shared reducer. `events` is the raw observed feed. Unless `initialEvents`
+explicitly seeds earlier entries, it begins after `initialIndex`. `index` is
+the stream frontier, the `lastSeenIndex` for
+[cancellation](/guides/cancellation).
+
+`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 the
+provider's `participant`. If the map holds only your own echo with
+participants active, the GET route forgot `presence: true`. See
+[Presence](/guides/presence).
 
 `push` appends optimistically: validated locally, rolled back on
-rejection, retried only for `LOG_UNAVAILABLE`. Awaiting it gives the
+rejection, retried only for `STORE_UNAVAILABLE`. 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:
@@ -485,6 +709,12 @@ 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 `A2Error`;
 `confirmed` is materialized only when accessed, so ignoring it costs
 nothing. It also reads as intent: `await push(...).confirmed` is
@@ -527,14 +757,47 @@ definition exposes only `contract` and `reducer`.
 
 Built-in event names cannot be replaced by `options.events`.
 
+### `handlerContext(agent)`
+
+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(agent)` (or pass a contract) anywhere below `execute`,
+including awaited helpers and async iteration. The argument types the
+result and is verified against the executing server's contract: a
+mismatched agent, or a call outside any tool execution, throws a
+`TypeError`.
+
+The returned `AgentToolContext<D>` is a union of the current A2
+handler's `event`, `attempt`, `session`, and `signal`. Automatic
+execution has an `ai.tool.called` event; execution after approval has an
+`ai.approval.responded` event. Narrow `ctx.event.type` when
+event-specific payload fields matter. Both variants have a session typed
+from the supplied agent's complete event vocabulary. The agent does not
+hold a scheduler. Calls such as `ctx.session.schedule()` use the
+scheduler of the server 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()`:
 
 | Input | Events |
 | --- | --- |
-| `inputs.message(message)` | `ai.message.created`; the server schedules a user turn |
-| `inputs.seed(message)` | `ai.message.created` for a trusted server append |
+| `inputs.message(message, { generate? })` | `ai.message.created`; pass `generate: false` to record context without scheduling |
+| `inputs.seed(message)` | `ai.message.created` with `generate: false`; non-user roles require a trusted append |
 | `inputs.approval(response)` | `ai.approval.responded` only |
 | `inputs.input(response)` | `ai.input.responded` only |
 | `inputs.requestInput(request)` | `ai.input.requested` for a trusted server append |
@@ -547,8 +810,20 @@ when an application uses them. Input event ids are stable for the interaction
 they describe, so a lost append acknowledgment can be resent safely. 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.seed()` and `inputs.requestInput()` are for
-trusted server appends.
+and AI lifecycle events. `inputs.requestInput()` and non-user messages built
+with `inputs.seed()` are for trusted server appends.
+
+`inputs.message(message, { generate: false })` is valid browser input. It keeps
+the user message in `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 and the existing `{ message }` event payload. `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
 `generationId`. Clients copy it from the pending request, which prevents a
@@ -561,10 +836,22 @@ delayed response from satisfying a newer model step.
 `ai.generation.failed` sets `stepLimit: true` when `maxSteps` rejects a
 continuation before another model step starts.
 
-`ai.message.interrupted` carries `{ messageId, generationId?, reason?,
-lastSeenIndex? }`. Omit `generationId` only while the matching response is in
-the requested phase and `activeGeneration` does not exist yet. Once a
-generation starts, include its id to fence delayed interruption actions.
+`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.
 
 ### `events` and `createEvents(options?)`
 
@@ -581,15 +868,24 @@ createReducer({ contract, name? }): Reducer<AIState>
 Builds the standard AI projection for a compatible contract. `AIState`
 contains session lifecycle, messages, generation status, pending approvals
 and input, tool activity, compaction, usage, the last error, and
-`activeRequestId` and `activeResponseMessageId`, plus
-`responseGenerationIds: Record<string, string>`.
+`activeRequestId`, `activeResponseMessageId`,
+`responseGenerationIds: Record<string, string>`, 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 chunk/tool frontier only while a
-generation is active; terminal events clear it. `responseGenerationIds` keeps
-the latest generation owner for each response message, so late events from a
-superseded owner cannot alter the projection. Extension events are ignored.
+`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, and after a generation fails while it awaits retry
+or interruption. Response completion, interruption, supersession, retry, or a
+later generation clears or replaces it. `responseGenerationIds` 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'>`.
+Extension events are ignored. The default reducer name is `a2.ai.state.v8`.
 
 ### `deriveUIMessages(history)` and `reduceAIState(state, event)`
 
@@ -609,10 +905,11 @@ createAgentServer({
   instructions?,
   generation?,
   maxSteps?,
+  messageMetadata?,
   generate?,
   compaction?,
   progress?,
-  log?, recovery?, telemetry?, handlers?,
+  store?, scheduler?, telemetry?, handlers?,
 }): A2Server
 ```
 
@@ -626,12 +923,23 @@ async resolvers.
 
 `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. `maxSteps`
-limits one complete assistant response and defaults to 20. Support for
-individual model settings depends on the selected model and provider.
-`generation` excludes `stopWhen`, tool execution callbacks, tool callers, tool
-context, sandbox execution, and the tool approval secret. Model-step timeouts
-remain available; tool-execution timeouts do not.
+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.
+
+`messageMetadata(context)` synchronously maps each default AI SDK stream part
+to the metadata type of the agent's `UIMessage`. The context includes the
+generation state and the current `TextStreamPart`. 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 messages, the resolved model and instructions, tools, generation
@@ -675,6 +983,13 @@ When selected, both the request and the replacement messages enter the log.
 
 This entry point is server-only and resolves to a throwing browser stub.
 
+### `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`
+for any agent argument.
+
 ### `createHandlers(options)`
 
 Returns the built-in A2 handler table without constructing a server. Spread
@@ -691,7 +1006,7 @@ handler. Custom assemblies pass `validateAgentPush` as
 
 Accepts the browser interaction allowlist: user messages, approval and input
 responses, interruptions, and explicit retries. It rejects server-authored
-scheduling and lifecycle events, trusted seed messages, and input requests.
+scheduling and lifecycle events, seeded non-user messages, and input requests.
 `createAgentServer()` installs it automatically.
 
 See [Durable AI agents](/guides/ai-agents) for the protocol and complete
@@ -702,38 +1017,60 @@ examples.
 ```ts
 createClient(options: {
   reducer: Reducer
-  api: string
+  api: ClientApi
   gcTime?: number // idle session lifetime; 5 minutes by default
 }): A2Client
+
+type ClientApi =
+  | string // one route: GET SSE stream + POST push
+  | { type: 'http'; push: string; stream: string } // split routes
+  | { type: 'ws'; url: string } // one socket, both directions
 ```
 
 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, {
-initialState?, initialIndex?, initialEvents? })` returns a handle with
-`getSnapshot()`/`subscribe()` (the `useSyncExternalStore` contract),
-`push()`, `connect()`, and `close()`. Snapshots carry `state`, `events`,
-`index`, and `connection` (the same fields `useSession` exposes), and
-`push` returns the same ack-then-`confirmed` result. Use it directly
-from any other framework, or none.
+initialState?, initialIndex?, initialEvents?, participant? })` returns a
+handle with `getSnapshot()`/`subscribe()` (the `useSyncExternalStore`
+contract), `push()`, `connect()`, and `close()`. Snapshots carry
+`state`, `events`, `index`, 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. Use
+it directly from any other framework, or none.
 
 Within one `A2Client`, repeated `session(id)` calls return the same live
-handle. `initialEvents` seeds the raw feed for SSR. A later call with a further
-server-rendered frontier advances the handle, merges its history, and does not
-drop pending optimistic events; a stale render cannot move it backward. 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.
+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.
 
 ## `experimental-a2/http`
 
 | Helper                  | What it does                                                                   |
 | ----------------------- | ------------------------------------------------------------------------------ |
-| `parsePushBody(req)`    | validates the push envelope `{ sessionId, events }`, throws `INVALID_PAYLOAD`   |
-| `sseResponse(iterable)` | pipes a `session.stream()` iterable into an SSE `Response`, with a `: connected` prelude and a `: ping` heartbeat every 15s |
+| `schedulerHandler(...servers)` | returns the delivery route after synchronously verifying one shared scheduler |
+| `parsePushBody(req)`    | validates the push envelope `{ sessionId, events, presence? }`, throws `INVALID_PAYLOAD`   |
+| `sseResponse(iterable)` | pipes a `session.stream()` iterable into an SSE `Response`, with a `: connected` prelude, a `: ping` heartbeat every 15s, and a clean close one second before an ambient Vercel invocation deadline when available; presence patches ride as named `presence` frames |
+| `sessionSocket(session, socket, options?)` | speaks the A2 wire over any `ws`-shaped socket: the stream pumps down as JSON frames, pushes and presence come up with the same validation and `validatePush` seam as the POST route; `options` carries `startAfter`, `presence`, and an optional `deadline` for clean pre-deadline closes. See [Transports](/guides/transports) |
 | `errorResponse(err)`    | serializes an `A2Error` to `{ error: { code, message, details } }` + status     |
 | `deserializeError(body)` | rebuilds an `A2Error` from a wire body, or `null` if the body isn't one        |
 
+`schedulerHandler(...servers)` is the application-facing scheduler route. It
+requires at least one A2 server. Every server must have a scheduler, use the
+exact same scheduler instance, and have a unique contract name. Non-A2 values
+also fail. These checks throw before the request handler is returned, so bad
+wiring fails when the route module loads. The helper then delegates delivery
+to the shared adapter's `A2Scheduler.handler(...)` method.
+
+Different scheduler instances use different routes. Match each QStash route to
+that instance's resolved `url`; additional QStash routes pass an explicit
+`url`. Match each Vercel Queues route and trigger to that instance's `topic`.
+
 Together the last two are the `A2Error` wire format that `push` and the
 push route share. See [Errors](/reference/errors#over-the-wire).
 
@@ -767,7 +1104,7 @@ Four spans, all carrying `a2.contract` and `a2.session_id`:
 
 | Span        | Wraps                                                  |
 | ----------- | ------------------------------------------------------ |
-| `a2.append` | validation + the log write (one batch)                 |
+| `a2.append` | validation + the store write (one batch)               |
 | `a2.drain`  | one drain pass over a session's backlog                |
 | `a2.event`  | one claimed dispatch of one event                      |
 | `a2.state`  | one `state()` read: snapshot-plus-tail load + fold      |
@@ -783,7 +1120,7 @@ alert on are all mid-span.
 | `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 recovery arm failed and this append degraded to append-driven healing |
+| `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.event.type`       | `a2.event`  | start | the event's type                                      |
@@ -792,7 +1129,7 @@ alert on are all mid-span.
 | `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` |
+| `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) |
@@ -814,6 +1151,54 @@ log.
 renames and additions are breaking for dashboards, and are called out in the
 package's `CHANGELOG.md`.
 
+## `experimental-a2/devtools`
+
+The shared, isomorphic protocol for browser Devtools, the CLI, and `.a2log`
+captures.
+
+| Export | Contract |
+| --- | --- |
+| `DEVTOOLS_PROTOCOL_VERSION` | Current HTTP wire protocol version |
+| `DEVTOOLS_CAPTURE_VERSION` | Current `.a2log` record format version |
+| `DEVTOOLS_CAPTURE_MEDIA_TYPE` | `application/x-ndjson` |
+| `DEVTOOLS_SESSION_PAGE_LIMIT` | Default event count requested per session page |
+| `DEVTOOLS_SESSION_PAGE_MAX_LIMIT` | Maximum event count accepted per session page |
+| `DEVTOOLS_CAPABILITIES` | Protocol resources and capture format advertised by the server |
+| `devtoolsSessionRevision({ events, snapshots })` | Compute the lifecycle invalidation token after assembling pages |
+| `encodeDevtoolsCapture(detail, { capturedAt? })` | Encode one session detail as exact NDJSON and add its SHA-256 footer |
+| `parseDevtoolsCapture(value)` | Parse NDJSON text or bytes into a `DevtoolsCapture` while retaining unknown fields on known records |
+| `verifyDevtoolsCapture(capture)` | Verify versions, record shapes, session identity, indexes, counts, dates, and the SHA-256 digest |
+
+The wire types are `DevtoolsWireSessionSummary`, `DevtoolsWireEvent`,
+`DevtoolsWireSnapshot`, `DevtoolsContractsResponse`,
+`DevtoolsSessionsResponse`, `DevtoolsSessionDetail`, `DevtoolsSessionPage`, and
+`DevtoolsCapabilities`. Capture records use `DevtoolsCaptureManifest`,
+`DevtoolsCaptureEvent`, `DevtoolsCaptureSnapshot`,
+`DevtoolsCaptureFooter`, and `DevtoolsCaptureRecord`. A parsed
+`DevtoolsCapture` exposes the same canonical sequence through `records`.
+
+```ts test/verify-a2log.ts
+import { readFile } from 'node:fs/promises'
+import {
+  parseDevtoolsCapture,
+  verifyDevtoolsCapture,
+} from 'experimental-a2/devtools'
+
+export async function verifyA2Log(path: string) {
+  const capture = parseDevtoolsCapture(await readFile(path))
+  await verifyDevtoolsCapture(capture)
+  return capture
+}
+```
+
+The manifest records the contract, session, revision, capture time, protocol
+version, and capture version. Event records contain the exact durable payload
+and operational bookkeeping. Snapshot records contain metadata but never
+cached reducer state. The final `end` record contains counts, the highest event
+index, and a digest of every preceding encoded record. The session revision is
+an invalidation token, not the integrity digest. Encoding rejects durable
+values that canonical JSON would coerce or omit.
+
 ## `experimental-a2/devtools/server`
 
 ```ts
@@ -838,14 +1223,274 @@ from stored events. The initial page response includes the selected dashboard
 data so the browser does not need a contracts, sessions, and detail request
 waterfall. It never drains or heals a session.
 
-Without `authorize`, the handler is available outside production and returns
-404 in production. Returning `false` from `authorize` also returns 404.
-Returning a `Response` passes that response through, which supports redirects
-and authentication challenges.
+Every route is a `GET`. The versioned resources are `capabilities`,
+`contracts`, `sessions`, `session`, `watch`, and `export` under the handler's
+`_a2/` path. `export` returns an integrity-checkable `.a2log` with the media
+type from `DEVTOOLS_CAPTURE_MEDIA_TYPE`.
+
+`session` without pagination parameters returns one complete detail. Add a
+positive `limit` to receive a `DevtoolsSessionPage`. Its `throughIndex` is the
+inclusive event frontier frozen by the first request. Pass its opaque `cursor`
+back until the cursor is null. Snapshot metadata appears on the first page
+only. The cursor is bound to its contract and session, and the server rejects
+reuse against another log. The advertised maximum page size is clamped by the
+server.
+
+The browser, CLI, watch loop, and export route walk these bounded pages for
+you. They reject a gap or early end. An exact export includes every event
+through one finite frontier, even when a backend provider limits one range
+response. Events appended during the walk belong to a later read.
+
+Without `authorize`, the handler is available only when `NODE_ENV` is exactly
+`development`. Any other value, including unset, returns 404. When `authorize`
+is present, only a literal `true` grants access. Returning `false` also returns
+404. Returning a `Response` passes that response through, which supports
+redirects and authentication challenges. The mounted handler is the
+authorization boundary for the browser, CLI, SSE stream, and exact capture
+download. A2 does not add a separate Devtools credential store.
+
+The built-in memory, SQLite, Postgres, and Redis stores support inspection.
+Custom `A2Store` implementations can omit the optional `inspect` interface; the
+dashboard returns 501 for those logs. A custom inspection implementation may
+add `readEvents(sessionId, { afterIndex, throughIndex?, limit })` for efficient
+bounded reads. It returns `{ events, throughIndex }`, where the first call
+freezes the inclusive frontier and continuations preserve it. Without this
+method, A2 reads the complete log for each page and slices it in memory.
+
+## `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'` |
+| `scheduledAppends` | `'deployment' \| 'deploymentless'` | `'deployment'` |
+| `transport` | `QueueTransport` | lazy `@vercel/queue` client |
+| `clock` | `{ now(): Date }` | system clock |
+
+The default pins recovery watchdogs and scheduled appends to the deployment
+that publishes them. Recovery always remains pinned. Set `scheduledAppends` to
+`'deploymentless'` only when every eligible deploymentless consumer for the
+topic can decode pending tasks and validate their events. This option removes
+deployment affinity. It does not select the latest production deployment.
+
+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 selected deployment affinity as an optional fourth send
+argument while its message remains an exact `SchedulerTask`. It must honor that
+hint for `scheduledAppends: 'deploymentless'` to affect its provider-specific
+routing. The built-in transport adds its callback-routing metadata only after
+this injection seam.
+
+## `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 { schedulerHandler } from 'experimental-a2/http'
+import { ordersServer, billingServer } from '@/server'
+
+export const POST = schedulerHandler(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 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 both drain and append 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
+lineage includes its 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.
+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.
+
+## `a2 devtools`
+
+The package installs an `a2` binary with a read-only `devtools` namespace.
+
+| Command | Purpose |
+| --- | --- |
+| `contracts` | List contracts mounted at the Devtools URL |
+| `sessions --contract NAME` | List session summaries, with optional `--limit` and `--cursor` |
+| `show --contract NAME --session ID` | Read one session's exact durable detail |
+| `export --contract NAME --session ID` | Verify and save an `.a2log`; use `--output` and opt into replacement with `--force` |
+| `check --contract NAME --session ID` | Verify a live capture and optionally require `--settled`, `--no-dead-letters`, `--no-caught-failures`, or `--max-redispatches N` |
+| `verify FILE` | Verify a saved capture offline |
+
+Live commands read the mounted URL from `--url` or `A2_DEVTOOLS_URL`.
+`A2_DEVTOOLS_TOKEN` supplies the default bearer token. `--bearer-env ENV` and
+repeatable `--header-env HEADER=ENV` reference other environment variables.
+Credential values are never accepted as CLI arguments or URL components.
+Output uses `--format human`, `json`, or `ndjson`.
+
+## `experimental-a2/testing`
+
+Node-only helpers for verified capture loading and pure reducer replay.
+
+| Export | Contract |
+| --- | --- |
+| `loadCapture(source, contract)` | Read a filesystem path or URL, verify its integrity, validate its contract and payloads, and return typed events |
+| `prepareCapture(capture, contract)` | Apply the same verification and contract typing to an already parsed capture |
+| `replayCapture(loaded, reducer, { throughIndex? })` | Fold captured events through the reducer, stopping at an optional inclusive index |
+
+`LoadedCapture` contains the verified `capture`, the `contract`, typed public
+`events` with `createdAt` revived as `Date`, and unmodified operational
+`rawEvents`.
+`CaptureReplay` returns `{ state, index }`. A cutpoint of 0 returns the initial
+state and index 0. Supporting types are `CaptureSource`, `LoadedCapture`,
+`ReplayCaptureOptions`, and `CaptureReplay`.
 
-The built-in memory, SQLite, Postgres, and Redis logs support inspection.
-Custom `A2Log` implementations can omit the optional `inspect` interface; the
-dashboard returns 501 for those logs.
+Replay does not use cached snapshot state, construct a server, dispatch a
+handler, invoke an AI model or tool, or repeat external effects. It reproduces
+only the current reducer's pure projection over already recorded events.
 
 ## Entry points
 
@@ -855,18 +1500,22 @@ dashboard returns 501 for those logs.
 | `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`              | agent contract, reducer, and append builders: isomorphic | `ai` |
+| `experimental-a2/ai`              | agent contract, `handlerContext`, reducer, and append builders: isomorphic | `ai` |
 | `experimental-a2/ai/server`       | AI SDK runner and built-in handlers | `ai`           |
-| `experimental-a2/http`            | route-side transport helpers       | none            |
-| `experimental-a2/log-postgres`    | `postgres`: Postgres log backend   | `pg` (or inject a client) |
-| `experimental-a2/log-redis`       | `redis`: Redis Streams log backend, push-native streaming | `ioredis` (or inject a client) |
-| `experimental-a2/log-sqlite`      | SQLite log backend                 | none            |
-| `experimental-a2/log-memory`      | in-memory log backend              | none            |
-| `experimental-a2/recovery-vercel` | `vercelQueues` recovery            | `@vercel/queue` |
+| `experimental-a2/http`            | route-side transport and scheduler helpers | none            |
+| `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` |
+| `experimental-a2/devtools`        | versioned wire protocol and exact capture codec | none            |
 | `experimental-a2/devtools/server` | durable read-only dashboard handler | none            |
+| `experimental-a2/testing`         | Node-only capture loading and pure reducer replay | none            |
 
 Core `experimental-a2` imports none of the backends, enforced by a browser-bundle
-test in CI, not just convention. Importing `experimental-a2/log-postgres` is what
+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.