experimental-a2 0.4.0 → 0.5.1

package/docs/guides/03-react.mdx

@@ -23,52 +23,57 @@ reducer, and the provider + hook it returns.
 
 ## The API route
 
-One file exposes a session over HTTP: `GET` streams events, `POST` appends.
-These are ordinary route handlers; put whatever checks you like in front.
+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.
 
 ```ts app/api/order-events/route.ts
-import { A2Error } from 'experimental-a2'
+import { handle } from 'experimental-a2/http'
 import { ordersServer } from '@/server/orders'
-import { errorResponse, parsePushBody, sseResponse } from 'experimental-a2/http'
 
-export async function GET(req: Request) {
-  const { searchParams } = new URL(req.url)
-  const sessionId = searchParams.get('sessionId')
-  if (!sessionId) {
-    return errorResponse(new A2Error('INVALID_PAYLOAD', 'missing sessionId'))
-  }
-  const startAfter = Number(searchParams.get('index')) || 0
-
-  // here's where you'd do auth, or any other checks
-
-  return sseResponse(ordersServer.session(sessionId).stream({ startAfter }))
-}
-
-export async function POST(req: Request) {
-  try {
-    const { sessionId, events } = await parsePushBody(req)
-
-    // here's where you'd do auth, or any other checks
-
-    const result = await ordersServer.session(sessionId).append(...events)
-    return Response.json(result)
-  } catch (err) {
-    return errorResponse(err)
-  }
-}
+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 })
+  },
+})
 ```
 
-`GET` is the read path. `stream({ startAfter })` is a live `AsyncIterable` of
-one session's events starting after a given position, and `sseResponse`
-pipes it into a server-sent events response. Clients pass `index` to resume
-exactly where they left off, after a first paint or a dropped
-connection.
+`GET` is the read path. A plain `GET` is the live stream: a server-sent
+events response of one session's events, resumed after the `index` query
+parameter, so clients pick up exactly where they left off after a first
+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
+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.
+
+```ts
+// app/api/order-events/route.ts, now with response decoration:
+import { handle } from 'experimental-a2/http'
+import { ordersServer } from '@/server/orders'
 
-`POST` is the write path. `parsePushBody` validates the envelope (and
-throws `INVALID_PAYLOAD` on garbage), then `append` does the rest. The
-response is the appended events: an ack, not a stream. `errorResponse`
-serializes any thrown [`A2Error`](/reference/errors#over-the-wire) so the
-client can branch on the same codes.
+export const { GET, POST } = handle(ordersServer, {
+  after({ outcome, response }) {
+    if (outcome.type === 'history' && outcome.covered) {
+      response.headers.set('cache-control', 'private, max-age=31536000')
+    }
+  },
+})
+```
 
 ## The session module
 
@@ -174,6 +179,21 @@ What the hook gives you:
   seeded with. With only the server snapshot, it begins after `initialIndex`.
   Use it for UI that wants the log itself: an activity feed, a debug panel.
   Earlier events are not needed to hydrate `state`.
+- **`loadHistory`**: backscroll. `loadHistory({ before?, limit? })`
+  fetches a bounded slice of the log from below the frontier (the same
+  route, `gte`/`lte` query parameters) and merges it into `events`:
+  deduped, ordered, shared across every handle of the session. By
+  default each call walks backward 50 events at a time from the oldest
+  one loaded. After a hydrate jump (returning to a session whose
+  frontier advanced while away), default paging still continues from
+  the oldest loaded event; pass an explicit `before` to fill the gap
+  between the old feed and the new frontier. It never touches `state` or the optimistic overlay;
+  backscrolled events are display data. Calls serialize per session, so
+  a double-tap never fetches the same range twice. The `ws` api has no
+  history lane; `loadHistory` throws a `TypeError` there.
+- **`history`**: backscroll progress, `{ loading, complete,
+  oldestLoaded }`. `complete` means the feed reaches index 1 (or the
+  log is empty): nothing older is left, hide the "load older" button.
 - **`index`**: the stream frontier, the last server-confirmed log
   position. This is the `lastSeenIndex` that makes
   [cancellation](/guides/cancellation) exact.

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

@@ -129,36 +129,14 @@ 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 { A2Error } from 'experimental-a2'
-import { errorResponse, parsePushBody, sseResponse } from 'experimental-a2/http'
+import { handle } from 'experimental-a2/http'
 import { assistantServer } from '@/server/assistant'
 
