experimental-a2 0.6.0 → 0.8.0

package/docs/reference/01-api.mdx

@@ -72,7 +72,6 @@ createServer(options: {
   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]:
@@ -123,19 +122,6 @@ Server-only by construction: `experimental-a2/server` is the only entry point th
 can reach a store backend, and its exports map resolves to a loud error
 under the browser condition.
 
-`validatePush(context)` runs only for input that arrived over the wire
-through `handle`'s push lane, 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. The envelope parser inside `handle` 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
@@ -172,12 +158,11 @@ The context every handler receives:
 when a process dies before handler entry.
 
 `ctx.session.id` equals `ctx.event.sessionId`. Its `history`, `state`, and
-`stream` methods are the same session operations returned by
-`server.session(id)`. `ctx.session.state(reducer)` reads the cached snapshot
-plus immutable log tail and returns `{ state, index }`. The index is a
-consistent committed frontier captured when the call runs. It includes the
-triggering event and may include events committed later while another handler
-is active.
+`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:
 
@@ -198,10 +183,141 @@ 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
-eligible attempt converges on the same append.
+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>
+  },
+): 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.
+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,
+      }),
+  })
+}
+```
+
+Authenticate the physical WebSocket GET before calling `server.fetch`. Then
+use `authorize` for each session subscribe and each event or presence push.
+There is no WebSocket-upgrade operation in `A2Operation`. 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. Failed presence authorization is dropped the same way and does
+not disconnect unrelated sessions on the multiplexed socket.
+
+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)`
 
@@ -372,9 +488,9 @@ Custom scheduler adapters implement two methods:
 | `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.
+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`. These task types,
 plus `ScheduledEvent`, are exported from `experimental-a2/server`.
@@ -429,7 +545,7 @@ 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
-`handle`'s push lane are accepted directly.) See
+`server.fetch`'s push lane are accepted directly.) See
 [Durability](/concepts/durability).
 
 After the write, A2 dispatches only event types with registered handlers.
@@ -514,10 +630,13 @@ 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)`
+### `session.state(reducer, options?)`
 
 ```ts
-session.state(reducer: Reducer<S>): Promise<{ state: S; index: number }>
+session.state(
+  reducer: Reducer<S>,
+  options?: { through?: number | 'latest' },
+): Promise<{ state: S; index: number }>
 ```
 
 The log folded through one committed prefix. `index` is its exact boundary,
@@ -525,6 +644,24 @@ 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.
+
+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.
+
 ### `session.stream(options?)`
 
 ```ts
@@ -537,7 +674,7 @@ session.stream(options: {
 
 A live feed of the session's events. `startAfter` is a non-negative safe integer;
 `startAfter: 20` begins with event 21.
-Server-side only; `handle` exposes it over SSE, and over the multiplexed
+Server-side only; `server.fetch` exposes it over SSE, and over the multiplexed
 socket when `upgrade` is set. Subscribing never dispatches handlers.
 
 With `presence: true`, the feed yields one `PresenceSnapshot` first:
@@ -581,7 +718,7 @@ 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;
-`handle`'s push lane forwards it whole to `session.setPresence(presence)`.
+`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
@@ -707,9 +844,7 @@ 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. If
-the map holds only your own echo with
-participants active, the GET route forgot `presence: true`. See
+`participant`: the client's default, or the provider's override. See
 [Presence](/guides/presence).
 
 `push` appends optimistically: validated locally, rolled back on
