@ultimat3/realtime 20.2.0 → 21.0.0

package/src/client-channels.ts

@@ -0,0 +1,289 @@
+// The client's declared channels: one membership per topic however many components hold it, the
+// per-channel cursor that decides duplicate from new, and the catch-up read a `replay-gap` or a
+// new epoch triggers. `records` frames go to the store and nowhere else; `events` go to handlers.
+
+import { type PresenceEvent, readPresence } from './channel-presence';
+import type { JsonObject } from './json';
+import { carriedBy, type RecordKey } from './record-key';
+import type { RecordStore } from './record-store';
+import type {
+  ChannelEventsFrame,
+  ChannelRecordsFrame,
+  ReplayGapFrame,
+  SubscribeFrame,
+} from './sync-protocol';
+import { PROTOCOL_VERSION } from './wire-version';
+
+/** What a browser needs of a `channel()` declaration: its name, its topic rule, its catch-up read. */
+export interface ChannelRef<K extends string = string> {
+  readonly name: string;
+  readonly catchUp: string;
+  topic(params: Readonly<Record<K, string>>): string;
+}
+
+export type ChannelState = 'joining' | 'live' | 'catching-up' | 'offline' | 'failed';
+
+export interface ChannelHandlers {
+  /** An app's own ephemeral `events` frame on this channel. Never written to the store. */
+  readonly onEvent?: (event: JsonObject) => void;
+  /** A presence roster or delta — the `events` frames `readPresence` recognises. */
+  readonly onPresence?: (event: PresenceEvent) => void;
+}
+
+/** Everything the book reaches on the client. Narrow, like `ClientFrameTarget`. */
+export interface ChannelBookDeps {
+  readonly store: RecordStore;
+  send(frame: SubscribeFrame): void;
+  connected(): boolean;
+  /** Re-run the channel's catch-up read; its records land in the store through the transport. */
+  catchUp(query: string, params: Readonly<Record<string, string>>): Promise<unknown>;
+  report(error: unknown): void;
+}
+
+interface Entry {
+  readonly topic: string;
+  readonly name: string;
+  readonly catchUp: string;
+  readonly params: Readonly<Record<string, string>>;
+  readonly holders: Set<ChannelHandlers>;
+  readonly listeners: Set<() => void>;
+  state: ChannelState;
+  error: unknown;
+  /** The epoch the cursor counts in; `null` before the first frame. */
+  epoch: string | null;
+  /** Highest seq with no hole below it — what a resubscribe resumes from. */
+  contiguous: number | null;
+  /** Applied seqs above `contiguous`: a replay that fills a hole is new, one above is a duplicate. */
+  readonly above: Set<number>;
+  /** Frames that arrived while the catch-up read was in flight, applied after it lands. */
+  buffered: ChannelRecordsFrame[] | null;
+}
+
+export interface ChannelMembership extends Disposable {
+  readonly topic: string;
+  state(): ChannelState;
+  error(): unknown;
+  onChange(listener: () => void): () => void;
+  release(): void;
+}
+
+export class ChannelBook {
+  readonly #deps: ChannelBookDeps;
+  readonly #byTopic = new Map<string, Entry>();
+
+  constructor(deps: ChannelBookDeps) {
+    this.#deps = deps;
+  }
+
+  /** Join (or share) one channel. N holders on one topic are ONE subscribe frame. */
+  hold<K extends string>(
+    ref: ChannelRef<K>,
+    params: Readonly<Record<K, string>>,
+    handlers: ChannelHandlers = {},
+  ): ChannelMembership {
+    const topic = ref.topic(params);
+    let entry = this.#byTopic.get(topic);
+    if (entry === undefined) {
+      entry = {
+        topic,
+        name: ref.name,
+        catchUp: ref.catchUp,
+        params,
+        holders: new Set(),
+        listeners: new Set(),
+        state: this.#deps.connected() ? 'joining' : 'offline',
+        error: undefined,
+        epoch: null,
+        contiguous: null,
+        above: new Set(),
+        buffered: null,
+      };
+      this.#byTopic.set(topic, entry);
+      if (this.#deps.connected()) this.#deps.send(this.#frame(entry, 'add', true));
+    }
+    const held = entry;
+    held.holders.add(handlers);
+    let open = true;
+    const release = (): void => {
+      if (!open) return;
+      open = false;
+      held.holders.delete(handlers);
+      if (held.holders.size > 0) return;
+      this.#byTopic.delete(topic);
+      this.#deps.send(this.#frame(held, 'drop', false));
+    };
+    return {
+      topic,
+      state: () => held.state,
+      error: () => held.error,
+      onChange: (listener) => {
+        held.listeners.add(listener);
+        return () => {
+          held.listeners.delete(listener);
+        };
+      },
+      release,
+      [Symbol.dispose]: release,
+    };
+  }
+
+  /** Every membership again, on a new socket — resuming from each cursor. */
+  resubscribe(): void {
+    for (const entry of this.#byTopic.values()) {
+      this.#set(entry, 'joining');
+      this.#deps.send(this.#frame(entry, 'add', true));
+    }
+  }
+
+  /** The presence heartbeat: repeat each membership with NO `since`, so the node replays nothing. */
+  beat(): void {
+    for (const entry of this.#byTopic.values()) this.#deps.send(this.#frame(entry, 'add', false));
+  }
+
+  offline(): void {
+    for (const entry of this.#byTopic.values()) {
+      if (entry.state !== 'failed') this.#set(entry, 'offline');
+    }
+  }
+
+  /** The sid a channel is subscribed under — what a refusal `ack` names. */
+  refused(sid: string, error: unknown): boolean {
+    const entry = [...this.#byTopic.values()].find((candidate) => sidOf(candidate) === sid);
+    if (entry === undefined) return false;
+    entry.error = error;
+    this.#set(entry, 'failed');
+    return true;
+  }
+
+  records(frame: ChannelRecordsFrame): void {
+    const entry = this.#byTopic.get(frame.channel);
+    if (entry === undefined) return;
+    if (entry.buffered !== null) {
+      entry.buffered.push(frame);
+      return;
+    }
+    if (entry.epoch !== null && entry.epoch !== frame.epoch) {
+      // A new epoch: the node restarted or the client landed on another one. Its seqs mean
+      // nothing against ours, so the channel is re-read and this frame waits behind the read.
+      this.#catchUp(entry, [frame]);
+      return;
+    }
+    this.#apply(entry, frame);
+  }
+
+  gap(frame: ReplayGapFrame): void {
+    const entry = this.#byTopic.get(frame.channel);
+    if (entry === undefined) return;
+    this.#catchUp(entry, [], frame.epoch);
+  }
+
+  event(frame: ChannelEventsFrame): void {
+    const entry = this.#byTopic.get(frame.channel);
+    const presence = readPresence(frame.event);
+    for (const holder of entry?.holders ?? []) {
+      if (presence !== null) holder.onPresence?.(presence);
+      else holder.onEvent?.(frame.event);
+    }
+  }
+
+  /** Where a resubscribe resumes: the highest contiguous seq, in the epoch it counts in. */
+  since(topic: string): { readonly epoch: string; readonly seq: number } | undefined {
+    const entry = this.#byTopic.get(topic);
+    if (entry?.epoch === null || entry?.contiguous === null || entry === undefined)
+      return undefined;
+    return { epoch: entry.epoch, seq: entry.contiguous };
+  }
+
+  #apply(entry: Entry, frame: ChannelRecordsFrame): void {
+    if (entry.epoch === null) {
+      entry.epoch = frame.epoch;
+      entry.contiguous = frame.seq - 1;
+    }
+    const contiguous = entry.contiguous ?? frame.seq - 1;
+    // A duplicate is dropped; a replayed seq filling a hole is new. A numeric hole on its own is
+    // never a gap — a row this socket may not see is skipped for it; only `replay-gap` is.
+    if (frame.seq <= contiguous || entry.above.has(frame.seq)) return;
+    const store = this.#deps.store;
+    store.batch(() => {
+      for (const [type, rows] of Object.entries(frame.adopt ?? {})) store.adopt(type, rows);
+      for (const [type, keys] of Object.entries(frame.remove ?? {})) store.remove(type, keys);
+      // This page's own write, echoed: settled in the same batch as its rows, so its twin is
+      // never replayed over the truth that already holds it.
+      if (frame.write !== undefined) {
+        const carried = new Set<RecordKey>();
+        carriedBy({ records: frame.adopt ?? {}, removed: frame.remove ?? {} }, carried);
+        store.settleWrite(frame.write, carried);
+      }
+    });
+    entry.above.add(frame.seq);
+    let next = contiguous;
+    while (entry.above.delete(next + 1)) next += 1;
+    entry.contiguous = next;
+    if (entry.state !== 'live') this.#set(entry, 'live');
+  }
+
+  /**
+   * Re-read the channel through its catch-up query, holding every frame that arrives meanwhile;
+   * then apply those, in order, over the read. The cursor restarts in the new epoch.
+   */
+  #catchUp(entry: Entry, pending: ChannelRecordsFrame[], epoch?: string): void {
+    if (entry.buffered !== null) {
+      entry.buffered.push(...pending);
+      return;
+    }
+    entry.buffered = [...pending];
+    entry.epoch = epoch ?? pending[0]?.epoch ?? entry.epoch;
+    entry.contiguous = null;
+    entry.above.clear();
+    this.#set(entry, 'catching-up');
+    this.#deps.catchUp(entry.catchUp, entry.params).then(
+      () => this.#drain(entry),
+      (error: unknown) => {
+        this.#deps.report(error);
+        this.#drain(entry);
+      },
+    );
+  }
+
+  #drain(entry: Entry): void {
+    const held = entry.buffered ?? [];
+    entry.buffered = null;
+    // Frames of an epoch other than the one caught up to predate it; the read already holds them.
+    const current = held.filter((frame) => frame.epoch === entry.epoch);
+    current.sort((a, b) => a.seq - b.seq);
+    for (const frame of current) {
+      if (entry.contiguous === null) entry.contiguous = frame.seq - 1;
+      this.#apply(entry, frame);
+    }
+    if (entry.state === 'catching-up') this.#set(entry, 'live');
+  }
+
+  #set(entry: Entry, state: ChannelState): void {
+    entry.state = state;
+    for (const listener of entry.listeners) listener();
+  }
+
+  #frame(entry: Entry, op: 'add' | 'drop', resume: boolean): SubscribeFrame {
+    const since = resume && op === 'add' ? this.since(entry.topic) : undefined;
+    return {
+      type: 'subscribe',
+      v: PROTOCOL_VERSION,
+      op,
+      sid: sidOf(entry),
+      target: {
+        kind: 'channel',
+        channel: entry.name,
+        params: entry.params,
+        ...(since === undefined ? {} : { since }),
+      },
+    };
+  }
+}
+
+/** A channel membership's sid is its topic behind this — what the socket engine routes on too. */
+export const CHANNEL_SID_PREFIX = 'channel:';
+
+/** One sid per topic: re-sending it after a reconnect is the same membership, not a second one. */
+function sidOf(entry: Entry): string {
+  return `${CHANNEL_SID_PREFIX}${entry.topic}`;
+}

