experimental-a2 0.3.0 → 0.5.0

package/src/client.ts

@@ -0,0 +1,1826 @@
+/**
+ * experimental-a2/client — the framework-agnostic session client.
+ *
+ * Everything the browser needs to read a session live and push
+ * optimistically, with no framework attached: the SSE subscription with
+ * frontier resume and reconnection, the optimistic push queue with
+ * ack/rollback, and the local fold through the same reducer the server
+ * uses. `experimental-a2/react`'s `createReact` is a thin binding over it, and the
+ * store contract (`subscribe`/`getSnapshot`) is exactly what
+ * `useSyncExternalStore` wants.
+ *
+ * The client is a replica, never an access path — the routes it talks
+ * to authorize every read and write.
+ */
+
+// oxlint-disable no-await-in-loop -- retry/backoff/stream loops are sequential by nature
+import { A2Error } from './errors.ts'
+import {
+  PRESENCE_TIMINGS,
+  STREAM_TIMINGS,
+  nullProtoRecord,
+} from './internal.ts'
+import type {
+  AppendInput,
+  ContractEvent,
+  EventDefs,
+  PresenceDefs,
+  PresenceMap,
+  PresencePatch,
+  WithPresence,
+} from './contract.ts'
+import type { Reducer } from './reducer.ts'
+import { validateSync } from './validate.ts'
+import {
+  errorFromWire,
+  eventFromWire,
+  isWireEvent,
+  isWirePresencePatch,
+  isWirePresenceSnapshot,
+  parseSocketFrame,
+  presencePatchFromWire,
+  presenceSnapshotFromWire,
+  type SocketDownFrame,
+  type SocketPresenceFrame,
+  type SocketPushFrame,
+  type SocketSubscribeFrame,
+  type SocketUnsubscribeFrame,
+  type WireEvent,
+  type WirePresencePatch,
+  type WirePresenceSnapshot,
+} from './wire.ts'
+
+export type ConnectionStatus = 'idle' | 'connecting' | 'live' | 'closed'
+
+/**
+ * The connection, as a discriminated union — impossible states are
+ * unrepresentable: an error only exists while disconnected,
+ * `reconnects` only once a connection has been attempted.
+ * "Reconnecting…" is `status === 'connecting' && reconnects > 0`.
+ */
+export type Connection =
+  | { status: 'idle' }
+  | {
+      status: 'connecting'
+      /** Drops of an established stream so far. `0` = first connect. */
+      reconnects: number
+      /** Why the last connection ended; `null` on the first connect. */
+      error: Error | null
+    }
+  | { status: 'live'; reconnects: number }
+  | { status: 'closed' }
+
+/**
+ * What `push` returns: resolves at the server ack (exactly like a
+ * plain promise — `await push(...)` gives the acked events), and
+ * carries `confirmed` for the later moment when the live stream has
+ * delivered the whole batch back and the optimistic overlay entry
+ * retired — the view now shows server truth. `confirmed` is lazy:
+ * never accessed, never created. A rejected push rejects both.
+ */
+export type PushResult<D extends EventDefs> = Promise<ContractEvent<D>[]> & {
+  readonly confirmed: Promise<ContractEvent<D>[]>
+}
+
+export type LoadHistoryOptions = {
+  /**
+   * Exclusive upper bound for the fetch. Defaults to the oldest
+   * already-loaded index — successive calls page backward — or one
+   * past the hydration frontier while nothing is loaded yet.
+   */
+  before?: number
+  /** Page size; defaults to 50. */
+  limit?: number
+}
+
+/** Backscroll progress, derived from the raw event feed. */
+export type HistoryState = {
+  /** A `loadHistory` fetch is in flight. */
+  loading: boolean
+  /** The feed reaches index 1 — nothing older remains to fetch. */
+  complete: boolean
+  /** The oldest loaded index; `null` while nothing is loaded. */
+  oldestLoaded: number | null
+}
+
+/** One immutable view of the session — stable identity between changes. */
+export type SessionSnapshot<
+  D extends EventDefs,
+  S,
+  P extends PresenceDefs = Record<never, never>,
+> = WithPresence<
+  P,
+  {
+    /** The replicated presence map, this client included (local echo). */
+    presence: PresenceMap<P>
+  }
+> & {
+  /** The live view: server events folded, optimistic pushes applied. */
+  state: S
+  /** The raw event feed: server truth — observed, seeded, or
+   * backscrolled via `loadHistory` — plus pending optimistic events
+   * (provisional indexes past the frontier). `state` never folds
+   * backscrolled events; they are display data below the frontier. */
+  events: ContractEvent<D>[]
+  /** The stream frontier: the last server-confirmed index. This is the
+   * `lastSeenIndex` cancellation wants. */
+  index: number
+  /** Backscroll progress — `loadHistory` moves it. */
+  history: HistoryState
+  connection: Connection
+}
+
+/**
+ * The presence member of a client session — intersected in via
+ * `WithPresence`, so it exists exactly when the contract declares
+ * presence fields.
+ */
+export type SessionClientPresence<P extends PresenceDefs> = {
+  /**
+   * Fire-and-forget presence: validates locally against the reducer's
+   * presence schemas, merges into the local map immediately (the
+   * echo), and coalesces on the wire to a fixed cadence — a leading
+   * send immediately, then at most one merged send per interval,
+   * later values winning field-wise. `null` clears a field. No ack,
+   * no retry, no rollback: a lost patch is repainted by the next one.
+   * Requires the session's `participant`.
+   */
+  setPresence(values: PresencePatch<P>['values']): void
+}
+
+export type SessionClient<
+  D extends EventDefs,
+  S,
+  P extends PresenceDefs = Record<never, never>,
+> = WithPresence<P, SessionClientPresence<P>> & {
+  readonly sessionId: string
+  subscribe(listener: () => void): () => void
+  getSnapshot(): SessionSnapshot<D, S, P>
+  /**
+   * Optimistic append: validates locally against the reducer's event
+   * schemas (instant `INVALID_PAYLOAD`, no flicker), applies to the
+   * local fold, POSTs, swaps in the ack, rolls back on rejection.
+   * Auto-retries only `STORE_UNAVAILABLE`. Resolves with the appended
+   * events as the server recorded them. Overlapping calls on this
+   * handle enter the transport in invocation order without delaying
+   * their optimistic folds.
+   */
+  push(...events: AppendInput<D>[]): PushResult<D>
+  /**
+   * Backscroll: fetch a bounded slice of events from below the
+   * frontier and merge it into `events` — deduped, ordered, shared by
+   * every handle of this session. Folded state and the optimistic
+   * overlay are never touched. Calls serialize per session and skip
+   * already-loaded ranges, so overlapping backscrolls never fetch the
+   * same range twice. Resolves with the events in the requested range.
+   * Requires an http api; the `ws` transport has no history lane and
+   * this throws a TypeError there.
+   */
+  loadHistory(options?: LoadHistoryOptions): Promise<ContractEvent<D>[]>
+  /** Open the live stream (idempotent while open). Reconnects with
+   * backoff and resumes from the frontier until `close()`. */
+  connect(): void
+  /**
+   * Stop the live stream. Not terminal: `connect()` starts it again
+   * from the current frontier — which is what makes the React
+   * StrictMode mount dance (setup → cleanup → setup) work.
+   */
+  close(): void
+}
+
+export type SessionOptions<D extends EventDefs, S> = {
+  initialState?: S
+  initialIndex?: number
+  /** Server-rendered history through `initialIndex`. Seeds the event feed. */
+  initialEvents?: ContractEvent<D>[]
+  /**
+   * This client's presence identity — required to call `setPresence`.
+   * Caller-supplied (a user id, a tab nonce, a guest name): A2 does
+   * not invent an identity story. Bound once per session handle.
+   */
+  participant?: string
+}
+
+export type A2Client<
+  D extends EventDefs,
+  S,
+  P extends PresenceDefs = Record<never, never>,
+> = {
+  session(
+    sessionId: string,
+    options?: SessionOptions<D, S>,
+  ): SessionClient<D, S, P>
+}
+
+/**
+ * The wire the client rides. The string form is one route serving GET
+ * (SSE stream) + POST (push). `http` splits the verbs across two
+ * routes, for when platform duration limits differ per verb. `ws`
+ * rides everything — every session of this client — over one
+ * multiplexed WebSocket, served by `sessionsSocket`.
+ */
+export type ClientApi =
+  | string // one route: GET SSE stream + POST push
+  | { type: 'http'; push: string; stream: string } // split routes
+  | { type: 'ws'; url: string } // one socket, all sessions, both directions
+
+/**
+ * The socket surface the `ws` transport drives — satisfied structurally
+ * by the DOM `WebSocket` and Node's alike, and small enough to fake in
+ * tests.
+ */
+export type ClientWebSocket = {
+  readonly readyState: number
+  send(data: string): void
+  close(code?: number, reason?: string): void
+  addEventListener(type: 'open', listener: () => void): void
+  addEventListener(
+    type: 'message',
+    listener: (event: { data: unknown }) => void,
+  ): void
+  addEventListener(
+    type: 'close',
+    listener: (event: { code: number; reason: string }) => void,
+  ): void
+  addEventListener(type: 'error', listener: () => void): void
+}
+
+export type ClientWebSocketConstructor = new (url: string) => ClientWebSocket
+
+export type CreateClientOptions<
+  D extends EventDefs,
+  S,
+  P extends PresenceDefs = Record<never, never>,
+> = {
+  reducer: Reducer<D, S, P>
+  /** The route (or routes) the client speaks — see `ClientApi`. */
+  api: ClientApi
+  /** Injectable fetch — defaults to the global. */
+  fetch?: typeof globalThis.fetch
+  /** Injectable WebSocket constructor for the `ws` api — defaults to
+   * the global. The http transports never touch it. */
+  webSocket?: ClientWebSocketConstructor
+  /** How long an idle session keeps its in-memory identity, in
+   * milliseconds. Defaults to five minutes; `Infinity` disables GC. */
+  gcTime?: number
+}
+
+const PUSH_ATTEMPTS = 3
+const DEFAULT_GC_TIME_MS = 5 * 60 * 1_000
+const DEFAULT_HISTORY_LIMIT = 50
+
+// ── the transport seam ───────────────────────────────────────────────
+// Everything above it — optimistic queue, retry loop, presence
+// throttle, reconnect/backoff, stall watchdog — is transport-agnostic.
+
+/** The parsed frame lanes every transport yields: the SSE frame
+ * discrimination today, the ws `kind` discriminant tomorrow. `ping`
+ * carries no data — it exists so the watchdog sees liveness. */
+type TransportFrame =
+  | { kind: 'event'; event: WireEvent }
+  | { kind: 'presence'; patch: WirePresencePatch }
+  | { kind: 'presence-snapshot'; snapshot: WirePresenceSnapshot }
+  | { kind: 'ping' }
+
+type TransportPushBody = {
+  sessionId: string
+  events: Array<{ id: string; type: string; payload: unknown }>
+}
+
+type TransportPresenceEnvelope = {
+  sessionId: string
+  presence: {
+    participant: string
+    values: Record<string, unknown>
+    seen: number
+    at: number
+  }
+}
+
+type Transport = {
+  /**
+   * One live read: the first frame means the stream is established
+   * (any kind — a bare `ping` when no data is pending), the iterable
+   * ending or throwing is the disconnect. The caller owns
+   * reconnect/backoff and counts every frame as liveness.
+   */
+  connect(opts: {
+    sessionId: string
+    startAfter: number
+    signal: AbortSignal
+  }): AsyncIterable<TransportFrame>
+  /** One attempt (the retry loop lives above the seam): resolves with
+   * the acked wire events, throws the wire-deserialized A2Error. */
+  push(body: TransportPushBody): Promise<WireEvent[]>
+  /** One bounded cold read of the log, oldest first — the lane
+   * `loadHistory` rides. Absent on transports without a
+   * request/response wire (ws), where `loadHistory` fails fast. */
+  history?(opts: {
+    sessionId: string
+    gte: number
+    lte: number
+  }): Promise<WireEvent[]>
+  /** Fire-and-forget; failures are dropped (presence repaints). */
+  sendPresence(envelope: TransportPresenceEnvelope): void
+  /**
+   * Resolve when the session's wire can carry a push again, or after
+   * `maxWaitMs` — whichever comes first; never rejects. Transports
+   * whose pushes are connection-bound (ws) implement it so the retry
+   * loop waits for the wire instead of a fixed clock; HTTP pushes are
+   * stream-independent and omit it.
+   */
+  awaitReady?(sessionId: string, maxWaitMs: number): Promise<void>
+}
+
+const httpTransport = (
+  routes: { push: string; stream: string },
+  fetchImpl: typeof globalThis.fetch,
+  // Contracts that declare no presence skip presence frames unparsed,
+  // exactly like unknown named frames.
+  presence: boolean,
+): Transport => ({
+  async *connect({ sessionId, startAfter, signal }) {
+    const sep = routes.stream.includes('?') ? '&' : '?'
+    const res = await fetchImpl(
+      `${routes.stream}${sep}sessionId=${encodeURIComponent(sessionId)}&index=${startAfter}`,
+      { headers: { accept: 'text/event-stream' }, signal },
+    )
+    if (!res.ok || !res.body) {
+      throw new Error(`stream failed with ${res.status}`)
+    }
+    yield { kind: 'ping' } // connected — headers in hand, before any bytes
+    const decoder = new TextDecoder()
+    const reader = res.body.getReader()
+    let buffer = ''
+    try {
+      for (;;) {
+        // oxlint-disable-next-line no-await-in-loop -- stream read loop
+        const { done, value } = await reader.read()
+        if (done) return
+        // Any bytes count — heartbeat comments included. Liveness is
+        // about the connection, not about events.
+        yield { kind: 'ping' }
+        buffer += decoder.decode(value, { stream: true })
+        for (;;) {
+          const boundary = buffer.indexOf('\n\n')
+          if (boundary === -1) break
+          const frame = buffer.slice(0, boundary)
+          buffer = buffer.slice(boundary + 2)
+          let eventName: string | undefined
+          const dataLines: string[] = []
+          for (const line of frame.split('\n')) {
+            if (line.startsWith('data:')) {
+              dataLines.push(line.slice(5).trimStart())
+            } else if (line.startsWith('event:')) {
+              eventName = line.slice(6).trim()
+            }
+          }
+          const data = dataLines.join('\n')
+          if (!data) continue
+          if (eventName === undefined) {
+            const parsed: unknown = JSON.parse(data)
+            if (isWireEvent(parsed)) yield { kind: 'event', event: parsed }
+          } else if (presence && eventName === 'presence-snapshot') {
+            const parsed: unknown = JSON.parse(data)
+            if (isWirePresenceSnapshot(parsed)) {
+              yield { kind: 'presence-snapshot', snapshot: parsed }
+            }
+          } else if (presence && eventName === 'presence') {
+            const parsed: unknown = JSON.parse(data)
+            if (isWirePresencePatch(parsed)) {
+              yield { kind: 'presence', patch: parsed }
+            }
+          }
+          // Other named frames: skipped — old clients stay compatible
+          // with future lanes the same way.
+        }
+      }
+    } finally {
+      reader.cancel().catch(() => {})
+    }
+  },
+
+  async push(body) {
+    const res = await fetchImpl(routes.push, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    })
+    if (res.ok) {
+      const rows = (await res.json()) as unknown
+      if (!Array.isArray(rows) || !rows.every(isWireEvent)) {
+        throw new A2Error(
+          'STORE_UNAVAILABLE',
+          'push ack was not a list of events',
+        )
+      }
+      return rows
+    }
+    throw (
+      errorFromWire(await res.json().catch(() => null)) ??
+      new A2Error('STORE_UNAVAILABLE', `push failed with ${res.status}`)
+    )
+  },
+
+  async history({ sessionId, gte, lte }) {
+    const sep = routes.stream.includes('?') ? '&' : '?'
+    const res = await fetchImpl(
+      `${routes.stream}${sep}sessionId=${encodeURIComponent(sessionId)}&gte=${gte}&lte=${lte}`,
+      { headers: { accept: 'application/json' } },
+    )
+    if (!res.ok) {
+      throw (
+        errorFromWire(await res.json().catch(() => null)) ??
+        new A2Error('STORE_UNAVAILABLE', `history failed with ${res.status}`)
+      )
+    }
+    const rows = (await res.json()) as unknown
+    if (!Array.isArray(rows) || !rows.every(isWireEvent)) {
+      throw new A2Error(
+        'STORE_UNAVAILABLE',
+        'history response was not a list of events',
+      )
+    }
+    return rows
+  },
+
+  sendPresence(envelope) {
+    void (async () => {
+      try {
+        const res = await fetchImpl(routes.push, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify(envelope),
+        })
+        await res.arrayBuffer()
+      } catch {
+        // Dropped by design — nothing was ever true.
+      }
+    })()
+  },
+})
+
+/** `WebSocket.OPEN` — fixed by the spec, identical in every runtime. */
+const WS_OPEN = 1
+
+/** One session's lane on the shared ws socket — created per `connect`
+ * attempt, so `startAfter` is that attempt's resume frontier. */
+type WsChannel = {
+  sessionId: string
+  startAfter: number
+  queue: TransportFrame[]
+  /** The server confirmed the subscribe — pushes and presence ride. */
+  live: boolean
+  /** The server already dropped it — no unsubscribe frame owed. */
+  dropped: boolean
+  ended: boolean
+  failure: Error | null
+  wake: (() => void) | null
+}
+
+const wakeChannel = (channel: WsChannel): void => {
+  channel.wake?.()
+  channel.wake = null
+}
+
+const subscribeFrame = (
+  sessions: Array<{ id: string; index: number }>,
+): string => {
+  const frame: SocketSubscribeFrame = { kind: 'subscribe', sessions }
+  return JSON.stringify(frame)
+}
+
+const wsTransport = (
+  url: string,
+  webSocketImpl: ClientWebSocketConstructor | undefined,
+  presence: boolean,
+): Transport => {
+  type PendingAck = {
+    resolve: (events: WireEvent[]) => void
+    reject: (error: A2Error) => void
+  }
+  // ONE socket serves every session of this client (specs §13's
+  // multiplexed superset): channels subscribe on it at their own
+  // frontiers, down frames route back by sessionId, acks by req.
+  const channels = new Map<string, WsChannel>()
+  const pending = new Map<number, PendingAck>()
+  /** Push retries parked in `awaitReady`, flushed per session on its
+   * subscribe confirmation. */
+  const readyWaiters = new Map<string, Set<() => void>>()
+  let socket: ClientWebSocket | null = null
+  let socketOpen = false
+  let watchdog: ReturnType<typeof setTimeout> | undefined
+  let nextReq = 1
+
+  const flushReadyWaiters = (sessionId: string): void => {
+    const waiters = readyWaiters.get(sessionId)
+    if (!waiters) return
+    readyWaiters.delete(sessionId)
+    for (const waiter of waiters) waiter()
+  }
+
+  const socketUrl = (): string => {
+    let resolved: URL
+    if (/^(https?|wss?):\/\//i.test(url)) {
+      resolved = new URL(url)
+    } else {
+      // A relative url resolves against the page, exactly like fetch.
+      // Outside a browser (SSR, tests) there is nothing to resolve
+      // against — demand an absolute url there.
+      const base = (globalThis as { location?: { href: string } }).location
+        ?.href
+      if (base === undefined) {
+        throw new TypeError(
+          `cannot resolve the relative ws url '${url}' without a browser location — pass an absolute ws:// or wss:// url`,
+        )
+      }
+      resolved = new URL(url, base)
+    }
+    if (resolved.protocol === 'http:') resolved.protocol = 'ws:'
+    else if (resolved.protocol === 'https:') resolved.protocol = 'wss:'
+    return resolved.href
+  }
+
+  const trySend = (data: string): void => {
+    if (socket === null || !socketOpen) return
+    try {
+      socket.send(data)
+    } catch {
+      // Dropped — the socket is going down and its close event settles
+      // everything that depended on this frame.
+    }
+  }
+
+  const deliver = (channel: WsChannel, frame: TransportFrame): void => {
+    channel.queue.push(frame)
+    wakeChannel(channel)
+  }
+
+  const settleChannel = (channel: WsChannel, failure: Error | null): void => {
+    if (channel.ended) return
+    channel.ended = true
+    channel.failure = failure
+    wakeChannel(channel)
+  }
+
+  // Unhook the socket from the transport state and reject every
+  // outstanding ack — nothing was acked, and the client-generated ids
+  // make the retries idempotent (§13).
+  const releaseSocket = (): ClientWebSocket | null => {
+    const current = socket
+    socket = null
+    socketOpen = false
+    clearTimeout(watchdog)
+    watchdog = undefined
+    if (pending.size > 0) {
+      const rejection = new A2Error(
+        'STORE_UNAVAILABLE',
+        'socket closed with the ack outstanding',
+      )
+      for (const waiter of pending.values()) waiter.reject(rejection)
+      pending.clear()
+    }
+    return current
+  }
+
+  // Idempotent from every direction (close event, error event, stall):
+  // every channel ends — each session's reconnect loop re-subscribes at
+  // its own current frontier.
+  const failSocket = (failure: Error | null): void => {
+    const current = releaseSocket()
+    for (const channel of channels.values()) settleChannel(channel, failure)
+    try {
+      current?.close(1000)
+    } catch {
+      // Already closed — it is down either way.
+    }
+  }
+
+  const detach = (channel: WsChannel): void => {
+    if (channels.get(channel.sessionId) !== channel) return
+    channels.delete(channel.sessionId)
+    if (!channel.dropped) {
+      const frame: SocketUnsubscribeFrame = {
+        kind: 'unsubscribe',
+        sessions: [channel.sessionId],
+      }
+      trySend(JSON.stringify(frame))
+    }
+    if (channels.size === 0) {
+      // The last session left — the shared socket has no reason to live.
+      const current = releaseSocket()
+      try {
+        current?.close(1000)
+      } catch {
+        // Already closed — it is down either way.
+      }
+    }
+  }
+
+  // One heartbeat watchdog per socket: any frame is liveness, and
+  // silence past the stall timeout means the connection is dead in a
+  // way the socket won't report.
+  const armWatchdog = (created: ClientWebSocket): void => {
+    clearTimeout(watchdog)
+    watchdog = setTimeout(() => {
+      if (socket !== created) return
+      failSocket(
+        new Error(
+          `socket stalled: no data for ${STREAM_TIMINGS.stallTimeoutMs}ms`,
+        ),
+      )
+    }, STREAM_TIMINGS.stallTimeoutMs)
+    ;(watchdog as { unref?: () => void }).unref?.()
+  }
+
+  const route = (frame: SocketDownFrame): void => {
+    switch (frame.kind) {
+      case 'ping': {
+        // Global liveness — every live channel's stall watchdog feeds
+        // on it, the way each SSE stream feeds on its own heartbeat.
+        for (const channel of channels.values()) {
+          if (channel.live && !channel.ended) {
+            deliver(channel, { kind: 'ping' })
+          }
+        }
+        return
+      }
+      case 'subscribed': {
+        const channel = channels.get(frame.sessionId)
+        if (channel === undefined || channel.ended || channel.live) return
+        channel.live = true
+        deliver(channel, { kind: 'ping' }) // the connected signal
+        flushReadyWaiters(frame.sessionId)
+        return
+      }
+      case 'unsubscribed': {
+        const channel = channels.get(frame.sessionId)
+        if (channel === undefined) return
+        channel.dropped = true
+        settleChannel(
+          channel,
+          frame.reason === undefined ? null : new Error(frame.reason),
+        )
+        return
+      }
+      case 'ack': {
+        const waiter = pending.get(frame.req)
+        if (waiter === undefined) return
+        pending.delete(frame.req)
+        if ('events' in frame) waiter.resolve(frame.events)
+        else waiter.reject(frame.error)
+        return
+      }
+      case 'event': {
+        // Pre-confirmation frames are safe to drop: the subscription
+        // being confirmed replays from this channel's own frontier.
+        const channel = channels.get(frame.event.sessionId)
+        if (channel !== undefined && channel.live && !channel.ended) {
+          deliver(channel, { kind: 'event', event: frame.event })
+        }
+        return
+      }
+      case 'presence': {
+        // Contracts that declare no presence skip presence frames,
+        // exactly like the http transport.
+        if (!presence || frame.sessionId === undefined) return
+        const channel = channels.get(frame.sessionId)
+        if (channel !== undefined && channel.live && !channel.ended) {
+          deliver(channel, { kind: 'presence', patch: frame.patch })
+        }
+        return
+      }
+      case 'presence-snapshot': {
+        if (!presence || frame.sessionId === undefined) return
+        const channel = channels.get(frame.sessionId)
+        if (channel !== undefined && channel.live && !channel.ended) {
+          deliver(channel, {
+            kind: 'presence-snapshot',
+            snapshot: frame.snapshot,
+          })
+        }
+        return
+      }
+    }
+  }
+
+  const ensureSocket = (): void => {
+    if (socket !== null) return
+    if (webSocketImpl === undefined) {
+      throw new TypeError(
+        'no WebSocket implementation available — pass one via createClient({ webSocket }) where the global is missing',
+      )
+    }
+    const created = new webSocketImpl(socketUrl())
+    socket = created
+    socketOpen = false
+    armWatchdog(created)
+    created.addEventListener('open', () => {
+      if (socket !== created) return
+      socketOpen = true
+      armWatchdog(created)
+      const sessions = [...channels.values()]
+        .filter((channel) => !channel.ended)
+        .map((channel) => ({
+          id: channel.sessionId,
+          index: channel.startAfter,
+        }))
+      if (sessions.length > 0) trySend(subscribeFrame(sessions))
+    })
+    created.addEventListener('message', (event) => {
+      if (socket !== created) return
+      if (typeof event.data !== 'string') return
+      armWatchdog(created)
+      const frame = parseSocketFrame(event.data)
+      if (frame === null) return
+      route(frame)
+    })
+    created.addEventListener('close', (event) => {
+      if (socket !== created) return
+      failSocket(
+        event.code === 1000
+          ? null // deliberate server close — reconnect, but not an error
+          : new Error(
+              `socket closed (${event.code}${event.reason ? `: ${event.reason}` : ''})`,
+            ),
+      )
+    })
+    created.addEventListener('error', () => {
+      if (socket !== created) return
+      failSocket(new Error('socket error'))
+    })
+  }
+
+  return {
+    async *connect({ sessionId, startAfter, signal }) {
+      const channel: WsChannel = {
+        sessionId,
+        startAfter,
+        queue: [],
+        live: false,
+        dropped: false,
+        ended: false,
+        failure: null,
+        wake: null,
+      }
+      channels.set(sessionId, channel)
+      try {
+        ensureSocket()
+        if (socketOpen) {
+          trySend(subscribeFrame([{ id: sessionId, index: startAfter }]))
+        }
+      } catch (error) {
+        if (channels.get(sessionId) === channel) channels.delete(sessionId)
+        throw error
+      }
+
+      const onAbort = (): void => {
+        settleChannel(
+          channel,
+          signal.reason instanceof Error
+            ? signal.reason
+            : new Error('stream aborted'),
+        )
+        // Synchronously, not from the pump's finally: the watchdog and
+        // close() must not leave a dead subscription behind.
+        detach(channel)
+      }
+      if (signal.aborted) onAbort()
+      else signal.addEventListener('abort', onAbort, { once: true })
+
+      // An unconfirmed subscribe receives no frames at all (global
+      // pings only feed live channels), so a server that never answers
+      // — a single-session route, say — would hang this session
+      // silently. Fail it loudly instead; the reconnect loop retries.
+      const pendingSubscribe = setTimeout(() => {
+        if (channel.live) return
+        settleChannel(
+          channel,
+          new Error(
+            'subscribe not confirmed: is the ws route serving the multiplexed socket (handle with options.upgrade)?',
+          ),
+        )
+      }, STREAM_TIMINGS.stallTimeoutMs)
+      ;(pendingSubscribe as { unref?: () => void }).unref?.()
+
+      try {
+        for (;;) {
+          while (channel.queue.length > 0) yield channel.queue.shift()!
+          if (channel.ended) {
+            if (channel.failure) throw channel.failure
+            return
+          }
+          // oxlint-disable-next-line no-await-in-loop -- frame pump
+          await new Promise<void>((resolve) => {
+            channel.wake = resolve
+          })
+        }
+      } finally {
+        clearTimeout(pendingSubscribe)
+        signal.removeEventListener('abort', onAbort)
+        settleChannel(channel, null)
+        detach(channel)
+      }
+    },
+
+    async push(body) {
+      const channel = channels.get(body.sessionId)
+      const target = socket
+      if (
+        channel === undefined ||
+        !channel.live ||
+        channel.ended ||
+        target === null ||
+        !socketOpen ||
+        target.readyState !== WS_OPEN
+      ) {
+        // Retryable by contract: the reconnect loop restores the
+        // socket and the retry rides the same event ids.
+        throw new A2Error('STORE_UNAVAILABLE', 'no open socket for the session')
+      }
+      const req = nextReq
+      nextReq += 1
+      return await new Promise<WireEvent[]>((resolve, reject) => {
+        pending.set(req, { resolve, reject })
+        const frame: SocketPushFrame = {
+          kind: 'push',
+          req,
+          sessionId: body.sessionId,
+          events: body.events,
+        }
+        try {
+          target.send(JSON.stringify(frame))
+        } catch (cause) {
+          pending.delete(req)
+          reject(
+            new A2Error('STORE_UNAVAILABLE', 'socket send failed', { cause }),
+          )
+        }
+      })
+    },
+
+    awaitReady(sessionId, maxWaitMs) {
+      const channel = channels.get(sessionId)
+      if (
+        channel !== undefined &&
+        channel.live &&
+        !channel.ended &&
+        socketOpen
+      ) {
+        return Promise.resolve()
+      }
+      return new Promise((resolve) => {
+        let waiters = readyWaiters.get(sessionId)
+        if (!waiters) {
+          waiters = new Set()
+          readyWaiters.set(sessionId, waiters)
+        }
+        let settled = false
+        const done = (): void => {
+          if (settled) return
+          settled = true
+          clearTimeout(timer)
+          waiters.delete(done)
+          if (waiters.size === 0) readyWaiters.delete(sessionId)
+          // oxlint-disable-next-line promise/no-multiple-resolved -- `settled` guards the two callers (timer, open flush); the rule cannot see through the flag
+          resolve()
+        }
+        // The cap keeps a session nobody reconnects (write-only usage,
+        // an unreachable server) from parking a push forever — the
+        // attempt then fails fast and the loop moves on.
+        const timer = setTimeout(done, maxWaitMs)
+        ;(timer as { unref?: () => void }).unref?.()
+        waiters.add(done)
+      })
+    },
+    sendPresence(envelope) {
+      const channel = channels.get(envelope.sessionId)
+      if (channel === undefined || !channel.live || channel.ended) {
+        return // dropped by design — the reconnect re-send covers the gap
+      }
+      const frame: SocketPresenceFrame = {
+        kind: 'presence',
+        sessionId: envelope.sessionId,
+        ...envelope.presence,
+      }
+      trySend(JSON.stringify(frame))
+    },
+  }
+}
+
+const transportFor = (
+  api: ClientApi,
+  fetchImpl: typeof globalThis.fetch,
+  webSocketImpl: ClientWebSocketConstructor | undefined,
+  presence: boolean,
+): Transport => {
+  if (typeof api === 'string') {
+    return httpTransport({ push: api, stream: api }, fetchImpl, presence)
+  }
+  if (api.type === 'http') {
+    return httpTransport(
+      { push: api.push, stream: api.stream },
+      fetchImpl,
+      presence,
+    )
+  }
+  return wsTransport(api.url, webSocketImpl, presence)
+}
+
+type Pending<D extends EventDefs> = {
+  id: string
+  type: string
+  payload: unknown
+  createdAt: Date
+  /** Set once the POST ack returns; the entry leaves the overlay when
+   * the stream delivers its index. */
+  acked?: ContractEvent<D>
+}
+
+type SessionRuntime<
+  D extends EventDefs,
+  S,
+  P extends PresenceDefs,
+> = SessionClient<D, S, P> & {
+  hydrate(options?: SessionOptions<D, S>): void
+  canEvict(): boolean
+}
+
+type CachedSession<D extends EventDefs, S, P extends PresenceDefs> = {
+  runtime: SessionRuntime<D, S, P>
+  timer?: ReturnType<typeof setTimeout>
+}
+
+export function createClient<
+  D extends EventDefs,
+  S,
+  P extends PresenceDefs = Record<never, never>,
+>(options: CreateClientOptions<D, S, P>): A2Client<D, S, P> {
+  const { reducer, api } = options
+  const presenceDefs: Readonly<PresenceDefs> = reducer.presence
+  const declaresPresence = Object.keys(presenceDefs).length > 0
+  const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis)
+  const webSocketImpl =
+    options.webSocket ??
+    (globalThis as { WebSocket?: ClientWebSocketConstructor }).WebSocket
+  const transport = transportFor(
+    api,
+    fetchImpl,
+    webSocketImpl,
+    declaresPresence,
+  )
+  const gcTime = options.gcTime ?? DEFAULT_GC_TIME_MS
+  if (Number.isNaN(gcTime) || gcTime < 0) {
+    throw new RangeError('gcTime must be a non-negative number or Infinity')
+  }
+  const sessions = new Map<string, CachedSession<D, S, P>>()
+
+  const scheduleGc = (sessionId: string, delay = gcTime): void => {
+    const entry = sessions.get(sessionId)
+    if (!entry) return
+    clearTimeout(entry.timer)
+    if (gcTime === Infinity) return
+    entry.timer = setTimeout(() => {
+      const current = sessions.get(sessionId)
+      if (current !== entry) return
+      if (entry.runtime.canEvict()) {
+        sessions.delete(sessionId)
+        return
+      }
+      // `gcTime: 0` is useful for tests and explicit no-cache clients,
+      // but must not spin while a session is mounted or a push is in flight.
+      scheduleGc(sessionId, Math.max(gcTime, 1_000))
+    }, delay)
+    ;(entry.timer as { unref?: () => void }).unref?.()
+  }
+
+  const touch = (sessionId: string): void => {
+    scheduleGc(sessionId)
+  }
+
+  const makeSession = (
+    sessionId: string,
+    sessionOptions?: SessionOptions<D, S>,
+  ): SessionRuntime<D, S, P> => {
+    // ── server truth ─────────────────────────────────────────────
+    let frontier = sessionOptions?.initialIndex ?? 0
+    let foldedState: S =
+      sessionOptions?.initialState !== undefined
+        ? sessionOptions.initialState
+        : reducer.initialState
+    const serverEvents: ContractEvent<D>[] = (
+      sessionOptions?.initialEvents ?? []
+    )
+      .filter((event) => event.index <= frontier)
+      .toSorted((a, b) => a.index - b.index)
+
+    // ── optimistic overlay ───────────────────────────────────────
+    let pending: Pending<D>[] = []
+
+    // ── the presence plane ───────────────────────────────────────
+    // Never cached, never folded. Foreign entries replicate from the
+    // stream; the own entry is the local echo — server copies of self
+    // are ignored (the echo is at least as new, and comparing it to
+    // server stamps would put two clocks in one order).
+    let participant = sessionOptions?.participant
+    // Participant and field keys arrive off the wire, so the map and
+    // every entry are built null-prototype — see `nullProtoRecord`.
+    let presenceState: PresenceMap = nullProtoRecord()
+    let presenceLastSentAt = 0
+    /** The last LWW stamp issued — see `nextPresenceAt`. */
+    let presenceLastAt = 0
+    /** Values awaiting the trailing send — non-null exactly while
+     * `presenceTimer` is armed. */
+    let presenceBuffer: Record<string, unknown> | null = null
+    let presenceTimer: ReturnType<typeof setTimeout> | undefined
+    /** Own fields set while the stream was down — re-sent once on
+     * reconnect (their POSTs may have been lost with the network). */
+    let presenceResend: Record<string, unknown> | null = null
+
+    // ── store plumbing ───────────────────────────────────────────
+    const listeners = new Set<() => void>()
+    let snapshot: SessionSnapshot<D, S> | null = null
+    let status: ConnectionStatus = 'idle'
+    let reconnects = 0
+    let lastError: Error | null = null
+    let inFlightPushes = 0
+    let pushWireTail: Promise<void> = Promise.resolve()
+    let deferredHydration: SessionOptions<D, S> | undefined
+    let hydrationNotification: ReturnType<typeof setTimeout> | undefined
+
+    const emit = (): void => {
+      // copy: a listener may unsubscribe (or subscribe) mid-notify
+      // oxlint-disable-next-line no-useless-spread
+      for (const listener of [...listeners]) listener()
+    }
+
+    const notify = (): void => {
+      snapshot = null
+      emit()
+    }
+
+    const notifyHydrated = (): void => {
+      // `session(id, serverFold)` is also called while a destination
+      // provider renders. Its own snapshot must advance synchronously,
+      // but notifying an outgoing provider during that render would be a
+      // React setState-in-render violation.
+      snapshot = null
+      clearTimeout(hydrationNotification)
+      hydrationNotification = setTimeout(emit, 0)
+      ;(hydrationNotification as { unref?: () => void }).unref?.()
+    }
+
+    const mergeServerEvents = (
+      events: ContractEvent<D>[] | undefined,
+      throughIndex: number,
+    ): boolean => {
+      if (!events || events.length === 0) return false
+      const byIndex = new Map(serverEvents.map((event) => [event.index, event]))
+      let changed = false
+      for (const event of events) {
+        if (event.index > throughIndex) continue
+        const existing = byIndex.get(event.index)
+        if (existing?.id === event.id) continue
+        byIndex.set(event.index, event)
+        changed = true
+      }
+      if (!changed) return false
+      serverEvents.splice(
+        0,
+        serverEvents.length,
+        ...[...byIndex.values()].toSorted((a, b) => a.index - b.index),
+      )
+      return true
+    }
+
+    const overlayEvents = (): ContractEvent<D>[] => {
+      // Acked entries first (they have a server-assigned order), then
+      // unacked in push order with provisional indexes.
+      const acked = pending
+        .filter((p) => p.acked)
+        .map((p) => p.acked!)
+        .toSorted((a, b) => a.index - b.index)
+      const maxKnown = acked.at(-1)?.index ?? frontier
+      const unacked = pending
+        .filter((p) => !p.acked)
+        .map(
+          (p, i) =>
+            ({
+              id: p.id,
+              type: p.type,
+              payload: p.payload,
+              index: maxKnown + 1 + i, // provisional
+              sessionId,
+              createdAt: p.createdAt,
+            }) as ContractEvent<D>,
+        )
+      return [...acked, ...unacked]
+    }
+
+    const connection = (): Connection => {
+      switch (status) {
+        case 'idle':
+          return { status: 'idle' }
+        case 'closed':
+          return { status: 'closed' }
+        case 'live':
+          return { status: 'live', reconnects }
+        case 'connecting':
+          return { status: 'connecting', reconnects, error: lastError }
+      }
+    }
+
+    const historyState = (): HistoryState => {
+      const oldestLoaded = serverEvents[0]?.index ?? null
+      return {
+        loading: historyLoads > 0,
+        // Index 1 loaded — or a frontier of 0, an empty log as far as
+        // this client knows — means nothing older is left to fetch.
+        complete: oldestLoaded === 1 || frontier === 0,
+        oldestLoaded,
+      }
+    }
+
+    const buildSnapshot = (): SessionSnapshot<D, S, P> => {
+      const overlay = overlayEvents()
+      let state = foldedState
+      for (const event of overlay) state = reducer.fold(state, event)
+      return {
+        state,
+        events: [...serverEvents, ...overlay],
+        index: frontier,
+        history: historyState(),
+        connection: connection(),
+        ...(declaresPresence
+          ? { presence: presenceState as PresenceMap<P> }
+          : {}),
+      } as SessionSnapshot<D, S, P>
+    }
+
+    // ── presence ─────────────────────────────────────────────────
+    /**
+     * The per-session monotonic LWW stamp: wall-seeded, guarded
+     * `max(now, last + 1)`, so overlapping sends can never invert —
+     * the wall clock seeds it because it is the only monotonic state
+     * that survives a reload without A2 owning persistence.
+     */
+    const nextPresenceAt = (): number => {
+      presenceLastAt = Math.max(Date.now(), presenceLastAt + 1)
+      return presenceLastAt
+    }
+
+    // Copy-on-write throughout: snapshots alias `presenceState`, so
+    // every change replaces the map and the touched entry instead of
+    // mutating them.
+    const applyPresencePatch = (patch: PresencePatch): void => {
+      if (patch.participant === participant) return // the echo is self truth
+      const entry: PresenceMap[string] = Object.assign(
+        nullProtoRecord<PresenceMap[string]>(),
+        presenceState[patch.participant],
+      )
+      let changed = false
+      for (const [field, value] of Object.entries(patch.values)) {
+        if (value === undefined) continue
+        const existing = entry[field]
+        // Field-wise LWW: an older stamp loses, a tie goes to the wire.
+        if (existing && existing.at.getTime() > patch.at.getTime()) continue
+        if (value === null) {
+          if (existing) {
+            delete entry[field]
+            changed = true
+          }
+        } else {
+          entry[field] = { value, seen: patch.seen, at: patch.at }
+          changed = true
+        }
+      }
+      if (!changed) return
+      const next = Object.assign(nullProtoRecord<PresenceMap>(), presenceState)
+      if (Object.keys(entry).length === 0) delete next[patch.participant]
+      else next[patch.participant] = entry
+      presenceState = next
+      notify()
+    }
+
+    const applyPresenceSnapshot = (incoming: PresenceMap): void => {
+      const next: PresenceMap = nullProtoRecord()
+      for (const [id, fields] of Object.entries(incoming)) {
+        if (id === participant) continue
+        next[id] = fields
+      }
+      // Foreign entries replaced wholesale; the own echo survives.
+      const own =
+        participant === undefined ? undefined : presenceState[participant]
+      if (participant !== undefined && own !== undefined)
+        next[participant] = own
+      presenceState = next
+      notify()
+    }
+
+    const echoPresence = (
+      id: string,
+      values: Record<string, unknown>,
+      atMs: number,
+    ): void => {
+      const entry: PresenceMap[string] = Object.assign(
+        nullProtoRecord<PresenceMap[string]>(),
+        presenceState[id],
+      )
+      const at = new Date(atMs)
+      for (const [field, value] of Object.entries(values)) {
+        if (value === null) delete entry[field]
+        else entry[field] = { value, seen: frontier, at }
+      }
+      const next = Object.assign(nullProtoRecord<PresenceMap>(), presenceState)
+      if (Object.keys(entry).length === 0) delete next[id]
+      else next[id] = entry
+      presenceState = next
+      notify()
+    }
+
+    // One send, fire-and-forget: no retry, no rollback, failures
+    // dropped silently — the next send repaints. Sends are NOT
+    // serialized on the ack and may overlap in flight: safe, because
+    // merges are LWW by `at` per (participant, field) and one
+    // sender's stamps are monotonic. `seen` is the frontier at send
+    // time, not at set time; `at` is the sender's monotonic stamp.
+    const sendPresence = (
+      values: Record<string, unknown>,
+      at: number,
+    ): void => {
+      presenceLastSentAt = Date.now()
+      transport.sendPresence({
+        sessionId,
+        // Every path here starts at setPresence, which requires the
+        // participant.
+        presence: { participant: participant!, values, seen: frontier, at },
+      })
+      touch(sessionId)
+    }
+
+    // The fixed-cadence throttle: a set outside the interval sends on
+    // the leading edge; within it, values merge field-wise into one
+    // trailing send at the boundary. The cadence never couples to RTT
+    // — waiting on the ack served no purpose on this plane and
+    // stretched remote motion on slow links.
+    const queuePresenceSend = (
+      values: Record<string, unknown>,
+      at?: number,
+    ): void => {
+      if (presenceTimer !== undefined) {
+        presenceBuffer = { ...presenceBuffer, ...values }
+        return
+      }
+      const wait =
+        presenceLastSentAt + PRESENCE_TIMINGS.sendIntervalMs - Date.now()
+      if (wait <= 0) {
+        sendPresence(values, at ?? nextPresenceAt())
+        return
+      }
+      presenceBuffer = { ...presenceBuffer, ...values }
+      presenceTimer = setTimeout(() => {
+        presenceTimer = undefined
+        const buffered = presenceBuffer
+        presenceBuffer = null
+        // The trailing send stamps at fire time — always past every
+        // stamp its merged values echoed with.
+        if (buffered) sendPresence(buffered, nextPresenceAt())
+      }, wait)
+      ;(presenceTimer as { unref?: () => void }).unref?.()
+    }
+
+    const setPresence = (values: PresencePatch<P>['values']): void => {
+      if (participant === undefined) {
+        throw new TypeError(
+          'setPresence requires a participant — pass one in the session options (the SessionProvider participant prop)',
+        )
+      }
+      const validated: Record<string, unknown> = nullProtoRecord()
+      for (const [field, value] of Object.entries(values)) {
+        if (value === undefined) continue
+        const schema = Object.hasOwn(presenceDefs, field)
+          ? presenceDefs[field]
+          : undefined
+        if (!schema) {
+          throw new A2Error(
+            'UNKNOWN_PRESENCE_FIELD',
+            `no presence field '${field}' in the reducer's vocabulary`,
+          )
+        }
+        if (value === null) {
+          validated[field] = null
+          continue
+        }
+        const result = validateSync(schema, value, `presence field '${field}'`)
+        if (result.issues) {
+          throw new A2Error(
+            'INVALID_PAYLOAD',
+            `invalid value for presence field '${field}'`,
+            { details: result.issues },
+          )
+        }
+        validated[field] = result.value
+      }
+      if (Object.keys(validated).length === 0) return
+      // One stamp per set: the echo and a leading send share it, so
+      // the local map and the wire agree on this write's LWW position.
+      const at = nextPresenceAt()
+      echoPresence(participant, validated, at)
+      if (status !== 'live') {
+        presenceResend = { ...presenceResend, ...validated }
+      }
+      queuePresenceSend(validated, at)
+      touch(sessionId)
+    }
+
+    /** Pushes awaiting stream confirmation — resolved by `ingest` the
+     * moment the frontier passes their batch. */
+    let confirmWatchers: Array<{ index: number; resolve: () => void }> = []
+
+    /** The single ingest point: every server-confirmed event, in log
+     * order, from the stream. */
+    const ingest = (event: ContractEvent<D>): void => {
+      if (event.index <= frontier) return
+      frontier = event.index
+      serverEvents.push(event)
+      foldedState = reducer.fold(foldedState, event)
+      pending = pending.filter((p) => p.id !== event.id)
+      if (confirmWatchers.some((w) => w.index <= frontier)) {
+        const due = confirmWatchers.filter((w) => w.index <= frontier)
+        confirmWatchers = confirmWatchers.filter((w) => w.index > frontier)
+        for (const watcher of due) watcher.resolve()
+      }
+      notify()
+      touch(sessionId)
+    }
+
+    // ── push ─────────────────────────────────────────────────────
+    const validated = (
+      events: AppendInput<D>[],
+    ): Array<{ id: string; type: string; payload: unknown }> =>
+      events.map((event) => {
+        const schema = Object.hasOwn(reducer.events, event.type)
+          ? reducer.events[event.type]
+          : undefined
+        if (!schema) {
+          throw new A2Error(
+            'UNKNOWN_EVENT_TYPE',
+            `no event type '${String(event.type)}' in the reducer's vocabulary`,
+          )
+        }
+        const result = validateSync(
+          schema,
+          event.payload,
+          `event '${String(event.type)}'`,
+        )
+        if (result.issues) {
+          throw new A2Error(
+            'INVALID_PAYLOAD',
+            `invalid payload for event '${String(event.type)}'`,
+            { details: result.issues },
+          )
+        }
+        return {
+          id: event.id ?? crypto.randomUUID(),
+          type: event.type,
+          payload: result.value,
+        }
+      })
+
+    const post = async (
+      body: TransportPushBody,
+    ): Promise<ContractEvent<D>[]> => {
+      let lastPushError: A2Error = new A2Error(
+        'STORE_UNAVAILABLE',
+        'push failed',
+      )
+      for (let attempt = 1; attempt <= PUSH_ATTEMPTS; attempt += 1) {
+        try {
+          const rows = await transport.push(body)
+          return rows.map((row) => eventFromWire(row) as ContractEvent<D>)
+        } catch (err) {
+          lastPushError =
+            err instanceof A2Error
+              ? err
+              : new A2Error('STORE_UNAVAILABLE', 'push request failed', {
+                  cause: err,
+                })
+        }
+        // Only the documented retryable code retries; identical ids
+        // make the retry idempotent on the server.
+        if (lastPushError.code !== 'STORE_UNAVAILABLE') throw lastPushError
+        if (attempt < PUSH_ATTEMPTS) {
+          const sleepMs = 250 * attempt
+          // Wait for the clock AND, when the transport can tell us,
+          // the wire. The pacing sleep is a floor: a failure acked
+          // over a healthy socket (a shedding store) must not re-fire
+          // at wire speed. A push caught in a routine reconnect blip
+          // additionally parks until the subscription is confirmed;
+          // that cap scales with the reconnect backoff so an
+          // unreachable server still exhausts attempts promptly.
+          await Promise.all([
+            new Promise((resolve) => setTimeout(resolve, sleepMs)),
+            transport.awaitReady?.(
+              sessionId,
+              sleepMs + STREAM_TIMINGS.reconnectBaseMs * attempt,
+            ),
+          ])
+        }
+      }
+      throw lastPushError
+    }
+
+    /**
+     * Decorate the ack promise into a PushResult. `confirmed` is a
+     * lazy getter — materialized on first access, so callers that
+     * ignore it can't leak an unhandled rejection.
+     */
+    const withConfirmed = (ack: Promise<ContractEvent<D>[]>): PushResult<D> => {
+      let confirmed: Promise<ContractEvent<D>[]> | undefined
+      return Object.defineProperty(ack as PushResult<D>, 'confirmed', {
+        get(): Promise<ContractEvent<D>[]> {
+          confirmed ??= ack.then(
+            (acked) =>
+              new Promise<ContractEvent<D>[]>((resolve) => {
+                const last = acked.at(-1)?.index ?? 0
+                if (frontier >= last) {
+                  resolve(acked)
+                  return
+                }
+                confirmWatchers.push({
+                  index: last,
+                  resolve: () => resolve(acked),
+                })
+              }),
+          )
+          return confirmed
+        },
+      })
+    }
+
+    const push = (...events: AppendInput<D>[]): PushResult<D> => {
+      touch(sessionId)
+      return withConfirmed(
+        (async () => {
+          if (events.length === 0) {
+            throw new TypeError('push requires at least one event')
+          }
+          const entries: Pending<D>[] = validated(events).map((e) => ({
+            id: e.id,
+            type: e.type,
+            payload: e.payload,
+            createdAt: new Date(),
+          }))
+          // Reserve before notifying: a subscriber may reenter push(),
+          // and that work must follow the call whose state it observed.
+          const waitForPriorPush = pushWireTail
+          let releasePush!: () => void
+          pushWireTail = new Promise<void>((resolve) => {
+            releasePush = resolve
+          })
+          pending.push(...entries)
+          inFlightPushes += 1
+
+          try {
+            notify() // optimistic — the view updates before the network moves
+            await waitForPriorPush
+            const acked = await post({
+              sessionId,
+              events: entries.map(({ id, type, payload }) => ({
+                id,
+                type,
+                payload,
+              })),
+            })
+            for (const event of acked) {
+              const entry = pending.find((p) => p.id === event.id)
+              if (entry) entry.acked = event // stream retires it at its index
+            }
+            notify()
+            return acked
+          } catch (err) {
+            // Rollback: refold without the rejected events.
+            const ids = new Set(entries.map((e) => e.id))
+            pending = pending.filter((p) => !ids.has(p.id))
+            notify()
+            throw err
+          } finally {
+            releasePush()
+            inFlightPushes -= 1
+            if (inFlightPushes === 0 && deferredHydration) {
+              const next = deferredHydration
+              deferredHydration = undefined
+              runtime.hydrate(next)
+            }
+            touch(sessionId)
+          }
+        })(),
+      )
+    }
+
+    // ── backscroll ───────────────────────────────────────────────
+    // Cold reads of the log below the frontier. Fetched events merge
+    // into `serverEvents` only — never the fold, never the overlay.
+    let historyLoads = 0
+    /** Calls chain per session: each resolves its bounds after the
+     * prior call's merge, so overlapping backscrolls page backward
+     * instead of re-fetching the same range. */
+    let historyTail: Promise<unknown> = Promise.resolve()
+
+    const eventsBetween = (gte: number, lte: number): ContractEvent<D>[] =>
+      serverEvents.filter((event) => event.index >= gte && event.index <= lte)
+
+    /** The narrowest sub-range of [gte, lte] missing from the feed, or
+     * null when the range is fully loaded (nothing to fetch). */
+    const missingBetween = (
+      gte: number,
+      lte: number,
+    ): { gte: number; lte: number } | null => {
+      const present = new Set(eventsBetween(gte, lte).map((e) => e.index))
+      let lo = gte
+      while (lo <= lte && present.has(lo)) lo += 1
+      if (lo > lte) return null
+      let hi = lte
+      while (hi > lo && present.has(hi)) hi -= 1
+      return { gte: lo, lte: hi }
+    }
+
+    const loadHistory = (
+      loadOptions?: LoadHistoryOptions,
+    ): Promise<ContractEvent<D>[]> => {
+      const readHistory = transport.history
+      if (readHistory === undefined) {
+        throw new TypeError(
+          'loadHistory requires an http api — the ws transport has no history lane; serve the session over handle() and pass its route url as the string or { type: "http" } api',
+        )
+      }
+      const before = loadOptions?.before
+      const limit = loadOptions?.limit
+      if (
+        before !== undefined &&
+        (!Number.isSafeInteger(before) || before < 1)
+      ) {
+        throw new TypeError(
+          'loadHistory before must be a positive safe integer',
+        )
+      }
+      if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 1)) {
+        throw new TypeError('loadHistory limit must be a positive safe integer')
+      }
+      touch(sessionId)
+      const run = historyTail.then(async () => {
+        const upper = before ?? serverEvents[0]?.index ?? frontier + 1
+        // Strictly at or below the frontier: the live stream owns
+        // everything above it, and the optimistic overlay must never
+        // collide with a backscrolled row.
+        const lte = Math.min(upper - 1, frontier)
+        const gte = Math.max(1, upper - (limit ?? DEFAULT_HISTORY_LIMIT))
+        if (gte > lte) return []
+        const missing = missingBetween(gte, lte)
+        if (missing === null) return eventsBetween(gte, lte)
+        historyLoads += 1
+        notify()
+        try {
+          const rows = await readHistory({ sessionId, ...missing })
+          mergeServerEvents(
+            rows.map((row) => eventFromWire(row) as ContractEvent<D>),
+            frontier,
+          )
+          return eventsBetween(gte, lte)
+        } finally {
+          historyLoads -= 1
+          notify()
+          touch(sessionId)
+        }
+      })
+      // Failures reject the caller, never the chain.
+      historyTail = run.catch(() => {})
+      return run
+    }
+
+    // ── the live stream ──────────────────────────────────────────
+    // A run-generation model instead of a terminal `closed` flag:
+    // close() bumps the generation (the running loop notices and
+    // exits), connect() starts a fresh one. Reentrant by design.
+    let generation = 0
+    let active = false
+    let abort: AbortController | null = null
+
+    const runStream = async (run: number): Promise<void> => {
+      let backoff = STREAM_TIMINGS.reconnectBaseMs
+      // oxlint-disable no-await-in-loop -- sequential reconnect loop
+      // oxlint-disable-next-line no-unmodified-loop-condition -- close() bumps `generation`
+      while (generation === run) {
+        const controller = new AbortController()
+        abort = controller
+        // The stall watchdog: the server heartbeats the stream, so a
+        // healthy connection is never silent for long. Silence past the
+        // timeout means the connection is dead in a way the socket
+        // won't report (an offline browser's established SSE socket
+        // neither errors nor receives) — abort it and let the normal
+        // reconnect path run. This is what keeps `status: 'live'`
+        // honest.
+        let stall: ReturnType<typeof setTimeout> | undefined
+        let stalled = false
+        const armStall = (): void => {
+          clearTimeout(stall)
+          stall = setTimeout(() => {
+            stalled = true
+            controller.abort()
+          }, STREAM_TIMINGS.stallTimeoutMs)
+          ;(stall as { unref?: () => void }).unref?.()
+        }
+        let wasLive = false
+        try {
+          const frames = transport.connect({
+            sessionId,
+            startAfter: frontier,
+            signal: controller.signal,
+          })
+          for await (const frame of frames) {
+            if (generation !== run) break
+            // Every frame counts — heartbeats included. Liveness is
+            // about the connection, not about events.
+            armStall()
+            if (!wasLive) {
+              // The first frame is the connection signal: the transport
+              // yields it the moment the stream is established.
+              backoff = STREAM_TIMINGS.reconnectBaseMs
+              wasLive = true
+              status = 'live'
+              lastError = null
+              notify()
+              if (presenceResend) {
+                const values = presenceResend
+                presenceResend = null
+                queuePresenceSend(values)
+              }
+            }
+            if (frame.kind === 'event') {
+              ingest(eventFromWire(frame.event) as ContractEvent<D>)
+            } else if (frame.kind === 'presence') {
+              applyPresencePatch(presencePatchFromWire(frame.patch))
+            } else if (frame.kind === 'presence-snapshot') {
+              applyPresenceSnapshot(
+                presenceSnapshotFromWire(frame.snapshot).snapshot,
+              )
+            }
+          }
+          // The transport ended the stream cleanly — reconnect, but it
+          // isn't an error.
+          if (generation === run) {
+            lastError = null
+          }
+        } catch (err) {
+          if (generation === run) {
+            lastError = stalled
+              ? new Error(
+                  `stream stalled: no data for ${STREAM_TIMINGS.stallTimeoutMs}ms`,
+                )
+              : err instanceof Error
+                ? err
+                : new Error(String(err))
+          }
+        } finally {
+          clearTimeout(stall)
+        }
+        if (generation !== run) break
+        if (wasLive) reconnects += 1
+        status = 'connecting'
+        notify()
+        await new Promise<void>((resolve) => {
+          let settled = false
+          const finish = (): void => {
+            if (settled) return
+            settled = true
+            clearTimeout(timer)
+            // oxlint-disable-next-line no-multiple-resolved -- guarded above
+            resolve()
+          }
+          const timer = setTimeout(finish, backoff)
+          ;(timer as { unref?: () => void }).unref?.()
+          abort?.signal.addEventListener('abort', finish)
+        })
+        backoff = Math.min(backoff * 2, STREAM_TIMINGS.reconnectMaxMs)
+      }
+      // oxlint-enable no-await-in-loop
+    }
+
+    const runtime: SessionRuntime<D, S, P> = {
+      sessionId,
+      // Only on presence-declaring contracts — the type surface
+      // promises no runtime-inert members (a2-api.md §12).
+      ...(declaresPresence ? { setPresence } : {}),
+      subscribe(listener) {
+        touch(sessionId)
+        listeners.add(listener)
+        return () => {
+          listeners.delete(listener)
+          touch(sessionId)
+        }
+      },
+      getSnapshot() {
+        snapshot ??= buildSnapshot()
+        return snapshot
+      },
+      push,
+      loadHistory,
+      connect() {
+        touch(sessionId)
+        if (active) return
+        active = true
+        status = 'connecting'
+        notify()
+        void runStream(generation)
+      },
+      close() {
+        touch(sessionId)
+        if (!active) return
+        active = false
+        generation += 1 // the running loop notices and exits
+        abort?.abort()
+        abort = null
+        // A pending trailing send dies with the stream — losing one is
+        // fine by definition; sets made while closed accumulate in
+        // `presenceResend` and repaint after the next connect.
+        clearTimeout(presenceTimer)
+        presenceTimer = undefined
+        presenceBuffer = null
+        status = 'closed'
+        notify()
+      },
+      hydrate(next) {
+        touch(sessionId)
+        if (!next) return
+        participant ??= next.participant
+        const nextIndex = next.initialIndex ?? 0
+        if (nextIndex > frontier && inFlightPushes > 0) {
+          if (
+            !deferredHydration ||
+            nextIndex > (deferredHydration.initialIndex ?? 0)
+          ) {
+            deferredHydration = next
+          }
+          return
+        }
+
+        const historyChanged = mergeServerEvents(
+          next.initialEvents,
+          Math.min(nextIndex, frontier),
+        )
+        if (next.initialState === undefined || nextIndex <= frontier) {
+          if (historyChanged) notifyHydrated()
+          return
+        }
+
+        // The server fold subsumes everything observed through the old
+        // frontier. Keep later optimistic work overlaid, retiring acked
+        // entries the new frontier proves are already durable.
+        frontier = nextIndex
+        foldedState = next.initialState
+        mergeServerEvents(next.initialEvents, frontier)
+        pending = pending.filter(
+          (entry) => !entry.acked || entry.acked.index > frontier,
+        )
+        if (confirmWatchers.some((watcher) => watcher.index <= frontier)) {
+          const due = confirmWatchers.filter(
+            (watcher) => watcher.index <= frontier,
+          )
+          confirmWatchers = confirmWatchers.filter(
+            (watcher) => watcher.index > frontier,
+          )
+          for (const watcher of due) watcher.resolve()
+        }
+        notifyHydrated()
+      },
+      canEvict() {
+        return (
+          listeners.size === 0 &&
+          !active &&
+          inFlightPushes === 0 &&
+          historyLoads === 0 &&
+          confirmWatchers.length === 0 &&
+          presenceTimer === undefined
+        )
+      },
+    } as SessionRuntime<D, S, P>
+
+    return runtime
+  }
+
+  return {
+    session(sessionId, sessionOptions) {
+      const existing = sessions.get(sessionId)
+      if (existing) {
+        existing.runtime.hydrate(sessionOptions)
+        touch(sessionId)
+        return existing.runtime
+      }
+
+      const runtime = makeSession(sessionId, sessionOptions)
+      sessions.set(sessionId, { runtime })
+      touch(sessionId)
+      return runtime
+    },
+  }
+}