@rindle/remote 0.1.0-rc.5

package/src/optimistic-source.ts

@@ -0,0 +1,374 @@
+// RemoteOptimisticSource: an `OptimisticSource` over a network transport — the ws sibling of
+// the in-process native source (OPTIMISTIC-WRITES-DESIGN.md §8). The optimistic protocol is
+// the normalized subscription stream with `cv`-stamped frames, plus two extras:
+//
+//   - upstream: `init` (the connection's stable clientID, sent once) and `pushMutation`
+//     (one named-mutator envelope, §8.1) — confirmation rides the progress frames, so
+//     `pushMutation` resolves on send;
+//   - downstream: connection-level `progress` frames `{cvMin}` (§8.6; mutation confirmation is DATA — the lmid system query),
+//     relayed verbatim to the `OptimisticBackend` (which buffers data frames by `cv` and
+//     releases all `cv ≤ cvMin` as one coherent step, §8.5).
+//
+// Per-query validation is the ordinary `NormalizedSubscriber` (epoch/fp/seq); on a gap it
+// re-subscribes, and the server re-registers under a NEW epoch and replies with a fresh
+// `cv`-stamped snapshot + a progress frame that releases it.
+
+import { LMID_QUERY_NAME } from "@rindle/client";
+import type {
+  MutationEnvelope,
+  NormalizedEvent,
+  NormalizedTableSchema,
+  OptimisticSource,
+  ProgressFrame,
+  QueryId,
+  RemoteQuery,
+} from "@rindle/client";
+
+import { NormalizedSubscriber } from "./normalized.ts";
+import type { NormalizedBatch, NormalizedHello } from "./normalized.ts";
+import { ProtocolError } from "./protocol.ts";
+import type { ServerMsg } from "./protocol.ts";
+import {
+  defaultSubscribeTarget,
+  isThenable,
+  subscribeMessage,
+  type MutationEnvelopeSender,
+  type SubscribeResolver,
+  type SubscribeTarget,
+} from "./subscribe.ts";
+import { WsTransport } from "./transport.ts";
+import type { Transport } from "./transport.ts";
+
+interface QState {
+  remote: RemoteQuery;
+  subscriber: NormalizedSubscriber | null;
+  /** The epoch of the current subscription (0 before the first hello). */
+  epoch: number;
+  /** True between sending a re-subscribe and receiving its hello (so a second gap is ignored). */
+  resubscribing: boolean;
+  /** Monotonic token that cancels stale async lease resolutions. */
+  subscribeTicket: number;
+}
+
+/** Build a transport to a follower's public ws endpoint (READ-ROUTER-DESIGN.md §2.3). Default
+ *  `(endpoint) => new WsTransport(endpoint)`. */
+export type TransportFactory = (endpoint: string) => Transport;
+
+/** How the source obtains its transport:
+ *  - a pre-built {@link Transport} (or `{ transport }`) — FIXED: no endpoint migration, `wsEndpoint`
+ *    on leases is ignored (in-process / tests / a single static daemon);
+ *  - `{ factory, endpoint? }` — REPLACEABLE: transports are built on demand. An initial `endpoint`
+ *    (a static `wsUrl` or an SSR-injected bootstrap) opens eagerly; otherwise the first lease's
+ *    `wsEndpoint` opens it lazily, and a later lease naming a DIFFERENT endpoint migrates the whole
+ *    session there. */
+export type RemoteOptimisticConnection =
+  | Transport
+  | { transport: Transport }
+  | { factory: TransportFactory; endpoint?: string };
+
+export interface RemoteOptimisticSourceOptions {
+  /** Resolve the upstream subscribe target. Defaults to embedded-server `{name,args}`. */
+  resolveSubscribe?: SubscribeResolver;
+  /** Override named-mutator delivery, e.g. POST envelopes to the app API server. */
+  pushMutation?: MutationEnvelopeSender;
+}
+
+export class RemoteOptimisticSource implements OptimisticSource {
+  /** The CURRENT transport (undefined in pure-lazy mode until the first lease opens one). */
+  private transport: Transport | undefined;
+  /** The ws endpoint the current transport points at (undefined for a fixed transport). */
+  private currentEndpoint: string | undefined;
+  /** Builds a transport for an endpoint; undefined ⇒ fixed transport (no migration). */
+  private readonly transportFactory: TransportFactory | undefined;
+  private readonly clientID: string;
+  private readonly resolveSubscribe: SubscribeResolver;
+  private readonly pushMutationSender?: MutationEnvelopeSender;
+  private handler: (qid: QueryId, ev: NormalizedEvent) => void = () => {};
+  private progressHandler: (frame: ProgressFrame) => void = () => {};
+  private restartHandler: () => void = () => {};
+  private readonly subs = new Map<QueryId, QState>();
+  /** Queries whose subscribe is waiting for a transport to exist — endpoint-less subscribes issued
+   *  in pure-lazy mode before any lease opens a transport (the lmid system query is registered by
+   *  the backend at construction). Flushed when a transport comes up. */
+  private readonly deferred = new Set<QueryId>();
+  /** The daemon's boot id (from each `nhello`); a change means it restarted. */
+  private lastBootId: string | undefined;
+  /** The client's own typed per-table schemas, for hello validation (CRIT#4); set by the backend. */
+  private clientTables: NormalizedTableSchema[] | undefined;
+  /** Once true (set by {@link close}), in-flight lease resolutions are inert — they must not open a
+   *  new transport or send after teardown. */
+  private closed = false;
+  /** True once any lease has carried a routed `wsEndpoint`. Gates onDown re-leasing so a single
+   *  UNROUTED daemon keeps its pre-router behavior (recover via reconnect→resync only), not an extra
+   *  lease POST during an outage. */
+  private sawRoutedEndpoint = false;
+  /** Bumped at the start of every re-subscribe-all pass. A migrate triggered mid-pass starts a new
+   *  pass (higher generation); the outer pass then aborts instead of re-subscribing queries twice. */
+  private resubscribeGen = 0;
+
+  constructor(connection: RemoteOptimisticConnection, clientID: string, opts: RemoteOptimisticSourceOptions = {}) {
+    this.clientID = clientID;
+    this.resolveSubscribe = opts.resolveSubscribe ?? defaultSubscribeTarget;
+    this.pushMutationSender = opts.pushMutation;
+    if (isTransport(connection)) {
+      this.transportFactory = undefined;
+      this.bringUp(connection, undefined);
+    } else if ("transport" in connection) {
+      this.transportFactory = undefined;
+      this.bringUp(connection.transport, undefined);
+    } else {
+      this.transportFactory = connection.factory;
+      if (connection.endpoint !== undefined) this.openEndpoint(connection.endpoint);
+    }
+  }
+
+  /** Wire a transport's handlers (no `init`). */
+  private attach(transport: Transport): void {
+    transport.onMessage((msg) => this.onServerMsg(msg));
+    // Heal a dropped/restarted connection (same endpoint): on reconnect, replay init + re-subscribe.
+    transport.onReconnect?.(() => this.resync());
+    // Sustained outage on this endpoint: re-lease (the router may move us off a dead follower, §3).
+    transport.onDown?.(() => this.onDown());
+  }
+
+  /** Make `transport` the current one, announce identity, and (re)subscribe anything deferred. */
+  private bringUp(transport: Transport, endpoint: string | undefined): void {
+    this.transport = transport;
+    this.currentEndpoint = endpoint;
+    this.attach(transport);
+    transport.send({ t: "init", clientID: this.clientID });
+    this.flushDeferred();
+  }
+
+  /** Build + bring up a fresh transport to `endpoint` (replaceable mode only). */
+  private openEndpoint(endpoint: string): void {
+    if (!this.transportFactory) return;
+    this.bringUp(this.transportFactory(endpoint), endpoint);
+  }
+
+  /** Migrate the whole session to a new follower (§2.3): build the new transport, tear the old one
+   *  down, and re-subscribe EVERY active query there (re-leasing — the old tokens are
+   *  follower-local and invalid on the new node). */
+  private migrate(endpoint: string): void {
+    const old = this.transport;
+    this.openEndpoint(endpoint);
+    old?.close();
+    this.resubscribeAll();
+  }
+
+  /** Re-subscribe every live query on the current transport (each re-resolves its lease). A
+   *  re-subscribe can synchronously trigger a `migrate` (lease names a new endpoint), whose own
+   *  re-subscribe pass supersedes this one — the generation check then aborts this pass so a query
+   *  is never re-subscribed (and re-leased) twice. */
+  private resubscribeAll(): void {
+    const gen = ++this.resubscribeGen;
+    for (const [qid, s] of this.subs) {
+      if (this.resubscribeGen !== gen) return; // a nested migrate/resubscribe took over — stop
+      s.subscriber = null;
+      s.resubscribing = true;
+      this.subscribe(qid, s.remote);
+    }
+  }
+
+  /** Flush subscribes deferred until a transport existed (e.g. the lmid query in pure-lazy mode). */
+  private flushDeferred(): void {
+    if (this.deferred.size === 0) return;
+    const qids = [...this.deferred];
+    this.deferred.clear();
+    for (const qid of qids) {
+      const s = this.subs.get(qid);
+      if (s) this.subscribe(qid, s.remote);
+    }
+  }
+
+  /** The current follower's ws is sustainedly down — re-lease every query. The router returns a
+   *  (possibly new) `wsEndpoint`: a changed one migrates the session; an unchanged one re-subscribes
+   *  over the reconnecting transport (READ-ROUTER-DESIGN.md §3). No-op for an UNROUTED daemon (no
+   *  lease ever carried a `wsEndpoint`) — there is nowhere to move, so we keep the pre-router
+   *  behavior and let the transport's own reconnect→resync recover. */
+  private onDown(): void {
+    if (this.closed || !this.sawRoutedEndpoint) return;
+    this.resubscribeAll();
+  }
+
+  /** Tear down the current transport and make any in-flight lease resolution inert (a late lease
+   *  must NOT open a new transport after the consumer closed the client). */
+  close(): void {
+    this.closed = true;
+    this.transport?.close();
+    this.subs.clear();
+    this.deferred.clear();
+  }
+
+  /** Register a handler fired when the DAEMON restarts (a new boot id) — the backend resets its
+   *  `cv` watermark so the new daemon's reset `cv` sequence is accepted instead of dropped. */
+  onRestart(handler: () => void): void {
+    this.restartHandler = handler;
+  }
+
+  expectClientSchema(tables: NormalizedTableSchema[]): void {
+    this.clientTables = tables;
+  }
+
+  registerQuery(qid: QueryId, remote: RemoteQuery): void {
+    this.subs.set(qid, { remote, subscriber: null, epoch: 0, resubscribing: false, subscribeTicket: 0 });
+    this.subscribe(qid, remote);
+  }
+
+  unregisterQuery(qid: QueryId): void {
+    this.subs.delete(qid);
+    this.deferred.delete(qid);
+    this.transport?.send({ t: "unsubscribe", queryId: qid });
+  }
+
+  pushMutation(envelope: MutationEnvelope): Promise<void> {
+    if (this.pushMutationSender) return Promise.resolve(this.pushMutationSender(envelope));
+    this.transport?.send({ t: "pushMutation", envelope });
+    return Promise.resolve();
+  }
+
+  onNormalized(handler: (qid: QueryId, ev: NormalizedEvent) => void): void {
+    this.handler = handler;
+  }
+
+  onProgress(handler: (frame: ProgressFrame) => void): void {
+    this.progressHandler = handler;
+  }
+
+  // --- internals ---------------------------------------------------------------
+
+  private subscribe(qid: QueryId, remote: RemoteQuery): void {
+    const s = this.subs.get(qid);
+    if (!s) return;
+    const request = { queryId: qid, remote, mode: "normalized" as const };
+    const ticket = ++s.subscribeTicket;
+    const send = (target: SubscribeTarget) => {
+      if (this.closed) return; // a lease that resolved after close() must not (re)open anything
+      const cur = this.subs.get(qid);
+      if (cur !== s || cur.subscribeTicket !== ticket) return;
+      const endpoint = "leaseToken" in target ? target.wsEndpoint : undefined;
+      if (endpoint !== undefined) this.sawRoutedEndpoint = true;
+      if (this.transport) {
+        if (endpoint !== undefined && endpoint !== this.currentEndpoint && this.transportFactory) {
+          // The router placed this key on a DIFFERENT follower — migrate the whole session there.
+          // `migrate` re-subscribes every query (incl. this one) over the new transport, so return.
+          this.migrate(endpoint);
+          return;
+        }
+        this.transport.send(subscribeMessage(request, target));
+        return;
+      }
+      // No transport yet (pure-lazy): the first lease naming an endpoint opens it.
+      if (endpoint !== undefined && this.transportFactory) {
+        this.openEndpoint(endpoint);
+        this.transport!.send(subscribeMessage(request, target));
+        return;
+      }
+      // Endpoint-less with no transport (the lmid system query before the first lease): defer until
+      // a transport comes up, then re-run this subscribe.
+      this.deferred.add(qid);
+    };
+    const fail = (err: unknown) => {
+      const cur = this.subs.get(qid);
+      if (cur !== s || cur.subscribeTicket !== ticket) return;
+      s.resubscribing = false;
+      console.error(
+        `[rindle-remote] optimistic query ${qid} subscribe resolution failed: ${String((err as Error)?.message ?? err)}`,
+      );
+    };
+    try {
+      // The reserved lmid system query is part of the optimistic WIRE contract, not an app
+      // query: the server resolves it from the connection's own `init` identity. It must
+      // never route through the app's subscribe resolver (the API server has no such named
+      // query, and a lease for it would be meaningless).
+      const target =
+        remote.name === LMID_QUERY_NAME ? defaultSubscribeTarget(request) : this.resolveSubscribe(request);
+      if (isThenable(target)) void target.then(send, fail);
+      else send(target);
+    } catch (err) {
+      fail(err);
+    }
+  }
+
+  private onServerMsg(msg: ServerMsg): void {
+    if (msg.t === "progress") {
+      this.progressHandler(msg.frame);
+      return;
+    }
+    if (msg.t === "queryError") {
+      this.subs.delete(msg.queryId);
+      console.error(`[rindle-remote] optimistic query ${msg.queryId} subscription rejected: ${msg.message}`);
+      return;
+    }
+    if (msg.t !== "nhello" && msg.t !== "nbatch") return;
+    // Restart detection rides every nhello (connection-level) and runs BEFORE this query's
+    // snapshot buffers, so the backend's reset clears stale state ahead of the fresh hydrate.
+    if (msg.t === "nhello") this.observeBootId(msg.bootId);
+    const s = this.subs.get(msg.queryId);
+    if (!s) return; // unsubscribed / unknown query
+    if (msg.t === "nhello") this.openSubscriber(msg.queryId, s, msg.hello);
+    else this.applyBatch(msg.queryId, s, msg.batch);
+  }
+
+  /** On reconnect: re-announce identity and re-subscribe every live query (each re-resolves its
+   *  lease, so a restarted daemon re-materializes + re-leases on the fly). */
+  private resync(): void {
+    if (this.closed) return;
+    this.transport?.send({ t: "init", clientID: this.clientID });
+    this.resubscribeAll();
+  }
+
+  /** Track the daemon's boot id; a change (after the first) means it restarted — fire onRestart. */
+  private observeBootId(bootId: string | undefined): void {
+    if (!bootId) return;
+    if (this.lastBootId !== undefined && bootId !== this.lastBootId) this.restartHandler();
+    this.lastBootId = bootId;
+  }
+
+  private openSubscriber(qid: QueryId, s: QState, hello: NormalizedHello): void {
+    try {
+      s.subscriber = new NormalizedSubscriber(hello, (ev) => this.handler(qid, ev), this.clientTables);
+      s.epoch = hello.epoch;
+      s.resubscribing = false;
+    } catch (e) {
+      // A comparator/fp mismatch at hello is unrecoverable (a code-contract divergence).
+      s.subscriber = null;
+      console.error(`[rindle-remote] optimistic query ${qid} subscription rejected: ${(e as Error).message}`);
+    }
+  }
+
+  private applyBatch(qid: QueryId, s: QState, batch: NormalizedBatch): void {
+    if (!s.subscriber) return; // no hello yet (or mid re-hydrate)
+    if (batch.epoch < s.epoch) return; // a stale batch from a superseded epoch — drop
+    try {
+      s.subscriber.apply(batch);
+    } catch (e) {
+      if (!(e instanceof ProtocolError)) throw e;
+      if (s.resubscribing) return; // already recovering
+      // Gap / drift → re-hydrate under a new epoch; the fresh snapshot arrives `cv`-stamped
+      // and releases (re-hydrating the footprint) at the server's accompanying progress frame.
+      s.resubscribing = true;
+      s.subscriber = null;
+      this.subscribe(qid, s.remote);
+    }
+  }
+}
+
+/** Convenience: a `RemoteOptimisticSource` over a ws URL or a custom transport. A URL becomes a
+ *  replaceable connection seeded at that endpoint (so a routed lease can still migrate it); a
+ *  pre-built transport stays fixed. */
+export function createRemoteOptimisticSource(
+  urlOrTransport: string | Transport,
+  clientID: string,
+  opts: RemoteOptimisticSourceOptions = {},
+): RemoteOptimisticSource {
+  const connection: RemoteOptimisticConnection =
+    typeof urlOrTransport === "string"
+      ? { factory: (endpoint) => new WsTransport(endpoint), endpoint: urlOrTransport }
+      : urlOrTransport;
+  return new RemoteOptimisticSource(connection, clientID, opts);
+}
+
+function isTransport(value: RemoteOptimisticConnection): value is Transport {
+  return typeof (value as Transport).send === "function" && typeof (value as Transport).onMessage === "function";
+}