package/src/client-contract.ts

@@ -1,42 +1,45 @@
 // What a client IS, as types: the injected seams, the options, and the handles a subscription
-// gives back. Declared apart from the client that implements them for the same reason
-// `live-contract.ts` is — the hooks, the typed projection, the type pins and the mutation path all
-// need these shapes, and none of them needs the connection lifecycle that runs underneath.
+// gives back. Declared apart from the client that implements them, so a hook module can name the
+// shapes without importing the connection lifecycle underneath — and the bytes that come with it.
 
-import type { Clock } from '@ultimat3/core';
+import type { Clock, Row } from '@ultimat3/core/page';
 import type { LiveCursor } from './cursor';
-import type { JsonValue, Row } from './json';
 import type { LiveState } from './live-rows';
-import type { LocalStore, LocalTx, TableMap } from './local-store';
-import type { OfflineQueue } from './offline-queue';
-import type { ConflictStrategy, RebaseLog } from './rebase';
+import type { RecordStore } from './record-store';
 import type { BackoffPolicy, Rng, Scheduler } from './thundering-herd';
 
-/** Injected reactive primitive. `createSignal` from Solid satisfies this exactly. */
+/**
+ * A reactive primitive: `createSignal` narrowed to two functions. Installed PER ISLAND BUNDLE
+ * (`installRealtime`), because every island carries its own solid-js and a signal made by one
+ * bundle's copy is invisible to another's effects.
+ */
 export type SignalFactory = <T>(initial: T) => [get: () => T, set: (next: T) => void];
 