@@ -1006,10 +1141,12 @@ retried or interrupted.
 Independent authorized tool handlers run concurrently without a fixed
 concurrency limit. 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()` reads the
-durable snapshot plus log tail. 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.
+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
@@ -1045,17 +1182,10 @@ it into `createServer({ handlers })` beside application handlers when you need
 a custom assembly. The table handles input facts, generation requests, model
 step completion, tool calls, approval responses, and terminal tool results.
 Application handlers spread later can deliberately replace a built-in
-handler. Custom assemblies pass `validateAgentPush` as
-`createServer({ validatePush })` to preserve the browser boundary.
-
-### `validateAgentPush(context)`
-
-`validateAgentPush({ sessionId, events }): void`
-
-Accepts the browser interaction allowlist: user messages, approval and input
-responses, interruptions, and explicit retries. It rejects server-authored
-scheduling and lifecycle events, seeded non-user messages, and input requests.
-`createAgentServer()` installs it automatically.
+handler. A custom assembly owns its browser ingress policy. Use
+`server.fetch(request, { authorize })` to reject server-authored AI event names
+before they reach the server. `createAgentServer()` installs the built-in
+browser allowlist automatically.
 
 See [Durable AI agents](/guides/ai-agents) for the protocol and complete
 examples.
@@ -1106,96 +1236,6 @@ 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`
-
-### `handle(server, options?)`
-
-```ts
-handle(server: A2Server, options?: {
-  before?(args: { request: Request; intent: A2Intent }):
-    Response | undefined | void | Promise<Response | undefined | void>
-  after?(args: { request: Request; intent: A2Intent; outcome: A2Outcome; response: Response }):
-    Response | undefined | void | Promise<Response | undefined | void>
-  upgrade?: UpgradeFn  // e.g. (attach) => experimental_upgradeWebSocket(attach)
-  presence?: boolean   // interleave presence on every stream lane
-  deadline?: number    // epoch ms: close sockets cleanly before it
-}): { GET(req: Request): Promise<Response>; POST(req: Request): Promise<Response> }
-
-type A2Intent =
-  | { type: 'ws-upgrade' }
-  | { type: 'stream'; sessionId: string; startAfter: number; transport: 'sse' | 'ws' }
-  | { type: 'history'; sessionId: string; gte: number; lte: number }
-  | { type: 'push'; sessionId: string; events: PushedEvent[]; presence?: PushedPresence; transport: 'http' | 'ws' }
-
-type A2Outcome =
-  | { type: 'stream' }
-  | { type: 'history'; covered: boolean; events: Event[] }
-  | { type: 'push'; appended: Event[] }
-```
-
-The session route pair as one call: `export const { GET, POST } =
-handle(server)` in a route module (any framework speaking
-`(req: Request) => Promise<Response>`). A plain `GET` is the live SSE
-stream, resumed after the `index` query parameter, 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 frames when `presence: true`. A `GET` with
-`gte`/`lte` query parameters is a history slice: the closed log range
-as JSON wire events, the read `loadHistory` rides. `POST` is the push
-envelope `{ sessionId, events, presence? }`, answered with the appended
-events. A `GET` carrying an upgrade header becomes the multiplexed
-WebSocket when `options.upgrade` is present, and answers `426` when it
-is not.
-
-Parsing is protocol, hooks are policy. A request that fails to parse
-(missing `sessionId`, malformed bounds, a bad push envelope) answers
-`INVALID_PAYLOAD` on the wire before any hook runs. `before` sees every
-parsed intent, HTTP requests and socket frames alike; over the socket,
-each subscribe arrives as a `stream` intent and each push as a `push`
-intent, with `request` always the original upgrade Request. Returning a
-Response short-circuits: over HTTP it is the response, verbatim; over
-the socket it is translated into the wire's own vocabulary (a denied
-subscribe answers `unsubscribed`, a denied push a non-retryable error
-ack), because a Response cannot cross a socket.
-
-`after` runs only where the library produced an HTTP response: never
-after a short-circuit, never for `ws-upgrade` or socket frames. It may
-mutate `response.headers` in place or return a replacement Response.
-`outcome.covered` on a history read means the closed range came back
-fully covered (`events.length === lte - gte + 1`): an immutable slice
-of the append-only log, safe to cache under whatever policy your
-`after` applies. The history response carries no cache headers of its
-own.
-
-The socket is one connection for all of a client's sessions:
-`subscribe`/`unsubscribe` frames open and close per-session lanes at
-their own resume frontiers, `sessionId` tags route pushes, presence,
-and acks, and a lane ending or failing answers `unsubscribed` without
-taking the socket down. See [Transports](/guides/transports).
-
-### The rest of the entry
-
-| Helper                  | What it does                                                                   |
-| ----------------------- | ------------------------------------------------------------------------------ |
-| `schedulerHandler(...servers)` | returns the delivery route after synchronously verifying one shared scheduler |
-| `errorResponse(err)`    | serializes an `A2Error` to `{ error: { code, message, details } }` + status; the natural return value of a refusing `before` hook |
-| `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`.
-
-`errorResponse` and `deserializeError` are the `A2Error` wire format
-that `push` and the push lane share. See
-[Errors](/reference/errors#over-the-wire).
-
 ## `experimental-a2/cache-indexeddb`
 
 ```ts
@@ -1273,112 +1313,6 @@ 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
-// anywhere on the server:
-import type { DevtoolsServer } from 'experimental-a2/devtools/server'
-
-declare function createDevtools(options: {
-  servers: readonly DevtoolsServer[]
-  authorize?: (
-    request: Request,
-  ) => boolean | Response | Promise<boolean | Response>
-}): {
-  handler(): (request: Request) => Promise<Response>
-}
-```
-
-A read-only dashboard over the servers' durable logs. The handler serves the
-complete browser application, its JSON endpoints, and live SSE invalidations.
-It discovers sessions and reads stored causal, dispatch, completion, failure,
-and snapshot metadata. The causal forest and lifecycle timeline come directly
-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.
-
-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.
@@ -1490,10 +1424,9 @@ 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'
+import { billingServer, ordersServer, scheduler } from '@/server'
 
-export const POST = schedulerHandler(ordersServer, billingServer)
+export const POST = scheduler.handler(ordersServer, billingServer)
 ```
 
 The route must be reachable by the selected QStash server after any platform
@@ -1574,46 +1507,6 @@ 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`.
-
-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
 
 | Entry point          | Ships                              | Peer dependency |
@@ -1624,7 +1517,6 @@ only the current reducer's pure projection over already recorded events.
 | `experimental-a2/react`           | `createReact`                      | `react`         |
 | `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 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 |
@@ -1634,9 +1526,6 @@ only the current reducer's pure projection over already recorded events.
 | `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/store-postgres` is what

package/docs/reference/02-errors.mdx

@@ -1,6 +1,6 @@
 ---
 title: Errors
-description: One error class, five codes, and clear rules about what append will never throw for.
+description: One error class, stable codes, and clear rules about what append will never throw for.
 ---
 
 ## `A2Error`
@@ -35,6 +35,7 @@ export async function POST(req: Request) {
 | Code                      | Thrown when                                                        | Retryable |
 | ------------------------- | ------------------------------------------------------------------ | --------- |
 | `INVALID_PAYLOAD`         | a payload fails its schema; nothing was written, and `details` carries the issues ([Standard Schema](https://standardschema.dev) format) | no        |
+| `FORBIDDEN`               | `server.fetch` authorization denies a parsed stream, history read, push, or presence update | no |
 | `UNKNOWN_EVENT_TYPE`      | an event type isn't in the contract's `events` map                  | no        |
 | `UNKNOWN_PRESENCE_FIELD`  | a presence field isn't in the contract's `presence` map             | no        |
 | `PRESENCE_NOT_SUPPORTED`  | the contract declares `presence` but the configured store has no presence capability (thrown at construction; for environment-resolved stores, deferred to the first store use) | no |
@@ -73,12 +74,9 @@ The push route serializes an `A2Error` as:
 ```
 
 with a mapped status: `INVALID_PAYLOAD`, `UNKNOWN_EVENT_TYPE`, and
-`PARTIAL_DUPLICATE_BATCH` are 400; `SUPERSEDED_ATTEMPT` is 409;
-`STORE_UNAVAILABLE` is 503.
+`PARTIAL_DUPLICATE_BATCH` are 400; `FORBIDDEN` is 403;
+`SUPERSEDED_ATTEMPT` is 409; `STORE_UNAVAILABLE` is 503.
 
 The client's `push` deserializes the body back into an `A2Error`, so client
 and server code branch on identical codes. `push` auto-retries only
-`STORE_UNAVAILABLE`. The serializer pair, `errorResponse` and
-`deserializeError`, ships in `experimental-a2/http` alongside `handle`;
-a `before` hook that wants the wire's own error shapes returns
-`errorResponse(new A2Error(...))`.
+`STORE_UNAVAILABLE`. `server.fetch` owns the HTTP serialization.