experimental-a2 0.6.0 → 0.8.0

package/docs/concepts/04-state.mdx

@@ -96,17 +96,57 @@ arguments or annotations are needed, and literal unions survive the fold.
 fold includes every event through that index and none after it. The browser
 resumes its live stream from that boundary. See [Live UI](/guides/react).
 
+A root session reads the latest committed frontier by default. A handler's
+session is causally scoped, so the same call stops at its triggering event:
+
+```ts causal-server.ts
+import { createServer } from 'experimental-a2/server'
+import { orders } from './contracts'
+import { ordersReducer } from './reducer'
+
+export const causalOrdersServer = createServer({
+  contract: orders,
+  handlers: {
+    created: async ({ event, session }) => {
+      const atTrigger = await session.state(ordersReducer)
+      // atTrigger.index === event.index
+
+      const current = await session.state(ordersReducer, {
+        through: 'latest',
+      })
+      void current
+    },
+  },
+})
+```
+
+The trigger boundary is stable across concurrent appends and retries. Use the
+explicit latest read for joins or other logic that intentionally observes later
+events. A numeric `{ through: index }` reads any inclusive log boundary;
+`through: 0` returns `initialState`.
+
+A bounded handler read also keeps that exact folded checkpoint available while
+the triggering event is unfinished. This is automatic. When concurrent work
+advances the reducer's latest snapshot, A2 retains the older checkpoint until
+every handler event using it completes or dead-letters. There is no TTL, history
+limit, or retention setting to tune.
+
+Root reads and handler reads with `{ through: 'latest' }` do not retain
+historical checkpoints. A root numeric read can use an older checkpoint that an
+active handler already retained, but querying an old boundary does not keep it
+around or write a stale snapshot behind the current head. If no suitable
+checkpoint exists, A2 folds the bounded log.
+
 The snapshot and its remaining event tail come back in one consistent store
 operation. A missing, invalid, or unreadable snapshot rebuilds from the full log.
 `state()` is observational: it never runs handlers or waits for pending work.
-Its index marks committed history, not handler completion. Inside a handler it
-includes the trigger and may include later events committed before the read.
+Its index marks committed history, not handler completion.
 
-The read and a following `ctx.session.append(name, ...events)` are separate
+A latest read and a following `ctx.session.append(name, ...events)` are separate
 operations. Concurrent appends and retries can move the frontier between them.
-For joins, use a monotone readiness check (once ready, always ready) and give
-the output event a stable explicit `id`. Repeated attempts then converge on the
-same append.
+For joins, read with `{ through: 'latest' }`, use a monotone readiness check
+(once ready, always ready), and give the output event a stable explicit `id`.
+Repeated attempts then converge on the same append.
 
 `stateSchema` declares the state's shape once. Without it, the state type
 is inferred from `initialState`, fine while every fold arm returns the
@@ -130,6 +170,12 @@ Folding a long session on every read would get slow, so the store backend
 caches folded state as a snapshot. You never interact with it, except for
 one string.
 
+Each session and reducer has one latest snapshot. Older snapshots exist only
+while unfinished handler events need their exact state boundary. Handler
+completion and dead-lettering release those references in the same store
+operation and remove any historical snapshot with no remaining reader. Several
+handlers can share one checkpoint; it stays until the last reference leaves.
+
 Snapshots are keyed by the reducer's `name`, which makes the name do two
 jobs. It's the identity: two different reducers over the same session
 never fight over a cache entry, because they have different names. And
