experimental-a2 0.4.0 → 0.5.0

package/dist/{wire-DCUZBUlT.js → wire-BFQmSJ-9.js}

@@ -1,5 +1,5 @@
 import { t as A2Error } from "./errors-BQuJpe82.js";
-import { g as nullProtoRecord } from "./internal-aEotMzu_.js";
+import { g as nullProtoRecord } from "./internal-DstsI6Re.js";
 //#region src/wire.ts
 /**
 * The wire format shared by experimental-a2/http (server side) and experimental-a2/client
@@ -109,6 +109,13 @@ function errorToWire(error) {
 	if (error.details !== void 0) body.error.details = error.details;
 	return body;
 }
+/** Wrap an arbitrary thrown value for the wire: A2Errors pass through,
+* anything else becomes STORE_UNAVAILABLE — from the client's
+* perspective an unknown server failure is retryable-once, not a
+* protocol contract. */
+function asA2Error(error) {
+	return error instanceof A2Error ? error : new A2Error("STORE_UNAVAILABLE", "internal error", { cause: error });
+}
 /** Rebuild an A2Error from a wire body; null if the body isn't one. */
 function errorFromWire(body) {
 	if (body === null || typeof body !== "object") return null;
@@ -120,33 +127,55 @@ function errorFromWire(body) {
 }
 const SOCKET_PING_FRAME = JSON.stringify({ kind: "ping" });
 /** One stream item as a socket frame — `sseResponse`'s framing over
-* the same codecs, with `kind` instead of an SSE event name. */
-function socketFrameFor(item) {
+* the same codecs, with `kind` instead of an SSE event name. On a
+* multiplexed socket presence frames carry the `sessionId` tag; events
+* already carry theirs in the wire event. */
+function socketFrameFor(item, sessionId) {
+	const tag = sessionId === void 0 ? {} : { sessionId };
 	if ("snapshot" in item) return JSON.stringify({
 		kind: "presence-snapshot",
-		...presenceSnapshotToWire(item)
+		...presenceSnapshotToWire(item),
+		...tag
 	});
 	if ("participant" in item) return JSON.stringify({
 		kind: "presence",
-		...presencePatchToWire(item)
+		...presencePatchToWire(item),
+		...tag
 	});
 	return JSON.stringify({
 		kind: "event",
 		...eventToWire(item)
 	});
 }
-function socketAckFor(req, events) {
+function socketAckFor(req, events, sessionId) {
 	return JSON.stringify({
 		kind: "ack",
 		req,
-		events: events.map(eventToWire)
+		events: events.map(eventToWire),
+		...sessionId === void 0 ? {} : { sessionId }
 	});
 }
-function socketErrorAckFor(req, error) {
+function socketErrorAckFor(req, error, sessionId) {
 	return JSON.stringify({
 		kind: "ack",
 		req,
-		...errorToWire(error)
+		...errorToWire(error),
+		...sessionId === void 0 ? {} : { sessionId }
+	});
+}
+function socketSubscribedFor(sessionId) {
+	return JSON.stringify({
+		kind: "subscribed",
+		sessionId
+	});
+}
+/** The subscription-over notice: with a `reason` the server rejected
+* or lost the session's stream, without one it ended cleanly. */
+function socketUnsubscribedFor(sessionId, reason) {
+	return JSON.stringify({
+		kind: "unsubscribed",
+		sessionId,
+		...reason === void 0 ? {} : { reason }
 	});
 }
 function parseSocketFrame(data) {
@@ -185,38 +214,71 @@ function parseSocketFrame(data) {
 					values,
 					seen,
 					at
-				}
+				},
+				...sessionTag(frame)
 			};
 		}
 		case "presence-snapshot":
 			if (!isWirePresenceSnapshot(parsed)) return null;
 			return {
 				kind: "presence-snapshot",
-				snapshot: { snapshot: parsed.snapshot }
+				snapshot: { snapshot: parsed.snapshot },
+				...sessionTag(frame)
+			};
+		case "subscribed": {
+			const sessionId = frame["sessionId"];
+			if (typeof sessionId !== "string") return null;
+			return {
+				kind: "subscribed",
+				sessionId
 			};
+		}
+		case "unsubscribed": {
+			const sessionId = frame["sessionId"];
+			if (typeof sessionId !== "string") return null;
+			const reason = frame["reason"];
+			return typeof reason === "string" ? {
+				kind: "unsubscribed",
+				sessionId,
+				reason
+			} : {
+				kind: "unsubscribed",
+				sessionId
+			};
+		}
 		case "ack": {
 			const req = frame["req"];
 			if (typeof req !== "number") return null;
+			const tag = sessionTag(frame);
 			const events = frame["events"];
 			if (Array.isArray(events) && events.every(isWireEvent)) return {
 				kind: "ack",
 				req,
-				events
+				events,
+				...tag
 			};
 			const error = errorFromWire(parsed);
 			if (error) return {
 				kind: "ack",
 				req,
-				error
+				error,
+				...tag
 			};
 			return {
 				kind: "ack",
 				req,
-				error: new A2Error("STORE_UNAVAILABLE", "unintelligible ack")
+				error: new A2Error("STORE_UNAVAILABLE", "unintelligible ack"),
+				...tag
 			};
 		}
 		default: return null;
 	}
 }