-export async function GET(req: Request): Promise<Response> {
-  const { searchParams } = new URL(req.url)
-  const sessionId = searchParams.get('sessionId')
-  const startAfter = Number(searchParams.get('index')) || 0
-
-  if (!sessionId) {
-    return errorResponse(new A2Error('INVALID_PAYLOAD', 'missing sessionId'))
-  }
-
-  // here's where you'd do auth, or any other checks
-
-  return sseResponse(assistantServer.session(sessionId).stream({ startAfter }))
-}
-
-export async function POST(req: Request): Promise<Response> {
-  try {
-    const { sessionId, events } = await parsePushBody(req)
-
+export const { GET, POST } = handle(assistantServer, {
+  before({ request, intent }) {
     // here's where you'd do auth, or any other checks
-
-    const appended = await assistantServer.session(sessionId).append(...events)
-    return Response.json(appended)
-  } catch (error) {
-    return errorResponse(error)
-  }
-}
+  },
+})
 ```
 
 The route never calls the model directly. The browser appends user facts such

package/docs/guides/09-presence.mdx

@@ -63,55 +63,34 @@ explicit leave required).
 
 ## The route
 
-The same two handlers as [Live UI](/guides/react), with one option and
-one branch. `stream({ presence: true })` interleaves presence patches
-with events on the SSE response, starting with a snapshot of the current
-map. The push body grows an optional `presence` sibling to `events`.
+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`.
 
 ```ts app/api/canvas-events/route.ts
-import { A2Error } from 'experimental-a2'
-import { errorResponse, parsePushBody, sseResponse } from 'experimental-a2/http'
+import { handle } from 'experimental-a2/http'
 import { canvasServer } from '@/server/canvas'
 
-export async function GET(req: Request) {
-  const { searchParams } = new URL(req.url)
-  const sessionId = searchParams.get('sessionId')
-  if (!sessionId) {
-    return errorResponse(new A2Error('INVALID_PAYLOAD', 'missing sessionId'))
-  }
-  const startAfter = Number(searchParams.get('index')) || 0
-
-  // here's where you'd do auth, or any other checks
-
-  return sseResponse(
-    canvasServer.session(sessionId).stream({ startAfter, presence: true }),
-  )
-}
-
-export async function POST(req: Request) {
-  try {
-    const { sessionId, events, presence } = await parsePushBody(req)
-    const session = canvasServer.session(sessionId)
-
-    // here's where you'd do auth, or any other checks; the participant
-    // id is caller-supplied, so authorize it like you authorize events.
-    // createServer's validatePush is the same seam: on the presence
-    // plane it receives { sessionId, events: [], presence }, the whole
-    // patch, participant included
-
-    if (presence) await session.setPresence(presence)
-    if (events.length === 0) return Response.json([])
-    return Response.json(await session.append(...events))
-  } catch (err) {
-    return errorResponse(err)
-  }
-}
+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 }.
+  },
+})
 ```
 
 `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
-`UNKNOWN_PRESENCE_FIELD`; nothing is broadcast on either.
+`UNKNOWN_PRESENCE_FIELD`; nothing is broadcast on either. A
+presence-only push acks `[]`.
 
 ## The browser
 

package/docs/guides/10-transports.mdx

@@ -24,58 +24,67 @@ api: { type: 'ws', url: '/api/order-events' }
   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: the stream comes down
-  it, pushes and presence go up it. 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.
+- **`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.
 
 A split socket is unrepresentable on purpose. The socket is one
 connection in both directions; there is nothing left to split.
 
+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`.
+
 ## The WebSocket route
 
-The same route can serve both transports by branching on the upgrade
-header. Auth runs before the upgrade, while the request is still a
-request.
+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.
 
 ```ts app/api/order-events/route.ts
 import { experimental_upgradeWebSocket } from '@vercel/functions'
-import { A2Error } from 'experimental-a2'
-import { errorResponse, sessionSocket, sseResponse } from 'experimental-a2/http'
+import { handle } from 'experimental-a2/http'
 import { ordersServer } from '@/server/orders'
 