package/src/protocol.ts

@@ -0,0 +1,252 @@
+// The flat-change subscription protocol, ported from `src/flat_protocol.rs` + the
+// `schema_fp` fingerprint from `src/wire_schema.rs`. This is the wire contract shared by the
+// server (`@rindle/server`, which frames via {@link Publisher}) and the client RemoteBackend
+// (which validates via {@link Subscriber}).
+//
+// The §2.2 split (WASM-CLIENT-DESIGN.md): the Rust `Subscriber` owns a `Receiver` and does
+// validation *and* folding. Here we keep ONLY validation/sequencing in {@link Subscriber} and
+// hand the clean `hello`/`snapshot`/`batch` `ChangeEvent`s up to the core `ArrayView` to fold —
+// so one `ArrayView` serves both the local and remote backends.
+
+import { COMPARATOR_VERSION } from "@rindle/client";
+import type { ChangeEvent, FlatChange, Mutation, MutationEnvelope, ProgressFrame, WireSchema } from "@rindle/client";
+import type { NormalizedBatch, NormalizedHello } from "./normalized.ts";
+
+export { COMPARATOR_VERSION };
+
+// ----------------------------- schema fingerprint (FNV-1a 64) -----------------------------
+
+const enc = new TextEncoder();
+const FNV_OFFSET = 0xcbf29ce484222325n;
+const FNV_PRIME = 0x00000100000001b3n;
+const MASK = 0xffffffffffffffffn;
+
+export class Fnv {
+  h = FNV_OFFSET;
+  private byte(b: number): void {
+    this.h = ((this.h ^ BigInt(b & 0xff)) * FNV_PRIME) & MASK;
+  }
+  u8(v: number): void {
+    this.byte(v);
+  }
+  /** A `u32` little-endian (matching Rust `v.to_le_bytes()`). */
+  u32(v: number): void {
+    this.byte(v & 0xff);
+    this.byte((v >>> 8) & 0xff);
+    this.byte((v >>> 16) & 0xff);
+    this.byte((v >>> 24) & 0xff);
+  }
+  /** A length-prefixed string: `u32(byteLen)` then the UTF-8 bytes (disambiguates joins). */
+  s(str: string): void {
+    const bytes = enc.encode(str);
+    this.u32(bytes.length);
+    for (const b of bytes) this.byte(b);
+  }
+}
+
+function hashLevel(f: Fnv, ws: WireSchema): void {
+  f.u8(0x53); // 'S'
+  f.u32(ws.columns.length);
+  for (const c of ws.columns) f.s(c);
+  // PK + sort resolved to column NAMES (semantic identity, independent of indices).
+  f.u32(ws.primaryKey.length);
+  for (const pk of ws.primaryKey) f.s(ws.columns[pk]);
+  f.u32(ws.sort.length);
+  for (const [c, asc] of ws.sort) {
+    f.s(ws.columns[c]);
+    f.u8(asc ? 1 : 0);
+  }
+  f.u8(ws.singular ? 1 : 0);
+  f.u32(ws.relationships.length);
+  for (const r of ws.relationships) {
+    f.s(r.name);
+    if (r.child) {
+      f.u8(1);
+      hashLevel(f, r.child);
+      // Scalar-projection marker (REDUCE-DESIGN.md §9): a presence byte, then — when present
+      // — the projected column's NAME in the child schema (index-independent, matching
+      // PK/sort). The empty-identity value is NOT hashed (a bare cell can't reproduce its
+      // type variant). Must match `hash_level` in `src/wire_schema.rs`.
+      if (r.project) {
+        f.u8(1);
+        f.s(r.child.columns[r.project.col]);
+      } else {
+        f.u8(0);
+      }
+    } else {
+      f.u8(0);
+    }
+  }
+}
+
+/** A `WireSchema`'s content fingerprint — FNV-1a 64 over the canonical, length-prefixed byte
+ *  stream of `src/wire_schema.rs`, rendered as 16-char lowercase hex (=== Rust `SchemaFp`
+ *  `Display`). A string (not a JS number) so the full 64 bits survive JSON without precision loss. */
+export function schemaFp(ws: WireSchema): string {
+  const f = new Fnv();
+  hashLevel(f, ws);
+  return f.h.toString(16).padStart(16, "0");
+}
+
+// ----------------------------- the wire frames -----------------------------
+
+/** The subscription handshake, sent once before any {@link Batch}. */
+export interface Hello {
+  epoch: number;
+  comparatorVersion: number;
+  schema: WireSchema;
+  schemaFp: string;
+}
+
+/** One transaction's flat changes (or the seq-0 hydrate snapshot). `events` apply in order. */
+export interface Batch {
+  epoch: number;
+  seq: number;
+  schemaFp: string;
+  events: FlatChange[];
+}
+
+/** The multiplexed wire messages (many queries over one connection, tagged by `queryId`).
+ *  `subscribe.mode` selects the serializer (default flat); a normalized subscription gets
+ *  `nhello`/`nbatch` back instead of `hello`/`batch` (NORMALIZED-CHANGES-DESIGN.md §6).
+ *  Embedded servers receive `{name,args}`. Daemon/serverless deployments can instead receive an
+ *  opaque `leaseToken` that the app API server minted after auth + named-query resolution.
+ *
+ *  The OPTIMISTIC path (OPTIMISTIC-WRITES-DESIGN.md §8) adds `init` (the connection
+ *  identifies its stable clientID, so progress frames can carry that client's `lmid`) and
+ *  `pushMutation` (one named-mutator envelope up); the server answers with the normalized
+ *  frames (`cv`-stamped) plus connection-level `progress` frames. */
+export type SubscribeClientMsg =
+  | { t: "subscribe"; queryId: number; name: string; args: unknown; mode?: "flat" | "normalized" }
+  | { t: "subscribe"; queryId: number; leaseToken: string; mode?: "flat" | "normalized" };
+
+export type ClientMsg =
+  | { t: "init"; clientID: string }
+  | SubscribeClientMsg
+  | { t: "unsubscribe"; queryId: number }
+  | { t: "mutate"; mutations: Mutation[] }
+  | { t: "pushMutation"; envelope: MutationEnvelope };
+
+export type ServerMsg =
+  | { t: "hello"; queryId: number; hello: Hello }
+  | { t: "batch"; queryId: number; batch: Batch }
+  // `bootId` is the daemon's per-process id (same on every frame of one connection). A change
+  // across (re)connections means the daemon restarted — it keeps no durable lease/materialization
+  // or `cv` state — so the client must force a clean re-hydrate (reset its `cv` watermark).
+  | { t: "nhello"; queryId: number; hello: NormalizedHello; bootId?: string }
+  | { t: "nbatch"; queryId: number; batch: NormalizedBatch }
+  | { t: "queryError"; queryId: number; message: string }
+  | { t: "progress"; frame: ProgressFrame }
+  // A per-connection error reply: the server could not process this client's message (bad
+  // table/AST, a commit/derive failure). Sent INSTEAD of crashing the process — the connection
+  // stays open and every other connection is unaffected. Existing clients ignore unknown `t`.
+  | { t: "error"; queryId?: number; message: string };
+
+// ----------------------------- Publisher (server side) -----------------------------
+
+/** Sender side: stamps batches with the subscription `epoch` + `schemaFp` and drives the
+ *  gap-free seq. The hydrate snapshot is seq 0; increments are seq 1, 2, …. An empty
+ *  transaction emits no batch and consumes no seq (so a gap always means a lost batch). */
+export class Publisher {
+  readonly epoch: number;
+  readonly schema: WireSchema;
+  readonly schemaFp: string;
+  private nextSeq = 0;
+
+  constructor(epoch: number, schema: WireSchema) {
+    this.epoch = epoch;
+    this.schema = schema;
+    this.schemaFp = schemaFp(schema);
+  }
+
+  hello(): Hello {
+    return { epoch: this.epoch, comparatorVersion: COMPARATOR_VERSION, schema: this.schema, schemaFp: this.schemaFp };
+  }
+
+  /** The hydrate snapshot (seq 0). Always emitted, even when empty, so the receiver learns it. */
+  snapshot(events: FlatChange[]): Batch {
+    return this.emit(events);
+  }
+
+  /** One transaction's events — `null` for an empty transaction (no batch, no seq consumed). */
+  commit(events: FlatChange[]): Batch | null {
+    return events.length ? this.emit(events) : null;
+  }
+
+  private emit(events: FlatChange[]): Batch {
+    const seq = this.nextSeq++;
+    return { epoch: this.epoch, seq, schemaFp: this.schemaFp, events };
+  }
+}
+
+// ----------------------------- Subscriber (client side) -----------------------------
+
+export type ProtocolErrorKind = "comparator-mismatch" | "epoch-mismatch" | "schema-mismatch" | "gap";
+
+/** A protocol violation. All but a duplicate (handled silently) are unrecoverable for the
+ *  current subscription — the RemoteBackend re-hydrates under a new epoch. */
+export class ProtocolError extends Error {
+  readonly kind: ProtocolErrorKind;
+  constructor(kind: ProtocolErrorKind, message: string) {
+    super(message);
+    this.kind = kind;
+    this.name = "ProtocolError";
+  }
+}
+
+/** Receiver side: validates a frame stream (comparator at `hello`; per batch — epoch match,
+ *  schema-fp match, strict in-order seq) and emits the clean `hello`/`snapshot`/`batch`
+ *  `ChangeEvent`s. It does NOT fold (the core `ArrayView` does) — the §2.2 split. */
+export class Subscriber {
+  readonly epoch: number;
+  readonly schemaFp: string;
+  private readonly emit: (ev: ChangeEvent) => void;
+  private phase: "snapshot" | "live" = "snapshot";
+  private lastSeq = 0;
+
+  constructor(hello: Hello, emit: (ev: ChangeEvent) => void) {
+    this.emit = emit;
+    if (hello.comparatorVersion !== COMPARATOR_VERSION) {
+      throw new ProtocolError(
+        "comparator-mismatch",
+        `comparator version ${hello.comparatorVersion} != ${COMPARATOR_VERSION}`,
+      );
+    }
+    const computed = schemaFp(hello.schema);
+    if (computed !== hello.schemaFp) {
+      throw new ProtocolError("schema-mismatch", `advertised fp ${hello.schemaFp} != computed ${computed}`);
+    }
+    this.epoch = hello.epoch;
+    this.schemaFp = hello.schemaFp;
+    emit({ type: "hello", schema: hello.schema, comparatorVersion: hello.comparatorVersion });
+  }
+
+  /** Apply one incremental batch (or the seq-0 snapshot). Returns `"duplicate"` for an
+   *  already-applied seq (discarded — rc ops are not idempotent); throws {@link ProtocolError}
+   *  on a gap / epoch / schema mismatch (the caller re-hydrates). */
+  apply(batch: Batch): "applied" | "duplicate" {
+    if (batch.epoch !== this.epoch) {
+      throw new ProtocolError("epoch-mismatch", `expected epoch ${this.epoch}, got ${batch.epoch}`);
+    }
+    if (batch.schemaFp !== this.schemaFp) {
+      throw new ProtocolError("schema-mismatch", `expected fp ${this.schemaFp}, got ${batch.schemaFp}`);
+    }
+    if (this.phase === "snapshot") {
+      if (batch.seq === 0) {
+        this.phase = "live";
+        this.lastSeq = 0;
+        this.emit({ type: "snapshot", adds: batch.events, last: true });
+        return "applied";
+      }
+      throw new ProtocolError("gap", `expected the seq-0 snapshot, got seq ${batch.seq}`);
+    }
+    const expected = this.lastSeq + 1;
+    if (batch.seq < expected) return "duplicate";
+    if (batch.seq > expected) {
+      throw new ProtocolError("gap", `expected seq ${expected}, got ${batch.seq}`);
+    }
+    this.lastSeq = batch.seq;
+    this.emit({ type: "batch", events: batch.events });
+    return "applied";
+  }
+}