+const sessionTag = (frame) => {
+	const sessionId = frame["sessionId"];
+	return typeof sessionId === "string" ? { sessionId } : {};
+};
 //#endregion
-export { socketFrameFor as _, eventFromWire as a, isWirePresencePatch as c, presencePatchFromWire as d, presencePatchToWire as f, socketErrorAckFor as g, socketAckFor as h, errorToWire as i, isWirePresenceSnapshot as l, presenceSnapshotToWire as m, errorFromWire as n, eventToWire as o, presenceSnapshotFromWire as p, errorStatus as r, isWireEvent as s, SOCKET_PING_FRAME as t, parseSocketFrame as u };
+export { socketErrorAckFor as _, errorToWire as a, socketUnsubscribedFor as b, isWireEvent as c, parseSocketFrame as d, presencePatchFromWire as f, socketAckFor as g, presenceSnapshotToWire as h, errorStatus as i, isWirePresencePatch as l, presenceSnapshotFromWire as m, asA2Error as n, eventFromWire as o, presencePatchToWire as p, errorFromWire as r, eventToWire as s, SOCKET_PING_FRAME as t, isWirePresenceSnapshot as u, socketFrameFor as v, socketSubscribedFor as y };
+
+//# sourceMappingURL=wire-BFQmSJ-9.js.map