-export async function GET(req: Request) {
-  const { searchParams } = new URL(req.url)
-  const sessionId = searchParams.get('sessionId')
-  if (!sessionId) {
-    return errorResponse(new A2Error('INVALID_PAYLOAD', 'missing sessionId'))
-  }
-  const startAfter = Number(searchParams.get('index')) || 0
-
-  // here's where you'd do auth, or any other checks
-
-  if (req.headers.get('upgrade')?.toLowerCase() === 'websocket') {
-    return experimental_upgradeWebSocket(
-      (ws) => sessionSocket(ordersServer.session(sessionId), ws, { startAfter }),
+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 },
-    )
-  }
-  return sseResponse(ordersServer.session(sessionId).stream({ startAfter }))
-}
+      maxPayload: 4 * 1024 * 1024,
+    }),
+})
 ```
 
-`sessionSocket` speaks the whole protocol against any `ws`-shaped
-socket: it pumps the session's stream down as JSON frames, accepts push
-and presence frames up, validates them exactly as `parsePushBody` does
-(same provenance brand, same `validatePush` calls, once per plane), and
-answers each push with its ack. POST keeps working unchanged next to
-it; a `ws` client never calls it, an `http` client never upgrades. The
-transports are additive.
-
-Contracts that declare presence pass `{ presence: true }` in the
-options, the same opt-in as `stream()`.
+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 client
 
@@ -105,9 +114,9 @@ are the same machinery above the wire seam.
 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, resume from the current frontier, receive a
-fresh presence snapshot, re-send its own presence fields set since the
-disconnect. A push whose socket died before the ack rejects as
+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

package/docs/reference/01-api.mdx

@@ -123,8 +123,8 @@ 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 came from `parsePushBody()`,
-once per plane. The events plane invokes it with `{ sessionId, events }` before
+`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
@@ -132,7 +132,7 @@ 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
+`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.
 
@@ -428,8 +428,8 @@ The only way to move a session forward. Payloads are validated against
 the contract's schemas before anything is written. A multi-event append
 is atomic: all-or-nothing, consecutive positions, one transaction. Pass
 `id` to make an append idempotent across retries; re-sending an
-identical batch returns the original rows. (Events parsed by
-`parsePushBody` are accepted directly, the push-route path.) See
+identical batch returns the original rows. (Events that arrived through
+`handle`'s push lane are accepted directly.) See
 [Durability](/concepts/durability).
 
 After the write, A2 dispatches only event types with registered handlers.
@@ -537,14 +537,14 @@ 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; expose it over SSE with `sseResponse`. Subscribing never
-dispatches handlers.
+Server-side only; `handle` 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:
 `{ 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
+events. The stream response sends both as named SSE frames, so clients
+that don't know them skip them. The return type widens only under the
 literal `presence: true`; without it, existing consumers keep
 `AsyncIterable<Event>`. The option itself exists only on sessions of
 contracts that declare `presence`; elsewhere it is a type error, not a
@@ -580,9 +580,9 @@ by backend TTL when a participant goes silent (default 60 seconds; set
 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 patch is structurally the `presence` sibling of the push envelope;
+`handle`'s push lane forwards it whole to `session.setPresence(presence)`.
+The API mirrors the wire.
 
 The handler-scoped form `ctx.session.setPresence(...)` is the same
 operation; `seen` defaults to the triggering event's `index`.
@@ -666,16 +666,32 @@ not affect state hydration or stream resumption.
 ### `useSession()`
 
 ```ts
-const { state, push, events, index, connection, presence, setPresence } =
-  useSession()
+const { state, push, events, index, loadHistory, history, connection,
+  presence, setPresence } = useSession()
 ```
 
 `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
+shared reducer. `events` is the raw event feed: observed, explicitly
+seeded, or backscrolled. Unless `initialEvents` seeds earlier entries or
+`loadHistory` fetches them, it begins after `initialIndex`. `index` is
 the stream frontier, the `lastSeenIndex` for
 [cancellation](/guides/cancellation).
 
+`loadHistory({ before?, limit? })` backscrolls: it fetches a bounded
+slice of the log from below the frontier (the same route, `gte`/`lte`
+query parameters) and merges it into `events`, deduped, ordered, and
+shared across every handle of the session. It resolves with the events
+in the requested range. Defaults walk backward 50 at a time from the
+oldest loaded event; `before` is an exclusive upper bound. After a
+hydrate jump (returning to a session whose frontier advanced while
+away), default paging still continues from the oldest loaded event;
+pass an explicit `before` to fill the gap between the old feed and the
+new frontier. It never touches `state` or the optimistic overlay. Calls
+serialize per session and already-loaded ranges are not refetched.
+`history` is the progress: `{ loading, complete, oldestLoaded }`, where
+`complete` means the feed reaches index 1 (or the log is empty). The `ws` api has no history lane; there `loadHistory`
+throws a `TypeError`.
+
 `presence` is the replicated ephemeral map,
 `Record<participantId, { [field]: { value, seen, at } }>`, including
 this client. `setPresence(values)` is fire-and-forget: validated
@@ -1032,10 +1048,10 @@ subscription with frontier resume and reconnection, the optimistic push
 queue with ack/rollback, and the local fold. `client.session(id, {
 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
+contract), `push()`, `loadHistory()`, `connect()`, and `close()`.
+Snapshots carry `state`, `events`, `index`, `history`, and `connection`
+(the same fields `useSession` exposes), and `push` returns the same
+ack-then-`confirmed` result. On contracts that declare `presence` the handle also carries
 `setPresence()` and snapshots carry the `presence` map, exactly like
 the hook; `participant` is the identity `setPresence` sends under. Use
 it directly from any other framework, or none.
@@ -1051,13 +1067,77 @@ 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 |
-| `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     |
+| `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
@@ -1071,8 +1151,9 @@ 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).
+`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`
 

package/docs/reference/02-errors.mdx

@@ -78,5 +78,7 @@ with a mapped status: `INVALID_PAYLOAD`, `UNKNOWN_EVENT_TYPE`, and
 
 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 ships in `experimental-a2/http`, alongside
-`parsePushBody` and `sseResponse`.
+`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(...))`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-a2",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Durable sync and reactions for things with a lifecycle: one event log, derived state, and live client per session.",
   "license": "MIT",
   "type": "module",
@@ -23,6 +23,7 @@
   "files": [
     "dist",
     "docs",
+    "src",
     "CHANGELOG.md"
   ],
   "exports": {