@@ -138,9 +184,11 @@ it's the invalidation knob. Changed the fold's logic? Change the name (a
 ignored; the next read refolds from raw events and caches under the new
 name. That's the entire cache invalidation story: one string.
 
-Snapshot write-back runs in platform `waitUntil` after the state is ready. It
-never delays the read, and a failed or interrupted cache write changes no
-application behavior. The next read folds the missing tail again.
+Snapshot write-back runs in platform `waitUntil` after the state is ready. One
+same-tick group of reads for a reducer and session reads the widest required log
+range once, folds it once, and writes the needed prefixes together. A failed or
+interrupted cache write changes no application behavior. The next read folds
+the missing tail again.
 
 Deleting every snapshot is always safe. The log rebuilds them.
 

package/docs/guides/03-react.mdx

@@ -23,22 +23,15 @@ reducer, and the provider + hook it returns.
 
 ## The API route
 
-One call exposes a session over HTTP: `GET` streams events (and serves
-history slices), `POST` appends. `handle` parses each request into an
-intent, runs your hooks, then acts.
+`server.fetch` exposes a session over HTTP. It is bound, so the route can
+export it directly: `GET` streams events and serves history slices;
+`POST` appends.
 
 ```ts app/api/order-events/route.ts
-import { handle } from 'experimental-a2/http'
 import { ordersServer } from '@/server/orders'
 
-export const { GET, POST } = handle(ordersServer, {
-  before({ request, intent }) {
-    // here's where you'd do auth, or any other checks. Every lane
-    // arrives parsed: intent.type is 'stream', 'history', 'push', or
-    // 'ws-upgrade'. Return a Response to refuse, e.g.:
-    // if (!canRead(request, intent)) return new Response(null, { status: 403 })
-  },
-})
+export const GET = ordersServer.fetch
+export const POST = ordersServer.fetch
 ```
 
 `GET` is the read path. A plain `GET` is the live stream: a server-sent
@@ -48,31 +41,30 @@ paint or a dropped connection. A `GET` carrying `gte`/`lte` query
 parameters is a history slice instead: the bounded log range as JSON,
 the cold read [`loadHistory`](#the-client-component) rides.
 
-`POST` is the write path. The push envelope is validated (garbage
-answers `INVALID_PAYLOAD` before your hooks run), then `append` does the
+`POST` is the write path. The push envelope is validated, then `append` does the
 rest. The response is the appended events: an ack, not a stream. Thrown
 [`A2Error`s](/reference/errors#over-the-wire) serialize onto the wire so
 the client can branch on the same codes.
 
-Parsing is protocol, hooks are policy. `before` sees every parsed
-intent and short-circuits by returning a Response. `after` runs when the
-library produced an HTTP response and can decorate or replace it. That
-is where caching policy lives, if you want any: `outcome.covered` on a
-history read means the closed range came back fully covered, an
-immutable slice of an append-only log.
+Wrap `server.fetch` when the route needs authentication, per-operation
+authorization, or response decoration. `authorize` receives the parsed
+A2 operation after envelope parsing and before schema validation or I/O.
+Return `false` to answer `FORBIDDEN`. A thrown error is treated as an
+infrastructure failure.
 
 ```ts
 // app/api/order-events/route.ts, now with response decoration:
-import { handle } from 'experimental-a2/http'
 import { ordersServer } from '@/server/orders'
 
-export const { GET, POST } = handle(ordersServer, {
-  after({ outcome, response }) {
-    if (outcome.type === 'history' && outcome.covered) {
-      response.headers.set('cache-control', 'private, max-age=31536000')
-    }
-  },
-})
+export async function GET(request: Request): Promise<Response> {
+  const response = await ordersServer.fetch(request)
+  if (response.headers.get('a2-history-covered') === 'true') {
+    response.headers.set('cache-control', 'private, max-age=31536000')
+  }
+  return response
+}
+
+export const POST = ordersServer.fetch
 ```
 
 ## The session module

package/docs/guides/05-production.mdx

@@ -89,21 +89,19 @@ export const ordersServer = createServer({
 })
 ```
 
-One scheduler instance is shared by every server on this route. The route
-derives that scheduler from the servers:
+One scheduler instance is shared by every server on this route. Mount its
+handler with every server it may deliver to:
 
 ```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)
 ```
 
-`schedulerHandler(...)` checks the wiring synchronously when this module loads.
-Every argument must be an A2 server with a scheduler, every contract name must
-be unique, and every server must hold the exact same scheduler instance. A bad
-route fails during startup or a build that evaluates route modules, before it
-can accept a delivery.
+`scheduler.handler(...)` checks the server list synchronously when this module
+loads. It requires at least one drainable server and unique contract names. A
+bad route fails during startup or a build that evaluates route modules, before
+it can accept a delivery.
 
 ```json vercel.json
 {
@@ -177,7 +175,7 @@ export const ordersServer = createServer({
 })
 ```
 
-Mount `schedulerHandler(ordersServer, billingServer)` once with the same
+Mount `scheduler.handler(ordersServer, billingServer)` once with the same
 `app/api/a2/scheduler/route.ts` module shown above. Local Node.js development
 needs no QStash environment variables. With `@upstash/qstash` 2.11.0 or newer,
 A2 uses `http://localhost:${PORT ?? 3000}/api/a2/scheduler` and enables the

package/docs/guides/06-ai-agents.mdx

@@ -129,14 +129,10 @@ One HTTP route gives the browser a read and write path. `GET` streams events;
 `POST` accepts optimistic pushes:
 
 ```ts app/api/agent-events/route.ts
-import { handle } from 'experimental-a2/http'
 import { assistantServer } from '@/server/assistant'
 
-export const { GET, POST } = handle(assistantServer, {
-  before({ request, intent }) {
-    // here's where you'd do auth, or any other checks
-  },
-})
+export const GET = assistantServer.fetch
+export const POST = assistantServer.fetch
 ```
 
 The route never calls the model directly. The browser appends user facts such
@@ -631,7 +627,8 @@ authorization are ready. There is no fixed tool concurrency limit. A private
 coordinator reducer tracks generation closure, cancellation, calls, approvals,
 and terminal results for the active response. Its retained state is bounded;
 completed responses do not accumulate in the coordinator. Each join reads a
-durable reducer snapshot plus the log tail through `ctx.session.state()`. The snapshot
+durable reducer snapshot plus the log tail through
+`ctx.session.state(coordinator, { through: 'latest' })`. The snapshot
 is only a cache. Recovery can rebuild the same coordinator state from the event
 log after process death.
 
@@ -814,10 +811,7 @@ different server assembly:
 ```ts server/custom.ts
 import { z } from 'zod'
 import { agent } from 'experimental-a2/ai'
-import {
-  createHandlers,
-  validateAgentPush,
-} from 'experimental-a2/ai/server'
+import { createHandlers } from 'experimental-a2/ai/server'
 import { createServer } from 'experimental-a2/server'
 
 const supportAgent = agent({
@@ -834,7 +828,6 @@ const aiHandlers = createHandlers({
 
 export const customAssistantServer = createServer({
   contract: supportAgent.contract,
-  validatePush: validateAgentPush,
   handlers: {
     ...aiHandlers,
     'ticket.linked': async ({ event }) => {
@@ -847,9 +840,11 @@ export const customAssistantServer = createServer({
 
 Application events stay fully typed. The standard AI reducer ignores unknown
 events, so another reducer can project application state without forking the AI
-protocol. `validateAgentPush` preserves the same browser boundary as
-`createAgentServer()`: user facts may enter through a parsed push, while model
-scheduling, tool lifecycle, and seeded non-user messages stay server-authored.
+protocol. A custom `createServer()` assembly owns its browser ingress policy.
+Use `server.fetch(request, { authorize })` to authorize operations, and reject
+server-only AI event names there before they reach the custom server.
+`createAgentServer()` applies its stricter built-in ingress allowlist
+automatically.
 
 ### Replace generation, not durability
 

package/docs/guides/09-presence.mdx

@@ -63,29 +63,25 @@ explicit leave required).
 
 ## The route
 
-The same `handle` route as [Live UI](/guides/react), with one option.
-`presence: true` interleaves presence patches with events on the
-stream, starting with a snapshot of the current map; the push body
-grows an optional `presence` sibling to `events`, forwarded to
-`setPresence`.
+The same `server.fetch` route as [Live UI](/guides/react). Presence is
+inferred from the contract. A contract with presence fields streams
+presence patches with events, starting with a snapshot of the current
+map. Its push body also accepts an optional `presence` sibling to
+`events`, forwarded to `setPresence`.
 
 ```ts app/api/canvas-events/route.ts
-import { handle } from 'experimental-a2/http'
 import { canvasServer } from '@/server/canvas'
 
-export const { GET, POST } = handle(canvasServer, {
-  presence: true,
-  before({ request, intent }) {
-    // here's where you'd do auth, or any other checks. On a push,
-    // intent.presence carries the whole patch; the participant id
-    // is caller-supplied, so authorize it like you authorize events.
-    // createServer's validatePush is the same seam and covers every
-    // transport (socket presence frames never become intents): on the
-    // presence plane it receives { sessionId, events: [], presence }.
-  },
-})
+export const GET = canvasServer.fetch
+export const POST = canvasServer.fetch
 ```
 
+Wrap `server.fetch` when the route needs authentication. Pass
+`authorize` to check the typed A2 operation before field validation or
+I/O. A push operation carries the complete presence patch, including
+its caller-supplied participant id. The same hook runs for HTTP and
+WebSocket presence.
+
 `setPresence` validates each field against the contract, then
 broadcasts. No append transaction, no dispatch, no scheduler arm, no log
 row. A bad field throws `INVALID_PAYLOAD`; an unknown field throws
@@ -177,8 +173,7 @@ Both members are typed from the contract's `presence` map, through the
 reducer, with no type arguments: field names, payloads, and `null`
 clears all autocomplete. On a contract without `presence` the members
 do not exist, so reaching for them is a compile error, not a silent
-no-op. One symptom worth knowing: if the map holds only your own
-echo while others are active, the GET route forgot `presence: true`.
+no-op.
 
 ## Reconciling the planes: `seen`
 

package/docs/guides/10-transports.mdx

@@ -7,8 +7,8 @@ description: "One client, three wires: a single HTTP route, split routes for per
 
 Everything the client does is transport-agnostic: optimistic pushes
 with ack and `confirmed`, frontier-resumed live reads, reconnection
-with backoff, the presence throttle and re-send. `api` picks the wire
-underneath it:
+with backoff, and presence throttling. `api` picks the wire underneath
+it:
 
 ```ts
 // in a 'use client' session module:
@@ -18,73 +18,111 @@ api: { type: 'ws', url: '/api/order-events' }
 ```
 
 - **The string** is the default and the recommendation: one route
-  serving GET (SSE stream) and POST (push), one file, one auth surface.
-  Everything else in these docs uses it.
-- **`http` split** serves the two verbs from two routes. Use it when
-  platform duration limits differ per verb: the stream is a long-lived
-  read that wants a high `maxDuration`, the push is a short write that
-  doesn't.
-- **`ws`** rides everything over one WebSocket: streams come down it,
-  pushes and presence go up it. One socket carries every session of
-  the client; a page showing ten sessions holds one connection, not
-  ten. Use it when latency or per-message cost matters; at a presence
-  cadence of fifteen sends a second, each send is a socket frame
-  instead of a route invocation.
+  serving GET (SSE stream and history) and POST (push).
+- **`http` split** serves the two verbs from separate routes. Use it
+  when platform duration limits differ per verb.
+- **`ws`** rides streams, pushes, and presence over one multiplexed
+  WebSocket. One socket carries every session of the client.
 
 A split socket is unrepresentable on purpose. The socket is one
-connection in both directions; there is nothing left to split.
+connection in both directions.
 
 One wire is missing from `ws` by design: the history lane.
 [`loadHistory`](/guides/react#the-client-component) is a bounded cold
-read and rides plain HTTP; on a `ws` api it throws a `TypeError`.
+read and rides plain HTTP. On a `ws` API it throws a `TypeError`.
+
+## The HTTP route
+
+`server.fetch` is bound, so an unprotected route is two exports:
+
+```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. A GET with `gte` and `lte`
+returns a history slice. POST parses the push envelope and appends its
+events. If the contract declares presence, the same route streams and
+accepts presence automatically.
+
+Wrap the call when the route needs authentication or authorization:
+
+```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
+```
+
+`authorize` runs after A2 parses the operation and before schema
+validation or durable I/O. It receives `stream`, `history`, and `push`
+operations. Push operations include parsed event names and payloads,
+plus the complete presence patch when present. Return `false` to deny.
+A2 answers `FORBIDDEN` with status 403. If the hook throws, A2 treats
+that as an infrastructure failure and answers `STORE_UNAVAILABLE`.
+
+The hook is per `fetch` call. Authentication stays in the route, where
+request headers, cookies, and framework context are available. The
+captured user can then authorize strongly typed A2 operations without
+repeating request parsing.
 
 ## The WebSocket route
 
-The same `handle` route serves both transports. Pass `options.upgrade`
-and a GET carrying an upgrade header becomes the socket; plain GETs
-stay SSE, POST keeps working next to it. A `ws` client never calls
-POST, an `http` client never upgrades; the transports are additive.
+Pass the platform's upgrade capability on GET. POST can stay a direct
+export for HTTP clients:
 
-```ts app/api/order-events/route.ts
+```ts app/api/socket-order-events/route.ts
 import { experimental_upgradeWebSocket } from '@vercel/functions'
-import { handle } from 'experimental-a2/http'
 import { ordersServer } from '@/server/orders'
 
-export const { GET, POST } = handle(ordersServer, {
-  before({ request, intent }) {
-    // here's where you'd do auth, or any other checks: the upgrade
-    // itself, every subscribe, and every push arrive here as intents
-  },
-  upgrade: (attach) =>
-    experimental_upgradeWebSocket(attach, {
-      // ws defaults to 100 MiB per frame; POST bodies cap at about
-      // 4.5 MB on the platform. Keep the two ingress paths at parity.
-      maxPayload: 4 * 1024 * 1024,
-    }),
-})
+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,
+      }),
+  })
+}
 ```
 
-The socket is multiplexed: `subscribe` frames open per-session lanes,
-each resuming from its own frontier; every down frame carries the
-`sessionId` it belongs to; pushes and presence route by it. One
-heartbeat, one connection, all of the client's sessions.
-
-Auth has two moments. `before` runs for the upgrade itself
-(`intent.type === 'ws-upgrade'`), while the request is still a request;
-return a Response to refuse and no socket ever opens. It then runs
-again for every subscribe and push frame: each subscribe arrives as a
-`stream` intent, each push as a `push` intent, with `request` always
-the original upgrade Request. A Response cannot cross a socket, so a
-denial answers in the wire's own vocabulary: a denied subscribe gets an
-`unsubscribed` notice (every other session on the socket streams on), a
-denied push a non-retryable error ack. Socket presence frames are
-fire-and-forget and never become intents; the presence plane's policy
-seam on every wire is `validatePush`.
-
-Two more options ride along: `presence: true` interleaves presence with
-events on every lane, the same opt-in as `stream()`, and `deadline`
-(epoch milliseconds) closes the socket cleanly ahead of a known
-platform deadline, so clients reconnect on your schedule.
+The socket is multiplexed. Subscribe frames open per-session lanes,
+each resuming from its own frontier. Every down frame carries its
+`sessionId`; pushes and presence route by it. One heartbeat and one
+connection serve all of the client's sessions.
+
+Authenticate the physical upgrade before calling `server.fetch`.
+Then pass `authorize` to check every session subscribe and every push
+or presence frame. There is no separate upgrade operation: request
+policy belongs to the route, while A2 operation policy belongs to
+`authorize`.
+
+A denied subscribe receives an `unsubscribed` notice and leaves other
+sessions connected. A denied event push receives a non-retryable
+`FORBIDDEN` ack. Denied presence is silently dropped because presence
+is fire-and-forget and repaints on the next update. Failed presence
+authorization is dropped the same way and leaves the socket connected.
+
+A2 reads the platform's ambient invocation deadline and closes the
+socket cleanly before it. `waitUntil` and deadline discovery remain
+platform capabilities used internally, not options on `server.fetch`.
 
 ## The client
 
@@ -104,37 +142,17 @@ export const { SessionProvider, useSession } = createReact({
 ```
 
 Nothing else changes. `useSession` is identical, `push` returns the