package/dist/wire-BFQmSJ-9.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-BFQmSJ-9.js","names":[],"sources":["../src/wire.ts"],"sourcesContent":["/**\n * The wire format shared by experimental-a2/http (server side) and experimental-a2/client\n * (browser side): events as JSON with ISO timestamps, and the A2Error\n * envelope. Internal module — both entry points re-export what's\n * public.\n */\n\nimport { A2Error, type A2ErrorCode } from './errors.ts'\nimport { nullProtoRecord } from './internal.ts'\nimport type { Event } from './store.ts'\nimport type {\n  PresenceMap,\n  PresencePatch,\n  PresenceSnapshot,\n} from './contract.ts'\n\nexport type WireEvent = {\n  id: string\n  type: string\n  payload: unknown\n  index: number\n  sessionId: string\n  /** ISO 8601 — revived to a Date on the client so reducers see the\n   * same shape on both sides of the wire. */\n  createdAt: string\n}\n\nexport function eventToWire(event: Event): WireEvent {\n  return {\n    id: event.id,\n    type: event.type,\n    payload: event.payload,\n    index: event.index,\n    sessionId: event.sessionId,\n    createdAt: event.createdAt.toISOString(),\n  }\n}\n\nexport function eventFromWire(wire: WireEvent): Event {\n  return {\n    id: wire.id,\n    type: wire.type,\n    payload: wire.payload,\n    index: wire.index,\n    sessionId: wire.sessionId,\n    createdAt: new Date(wire.createdAt),\n  }\n}\n\nexport function isWireEvent(value: unknown): value is WireEvent {\n  if (value === null || typeof value !== 'object') return false\n  const v = value as Record<string, unknown>\n  return (\n    typeof v['id'] === 'string' &&\n    typeof v['type'] === 'string' &&\n    typeof v['index'] === 'number' &&\n    typeof v['sessionId'] === 'string' &&\n    typeof v['createdAt'] === 'string'\n  )\n}\n\n// ── the presence wire pair ───────────────────────────────────────────\n\n/** The `event: presence` SSE frame body: one patch as JSON. */\nexport type WirePresencePatch = {\n  participant: string\n  values: Record<string, unknown>\n  seen: number\n  /** ISO 8601 — revived to a Date on the client. */\n  at: string\n}\n\n/**\n * The `event: presence-snapshot` SSE frame body: the in-memory\n * `PresenceSnapshot` shape verbatim, with each per-field `at`\n * serialized to ISO 8601.\n */\nexport type WirePresenceSnapshot = {\n  snapshot: {\n    [participant: string]: {\n      [field: string]: { value: unknown; seen: number; at: string }\n    }\n  }\n}\n\nexport function presencePatchToWire(patch: PresencePatch): WirePresencePatch {\n  return {\n    participant: patch.participant,\n    values: patch.values,\n    seen: patch.seen,\n    at: patch.at.toISOString(),\n  }\n}\n\nexport function presencePatchFromWire(wire: WirePresencePatch): PresencePatch {\n  return {\n    participant: wire.participant,\n    values: wire.values,\n    seen: wire.seen,\n    at: new Date(wire.at),\n  }\n}\n\n// Participant and field keys come off the wire, so every object keyed\n// by them is built null-prototype — see `nullProtoRecord`.\nexport function presenceSnapshotToWire(\n  snapshot: PresenceSnapshot,\n): WirePresenceSnapshot {\n  const wire: WirePresenceSnapshot['snapshot'] = nullProtoRecord()\n  for (const [participant, fields] of Object.entries(snapshot.snapshot)) {\n    const wireFields: WirePresenceSnapshot['snapshot'][string] =\n      nullProtoRecord()\n    for (const [field, entry] of Object.entries(fields)) {\n      if (entry === undefined) continue\n      wireFields[field] = {\n        value: entry.value,\n        seen: entry.seen,\n        at: entry.at.toISOString(),\n      }\n    }\n    wire[participant] = wireFields\n  }\n  return { snapshot: wire }\n}\n\nexport function presenceSnapshotFromWire(\n  wire: WirePresenceSnapshot,\n): PresenceSnapshot {\n  const map: PresenceMap = nullProtoRecord()\n  for (const [participant, fields] of Object.entries(wire.snapshot)) {\n    const revived: PresenceMap[string] = nullProtoRecord()\n    for (const [field, entry] of Object.entries(fields)) {\n      revived[field] = {\n        value: entry.value,\n        seen: entry.seen,\n        at: new Date(entry.at),\n      }\n    }\n    map[participant] = revived\n  }\n  return { snapshot: map }\n}\n\nexport function isWirePresencePatch(\n  value: unknown,\n): value is WirePresencePatch {\n  if (value === null || typeof value !== 'object') return false\n  const v = value as Record<string, unknown>\n  return (\n    typeof v['participant'] === 'string' &&\n    v['values'] !== null &&\n    typeof v['values'] === 'object' &&\n    !Array.isArray(v['values']) &&\n    typeof v['seen'] === 'number' &&\n    typeof v['at'] === 'string'\n  )\n}\n\nexport function isWirePresenceSnapshot(\n  value: unknown,\n): value is WirePresenceSnapshot {\n  if (value === null || typeof value !== 'object') return false\n  const v = value as Record<string, unknown>\n  return (\n    v['snapshot'] !== null &&\n    typeof v['snapshot'] === 'object' &&\n    !Array.isArray(v['snapshot'])\n  )\n}\n\n// ── the A2Error envelope ─────────────────────────────────────────────\n\nexport type WireError = {\n  error: { code: A2ErrorCode; message: string; details?: unknown }\n}\n\nconst ERROR_STATUS: Record<A2ErrorCode, number> = {\n  INVALID_PAYLOAD: 400,\n  UNKNOWN_EVENT_TYPE: 400,\n  PARTIAL_DUPLICATE_BATCH: 400,\n  SUPERSEDED_ATTEMPT: 409,\n  CLAIM_EXPIRED: 409,\n  STORE_UNAVAILABLE: 503,\n  STORE_NOT_CONFIGURED: 500,\n  UNKNOWN_PRESENCE_FIELD: 400,\n  PRESENCE_NOT_SUPPORTED: 500,\n}\n\nexport function errorStatus(code: A2ErrorCode): number {\n  return ERROR_STATUS[code]\n}\n\nexport function errorToWire(error: A2Error): WireError {\n  const body: WireError = {\n    error: { code: error.code, message: error.message },\n  }\n  if (error.details !== undefined) body.error.details = error.details\n  return body\n}\n\n/** Wrap an arbitrary thrown value for the wire: A2Errors pass through,\n * anything else becomes STORE_UNAVAILABLE — from the client's\n * perspective an unknown server failure is retryable-once, not a\n * protocol contract. */\nexport function asA2Error(error: unknown): A2Error {\n  return error instanceof A2Error\n    ? error\n    : new A2Error('STORE_UNAVAILABLE', 'internal error', { cause: error })\n}\n\n/** Rebuild an A2Error from a wire body; null if the body isn't one. */\nexport function errorFromWire(body: unknown): A2Error | null {\n  if (body === null || typeof body !== 'object') return null\n  const err = (body as { error?: unknown }).error\n  if (err === null || typeof err !== 'object') return null\n  const { code, message, details } = err as Record<string, unknown>\n  if (typeof code !== 'string' || !Object.hasOwn(ERROR_STATUS, code))\n    return null\n  return new A2Error(code as A2ErrorCode, String(message ?? code), {\n    details,\n  })\n}\n\n// ── the ws frame layer ───────────────────────────────────────────────\n// The SSE lanes reframed for a socket (specs/a2-api.md §13): every\n// message is one JSON text frame, and a frame is its wire payload plus\n// a `kind` discriminant (plus `req` where a reply must correlate).\n// Unknown kinds are skipped by both sides — the same\n// forward-compatibility rule as named SSE frames.\n//\n// The multiplexed superset rides the same frames: `subscribe` /\n// `unsubscribe` up-frames open and close per-session lanes on one\n// socket, `sessionId` tags route everything else. Single-session\n// frames (no tags) keep parsing unchanged — a route opts into\n// multiplexing by choosing the multi-session server handler, never by\n// breaking the old protocol.\n\n/**\n * Server → client, parsed: a live-stream item, a push ack, a\n * subscription lifecycle notice, or the heartbeat. `parseSocketFrame`\n * yields these; frames of unknown kind (or ones failing their shape\n * guard) come back `null`. `sessionId` is present on frames from a\n * multiplexed socket and absent on a single-session one.\n */\nexport type SocketDownFrame =\n  | { kind: 'event'; event: WireEvent }\n  | { kind: 'presence'; patch: WirePresencePatch; sessionId?: string }\n  | {\n      kind: 'presence-snapshot'\n      snapshot: WirePresenceSnapshot\n      sessionId?: string\n    }\n  | { kind: 'ack'; req: number; events: WireEvent[]; sessionId?: string }\n  | { kind: 'ack'; req: number; error: A2Error; sessionId?: string }\n  | { kind: 'subscribed'; sessionId: string }\n  | { kind: 'unsubscribed'; sessionId: string; reason?: string }\n  | { kind: 'ping' }\n\n/**\n * Client → server: the push envelope's two planes. `sessionId` is\n * implied by the socket on a single-session connection and required by\n * the multiplexed handler. Plain JSON on the wire; the server parses\n * and validates them through the same seams as `parsePushBody`.\n */\nexport type SocketPushFrame = {\n  kind: 'push'\n  /** Client-local ack correlator — opaque to the server. */\n  req: number\n  events: Array<{ type: string; payload: unknown; id?: string }>\n  sessionId?: string\n}\n\nexport type SocketPresenceFrame = {\n  kind: 'presence'\n  participant: string\n  values: Record<string, unknown>\n  seen?: number\n  at?: number\n  sessionId?: string\n}\n\n/** Open per-session lanes on a multiplexed socket. `index` is each\n * session's exclusive resume frontier — `stream({ startAfter })`. */\nexport type SocketSubscribeFrame = {\n  kind: 'subscribe'\n  sessions: Array<{ id: string; index: number }>\n}\n\nexport type SocketUnsubscribeFrame = {\n  kind: 'unsubscribe'\n  sessions: string[]\n}\n\nexport type SocketUpFrame =\n  | SocketPushFrame\n  | SocketPresenceFrame\n  | SocketSubscribeFrame\n  | SocketUnsubscribeFrame\n\nexport const SOCKET_PING_FRAME: string = JSON.stringify({ kind: 'ping' })\n\n/** One stream item as a socket frame — `sseResponse`'s framing over\n * the same codecs, with `kind` instead of an SSE event name. On a\n * multiplexed socket presence frames carry the `sessionId` tag; events\n * already carry theirs in the wire event. */\nexport function socketFrameFor(\n  item: Event | PresencePatch | PresenceSnapshot,\n  sessionId?: string,\n): string {\n  const tag = sessionId === undefined ? {} : { sessionId }\n  if ('snapshot' in item) {\n    return JSON.stringify({\n      kind: 'presence-snapshot',\n      ...presenceSnapshotToWire(item),\n      ...tag,\n    })\n  }\n  if ('participant' in item) {\n    return JSON.stringify({\n      kind: 'presence',\n      ...presencePatchToWire(item),\n      ...tag,\n    })\n  }\n  return JSON.stringify({ kind: 'event', ...eventToWire(item) })\n}\n\nexport function socketAckFor(\n  req: number,\n  events: Event[],\n  sessionId?: string,\n): string {\n  return JSON.stringify({\n    kind: 'ack',\n    req,\n    events: events.map(eventToWire),\n    ...(sessionId === undefined ? {} : { sessionId }),\n  })\n}\n\nexport function socketErrorAckFor(\n  req: number,\n  error: A2Error,\n  sessionId?: string,\n): string {\n  return JSON.stringify({\n    kind: 'ack',\n    req,\n    ...errorToWire(error),\n    ...(sessionId === undefined ? {} : { sessionId }),\n  })\n}\n\nexport function socketSubscribedFor(sessionId: string): string {\n  return JSON.stringify({ kind: 'subscribed', sessionId })\n}\n\n/** The subscription-over notice: with a `reason` the server rejected\n * or lost the session's stream, without one it ended cleanly. */\nexport function socketUnsubscribedFor(\n  sessionId: string,\n  reason?: string,\n): string {\n  return JSON.stringify({\n    kind: 'unsubscribed',\n    sessionId,\n    ...(reason === undefined ? {} : { reason }),\n  })\n}\n\nexport function parseSocketFrame(data: string): SocketDownFrame | null {\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(data)\n  } catch {\n    return null\n  }\n  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {\n    return null\n  }\n  const frame = parsed as Record<string, unknown>\n  switch (frame['kind']) {\n    case 'ping':\n      return { kind: 'ping' }\n    case 'event': {\n      if (!isWireEvent(parsed)) return null\n      const { id, type, payload, index, sessionId, createdAt } = parsed\n      return {\n        kind: 'event',\n        event: { id, type, payload, index, sessionId, createdAt },\n      }\n    }\n    case 'presence': {\n      if (!isWirePresencePatch(parsed)) return null\n      const { participant, values, seen, at } = parsed\n      return {\n        kind: 'presence',\n        patch: { participant, values, seen, at },\n        ...sessionTag(frame),\n      }\n    }\n    case 'presence-snapshot': {\n      if (!isWirePresenceSnapshot(parsed)) return null\n      return {\n        kind: 'presence-snapshot',\n        snapshot: { snapshot: parsed.snapshot },\n        ...sessionTag(frame),\n      }\n    }\n    case 'subscribed': {\n      const sessionId = frame['sessionId']\n      if (typeof sessionId !== 'string') return null\n      return { kind: 'subscribed', sessionId }\n    }\n    case 'unsubscribed': {\n      const sessionId = frame['sessionId']\n      if (typeof sessionId !== 'string') return null\n      const reason = frame['reason']\n      return typeof reason === 'string'\n        ? { kind: 'unsubscribed', sessionId, reason }\n        : { kind: 'unsubscribed', sessionId }\n    }\n    case 'ack': {\n      const req = frame['req']\n      if (typeof req !== 'number') return null\n      const tag = sessionTag(frame)\n      const events = frame['events']\n      if (Array.isArray(events) && events.every(isWireEvent)) {\n        return { kind: 'ack', req, events, ...tag }\n      }\n      const error = errorFromWire(parsed)\n      if (error) return { kind: 'ack', req, error, ...tag }\n      // A correlatable ack must never be dropped: its waiter would hang\n      // forever behind a healthy socket (pings keep the watchdog fed).\n      // An outcome this client cannot interpret — an error code from a\n      // newer server, an event shape that fails a guard — degrades to\n      // a lost ack: retryable, and the client-generated ids make the\n      // retry idempotent even if the append actually committed.\n      return {\n        kind: 'ack',\n        req,\n        error: new A2Error('STORE_UNAVAILABLE', 'unintelligible ack'),\n        ...tag,\n      }\n    }\n    default:\n      return null\n  }\n}\n\nconst sessionTag = (frame: Record<string, unknown>): { sessionId?: string } => {\n  const sessionId = frame['sessionId']\n  return typeof sessionId === 'string' ? { sessionId } : {}\n}\n"],"mappings":"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"}

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