experimental-a2 0.16.1 → 0.18.0

package/src/client.ts

@@ -14,7 +14,14 @@
  */
 
 // oxlint-disable no-await-in-loop -- retry/backoff/stream loops are sequential by nature
+import { decodeState, projectClientState } from './reducer-runtime.ts'
 import { A2ClientError, asClientError } from './client-errors.ts'
+import {
+  isInitialPromise,
+  observeInitial,
+  type InitialSnapshot,
+} from './initial-snapshot.ts'
+import { registerRenderSessionFactory } from './client-render-session.ts'
 import {
   PRESENCE_TIMINGS,
   RESERVED_PARTICIPANT_IDS,
@@ -23,6 +30,7 @@ import {
 } from './internal.ts'
 import type {
   AppendInput,
+  Contract,
   ContractEvent,
   EventDefs,
   PresenceDefs,
@@ -30,11 +38,17 @@ import type {
   PresencePatch,
   WithPresence,
 } from './contract.ts'
-import { clientStateProjection, type Reducer } from './reducer.ts'
+import { foldEvent, type Reducer, type StateSnapshot } from './reducer.ts'
+import { isSessionCleared } from './session-clear.ts'
 import { validateSync } from './validate.ts'
 import {
+  isStateSnapshotFrame,
+  type StateSnapshotFrame,
+  type SubscriptionStart,
   errorFromWire,
+  eventFromCompactWire,
   eventFromWire,
+  isCompactWireEvent,
   isWireEvent,
   isWirePresencePatch,
   isWirePresenceSnapshot,
@@ -50,8 +64,11 @@ import {
   type WirePresencePatch,
   type WirePresenceSnapshot,
 } from './wire.ts'
+import type { Event } from './store.ts'
 
 export { A2ClientError } from './client-errors.ts'
+export type { StateSnapshot } from './reducer.ts'
+export type { InitialSnapshot } from './initial-snapshot.ts'
 export type { A2ClientErrorOptions } from './client-errors.ts'
 
 export type ReconnectPolicy = (failure: {
@@ -129,6 +146,8 @@ export type SessionSnapshot<
 > & {
   /** The live view: server events folded, optimistic pushes applied. */
   state: S
+  /** A state/index snapshot has been applied; independent of connection status. */
+  hydrated: boolean
   /** The raw event feed: server truth — observed, seeded, or
    * backscrolled via `loadHistory` — plus pending optimistic events
    * (provisional indexes past the frontier). `state` never folds
@@ -164,11 +183,10 @@ export type SessionClient<
   D extends EventDefs,
   S,
   P extends PresenceDefs = Record<never, never>,
-  V = S,
 > = WithPresence<P, SessionClientPresence<P>> & {
   readonly sessionId: string
   subscribe(listener: () => void): () => void
-  getSnapshot(): SessionSnapshot<D, V, P>
+  getSnapshot(): SessionSnapshot<D, S, P>
   /**
    * Optimistic append: validates locally against the reducer's event
    * schemas (instant `INVALID_PAYLOAD`, no flicker), applies to the
@@ -212,25 +230,53 @@ export type SessionClient<
 }
 
 export type SessionOptions<D extends EventDefs, S> = {
-  initialState?: S
-  initialIndex?: number
-  /** Server-rendered history through `initialIndex`. Seeds the event feed. */
+  initial?: InitialSnapshot<S>
+  /** Server-rendered history through `initial.index`. Seeds the event feed. */
   initialEvents?: ContractEvent<D>[]
   /** Overrides the client's `participant` for this session handle.
    * Bound once per handle. */
   participant?: string
 }
 
+function assertSessionSeed(options: { initial?: unknown } | undefined): void {
+  const initial = options?.initial
+  if (initial == null || isInitialPromise(initial as InitialSnapshot<unknown>))
+    return
+  if (
+    initial === null ||
+    typeof initial !== 'object' ||
+    !Object.hasOwn(initial, 'state') ||
+    !Object.hasOwn(initial, 'index') ||
+    !('index' in initial) ||
+    typeof initial.index !== 'number' ||
+    !Number.isSafeInteger(initial.index) ||
+    initial.index < 0
+  )
+    throw new TypeError(
+      'initial must contain state and a non-negative safe integer index',
+    )
+  const clearIndex = (initial as { clearIndex?: unknown }).clearIndex
+  if (
+    clearIndex !== undefined &&
+    (typeof clearIndex !== 'number' ||
+      !Number.isSafeInteger(clearIndex) ||
+      clearIndex < 0 ||
+      clearIndex > initial.index)
+  )
+    throw new TypeError(
+      'initial.clearIndex must be a non-negative safe integer no greater than its index',
+    )
+}
+
 export type A2Client<
   D extends EventDefs,
   S,
   P extends PresenceDefs = Record<never, never>,
-  V = S,
 > = {
   session(
     sessionId: string,
     options?: SessionOptions<D, S>,
-  ): SessionClient<D, S, P, V>
+  ): SessionClient<D, S, P>
 }
 
 /**
@@ -277,9 +323,8 @@ export type CreateClientOptions<
   D extends EventDefs,
   S,
   P extends PresenceDefs = Record<never, never>,
-  V = S,
 > = {
-  reducer: Reducer<D, S, P, V>
+  contract: Contract<D, P, Reducer<D, S, P>>
   /** The route (or routes) the client speaks — see `ClientApi`. */
   api: ClientApi
   /** Delay the next connection attempt in milliseconds, or pause with false. */
@@ -321,7 +366,9 @@ const DEFAULT_HISTORY_LIMIT = 50
  * discrimination today, the ws `kind` discriminant tomorrow. `ping`
  * carries no data — it exists so the watchdog sees liveness. */
 type TransportFrame =
+  | StateSnapshotFrame
   | { kind: 'event'; event: WireEvent }
+  | { kind: 'events'; events: Event[] }
   | { kind: 'presence'; patch: WirePresencePatch }
   | { kind: 'presence-snapshot'; snapshot: WirePresenceSnapshot }
   | { kind: 'activity'; idle: boolean }
@@ -351,7 +398,8 @@ type Transport = {
    */
   connect(opts: {
     sessionId: string
-    startAfter: number
+    startAfter: number | undefined
+    reducer: string
     signal: AbortSignal
   }): AsyncIterable<TransportFrame>
   /** One attempt (the retry loop lives above the seam): resolves with
@@ -364,7 +412,7 @@ type Transport = {
     sessionId: string
     gte: number
     lte: number
-  }): Promise<WireEvent[]>
+  }): Promise<{ events: WireEvent[]; clearIndex?: number }>
   /** Fire-and-forget; failures are dropped (presence repaints). */
   sendPresence(envelope: TransportPresenceEnvelope): void
   /**
@@ -409,11 +457,11 @@ const httpTransport = (
   // exactly like unknown named frames.
   presence: boolean,
 ): Transport => ({
-  async *connect({ sessionId, startAfter, signal }) {
+  async *connect({ sessionId, startAfter, reducer: reducerName, signal }) {
     const streamUrl = sessionUrl(routes.stream, sessionId)
     const sep = streamUrl.includes('?') ? '&' : '?'
     const res = await fetchImpl(
-      `${streamUrl}${sep}sessionId=${encodeURIComponent(sessionId)}&index=${startAfter}`,
+      `${streamUrl}${sep}${new URLSearchParams({ sessionId, reducer: reducerName, wire: '2', ...(startAfter === undefined ? { bootstrap: '1' } : { index: String(startAfter) }) })}`,
       { headers: { accept: 'text/event-stream' }, signal },
     )
     if (!res.ok) throw await httpError(res)
@@ -453,7 +501,30 @@ const httpTransport = (
           if (!data) continue
           if (eventName === undefined) {
             const parsed: unknown = JSON.parse(data)
-            if (isWireEvent(parsed)) yield { kind: 'event', event: parsed }
+            // A version 2 server batches events; an older one sends one.
+            if (Array.isArray(parsed)) {
+              // Dropping a batch would leave a gap the frontier then skips past.
+              if (!parsed.every(isCompactWireEvent))
+                throw new A2ClientError(
+                  'INVALID_PAYLOAD',
+                  'invalid event batch',
+                )
+              yield {
+                kind: 'events',
+                events: parsed.map((row) =>
+                  eventFromCompactWire(row, sessionId),
+                ),
+              }
+            } else if (isWireEvent(parsed))
+              yield { kind: 'event', event: parsed }
+          } else if (eventName === 'a2-snapshot') {
+            const parsed: unknown = JSON.parse(data)
+            if (!isStateSnapshotFrame(parsed))
+              throw new A2ClientError(
+                'INVALID_PAYLOAD',
+                'invalid bootstrap snapshot',
+              )
+            yield parsed
           } else if (presence && eventName === 'presence-snapshot') {
             const parsed: unknown = JSON.parse(data)
             if (isWirePresenceSnapshot(parsed)) {
@@ -515,7 +586,10 @@ const httpTransport = (
         'history response was not a list of events',
       )
     }
-    return rows
+    const clearIndex = Number(res.headers.get('a2-clear-index') ?? Number.NaN)
+    return Number.isSafeInteger(clearIndex) && clearIndex > 0
+      ? { events: rows, clearIndex }
+      : { events: rows }
   },
 
   sendPresence(envelope) {
@@ -622,21 +696,32 @@ const sessionWsTransport = (
   const ready = socketReadyWaiters()
   let nextReq = 1
 
-  const socketUrl = (sessionId: string, startAfter: number): string => {
+  const socketUrl = (
+    sessionId: string,
+    startAfter: number | undefined,
+    reducerName: string,
+  ): string => {
     const resolved = webSocketUrl(sessionUrl(url, sessionId))
     resolved.searchParams.set('sessionId', sessionId)
-    resolved.searchParams.set('index', String(startAfter))
+    resolved.searchParams.delete('index')
+    resolved.searchParams.delete('bootstrap')
+    resolved.searchParams.set('reducer', reducerName)
+    resolved.searchParams.set('wire', '2')
+    if (startAfter === undefined) resolved.searchParams.set('bootstrap', '1')
+    else resolved.searchParams.set('index', String(startAfter))
     return resolved.href
   }
 
   return {
-    async *connect({ sessionId, startAfter, signal }) {
+    async *connect({ sessionId, startAfter, reducer: reducerName, signal }) {
       if (webSocketImpl === undefined) {
         throw new TypeError(
           'no WebSocket implementation available — pass one via createClient({ webSocket }) where the global is missing',
         )
       }
-      const socket = new webSocketImpl(socketUrl(sessionId, startAfter))
+      const socket = new webSocketImpl(
+        socketUrl(sessionId, startAfter, reducerName),
+      )
       const connection: SocketConnection = { socket, pending: new Map() }
       connections.set(sessionId, connection)
 
@@ -654,6 +739,7 @@ const sessionWsTransport = (
         failure = error
         if (connections.get(sessionId) === connection) {
           connections.delete(sessionId)
+          ready.notify(sessionId)
         }
         rejectPendingAcks(connection.pending)
         notify()
@@ -668,9 +754,18 @@ const sessionWsTransport = (
       socket.addEventListener('message', (event) => {
         if (connections.get(sessionId) !== connection || ended) return
         if (typeof event.data !== 'string') return
-        const frame = parseSocketFrame(event.data)
+        let frame: SocketDownFrame | null
+        try {
+          frame = parseSocketFrame(event.data)
+        } catch (error) {
+          finish(asClientError(error))
+          return
+        }
         if (frame === null) return
         switch (frame.kind) {
+          case 'snapshot':
+            queue.push(frame)
+            break
           case 'ack': {
             const waiter = connection.pending.get(frame.req)
             if (waiter === undefined) return
@@ -696,6 +791,15 @@ const sessionWsTransport = (
             if (frame.event.sessionId !== sessionId) return
             queue.push({ kind: 'event', event: frame.event })
             break
+          case 'events':
+            if (frame.sessionId !== undefined) return
+            queue.push({
+              kind: 'events',
+              events: frame.events.map((row) =>
+                eventFromCompactWire(row, sessionId),
+              ),
+            })
+            break
           case 'presence':
             if (presence && frame.sessionId === undefined) {
               queue.push({ kind: 'presence', patch: frame.patch })
@@ -834,7 +938,12 @@ const sessionWsTransport = (
  * attempt, so `startAfter` is that attempt's resume frontier. */
 type WsChannel = {
   sessionId: string
-  startAfter: number
+  /** Echoed on this lane's subscribe answers. An answer to an earlier
+   * attempt for the same session must not confirm or end this one;
+   * data frames from that attempt precede this attempt's confirmation. */
+  attempt: number
+  startAfter: number | undefined
+  reducer: string
   queue: TransportFrame[]
   /** The server confirmed the subscribe — pushes and presence ride. */
   live: boolean
@@ -850,9 +959,18 @@ const wakeChannel = (channel: WsChannel): void => {
   channel.wake = null
 }
 
-const subscribeFrame = (
-  sessions: Array<{ id: string; index: number }>,
-): string => {
+const answersAttempt = (
+  frame: { attempt?: number },
+  channel: WsChannel,
+): boolean => frame.attempt === undefined || frame.attempt === channel.attempt
+
+const subscriptionStart = (
+  index: number | undefined,
+  reducer: string,
+): SubscriptionStart =>
+  index === undefined ? { bootstrap: true, reducer } : { index, reducer }
+
+const subscribeFrame = (sessions: SocketSubscribeFrame['sessions']): string => {
   const frame: SocketSubscribeFrame = { kind: 'subscribe', sessions }
   return JSON.stringify(frame)
 }
@@ -874,6 +992,7 @@ const multiplexedWsTransport = (
   let socketOpen = false
   let watchdog: ReturnType<typeof setTimeout> | undefined
   let nextReq = 1
+  let nextAttempt = 1
 
   const trySend = (data: string): void => {
     if (socket === null || !socketOpen) return
@@ -926,6 +1045,7 @@ const multiplexedWsTransport = (
   const detach = (channel: WsChannel): void => {
     if (channels.get(channel.sessionId) !== channel) return
     channels.delete(channel.sessionId)
+    ready.notify(channel.sessionId)
     if (!channel.dropped) {
       const frame: SocketUnsubscribeFrame = {
         kind: 'unsubscribe',
@@ -964,6 +1084,11 @@ const multiplexedWsTransport = (
 
   const route = (frame: SocketDownFrame): void => {
     switch (frame.kind) {
+      case 'snapshot': {
+        const channel = channels.get(frame.sessionId)
+        if (channel && channel.live && !channel.ended) deliver(channel, frame)
+        return
+      }
       case 'ping': {
         // Global liveness — every live channel's stall watchdog feeds
         // on it, the way each SSE stream feeds on its own heartbeat.
@@ -976,7 +1101,13 @@ const multiplexedWsTransport = (
       }
       case 'subscribed': {
         const channel = channels.get(frame.sessionId)
-        if (channel === undefined || channel.ended || channel.live) return
+        if (
+          channel === undefined ||
+          channel.ended ||
+          channel.live ||
+          !answersAttempt(frame, channel)
+        )
+          return
         channel.live = true
         deliver(channel, { kind: 'ping' }) // the connected signal
         ready.notify(frame.sessionId)
@@ -984,7 +1115,7 @@ const multiplexedWsTransport = (
       }
       case 'unsubscribed': {
         const channel = channels.get(frame.sessionId)
-        if (channel === undefined) return
+        if (channel === undefined || !answersAttempt(frame, channel)) return
         channel.dropped = true
         settleChannel(
           channel,
@@ -1013,6 +1144,20 @@ const multiplexedWsTransport = (
         }
         return
       }
+      case 'events': {
+        const { sessionId } = frame
+        if (sessionId === undefined) return
+        const channel = channels.get(sessionId)
+        if (channel !== undefined && channel.live && !channel.ended) {
+          deliver(channel, {
+            kind: 'events',
+            events: frame.events.map((row) =>
+              eventFromCompactWire(row, sessionId),
+            ),
+          })
+        }
+        return
+      }
       case 'presence': {
         // Contracts that declare no presence skip presence frames,
         // exactly like the http transport.
@@ -1044,7 +1189,9 @@ const multiplexedWsTransport = (
         'no WebSocket implementation available — pass one via createClient({ webSocket }) where the global is missing',
       )
     }
-    const created = new webSocketImpl(webSocketUrl(url).href)
+    const target = webSocketUrl(url)
+    target.searchParams.set('wire', '2')
+    const created = new webSocketImpl(target.href)
     socket = created
     socketOpen = false
     armWatchdog(created)
@@ -1056,7 +1203,8 @@ const multiplexedWsTransport = (
         .filter((channel) => !channel.ended)
         .map((channel) => ({
           id: channel.sessionId,
-          index: channel.startAfter,
+          attempt: channel.attempt,
+          ...subscriptionStart(channel.startAfter, channel.reducer),
         }))
       if (sessions.length > 0) trySend(subscribeFrame(sessions))
     })
@@ -1064,7 +1212,13 @@ const multiplexedWsTransport = (
       if (socket !== created) return
       if (typeof event.data !== 'string') return
       armWatchdog(created)
-      const frame = parseSocketFrame(event.data)
+      let frame: SocketDownFrame | null
+      try {
+        frame = parseSocketFrame(event.data)
+      } catch (error) {
+        failSocket(asClientError(error))
+        return
+      }
       if (frame === null) return
       route(frame)
     })
@@ -1087,10 +1241,12 @@ const multiplexedWsTransport = (
   }
 
   return {
-    async *connect({ sessionId, startAfter, signal }) {
+    async *connect({ sessionId, startAfter, reducer: reducerName, signal }) {
       const channel: WsChannel = {
         sessionId,
+        attempt: nextAttempt++,
         startAfter,
+        reducer: reducerName,
         queue: [],
         live: false,
         dropped: false,
@@ -1102,7 +1258,15 @@ const multiplexedWsTransport = (
       try {
         ensureSocket()
         if (socketOpen) {
-          trySend(subscribeFrame([{ id: sessionId, index: startAfter }]))
+          trySend(
+            subscribeFrame([
+              {
+                id: sessionId,
+                attempt: channel.attempt,
+                ...subscriptionStart(startAfter, reducerName),
+              },
+            ]),
+          )
         }
       } catch (error) {
         if (channels.get(sessionId) === channel) channels.delete(sessionId)
@@ -1261,20 +1425,40 @@ type Pending<D extends EventDefs> = {
   /** Set once the POST ack returns; the entry leaves the overlay when
    * the stream delivers its index. */
   acked?: ContractEvent<D>
+  sent?: true
+  /** Sent before the current baseline was adopted and not yet acked:
+   * the baseline may already contain it, so only its ack index can
+   * place it in the overlay. */
+  heldUntilAck?: true
+}
+
+type ResolvedSessionOptions<D extends EventDefs, S> = Omit<
+  SessionOptions<D, S>,
+  'initial'
+> & {
+  initial?: StateSnapshot<S> | null | undefined
+}
+
+type PendingInitial<D extends EventDefs, S> = {
+  source: Promise<StateSnapshot<S> | null | undefined>
+  version: number
+  settings: Omit<SessionOptions<D, S>, 'initial'>
+  cancel(): void
+  error?: A2ClientError
 }
 
 type SessionRuntime<
   D extends EventDefs,
   S,
   P extends PresenceDefs,
-  V,
-> = SessionClient<D, S, P, V> & {
+> = SessionClient<D, S, P> & {
   hydrate(options?: SessionOptions<D, S>): void
+  resolveInitial(options: { source: object; value: unknown }): void
   canEvict(): boolean
 }
 
-type CachedSession<D extends EventDefs, S, P extends PresenceDefs, V> = {
-  runtime: SessionRuntime<D, S, P, V>
+type CachedSession<D extends EventDefs, S, P extends PresenceDefs> = {
+  runtime: SessionRuntime<D, S, P>
   timer?: ReturnType<typeof setTimeout>
 }
 
@@ -1282,10 +1466,14 @@ export function createClient<
   D extends EventDefs,
   S,
   P extends PresenceDefs = Record<never, never>,
-  V = S,
->(options: CreateClientOptions<D, S, P, V>): A2Client<D, S, P, V> {
-  const { reducer, api } = options
-  const presenceDefs: Readonly<PresenceDefs> = reducer.presence
+>(options: CreateClientOptions<D, S, P>): A2Client<D, S, P> {
+  const { contract, api } = options
+  const reducer = contract?.reducer
+  if (!reducer)
+    throw new TypeError(
+      'createClient requires a contract with a public reducer',
+    )
+  const presenceDefs: Readonly<PresenceDefs> = contract.presence
   const declaresPresence = Object.keys(presenceDefs).length > 0
   const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis)
   const clientFetch: typeof globalThis.fetch = async (input, init) => {
@@ -1308,7 +1496,7 @@ export function createClient<
   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, V>>()
+  const sessions = new Map<string, CachedSession<D, S, P>>()
 
   const scheduleGc = (sessionId: string, delay = gcTime): void => {
     const entry = sessions.get(sessionId)
@@ -1319,6 +1507,8 @@ export function createClient<
       const current = sessions.get(sessionId)
       if (current !== entry) return
       if (entry.runtime.canEvict()) {
+        entry.runtime.close()
+        clearTimeout(entry.timer)
         sessions.delete(sessionId)
         return
       }
@@ -1336,21 +1526,26 @@ export function createClient<
   const makeSession = (
     sessionId: string,
     sessionOptions?: SessionOptions<D, S>,
-  ): SessionRuntime<D, S, P, V> => {
+  ): SessionRuntime<D, S, P> => {
+    assertSessionSeed(sessionOptions)
     // ── server truth ─────────────────────────────────────────────
-    let stateIndex = sessionOptions?.initialIndex ?? 0
-    let streamIndex =
-      sessionOptions?.initialState === undefined
-        ? sessionOptions?.initialIndex
-        : stateIndex
-    let foldedState: S =
-      sessionOptions?.initialState !== undefined
-        ? sessionOptions.initialState
-        : reducer.initialState
+    const supplied = sessionOptions?.initial
+    const initial = isInitialPromise(supplied) ? undefined : supplied
+    let hydrated = initial != null
+    let bootstrapGeneration: number | undefined
+    let stateIndex = initial?.index ?? 0
+    let streamIndex = initial?.index
+    let foldedState: S = initial == null ? reducer.initialState : initial.state
+    /** The latest clear marker this session has learned of, or 0. */
+    let clearIndex = initial?.clearIndex ?? 0
+    let initialVersion = 0
+    const seenInitials = new WeakSet<object>()
+    if (initial != null) seenInitials.add(initial)
+    let preload: PendingInitial<D, S> | undefined
     const serverEvents: ContractEvent<D>[] = (
       sessionOptions?.initialEvents ?? []
     )
-      .filter((event) => event.index <= stateIndex)
+      .filter((event) => event.index <= stateIndex && event.index > clearIndex)
       .toSorted((a, b) => a.index - b.index)
 
     // ── optimistic overlay ───────────────────────────────────────
@@ -1378,13 +1573,15 @@ export function createClient<
 
     // ── store plumbing ───────────────────────────────────────────
     const listeners = new Set<() => void>()
-    let snapshot: SessionSnapshot<D, V, P> | null = null
+    let snapshot: SessionSnapshot<D, S, P> | null = null
     let status: ConnectionStatus = 'idle'
     let reconnects = 0
     let lastError: A2ClientError | null = null
     let inFlightPushes = 0
     let pushWireTail: Promise<void> = Promise.resolve()
-    let deferredHydration: SessionOptions<D, S> | undefined
+    let deferredHydration:
+      { settings: ResolvedSessionOptions<D, S>; version?: number } | undefined
+    let resumeInitialError: A2ClientError | undefined
     let hydrationNotification: ReturnType<typeof setTimeout> | undefined
 
     const emit = (): void => {
@@ -1398,14 +1595,21 @@ export function createClient<
       emit()
     }
 
-    const notifyHydrated = (): void => {
+    const notifyHydrated = (resume?: A2ClientError): void => {
+      resumeInitialError ??= resume
       // `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 = setTimeout(() => {
+        const failure = resumeInitialError
+        resumeInitialError = undefined
+        if (failure && active && status === 'paused' && lastError === failure)
+          reconnectStream()
+        else emit()
+      }, 0)
       ;(hydrationNotification as { unref?: () => void }).unref?.()
     }
 
@@ -1417,7 +1621,8 @@ export function createClient<
       const byIndex = new Map(serverEvents.map((event) => [event.index, event]))
       let changed = false
       for (const event of events) {
-        if (event.index > throughIndex) continue
+        // Also drops rows from responses that began before a newer clear.
+        if (event.index > throughIndex || event.index <= clearIndex) continue
         const existing = byIndex.get(event.index)
         if (existing?.id === event.id) continue
         byIndex.set(event.index, event)
@@ -1432,6 +1637,22 @@ export function createClient<
       return true
     }
 
+    /**
+     * Raise the latest known clear marker (a2-implementation.md §17.4):
+     * drop the served history it ended and every push acked below it.
+     * The boundary never moves backward.
+     */
+    const applyClearBoundary = (index: number): boolean => {
+      if (index <= clearIndex) return false
+      clearIndex = index
+      const kept = serverEvents.filter((event) => event.index > index)
+      serverEvents.splice(0, serverEvents.length, ...kept)
+      pending = pending.filter(
+        (entry) => entry.acked === undefined || entry.acked.index > index,
+      )
+      return true
+    }
+
     const overlayEvents = (): ContractEvent<D>[] => {
       // Acked entries first (they have a server-assigned order), then
       // unacked in push order with provisional indexes.
@@ -1440,19 +1661,20 @@ export function createClient<
         .map((p) => p.acked!)
         .toSorted((a, b) => a.index - b.index)
       const maxKnown = Math.max(stateIndex, acked.at(-1)?.index ?? stateIndex)
-      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>,
-        )
+      const waiting = pending.filter((p) => !p.acked)
+      const held = waiting.findIndex((p) => p.heldUntilAck)
+      // Later pushes may depend on a held one, so they stay hidden with it.
+      const unacked = (held === -1 ? waiting : waiting.slice(0, held)).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]
     }
 
@@ -1474,17 +1696,20 @@ export function createClient<
       const oldestLoaded = serverEvents[0]?.index ?? null
       return {
         loading: historyLoads > 0,
-        // Index 1 loaded — or a state index of 0, an empty log as far as
-        // this client knows — means nothing older is left to fetch.
-        complete: oldestLoaded === 1 || stateIndex === 0,
+        // The first event of the lifetime loaded — or a state index at
+        // its start, an empty lifetime as far as this client knows —
+        // means nothing older is left to fetch.
+        complete:
+          hydrated &&
+          (oldestLoaded === clearIndex + 1 || stateIndex === clearIndex),
         oldestLoaded,
       }
     }
 
-    const buildSnapshot = (): SessionSnapshot<D, V, P> => {
+    const buildSnapshot = (): SessionSnapshot<D, S, P> => {
       const overlay = overlayEvents()
       let state = foldedState
-      for (const event of overlay) {
+      for (const event of hydrated ? overlay : []) {
         if (event.index > stateIndex) state = reducer.fold(state, event)
       }
       const displayedOverlay = overlay.filter((event) => {
@@ -1501,8 +1726,8 @@ export function createClient<
         return true
       })
       return {
-        state:
-          reducer[clientStateProjection]?.(state) ?? (state as unknown as V),
+        state: projectClientState({ reducer, state }),
+        hydrated,
         events: [...serverEvents, ...displayedOverlay],
         index: stateIndex,
         history: historyState(),
@@ -1510,7 +1735,7 @@ export function createClient<
         ...(declaresPresence
           ? { presence: presenceState as PresenceMap<P> }
           : {}),
-      } as SessionSnapshot<D, V, P>
+      } as SessionSnapshot<D, S, P>
     }
 
     // ── presence ─────────────────────────────────────────────────
@@ -1696,28 +1921,93 @@ export function createClient<
       touch(sessionId)
     }
 
-    /** Pushes awaiting stream confirmation — resolved by `ingest` the
-     * moment the state index passes their batch. */
-    let confirmWatchers: Array<{ index: number; resolve: () => void }> = []
+    /** Pushes awaiting stream confirmation — resolved the moment the
+     * stream, by event or bootstrap snapshot, passes their batch. */
+    let confirmWatchers: Array<{
+      index: number
+      resolve: () => void
+      lease?: true
+    }> = []
+
+    const resolveConfirmed = (): void => {
+      const delivered = streamIndex ?? 0
+      const due = confirmWatchers.filter(
+        (watcher) => watcher.index <= delivered,
+      )
+      if (due.length === 0) return
+      confirmWatchers = confirmWatchers.filter(
+        (watcher) => watcher.index > delivered,
+      )
+      for (const watcher of due) watcher.resolve()
+    }
+
+    // State hydration does not subsume delivery: unobserved ACKs still
+    // keep an idle stream catching up even when their state is covered.
+    const retireCoveredPending = (): void => {
+      pending = pending.filter(
+        (entry) =>
+          !entry.acked ||
+          entry.acked.index > Math.min(stateIndex, streamIndex ?? stateIndex),
+      )
+    }
+
+    const adoptBaseline = (baseline: StateSnapshot<S>): void => {
+      hydrated = true
+      stateIndex = baseline.index
+      foldedState = baseline.state
+      for (const entry of pending)
+        if (entry.sent && !entry.acked) entry.heldUntilAck = true
+      retireCoveredPending()
+    }
+
+    const bootstrapState = (frame: StateSnapshotFrame): S => {
+      let state: S
+      try {
+        state = decodeState({
+          reducer,
+          state: frame.stateUndefined ? undefined : frame.state,
+        }) as S
+      } catch (error) {
+        throw asClientError(error, { code: 'INVALID_PAYLOAD' })
+      }
+      if (!reducer.stateSchema) return state
+      const result = validateSync(
+        reducer.stateSchema,
+        state,
+        'bootstrap stateSchema',
+      )
+      if (result.issues)
+        throw new A2ClientError(
+          'INVALID_PAYLOAD',
+          'bootstrap state failed stateSchema',
+          { details: result.issues },
+        )
+      return result.value
+    }
 
     /** The single ingest point: every server-confirmed event, in log
      * order, from the stream. */
-    const ingest = (event: ContractEvent<D>): void => {
-      if (event.index <= (streamIndex ?? 0)) return
-      streamIndex = event.index
-      if (event.index > stateIndex) {
-        stateIndex = event.index
-        serverEvents.push(event)
-        foldedState = reducer.fold(foldedState, event)
-      } else {
-        mergeServerEvents([event], stateIndex)
-      }
-      pending = pending.filter((p) => p.id !== event.id)
-      if (confirmWatchers.some((w) => w.index <= stateIndex)) {
-        const due = confirmWatchers.filter((w) => w.index <= stateIndex)
-        confirmWatchers = confirmWatchers.filter((w) => w.index > stateIndex)
-        for (const watcher of due) watcher.resolve()
+    // A batch is folded whole before listeners hear about it, once.
+    const ingest = (events: readonly ContractEvent<D>[]): void => {
+      let delivered = false
+      for (const event of events) {
+        if (event.index <= (streamIndex ?? 0)) continue
+        delivered = true
+        streamIndex = event.index
+        const cleared = isSessionCleared(event)
+        // A marker at or below a newer hydrated fold is already reflected in it.
+        if (event.index > stateIndex) {
+          stateIndex = event.index
+          if (!cleared) serverEvents.push(event)
+          foldedState = foldEvent(reducer, foldedState, event)
+        } else if (!cleared) {
+          mergeServerEvents([event], stateIndex)
+        }
+        if (cleared) applyClearBoundary(event.index)
+        pending = pending.filter((p) => p.id !== event.id)
       }
+      if (!delivered) return
+      resolveConfirmed()
       notify()
       touch(sessionId)
     }
@@ -1727,8 +2017,8 @@ export function createClient<
       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]
+        const schema = Object.hasOwn(contract.events, event.type)
+          ? contract.events[event.type]
           : undefined
         if (!schema) {
           throw new A2ClientError(
@@ -1804,7 +2094,7 @@ export function createClient<
             (acked) =>
               new Promise<ContractEvent<D>[]>((resolve) => {
                 const last = acked.at(-1)?.index ?? 0
-                if (stateIndex >= last) {
+                if ((streamIndex ?? 0) >= last) {
                   resolve(acked)
                   return
                 }
@@ -1819,6 +2109,26 @@ export function createClient<
       })
     }
 
+    // A cold socket opens only after a pending initial Promise settles.
+    const initialSettled = (epoch: number): Promise<void> =>
+      new Promise((resolve, reject) => {
+        const check = (): void => {
+          const failure =
+            leaseEpoch !== epoch || status === 'closed'
+              ? new DOMException('session closed', 'AbortError')
+              : !hydrated && preload?.error
+          if (failure) {
+            listeners.delete(check)
+            reject(failure)
+          } else if (hydrated || !preload) {
+            listeners.delete(check)
+            resolve()
+          }
+        }
+        listeners.add(check)
+        check()
+      })
+
     const push = (...events: AppendInput<D>[]): PushResult<D> => {
       touch(sessionId)
       return withConfirmed(
@@ -1841,11 +2151,27 @@ export function createClient<
           })
           pending.push(...entries)
           inFlightPushes += 1
+          let acknowledgedIndex: number | undefined
+          const pushEpoch = leaseEpoch
+          const releaseConnection =
+            !hydrated || transport.awaitReady || active
+              ? runtime.connect()
+              : undefined
 
           try {
             refreshIdleStream()
             notify() // optimistic — the view updates before the network moves
             await waitForPriorPush
+            if (transport.awaitReady) {
+              await initialSettled(pushEpoch)
+              await transport.awaitReady(
+                sessionId,
+                STREAM_TIMINGS.stallTimeoutMs,
+              )
+            }
+            if (leaseEpoch !== pushEpoch)
+              throw new DOMException('session closed', 'AbortError')
+            for (const entry of entries) entry.sent = true
             const acked = await post({
               sessionId,
               events: entries.map(({ id, type, payload }) => ({
@@ -1854,16 +2180,12 @@ export function createClient<
                 payload,
               })),
             })
+            acknowledgedIndex = acked.at(-1)?.index
             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
             }
-            pending = pending.filter(
-              (entry) =>
-                entry.acked === undefined ||
-                entry.acked.index >
-                  Math.min(stateIndex, streamIndex ?? stateIndex),
-            )
+            retireCoveredPending()
             if ((acked.at(-1)?.index ?? 0) > (streamIndex ?? stateIndex))
               refreshIdleStream()
             notify()
@@ -1875,12 +2197,25 @@ export function createClient<
             notify()
             throw err
           } finally {
+            if (
+              releaseConnection &&
+              pushEpoch === leaseEpoch &&
+              acknowledgedIndex !== undefined &&
+              acknowledgedIndex > (streamIndex ?? 0)
+            ) {
+              confirmWatchers.push({
+                index: acknowledgedIndex,
+                resolve: releaseConnection,
+                lease: true,
+              })
+            } else releaseConnection?.()
             releasePush()
             inFlightPushes -= 1
             if (inFlightPushes === 0 && deferredHydration) {
               const next = deferredHydration
               deferredHydration = undefined
-              runtime.hydrate(next)
+              if (next.version === undefined || next.version === initialVersion)
+                if (applyInitial(next)) notifyHydrated()
             }
             touch(sessionId)
           }
@@ -1944,16 +2279,20 @@ export function createClient<
         // everything above it, and the optimistic overlay must never
         // collide with a backscrolled row.
         const lte = Math.min(upper - 1, stateIndex)
-        const gte = Math.max(1, upper - (limit ?? DEFAULT_HISTORY_LIMIT))
+        const gte = Math.max(
+          clearIndex + 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 })
+          const page = await readHistory({ sessionId, ...missing })
+          if (page.clearIndex !== undefined) applyClearBoundary(page.clearIndex)
           mergeServerEvents(
-            rows.map((row) => eventFromWire(row) as ContractEvent<D>),
+            page.events.map((row) => eventFromWire(row) as ContractEvent<D>),
             stateIndex,
           )
           return eventsBetween(gte, lte)
@@ -2031,9 +2370,26 @@ export function createClient<
         }
         let wasLive = false
         try {
+          // oxlint-disable-next-line no-unmodified-loop-condition -- hydration changes while this connection waits
+          while (!hydrated && preload && !preload.error)
+            await waitForInitial(controller.signal)
+          if (generation !== run || controller.signal.aborted) break
+          if (!hydrated && preload?.error) {
+            lastError = preload.error
+            status = 'paused'
+            notify()
+            return
+          }
+          if (hydrated && streamIndex === undefined) streamIndex = stateIndex
+          // Acks at or before this start are covered by the baseline and
+          // are never streamed.
+          resolveConfirmed()
+          if (generation !== run) break
+          bootstrapGeneration = streamIndex === undefined ? run : undefined
           const frames = transport.connect({
             sessionId,
-            startAfter: (streamIndex ??= stateIndex),
+            startAfter: streamIndex,
+            reducer: reducer.name,
             signal: controller.signal,
           })
           for await (const frame of frames) {
@@ -2041,6 +2397,41 @@ export function createClient<
             // Every frame counts — heartbeats included. Liveness is
             // about the connection, not about events.
             armStall()
+            if (frame.kind === 'snapshot') {
+              if (
+                frame.sessionId !== sessionId ||
+                frame.name !== reducer.name ||
+                !isStateSnapshotFrame(frame)
+              )
+                throw new A2ClientError(
+                  'INVALID_PAYLOAD',
+                  'bootstrap snapshot belongs to another session or reducer',
+                )
+              if (bootstrapGeneration !== run)
+                throw new A2ClientError(
+                  'INVALID_PAYLOAD',
+                  'unexpected bootstrap snapshot',
+                )
+              const baseline =
+                !hydrated || frame.index >= stateIndex
+                  ? { state: bootstrapState(frame), index: frame.index }
+                  : undefined
+              streamIndex = frame.index
+              bootstrapGeneration = undefined
+              applyClearBoundary(frame.clearIndex ?? 0)
+              if (baseline) adoptBaseline(baseline)
+              resolveConfirmed()
+              notify()
+              if (generation !== run) break
+            }
+            if (!hydrated || streamIndex === undefined) {
+              if (frame.kind === 'event' || frame.kind === 'events')
+                throw new A2ClientError(
+                  'INVALID_PAYLOAD',
+                  'received an event before the bootstrap snapshot',
+                )
+              continue
+            }
             if (!wasLive) {
               // The first frame is the connection signal: the transport
               // yields it the moment the stream is established.
@@ -2059,7 +2450,10 @@ export function createClient<
             }
             if (frame.kind === 'event') {
               streamIdle = false
-              ingest(eventFromWire(frame.event) as ContractEvent<D>)
+              ingest([eventFromWire(frame.event) as ContractEvent<D>])
+            } else if (frame.kind === 'events') {
+              streamIdle = false
+              ingest(frame.events as ContractEvent<D>[])
             } else if (frame.kind === 'activity') {
               streamIdle = frame.idle
               if (
@@ -2091,11 +2485,15 @@ export function createClient<
               ? new A2ClientError(
                   'TIMEOUT',
                   `stream stalled: no data for ${STREAM_TIMINGS.stallTimeoutMs}ms`,
-                  { phase: 'stream', timeoutMs: STREAM_TIMINGS.stallTimeoutMs },
+                  {
+                    phase: 'stream',
+                    timeoutMs: STREAM_TIMINGS.stallTimeoutMs,
+                  },
                 )
               : asClientError(err)
           }
         } finally {
+          if (bootstrapGeneration === run) bootstrapGeneration = undefined
           clearTimeout(stall)
         }
         if (generation !== run) break
@@ -2173,7 +2571,114 @@ export function createClient<
       previous?.abort()
     }
 
-    const runtime: SessionRuntime<D, S, P, V> = {
+    const applyInitial = ({
+      settings: next,
+      version,
+    }: {
+      settings: ResolvedSessionOptions<D, S>
+      version?: number
+    }): boolean => {
+      const nextIndex = next.initial?.index ?? 0
+      if (hydrated && nextIndex > stateIndex && inFlightPushes > 0) {
+        if (
+          !deferredHydration ||
+          nextIndex > (deferredHydration.settings.initial?.index ?? 0)
+        ) {
+          deferredHydration = {
+            settings: next,
+            ...(version === undefined ? {} : { version }),
+          }
+        }
+        return false
+      }
+
+      // The boundary applies even to an older fold: it only removes history.
+      const boundaryChanged = applyClearBoundary(next.initial?.clearIndex ?? 0)
+      const historyChanged =
+        mergeServerEvents(
+          next.initialEvents,
+          Math.min(nextIndex, stateIndex),
+        ) || boundaryChanged
+      if (next.initial != null && bootstrapGeneration === undefined)
+        streamIndex ??= nextIndex
+      if (next.initial == null || (hydrated && nextIndex <= stateIndex)) {
+        return historyChanged
+      }
+
+      adoptBaseline(next.initial)
+      mergeServerEvents(next.initialEvents, stateIndex)
+      return true
+    }
+
+    const invalidateInitial = (): void => {
+      initialVersion++
+      preload?.cancel()
+      preload = undefined
+      if (deferredHydration?.version !== undefined)
+        deferredHydration = undefined
+    }
+
+    const settleInitial = (
+      result:
+        { source: object; value: unknown } | { source: object; error: unknown },
+    ): void => {
+      const entry = preload
+      if (
+        !entry ||
+        entry.source !== result.source ||
+        entry.version !== initialVersion
+      )
+        return
+      entry.cancel()
+      const cold = !hydrated
+      let changed = false
+      if ('error' in result) {
+        if (cold) entry.error = asClientError(result.error)
+        else preload = undefined
+      } else {
+        try {
+          assertSessionSeed({ initial: result.value })
+          if (isInitialPromise(result.value as InitialSnapshot<unknown>))
+            throw new TypeError('an initial Promise must resolve to a snapshot')
+          preload = undefined
+          changed = applyInitial({
+            settings: {
+              ...entry.settings,
+              initial: result.value as StateSnapshot<S> | null | undefined,
+            },
+            version: entry.version,
+          })
+        } catch (error) {
+          if (cold) {
+            preload = entry
+            entry.error = asClientError(error, { code: 'INVALID_PAYLOAD' })
+          } else preload = undefined
+        }
+      }
+      if (cold || changed) notifyHydrated()
+    }
+
+    const waitForInitial = (signal: AbortSignal): Promise<void> =>
+      new Promise((resolve, reject) => {
+        let settled = false
+        const finish = (): void => {
+          if (
+            settled ||
+            (!signal.aborted && !hydrated && preload && !preload.error)
+          )
+            return
+          settled = true
+          listeners.delete(finish)
+          signal.removeEventListener('abort', finish)
+          if (signal.aborted) reject(signal.reason)
+          else resolve()
+        }
+        listeners.add(finish)
+        signal.addEventListener('abort', finish, { once: true })
+        finish()
+      })
+
+    const runtime: SessionRuntime<D, S, P> = {
       sessionId,
       // Only on presence-declaring contracts — the type surface
       // promises no runtime-inert members (a2-api.md §12).
@@ -2217,55 +2722,77 @@ export function createClient<
         }
       },
       close() {
+        invalidateInitial()
+        resumeInitialError = undefined
         leases = 0
         leaseEpoch += 1
+        confirmWatchers = confirmWatchers.filter((watcher) => !watcher.lease)
         stopStream()
       },
+      resolveInitial: settleInitial,
       hydrate(next) {
+        assertSessionSeed(next)
         touch(sessionId)
         if (!next) return
         participant ??= next.participant
-        const nextIndex = next.initialIndex ?? 0
-        if (nextIndex > stateIndex && inFlightPushes > 0) {
-          if (
-            !deferredHydration ||
-            nextIndex > (deferredHydration.initialIndex ?? 0)
-          ) {
-            deferredHydration = next
+        const input = next.initial
+        const resume =
+          !hydrated && status === 'paused' && preload?.error === lastError
+            ? preload.error
+            : undefined
+        if (isInitialPromise(input)) {
+          if (seenInitials.has(input)) {
+            if (preload?.source === input && next.initialEvents !== undefined)
+              preload.settings.initialEvents = next.initialEvents
+            if (mergeServerEvents(next.initialEvents, stateIndex))
+              notifyHydrated()
+            return
           }
+          invalidateInitial()
+          seenInitials.add(input)
+          const { initial: _initial, ...settings } = next
+          const entry: PendingInitial<D, S> = {
+            source: input,
+            version: initialVersion,
+            settings,
+            cancel() {},
+          }
+          preload = entry
+          entry.cancel = observeInitial({
+            promise: input,
+            settled: (result) => settleInitial({ source: input, ...result }),
+          })
+          if (resume) notifyHydrated(resume)
           return
         }
-
-        const historyChanged = mergeServerEvents(
-          next.initialEvents,
-          Math.min(nextIndex, stateIndex),
-        )
-        if (next.initialState !== undefined) streamIndex ??= nextIndex
-        if (next.initialState === undefined || nextIndex <= stateIndex) {
-          if (historyChanged) notifyHydrated()
-          return
+        if (input != null) {
+          const repeated = seenInitials.has(input)
+          seenInitials.add(input)
+          if (repeated || (hydrated && input.index <= stateIndex)) {
+            if (
+              deferredHydration?.settings.initial === input &&
+              next.initialEvents !== undefined
+            )
+              deferredHydration.settings.initialEvents = next.initialEvents
+            const boundaryChanged = applyClearBoundary(input.clearIndex ?? 0)
+            if (
+              mergeServerEvents(
+                next.initialEvents,
+                Math.min(input.index, stateIndex),
+              ) ||
+              boundaryChanged
+            )
+              notifyHydrated()
+            return
+          }
         }
-
-        // State hydration does not subsume delivery: unobserved ACKs still
-        // keep an idle stream catching up even when their state is covered.
-        stateIndex = nextIndex
-        foldedState = next.initialState
-        mergeServerEvents(next.initialEvents, stateIndex)
-        pending = pending.filter(
-          (entry) =>
-            !entry.acked ||
-            entry.acked.index > Math.min(stateIndex, streamIndex ?? stateIndex),
+        if (input !== undefined) invalidateInitial()
+        if (
+          applyInitial({ settings: { ...next, initial: input } }) ||
+          resume ||
+          input === null
         )
-        if (confirmWatchers.some((watcher) => watcher.index <= stateIndex)) {
-          const due = confirmWatchers.filter(
-            (watcher) => watcher.index <= stateIndex,
-          )
-          confirmWatchers = confirmWatchers.filter(
-            (watcher) => watcher.index > stateIndex,
-          )
-          for (const watcher of due) watcher.resolve()
-        }
-        notifyHydrated()
+          notifyHydrated(resume)
       },
       canEvict() {
         return (
@@ -2277,12 +2804,13 @@ export function createClient<
           presenceTimer === undefined
         )
       },
-    } as SessionRuntime<D, S, P, V>
+    } as SessionRuntime<D, S, P>
 
+    if (isInitialPromise(supplied)) runtime.hydrate(sessionOptions)
     return runtime
   }
 
-  return {
+  const client: A2Client<D, S, P> = {
     session(sessionId, sessionOptions) {
       const existing = sessions.get(sessionId)
       if (existing) {
@@ -2297,4 +2825,13 @@ export function createClient<
       return runtime
     },
   }
+  registerRenderSessionFactory({
+    client,
+    factory: (sessionId, settings) =>
+      makeSession(sessionId, settings as SessionOptions<D, S>),
+    resolveInitial: ({ session, source, value }) => {
+      ;(session as SessionRuntime<D, S, P>).resolveInitial({ source, value })
+    },
+  })
+  return client
 }