@rindle/remote 0.1.0-rc.5

package/dist/normalized.d.ts

@@ -0,0 +1,50 @@
+import type { NormalizedEvent, NormalizedOp, NormalizedTableSchema } from "@rindle/client";
+/** 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 declare function normalizedFp(tables: NormalizedTableSchema[]): string;
+/** 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;
+}
+/** 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 declare class NormalizedSubscriber {
+    readonly epoch: number;
+    readonly normalizedFp: string;
+    private readonly emit;
+    private phase;
+    private lastSeq;
+    /**
+     * @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[]);
+    /** 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";
+}
+//# sourceMappingURL=normalized.d.ts.map

package/dist/normalized.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalized.d.ts","sourceRoot":"","sources":["../src/normalized.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAO3F;;;+EAG+E;AAC/E,wBAAgB,YAAY,CAAC,MAAM,EAAE,qBAAqB,EAAE,GAAG,MAAM,CAWpE;AA0DD,wFAAwF;AACxF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;iFAEiF;AACjF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,YAAY,EAAE,CAAC;IACpB,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAID;;+FAE+F;AAC/F,qBAAa,oBAAoB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgC;IACrD,OAAO,CAAC,KAAK,CAAmC;IAChD,OAAO,CAAC,OAAO,CAAK;IAEpB;;;;;;;;;;OAUG;gBAED,KAAK,EAAE,eAAe,EACtB,IAAI,EAAE,CAAC,EAAE,EAAE,eAAe,KAAK,IAAI,EACnC,YAAY,CAAC,EAAE,qBAAqB,EAAE;IAwBxC;;iDAE6C;IAC7C,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,SAAS,GAAG,WAAW;CAyBvD"}

package/dist/normalized.js

@@ -0,0 +1,146 @@
+// 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 { Fnv } from "./protocol.js";
+import { ProtocolError } from "./protocol.js";
+// ----------------------------- 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) {
+    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, sup) {
+    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, clientTables) {
+    const byName = new Map(clientTables.map((t) => [t.name, t]));
+    const eq = (a, b) => 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}]`);
+        }
+    }
+}
+// ----------------------------- 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 {
+    epoch;
+    normalizedFp;
+    emit;
+    phase = "snapshot";
+    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, emit, clientTables) {
+        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) {
+        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";
+    }
+}
+//# sourceMappingURL=normalized.js.map

package/dist/normalized.js.map

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

package/dist/optimistic-source.d.ts

@@ -0,0 +1,108 @@
+import type { MutationEnvelope, NormalizedEvent, NormalizedTableSchema, OptimisticSource, ProgressFrame, QueryId, RemoteQuery } from "@rindle/client";
+import { type MutationEnvelopeSender, type SubscribeResolver } from "./subscribe.ts";
+import type { Transport } from "./transport.ts";
+/** 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 declare class RemoteOptimisticSource implements OptimisticSource {
+    /** The CURRENT transport (undefined in pure-lazy mode until the first lease opens one). */
+    private transport;
+    /** The ws endpoint the current transport points at (undefined for a fixed transport). */
+    private currentEndpoint;
+    /** Builds a transport for an endpoint; undefined ⇒ fixed transport (no migration). */
+    private readonly transportFactory;
+    private readonly clientID;
+    private readonly resolveSubscribe;
+    private readonly pushMutationSender?;
+    private handler;
+    private progressHandler;
+    private restartHandler;
+    private readonly subs;
+    /** 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;
+    /** The daemon's boot id (from each `nhello`); a change means it restarted. */
+    private lastBootId;
+    /** The client's own typed per-table schemas, for hello validation (CRIT#4); set by the backend. */
+    private clientTables;
+    /** 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;
+    /** 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;
+    /** 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;
+    constructor(connection: RemoteOptimisticConnection, clientID: string, opts?: RemoteOptimisticSourceOptions);
+    /** Wire a transport's handlers (no `init`). */
+    private attach;
+    /** Make `transport` the current one, announce identity, and (re)subscribe anything deferred. */
+    private bringUp;
+    /** Build + bring up a fresh transport to `endpoint` (replaceable mode only). */
+    private openEndpoint;
+    /** 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;
+    /** 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;
+    /** Flush subscribes deferred until a transport existed (e.g. the lmid query in pure-lazy mode). */
+    private flushDeferred;
+    /** 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;
+    /** 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;
+    /** 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;
+    expectClientSchema(tables: NormalizedTableSchema[]): void;
+    registerQuery(qid: QueryId, remote: RemoteQuery): void;
+    unregisterQuery(qid: QueryId): void;
+    pushMutation(envelope: MutationEnvelope): Promise<void>;
+    onNormalized(handler: (qid: QueryId, ev: NormalizedEvent) => void): void;
+    onProgress(handler: (frame: ProgressFrame) => void): void;
+    private subscribe;
+    private onServerMsg;
+    /** 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;
+    /** Track the daemon's boot id; a change (after the first) means it restarted — fire onRestart. */
+    private observeBootId;
+    private openSubscriber;
+    private applyBatch;
+}
+/** 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 declare function createRemoteOptimisticSource(urlOrTransport: string | Transport, clientID: string, opts?: RemoteOptimisticSourceOptions): RemoteOptimisticSource;
+//# sourceMappingURL=optimistic-source.d.ts.map

package/dist/optimistic-source.d.ts.map

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

package/dist/optimistic-source.js

@@ -0,0 +1,317 @@
+// 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 { NormalizedSubscriber } from "./normalized.js";
+import { ProtocolError } from "./protocol.js";
+import { defaultSubscribeTarget, isThenable, subscribeMessage, } from "./subscribe.js";
+import { WsTransport } from "./transport.js";
+export class RemoteOptimisticSource {
+    /** The CURRENT transport (undefined in pure-lazy mode until the first lease opens one). */
+    transport;
+    /** The ws endpoint the current transport points at (undefined for a fixed transport). */
+    currentEndpoint;
+    /** Builds a transport for an endpoint; undefined ⇒ fixed transport (no migration). */
+    transportFactory;
+    clientID;
+    resolveSubscribe;
+    pushMutationSender;
+    handler = () => { };
+    progressHandler = () => { };
+    restartHandler = () => { };
+    subs = new Map();
+    /** 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. */
+    deferred = new Set();
+    /** The daemon's boot id (from each `nhello`); a change means it restarted. */
+    lastBootId;
+    /** The client's own typed per-table schemas, for hello validation (CRIT#4); set by the backend. */
+    clientTables;
+    /** Once true (set by {@link close}), in-flight lease resolutions are inert — they must not open a
+     *  new transport or send after teardown. */
+    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. */
+    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. */
+    resubscribeGen = 0;
+    constructor(connection, clientID, opts = {}) {
+        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`). */
+    attach(transport) {
+        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. */
+    bringUp(transport, endpoint) {
+        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). */
+    openEndpoint(endpoint) {
+        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). */
+    migrate(endpoint) {
+        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. */
+    resubscribeAll() {
+        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). */
+    flushDeferred() {
+        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. */
+    onDown() {
+        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() {
+        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) {
+        this.restartHandler = handler;
+    }
+    expectClientSchema(tables) {
+        this.clientTables = tables;
+    }
+    registerQuery(qid, remote) {
+        this.subs.set(qid, { remote, subscriber: null, epoch: 0, resubscribing: false, subscribeTicket: 0 });
+        this.subscribe(qid, remote);
+    }
+    unregisterQuery(qid) {
+        this.subs.delete(qid);
+        this.deferred.delete(qid);
+        this.transport?.send({ t: "unsubscribe", queryId: qid });
+    }
+    pushMutation(envelope) {
+        if (this.pushMutationSender)
+            return Promise.resolve(this.pushMutationSender(envelope));
+        this.transport?.send({ t: "pushMutation", envelope });
+        return Promise.resolve();
+    }
+    onNormalized(handler) {
+        this.handler = handler;
+    }
+    onProgress(handler) {
+        this.progressHandler = handler;
+    }
+    // --- internals ---------------------------------------------------------------
+    subscribe(qid, remote) {
+        const s = this.subs.get(qid);
+        if (!s)
+            return;
+        const request = { queryId: qid, remote, mode: "normalized" };
+        const ticket = ++s.subscribeTicket;
+        const send = (target) => {
+            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) => {
+            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?.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);
+        }
+    }
+    onServerMsg(msg) {
+        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). */
+    resync() {
+        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. */
+    observeBootId(bootId) {
+        if (!bootId)
+            return;
+        if (this.lastBootId !== undefined && bootId !== this.lastBootId)
+            this.restartHandler();
+        this.lastBootId = bootId;
+    }
+    openSubscriber(qid, s, hello) {
+        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.message}`);
+        }
+    }
+    applyBatch(qid, s, batch) {
+        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, clientID, opts = {}) {
+    const connection = typeof urlOrTransport === "string"
+        ? { factory: (endpoint) => new WsTransport(endpoint), endpoint: urlOrTransport }
+        : urlOrTransport;
+    return new RemoteOptimisticSource(connection, clientID, opts);
+}
+function isTransport(value) {
+    return typeof value.send === "function" && typeof value.onMessage === "function";
+}
+//# sourceMappingURL=optimistic-source.js.map