@rindle/remote 0.1.0-rc.5

package/dist/transport.js

@@ -0,0 +1,105 @@
+// The transport seam: the RemoteBackend talks JSON messages through a `Transport`, so the
+// wire (ws / sse / http) is swappable + mockable. The default {@link WsTransport} uses the
+// global `WebSocket` (Node 22+ and browsers both provide it — zero dependency).
+/** A `Transport` over a `WebSocket` (text JSON frames). Messages sent before the socket
+ *  opens are buffered and flushed on open (so `registerQuery`/`mutate` can be called eagerly).
+ *  Reconnects with capped exponential backoff: if the socket drops (e.g. the daemon restarted)
+ *  it reopens and fires `onReconnect` so the source rebuilds its subscriptions. */
+export class WsTransport {
+    url;
+    ws;
+    handler = () => { };
+    reconnectHandler = () => { };
+    downHandler = () => { };
+    pending = [];
+    open = false;
+    everOpened = false;
+    closedByUser = false;
+    attempt = 0;
+    reconnectTimer;
+    /** Failed reconnect attempts after which the connection is declared "down" (fires `onDown`). */
+    downThreshold;
+    /** True once `onDown` has fired for the CURRENT down episode; reset on the next successful open
+     *  so a later outage fires again (but a single episode fires `onDown` exactly once — no re-lease
+     *  storm while a follower is gone). */
+    downFired = false;
+    constructor(url, opts = {}) {
+        this.url = url;
+        this.downThreshold = opts.downThreshold ?? 4;
+        this.ws = this.connect();
+    }
+    connect() {
+        const ws = new WebSocket(this.url);
+        ws.addEventListener("open", () => {
+            this.open = true;
+            this.attempt = 0;
+            this.downFired = false; // a fresh connection clears the down episode
+            if (!this.everOpened) {
+                // First connection: flush whatever was buffered eagerly (init + subscribes).
+                this.everOpened = true;
+                for (const m of this.pending)
+                    ws.send(JSON.stringify(m));
+                this.pending.length = 0;
+            }
+            else {
+                // A reconnect: drop any stale buffered frames — the source rebuilds the full desired
+                // state (re-init + re-subscribe, re-leasing as it goes) in onReconnect.
+                this.pending.length = 0;
+                this.reconnectHandler();
+            }
+        });
+        ws.addEventListener("message", (ev) => {
+            this.handler(JSON.parse(typeof ev.data === "string" ? ev.data : String(ev.data)));
+        });
+        ws.addEventListener("close", () => {
+            this.open = false;
+            if (!this.closedByUser)
+                this.scheduleReconnect();
+        });
+        // `error` is followed by `close`; let the close handler own reconnection.
+        ws.addEventListener("error", () => { });
+        return ws;
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer !== undefined)
+            return;
+        const delay = Math.min(250 * 2 ** this.attempt, 5000);
+        this.attempt++;
+        // Sustained failure (we had a connection, and several reconnects to this endpoint have failed):
+        // declare the connection down ONCE so the source can re-lease and migrate (§3). We keep
+        // reconnecting underneath in case the same follower returns (a reboot, same endpoint).
+        if (this.everOpened && !this.downFired && this.attempt >= this.downThreshold) {
+            this.downFired = true;
+            this.downHandler();
+        }
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            if (!this.closedByUser)
+                this.ws = this.connect();
+        }, delay);
+    }
+    send(msg) {
+        if (this.open)
+            this.ws.send(JSON.stringify(msg));
+        else
+            this.pending.push(msg);
+    }
+    onMessage(handler) {
+        this.handler = handler;
+    }
+    onReconnect(handler) {
+        this.reconnectHandler = handler;
+    }
+    onDown(handler) {
+        this.downHandler = handler;
+    }
+    close() {
+        this.closedByUser = true;
+        if (this.reconnectTimer !== undefined) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = undefined;
+        }
+        this.ws.close();
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@rindle/remote",
+  "version": "0.1.0-rc.5",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rindle-sh/rindle.git",
+    "directory": "packages/remote"
+  },
+  "type": "module",
+  "description": "Network backend for @rindle/client: RemoteBackend over a transport + the wire protocol (Publisher/Subscriber/schemaFp).",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "@rindle/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@rindle/client": "0.1.0-rc.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "tsc --noEmit && node --conditions=@rindle/source --test test/*.test.ts"
+  }
+}

package/src/backend.ts

@@ -0,0 +1,163 @@
+// The RemoteBackend: a `@rindle/client` `Backend` over a network transport. It owns the
+// epoch/seq/gap protocol (via {@link Subscriber}) and emits only CLEAN, in-order
+// `hello`/`snapshot`/`batch` `ChangeEvent`s upward — so the same `Store`/`ArrayView` that
+// drives the local backends drives this one, never seeing seq/epoch (WASM-CLIENT-DESIGN.md §2.2).
+//
+// On a gap (or epoch/schema drift) the backend re-hydrates INTERNALLY: it re-subscribes, the
+// server re-registers the query under a NEW epoch and replies with a fresh hello + snapshot,
+// and the `ArrayView` resets in place — the caller's materialized view reference survives.
+
+import { Store } from "@rindle/client";
+import type { Backend, ChangeEvent, ColsMap, Mutation, QueryId, RemoteQuery, Schema } from "@rindle/client";
+
+import { ProtocolError, Subscriber } from "./protocol.ts";
+import type { Batch, Hello, ServerMsg } from "./protocol.ts";
+import {
+  defaultSubscribeTarget,
+  isThenable,
+  subscribeMessage,
+  type RawMutationSender,
+  type SubscribeResolver,
+} from "./subscribe.ts";
+import { WsTransport } from "./transport.ts";
+import type { Transport } from "./transport.ts";
+
+interface QState {
+  remote: RemoteQuery;
+  subscriber: Subscriber | 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;
+}
+
+export interface RemoteBackendOptions {
+  /** Resolve the upstream subscribe target. Defaults to embedded-server `{name,args}`. */
+  resolveSubscribe?: SubscribeResolver;
+  /** Override raw authoritative writes, e.g. POST them to an app API server. */
+  sendMutation?: RawMutationSender;
+}
+
+export class RemoteBackend implements Backend {
+  private readonly transport: Transport;
+  private readonly resolveSubscribe: SubscribeResolver;
+  private readonly sendMutation?: RawMutationSender;
+  private handler: (qid: QueryId, ev: ChangeEvent) => void = () => {};
+  private readonly subs = new Map<QueryId, QState>();
+
+  constructor(transport: Transport, opts: RemoteBackendOptions = {}) {
+    this.transport = transport;
+    this.resolveSubscribe = opts.resolveSubscribe ?? defaultSubscribeTarget;
+    this.sendMutation = opts.sendMutation;
+    this.transport.onMessage((msg) => this.onServerMsg(msg));
+  }
+
+  registerQuery(qid: QueryId, _ast: unknown, remote?: RemoteQuery): void {
+    if (!remote) {
+      console.error(`[rindle-remote] flat query ${qid} has no named remote identity`);
+      return;
+    }
+    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.transport.send({ t: "unsubscribe", queryId: qid });
+  }
+
+  /** Eventually-consistent: the mutation is sent; the resulting batches arrive async on the
+   *  stream. The promise resolves once sent (the §2.3 write asymmetry, named not leaked). */
+  mutate(mutations: Mutation[]): Promise<void> {
+    if (this.sendMutation) return Promise.resolve(this.sendMutation(mutations));
+    this.transport.send({ t: "mutate", mutations });
+    return Promise.resolve();
+  }
+
+  onEvent(handler: (qid: QueryId, ev: ChangeEvent) => void): void {
+    this.handler = handler;
+  }
+
+  // --- internals ---------------------------------------------------------------
+
+  private subscribe(qid: QueryId, remote: RemoteQuery): void {
+    const s = this.subs.get(qid);
+    if (!s) return;
+    const request = { queryId: qid, remote, mode: "flat" as const };
+    const ticket = ++s.subscribeTicket;
+    const send = (target: ReturnType<typeof defaultSubscribeTarget>) => {
+      const cur = this.subs.get(qid);
+      if (cur !== s || cur.subscribeTicket !== ticket) return;
+      this.transport.send(subscribeMessage(request, target));
+    };
+    const fail = (err: unknown) => {
+      const cur = this.subs.get(qid);
+      if (cur !== s || cur.subscribeTicket !== ticket) return;
+      s.resubscribing = false;
+      console.error(`[rindle-remote] query ${qid} subscribe resolution failed: ${String((err as Error)?.message ?? err)}`);
+    };
+    try {
+      const target = 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 === "queryError") {
+      this.subs.delete(msg.queryId);
+      console.error(`[rindle-remote] query ${msg.queryId} subscription rejected: ${msg.message}`);
+      return;
+    }
+    // This backend is flat-only; it ignores normalized frames (`nhello`/`nbatch`).
+    if (msg.t !== "hello" && msg.t !== "batch") return;
+    const s = this.subs.get(msg.queryId);
+    if (!s) return; // unsubscribed / unknown query
+    if (msg.t === "hello") this.openSubscriber(msg.queryId, s, msg.hello);
+    else this.applyBatch(msg.queryId, s, msg.batch);
+  }
+
+  private openSubscriber(qid: QueryId, s: QState, hello: Hello): void {
+    try {
+      // The Subscriber ctor validates the comparator + fingerprint and emits the `hello`
+      // ChangeEvent (→ the Store resets the view to this schema).
+      s.subscriber = new Subscriber(hello, (ev) => this.handler(qid, ev));
+      s.epoch = hello.epoch;
+      s.resubscribing = false;
+    } catch (e) {
+      // A comparator/schema mismatch at hello is unrecoverable (a code-contract divergence) —
+      // leave the view pending and report it; do not loop.
+      s.subscriber = null;
+      console.error(`[rindle-remote] query ${qid} subscription rejected: ${(e as Error).message}`);
+    }
+  }
+
+  private applyBatch(qid: QueryId, s: QState, batch: Batch): 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 server bumps it on re-subscribe).
+      s.resubscribing = true;
+      s.subscriber = null;
+      this.subscribe(qid, s.remote);
+    }
+  }
+}
+
+/** Convenience: a `Store` backed by a remote server, over a ws URL or a custom transport. */
+export function createRemoteStore<S extends ColsMap>(
+  schema: Schema<S>,
+  urlOrTransport: string | Transport,
+  opts: RemoteBackendOptions = {},
+): Store<S> {
+  const transport = typeof urlOrTransport === "string" ? new WsTransport(urlOrTransport) : urlOrTransport;
+  return new Store(schema, new RemoteBackend(transport, opts));
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+// @rindle/remote — the network backend for @rindle/client: a `RemoteBackend` over a transport,
+// driving the SAME Store/ArrayView as the local (wasm/replica) backends. Also exports the
+// wire protocol (frames + `Publisher`/`Subscriber` + `schemaFp`) a server uses to talk to it.
+// Re-exports @rindle/client so an app can import everything from here.
+
+export * from "@rindle/client";
+
+export { RemoteBackend, createRemoteStore } from "./backend.ts";
+export type { RemoteBackendOptions } from "./backend.ts";
+export { WsTransport } from "./transport.ts";
+export type { Transport } from "./transport.ts";
+export type {
+  MutationEnvelopeSender,
+  RawMutationSender,
+  SubscribeMode,
+  SubscribeRequest,
+  SubscribeResolver,
+  SubscribeTarget,
+} from "./subscribe.ts";
+
+export { COMPARATOR_VERSION, Publisher, ProtocolError, Subscriber, schemaFp } from "./protocol.ts";
+export type { Batch, ClientMsg, Hello, ProtocolErrorKind, ServerMsg, SubscribeClientMsg } from "./protocol.ts";
+
+// The normalized subscription protocol (the path-free twin) + the client-side source.
+export { NormalizedSubscriber, normalizedFp } from "./normalized.ts";
+export type { NormalizedBatch, NormalizedHello } from "./normalized.ts";
+export { RemoteNormalizedSource, createRemoteNormalizedSource } from "./remote-source.ts";
+export type { RemoteNormalizedSourceOptions } from "./remote-source.ts";
+
+// The optimistic-writes source (the normalized stream + mutation push + progress frames).
+export { RemoteOptimisticSource, createRemoteOptimisticSource } from "./optimistic-source.ts";
+export type {
+  RemoteOptimisticConnection,
+  RemoteOptimisticSourceOptions,
+  TransportFactory,
+} from "./optimistic-source.ts";
+
+// The serverless mutation queue: confirmed, in-order batches over an unordered HTTP hop.
+export { createQueuedMutationSender } from "./mutation-queue.ts";
+export type { PushOutcome, QueuedMutationSenderOptions } from "./mutation-queue.ts";

package/src/mutation-queue.ts

@@ -0,0 +1,96 @@
+// The client-side mutation queue for daemon/serverless deployments. The optimistic engine
+// requires mids to arrive at the daemon CONTIGUOUSLY (`mid == lmid + 1`); a websocket gives
+// that ordering for free, but the serverless hop (client → API server over HTTP → daemon)
+// does not — two parallel fetches can reorder. The queue restores the invariant the cheap
+// way: envelopes are sent as in-order batches, and the next batch does not leave until the
+// prior one is confirmed (the API server's response means the daemon durably processed it).
+//
+// Delivery is at-least-once: a failed flush retries the SAME batch with backoff, which is
+// safe because the daemon absorbs `mid ≤ lmid` as an idempotent replay. A per-envelope
+// REJECTION (the API server's policy saying no) is not retried — the daemon has already
+// advanced lmid past it, the authoritative snap-back rides the lmid release, and the reason
+// surfaces here through `onRejected` (the wire itself carries no rejection signal).
+
+import type { MutationEnvelope } from "@rindle/client";
+
+import type { MutationEnvelopeSender } from "./subscribe.ts";
+
+/** One envelope's outcome from the API server's mutate endpoint. */
+export interface PushOutcome {
+  accepted: boolean;
+  reason?: string;
+}
+
+export interface QueuedMutationSenderOptions {
+  /** Deliver one in-order batch; resolve once the daemon durably processed it (i.e. the
+   *  API server awaited its daemon call before responding). Throw to have the SAME batch
+   *  retried. Return per-envelope outcomes, or void when everything was accepted. */
+  send: (envelopes: MutationEnvelope[]) => Promise<PushOutcome[] | void>;
+  /** A policy rejection for one envelope (never retried; the prediction snaps back via the
+   *  lmid release — this callback is where the reason reaches the app). */
+  onRejected?: (envelope: MutationEnvelope, reason: string) => void;
+  /** A failed flush attempt, before its retry (observability). */
+  onError?: (err: unknown, attempt: number) => void;
+  /** Backoff before retry `attempt` (1-based). Default: 200ms · 2^(attempt-1), capped at 5s. */
+  retryDelayMs?: (attempt: number) => number;
+  /** Max envelopes per flush. Default 32. */
+  maxBatch?: number;
+}
+
+interface Pending {
+  envelope: MutationEnvelope;
+  /** Resolves when the envelope's batch is confirmed (accepted OR rejected — both are
+   *  durably processed states). */
+  resolve: () => void;
+}
+
+const defaultDelay = (attempt: number): number => Math.min(200 * 2 ** (attempt - 1), 5_000);
+
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** A `MutationEnvelopeSender` (the `pushMutation` option of `RemoteOptimisticSource`) that
+ *  queues envelopes and delivers them as confirmed, in-order batches. */
+export function createQueuedMutationSender(opts: QueuedMutationSenderOptions): MutationEnvelopeSender {
+  const queue: Pending[] = [];
+  const maxBatch = Math.max(1, opts.maxBatch ?? 32);
+  const delay = opts.retryDelayMs ?? defaultDelay;
+  let flushing = false;
+
+  const flush = async (): Promise<void> => {
+    if (flushing) return;
+    flushing = true;
+    try {
+      while (queue.length > 0) {
+        const batch = queue.slice(0, maxBatch);
+        let outcomes: PushOutcome[] | void;
+        for (let attempt = 1; ; attempt++) {
+          try {
+            outcomes = await opts.send(batch.map((p) => p.envelope));
+            break;
+          } catch (err) {
+            opts.onError?.(err, attempt);
+            await sleep(delay(attempt));
+          }
+        }
+        queue.splice(0, batch.length);
+        batch.forEach((pending, i) => {
+          const outcome = Array.isArray(outcomes) ? outcomes[i] : undefined;
+          if (outcome && !outcome.accepted) {
+            opts.onRejected?.(pending.envelope, outcome.reason ?? "mutation rejected");
+          }
+          pending.resolve();
+        });
+      }
+    } finally {
+      flushing = false;
+    }
+    // Envelopes enqueued during the final await: a new flush owns them.
+    if (queue.length > 0) void flush();
+  };
+
+  return (envelope) =>
+    new Promise<void>((resolve) => {
+      queue.push({ envelope, resolve });
+      void flush();
+    });
+}

package/src/normalized.ts

@@ -0,0 +1,188 @@
+// The NORMALIZED subscription protocol — the wire contract shared by the server
+// (`@rindle/server`, which relays the native engine's already-stamped frames) and the client
+// (`RemoteNormalizedSource`, which validates via {@link NormalizedSubscriber}). The path-free
+// twin of `./protocol.ts`: same epoch/seq/gap envelope, normalized payloads (table-tagged
+// `NormalizedOp`s), and a slim per-table-schema hello (NORMALIZED-CHANGES-DESIGN.md §3).
+//
+// As with the flat path, the Subscriber does ONLY validation/sequencing and hands clean
+// `NormalizedEvent`s up — the `NormalizedSync` layer (in `@rindle/normalized`) folds them.
+
+import { COMPARATOR_VERSION } from "@rindle/client";
+import type { NormalizedEvent, NormalizedOp, NormalizedTableSchema } from "@rindle/client";
+
+import { Fnv } from "./protocol.ts";
+import { ProtocolError } from "./protocol.ts";
+
+// ----------------------------- normalized fingerprint -----------------------------
+
+/** A `tables` set's content fingerprint — FNV-1a 64 over the canonical, length-prefixed byte
+ *  stream of `rindle-replica::normalize_protocol::normalized_fp` (PK resolved to column NAMES),
+ *  as 16-char lowercase hex (=== the Rust hex). `tables` MUST be sorted by name (the server's
+ *  `NormalizedPublisher` guarantees it) so the fingerprint is order-stable. */
+export function normalizedFp(tables: NormalizedTableSchema[]): string {
+  const f = new Fnv();
+  f.u32(tables.length);
+  for (const t of tables) {
+    f.s(t.name);
+    f.u32(t.columns.length);
+    for (const c of t.columns) f.s(c);
+    f.u32(t.primaryKey.length);
+    for (const pk of t.primaryKey) f.s(t.columns[pk]); // PK by NAME
+  }
+  return f.h.toString(16).padStart(16, "0");
+}
+
+/** Is `sub` a subsequence of `sup` by NAME — every entry of `sub` present in `sup`, in order?
+ *  Accepts a projection (server ⊆ client) or an expansion (client ⊆ server); a rename/reorder
+ *  satisfies neither direction. */
+function isSubsequenceByName(sub: readonly string[], sup: readonly string[]): boolean {
+  let i = 0;
+  for (const name of sup) if (i < sub.length && sub[i] === name) i++;
+  return i === sub.length;
+}
+
+/** Validate the tables a `hello` advertises against the CLIENT's own typed schema, by name
+ *  (column order + PK indices). `hello.tables` is the query's table subtree, so each one must
+ *  be column-compatible with a client table. Throws {@link ProtocolError} `"schema-mismatch"`
+ *  on the first unknown table / column-order skew / PK skew — the §3 "drift ⇒ re-subscribe"
+ *  guard (CRIT#4). */
+function validateAgainstClientSchema(
+  serverTables: NormalizedTableSchema[],
+  clientTables: NormalizedTableSchema[],
+): void {
+  const byName = new Map(clientTables.map((t) => [t.name, t]));
+  const eq = (a: readonly (string | number)[], b: readonly (string | number)[]) =>
+    a.length === b.length && a.every((x, i) => x === b[i]);
+  for (const st of serverTables) {
+    const ct = byName.get(st.name);
+    if (!ct) {
+      throw new ProtocolError("schema-mismatch", `server advertises table "${st.name}" not in the client schema`);
+    }
+    // The server may advertise FEWER columns than the client (a projected query —
+    // PROJECTION-SUPPORT-DESIGN.md §5.2/§7) OR MORE (an EXPANDED server table mid an
+    // `expand-then-contract` migration — the client drops the columns it doesn't yet have).
+    // Both are safe: the client maps every advertised column to a base position BY NAME, so
+    // the relative order is preserved either way. Accept when one column list is a SUBSEQUENCE
+    // of the other by name — a narrowing (projection) or a widening (expand) — while still
+    // rejecting a genuine skew, where NEITHER is a subsequence of the other: a renamed column
+    // or a reordered one (the CRIT#4 guard). A server with more columns than the client is no
+    // longer drift; without this, `expand-then-contract` is impossible.
+    if (!isSubsequenceByName(st.columns, ct.columns) && !isSubsequenceByName(ct.columns, st.columns)) {
+      throw new ProtocolError(
+        "schema-mismatch",
+        `column drift on "${st.name}": server [${st.columns}] is neither a projection nor an expansion of client [${ct.columns}] (column order skew)`,
+      );
+    }
+    // PK compared by NAME (the server forces the PK into every projection, so it is always
+    // present): resolve each side's PK indices to names and require equality.
+    const serverPk = st.primaryKey.map((i) => st.columns[i]);
+    const clientPk = ct.primaryKey.map((i) => ct.columns[i]);
+    if (!eq(serverPk, clientPk)) {
+      throw new ProtocolError(
+        "schema-mismatch",
+        `primary-key drift on "${st.name}": client [${clientPk}] != server [${serverPk}]`,
+      );
+    }
+  }
+}
+
+// ----------------------------- the wire frames -----------------------------
+
+/** The slim normalized handshake (§3), sent once before any {@link NormalizedBatch}. */
+export interface NormalizedHello {
+  epoch: number;
+  comparatorVersion: number;
+  tables: NormalizedTableSchema[];
+  normalizedFp: string;
+}
+
+/** One committed transaction's normalized ops (or the seq-0 hydrate snapshot). `cv` (the
+ *  global commit version the frame reflects) is stamped by optimistic-protocol servers and
+ *  rides through to the `NormalizedEvent` (OPTIMISTIC-WRITES-DESIGN.md §8.3). */
+export interface NormalizedBatch {
+  epoch: number;
+  seq: number;
+  normalizedFp: string;
+  ops: NormalizedOp[];
+  cv?: number;
+}
+
+// ----------------------------- Subscriber (client side) -----------------------------
+
+/** Receiver side: validates a normalized frame stream (comparator at `hello`; per batch —
+ *  epoch match, fingerprint match, strict in-order seq) and emits clean `NormalizedEvent`s.
+ *  It does NOT fold (the `NormalizedSync` layer does). Mirrors the flat {@link Subscriber}. */
+export class NormalizedSubscriber {
+  readonly epoch: number;
+  readonly normalizedFp: string;
+  private readonly emit: (ev: NormalizedEvent) => void;
+  private phase: "snapshot" | "live" = "snapshot";
+  private lastSeq = 0;
+
+  /**
+   * @param hello         the server's normalized handshake.
+   * @param emit          clean-event sink (the `NormalizedSync` fold).
+   * @param clientTables  the CLIENT's own typed per-table schemas (all tables). When given,
+   *   each table the hello advertises is validated by NAME against it (column order + PK
+   *   indices). The hello's `tables` is a per-query SUBSET (the query's table tree), so this
+   *   checks each advertised table rather than one global fingerprint. A mismatch (routine
+   *   deployment / schema skew) is rejected here — without it, positional rows aligned to the
+   *   SERVER's column order are stored verbatim under the CLIENT's order, silently swapping
+   *   cells and mis-keying the refcount/GC (CRIT#4 / §3 "drift ⇒ re-subscribe").
+   */
+  constructor(
+    hello: NormalizedHello,
+    emit: (ev: NormalizedEvent) => void,
+    clientTables?: NormalizedTableSchema[],
+  ) {
+    this.emit = emit;
+    if (hello.comparatorVersion !== COMPARATOR_VERSION) {
+      throw new ProtocolError(
+        "comparator-mismatch",
+        `comparator version ${hello.comparatorVersion} != ${COMPARATOR_VERSION}`,
+      );
+    }
+    const computed = normalizedFp(hello.tables);
+    if (computed !== hello.normalizedFp) {
+      throw new ProtocolError("schema-mismatch", `advertised fp ${hello.normalizedFp} != computed ${computed}`);
+    }
+    if (clientTables) validateAgainstClientSchema(hello.tables, clientTables);
+    this.epoch = hello.epoch;
+    this.normalizedFp = hello.normalizedFp;
+    emit({
+      type: "hello",
+      tables: hello.tables,
+      comparatorVersion: hello.comparatorVersion,
+      normalizedFp: hello.normalizedFp,
+    });
+  }
+
+  /** Apply one normalized batch (or the seq-0 snapshot). Returns `"duplicate"` for an
+   *  already-applied seq; throws {@link ProtocolError} on a gap / epoch / fp mismatch (the
+   *  caller re-hydrates under a new epoch). */
+  apply(batch: NormalizedBatch): "applied" | "duplicate" {
+    if (batch.epoch !== this.epoch) {
+      throw new ProtocolError("epoch-mismatch", `expected epoch ${this.epoch}, got ${batch.epoch}`);
+    }
+    if (batch.normalizedFp !== this.normalizedFp) {
+      throw new ProtocolError("schema-mismatch", `expected fp ${this.normalizedFp}, got ${batch.normalizedFp}`);
+    }
+    if (this.phase === "snapshot") {
+      if (batch.seq === 0) {
+        this.phase = "live";
+        this.lastSeq = 0;
+        this.emit({ type: "snapshot", ops: batch.ops, cv: batch.cv });
+        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", ops: batch.ops, cv: batch.cv });
+    return "applied";
+  }
+}