-/** Injected socket, so tests drive the protocol without a network. */
+/**
+ * The socket seam. `browser-socket.ts` is the one production implementation — the only
+ * `new WebSocket` in the framework — and test harnesses supply their own. Not on the public API:
+ * an app never constructs a socket, the page does.
+ */
 export interface ClientSocket {
   send(data: string): void;
   close(code?: number, reason?: string): void;
   onOpen(handler: () => void): void;
   onMessage(handler: (data: string) => void): void;
   onClose(handler: (code: number) => void): void;
-  /**
-   * Bytes queued but not yet on the wire — `WebSocket.bufferedAmount`. Optional because a socket
-   * that cannot answer is treated as never backed up; supplying it is what lets the mutation drain
-   * stop instead of pushing a queue the tab is not draining into one it cannot see.
-   */
   readonly bufferedAmount?: number;
 }
 
-export interface LiveHandle<R extends Row = Row> extends Disposable {
-  /** The reactive accessor. In an app this is the Solid signal `useLive` returns. */
-  readonly rows: () => readonly R[];
-  readonly state: () => LiveState;
-  readonly cursor: () => LiveCursor | null;
+/** One live query's window, as plain reads plus a change listener — no reactive runtime here. */
+export interface LiveHandle<R extends object = Row> extends Disposable {
+  rows(): readonly R[];
+  state(): LiveState;
+  cursor(): LiveCursor | null;
+  /** What the node answered when it refused the subscription; `undefined` unless `failed`. */
+  error(): unknown;
+  /** Called after anything the reads above answer has moved. Returns the unsubscribe. */
+  onChange(listener: () => void): () => void;
   unsubscribe(): void;
-  /** The same call as `unsubscribe`, so `using sub = client.useLive(...)` just works. */
+  /** The same call as `unsubscribe`, so `using sub = client.subscribeLive(...)` just works. */
   [Symbol.dispose](): void;
 }
 
@@ -47,59 +50,26 @@ export interface LiveQueryRef {
   readonly name: string;
 }
 
-export interface MutatorRef<T extends TableMap = TableMap> {
-  readonly name: string;
-  /** Optimistic twin. Pure — no I/O, no Date.now(), no Math.random(). */
-  local?: (tx: LocalTx<T>, input: JsonValue) => void;
-  readonly entity?: string;
-  readonly conflict?: ConflictStrategy;
-}
-
-/**
- * What the HOOKS need a client to be — every member `hooks.ts` reads, and not one more.
- *
- * A structural interface rather than the `LiveClient` class, and the reason is measured: a value
- * import of that class from the hook seam put the whole connection lifecycle (heartbeat, topic
- * book, mutation sender, wire protocol, backoff) into every island that calls `useLive`, taking a
- * `useLive`-only browser chunk from 8,368 B to 26,571 B. The server render's client
- * (`server-render-client.ts`) satisfies this and imports no lifecycle at all, so the browser pays
- * nothing for a shape only the server uses. `type-pins.ts` pins that `LiveClient` still satisfies
- * it, so a member added there and not here is a build error rather than a hook that cannot see it.
- */
-export interface LiveClientLike<T extends TableMap = TableMap> {
-  readonly signal: SignalFactory;
-  readonly queue: OfflineQueue | undefined;
-  readonly connected: boolean;
-  readonly reconnectAt: () => number | null;
-  readonly appUpdateAvailable: () => string | null;
-  useLive<R extends Row>(query: LiveQueryRef, input: JsonValue): LiveHandle<R>;
-  mutate(mutator: MutatorRef<T>, input: JsonValue, key?: string): Promise<void>;
-  drain(): Promise<void>;
-  onQueueChange(listener: () => void): () => void;
-}
-
-export interface LiveClientOptions<T extends TableMap = TableMap> {
-  readonly signal: SignalFactory;
+export interface LiveClientOptions {
   /** Called for every connect attempt; returning a fresh socket keeps reconnect logic here. */
   readonly connect: () => ClientSocket;
   readonly buildId: string;
   readonly actorId?: string | null;
-  /** Tier 3 only. Without these, mutations are server-only and nothing is queued offline. */
-  readonly store?: LocalStore<T>;
-  readonly queue?: OfflineQueue;
-  readonly log?: RebaseLog<T>;
+  /** The page's record store every window renders out of. A client builds its own when absent. */
+  readonly store?: RecordStore;
+  /** Default `browserBackoff`: capped at `BROWSER_RECONNECT_MAX_MS`, never the server's 30s. */
   readonly backoff?: BackoffPolicy;
   readonly rng?: Rng;
   readonly clock?: Clock;
   /** How a pending reconnect is armed. Defaults to `setTimeout`; tests fire theirs by hand. */
   readonly scheduler?: Scheduler;
-  /**
-   * How often a live socket re-announces itself, in ms. `0` disables it. Defaults to
-   * `DEFAULT_HEARTBEAT_MS`, 15s. The one knob for the beat: `realtime.heartbeatMs` in
-   * `app.config.ts` was deleted 2026-08-19 because nothing read it, so this is not a restatement
-   * of a server value — browser code could never have reached one.
-   */
+  /** How often a live socket re-announces itself, in ms. `0` disables it. Default 15s. */
   readonly heartbeatMs?: number;
-  /** Where a dial failure inside the reconnect timer is reported. Defaults to `reportToConsole`. */
+  /** Where a failure nobody awaits is reported. Defaults to `console.error`. */
   readonly onError?: (error: unknown) => void;
+  /**
+   * A channel's catch-up read, re-run on `replay-gap` or a new epoch: the named query, through
+   * core's transport, so its records land in the store. `page-socket.ts` supplies the real one.
+   */
+  readonly catchUp: (query: string, params: Readonly<Record<string, string>>) => Promise<unknown>;
 }

package/src/client-frames.ts

@@ -3,42 +3,34 @@
 // every piece of the client a frame may touch, so the blast radius of a new frame kind is a
 // reviewable list rather than "whatever the router could reach through `this`".
 
+import type { ChannelBook } from './client-channels';
 import { CLOSE } from './close-codes';
 import { advance } from './cursor';
-import type { JsonObject, JsonValue } from './json';
 import type { Registration, RowWindows } from './live-rows';
-import type { LocalStore, TableMap } from './local-store';
-import type { OfflineQueue } from './offline-queue';
-import { type RebaseLog, reconcile, rollbackMutation } from './rebase';
-import type { Frame, PresenceMember } from './sync-protocol';
+import type { Frame } from './sync-protocol';
 
 /** Declared with the window it projects; re-exported here because the router is what writes it. */
 export type { LiveState, Registration } from './live-rows';
 
 /**
  * The code a `reconnect` frame closes with: `CLOSE.drain`, the same number the node uses for a
- * drain it closes itself, so a log reads one code for one event whichever side closed first. It
- * was 1001, and a browser refuses that from script: `WebSocket.close()` throws
- * `InvalidAccessError: The close code must be either 1000, or between 3000 and 4999` — measured
- * in Chrome, an uncaught exception in every tab on every node drain. The reconnect still happened,
- * because the node closed the socket a moment later; the exception was the only trace.
- * `HEARTBEAT_TIMEOUT_CODE` in `client.ts` is the sibling, for the other close the client makes.
+ * drain it closes itself, so a log reads one code for one event whichever side closed first. A
+ * browser refuses 1001 from script (`InvalidAccessError`), which is why it is not that.
  */
 export const RECONNECT_CODE = CLOSE.drain;
 
 /**
  * Everything an inbound frame is allowed to reach. Narrow on purpose — a router that took the
  * client itself could touch the reconnect timer, the socket and the outbound path, none of which
- * a received frame has any business writing.
+ * a received frame has any business writing. There is no write path here at all: the socket is
+ * read-only, and a client write is an HTTP call (`useMutation`).
  */
-export interface ClientFrameTarget<T extends TableMap = TableMap> {
+export interface ClientFrameTarget {
   registration(sid: string): Registration | undefined;
-  /** The projection every live window renders through. Rows live in its map, never on a frame. */
+  /** The projection every live window renders through. Rows live in the store, never on a frame. */
   readonly windows: RowWindows;
-  topicHandlers(topic: string): ReadonlySet<(message: JsonObject) => void> | undefined;
-  readonly queue: OfflineQueue | undefined;
-  readonly store: LocalStore<T> | undefined;
-  readonly log: RebaseLog<T> | undefined;
+  /** The declared channels this client holds: their cursors, their handlers, their catch-up. */
+  readonly channels: ChannelBook;
   /** The client's clock. A cursor carries `at`, and nothing here may read `Date.now()`. */
   now(): number;
   /** A newer build is live; the app decides when to reload. */
@@ -46,62 +38,26 @@ export interface ClientFrameTarget<T extends TableMap = TableMap> {
   /** The node assigned this socket its own delay before closing it. */
   scheduleReconnect(afterMs: number | null): void;
   closeSocket(code: number, reason: string): void;
-  notifyQueueChange(): void;
-  /** Where a promise nobody awaits reports its failure. The client's `onError`, never a swallow. */
-  detach(work: Promise<unknown>): void;
+  /** Where a refusal that names nothing this client holds is reported. */
+  report(error: unknown): void;
 }
 
-/**
- * The server refused a mutation: undo its optimistic half. Tier 2 has neither a store nor a log,
- * so there is nothing optimistic to undo and the queue entry is the whole record.
- */
-function rollbackFailed<T extends TableMap>(key: string, target: ClientFrameTarget<T>): void {
-  const store = target.store;
-  const log = target.log;
-  if (!store || !log) return;
-  // One batch for the whole undo: the rollback and every mutator replayed behind it are one
-  // frame's worth of change, so a live window holding those rows renders once.
-  store.identity.batch(() => {
-    rollbackMutation({ store, log, key });
-  });
-}
-
-/**
- * The server took it, so the write is no longer optimistic: the journal goes (there is nothing to
- * roll back TO any more — this write is what the server has) and the rebase entry goes with it, or
- * every later reconcile replays a mutation the server already applied, over rows that have moved
- * on. The row itself stays exactly as the twin left it — an accepted write does not flicker.
- *
- * Both calls are no-ops for a key nothing holds, which is what makes this safe as the tail of the
- * `rebase` + `ack` pair: the rebase in front of it has already reconciled and dropped the same key.
- */
-function commitAccepted<T extends TableMap>(key: string, target: ClientFrameTarget<T>): void {
-  target.store?.commit(key);
-  target.log?.drop(key);
-}
-
-/** Presence members cross the topic channel as plain JSON, like every other channel message. */
-function memberJson(member: PresenceMember): JsonValue {
-  return { id: member.id, actorId: member.actorId, meta: member.meta, updatedAt: member.updatedAt };
-}
-
-export function applyFrame<T extends TableMap>(frame: Frame, target: ClientFrameTarget<T>): void {
+export function applyFrame(frame: Frame, target: ClientFrameTarget): void {
   switch (frame.type) {
     case 'snapshot': {
       const registration = target.registration(frame.sid);
       if (!registration) return;
-      // The entity is the server's, and it is what upgrades this window from its own private scope
-      // to the one every other query over the same entity shares.
-      target.windows.snapshot(registration, frame.entity ?? null, frame.rows);
+      // State first: the window notifies once, after it has moved, and a reader must see `live`
+      // beside the rows it is handed. The record type is the server's — a browser cannot derive it.
       registration.cursor = frame.cursor;
-      registration.setCursor(frame.cursor);
-      registration.setState('live');
+      registration.state = 'live';
+      registration.error = undefined;
+      target.windows.snapshot(registration, frame.entity ?? null, frame.rows, frame.keys);
       return;
     }
     case 'patch': {
       const registration = target.registration(frame.sid);
       if (registration) {
-        target.windows.patch(registration, frame.patches);
         // The cursor moves with the patches, not only with a snapshot. Left behind, `cursor.at`
         // froze at the last snapshot and `shouldResnapshot`'s lag check answered "re-snapshot" for
         // every client connected longer than `maxLagMs` — the delta resume the retained change
@@ -110,53 +66,26 @@ export function applyFrame<T extends TableMap>(frame: Frame, target: ClientFrame
         if (registration.cursor && frame.lsn !== '') {
           const next = advance(registration.cursor, frame.patches, frame.lsn, target.now());
           registration.cursor = next;
-          registration.setCursor(next);
         }
-        registration.setState('live');
+        registration.state = 'live';
+        target.windows.patch(registration, frame.patches);
         return;
       }
-      // No registration: it is a tier-1 channel message on `sid = topic`.
-      const handlers = target.topicHandlers(frame.sid);
-      if (!handlers) return;
-      for (const patch of frame.patches) {
-        if (patch.row === null) continue;
-        for (const handler of handlers) handler(patch.row);
-      }
+      // A patch names a live registration or nothing: a channel's rows ride `records` frames.
       return;
     }
     case 'ack': {
-      const queue = target.queue;
-      // A refused mutation is not a mutation: its optimistic twin has to come off the screen, and
-      // its rebase entry has to leave the log, or a denied write stays rendered forever and every
-      // later reconcile replays it. `ref` is the mutation key — the same key the `mutate` frame
-      // carried — which is what makes both halves reachable from one frame.
-      if (frame.error) rollbackFailed(frame.ref, target);
-      else commitAccepted(frame.ref, target);
-      // `ack`/`fail` mutate the queue synchronously and persist asynchronously; chaining rather
-      // than notifying right after the call keeps this correct even if that ordering ever
-      // changes, and it still fires exactly once the persisted write actually lands.
-      const settled = frame.error ? queue?.fail(frame.ref, frame.error) : queue?.ack(frame.ref);
-      if (settled) target.detach(settled.then(() => target.notifyQueueChange()));
-      return;
-    }
-    case 'rebase': {
-      const store = target.store;
-      const log = target.log;
-      if (!store || !log) return;
-      // One batch for the whole reconcile — a rollback, server truth and every replayed mutator
-      // are one frame's worth of change, so a live window holding those rows renders once.
-      store.identity.batch(() => {
-        reconcile({
-          store,
-          log,
-          ack: {
-            key: frame.key,
-            entity: frame.entity,
-            id: frame.row?.id ?? frame.key,
-            row: frame.row,
-          },
-        });
-      });
+      // The socket carries no writes, so an `ack` is only ever a refusal: of a subscription (its
+      // `ref` is the sid) or of a frame the node could not read at all (its `ref` is the socket).
+      if (frame.error === null) return;
+      const registration = target.registration(frame.ref);
+      if (registration === undefined) {
+        if (!target.channels.refused(frame.ref, frame.error)) target.report(frame.error);
+        return;
+      }
+      registration.state = 'failed';
+      registration.error = frame.error;
+      registration.notify();
       return;
     }
     case 'reconnect': {
@@ -170,16 +99,19 @@ export function applyFrame<T extends TableMap>(frame: Frame, target: ClientFrame
       target.setUpdate(frame.buildId);
       return;
     }
-    case 'presence': {
-      const handlers = target.topicHandlers(frame.topic);
-      if (!handlers) return;
-      const message: JsonObject = { op: frame.op, members: frame.members.map(memberJson) };
-      for (const handler of handlers) handler(message);
+    case 'records':
+      // The channel's cursor decides new from duplicate, and a new epoch re-reads the channel;
+      // the records go to the store and nowhere else.
+      target.channels.records(frame);
+      return;
+    case 'events':
+      target.channels.event(frame);
+      return;
+    case 'replay-gap':
+      target.channels.gap(frame);
       return;
-    }
     case 'hello':
     case 'subscribe':
-    case 'mutate':
       // Client-authored frames: never received. Ignored rather than thrown, so a future
       // bidirectional use of the same kind cannot break an old client.
       return;