-same ack and `confirmed`, presence coalesces on the same cadence. The
-connection status, the stall watchdog (two missed heartbeats), and
-reconnection with backoff all behave as they do over SSE, because they
-are the same machinery above the wire seam.
+same ack and `confirmed`, and presence coalesces on the same cadence.
+The connection status, stall watchdog, and reconnection behavior are
+shared above the wire seam.
 
 ## Lifecycle
 
-A socket closes when the platform ends the function invocation, or
-when the server closes it deliberately ahead of a known deadline. The
-client treats every close the same way it treats a dropped SSE stream:
-reconnect with backoff, re-subscribe every session at its own frontier,
-receive fresh presence snapshots, re-send its own presence fields set
-since the disconnect. A push whose socket died before the ack rejects as
-retryable: nothing was acknowledged, and if the append had already
-committed, the client-generated event ids make the retry an idempotent
-replay (you get the original events back). Push retries wait for the
-restored socket rather than a fixed clock, capped by the reconnect
-backoff, so a push caught in a routine blip resolves the way it would
-have over HTTP, where pushes never depended on the stream.
-
-On Vercel, WebSocket connections pin to one function instance and new
-connections may land anywhere. A2 never relies on instance affinity:
-the log is the shared state, so two clients on two instances converge
-through it, exactly as they do over HTTP.
-
-## Choosing
-
-SSE plus POST is the right default: simplest route, ordinary HTTP
-semantics, and one auth surface. Reach for `ws` when the send rate
-makes per-request overhead visible (live cursors, drag ghosts) or when
-round-trip latency is the product. Reach for the `http` split only when
-per-route duration configuration forces it. The protocol underneath is
-the same in every case: the log replays, presence repaints, and the
-wire is an implementation detail.
+When a socket closes, the client reconnects with backoff, re-subscribes
+every session at its own frontier, receives fresh presence snapshots,
+and re-sends its own latest presence values. Event pushes keep their
+client-generated ids, so retry remains idempotent.
+
+SSE and WebSocket are transport choices, not different consistency
+models. Both resume from the durable event frontier and treat presence
+as ephemeral repaintable state.