@rindle/optimistic 0.4.2 → 0.4.4

package/dist/local-persist.js

@@ -0,0 +1,957 @@
+// Local-table persistence (207-LOCAL-TABLE-PERSISTENCE-DESIGN.md): durable, cross-tab
+// local-only tables via IndexedDB + a Web-Locks leader.
+//
+// The whole layer lives OUTSIDE the backend, over exactly two seams 201/207 carved:
+//   - `backend.onLocalWrite(observer)` — every committed `writeLocal` batch (the write-through tap);
+//   - `backend.applyLocalReplica(muts)` — the application path for restore + commits (no observer,
+//     so the echo guard is structural; still funnels the engine's M2 locality guard, P8).
+//
+// Shape (§4): every tab requests one exclusive Web Lock — the holder is the leader, the browser's
+// queue is the whole election (§4.1). The leader is the sole IDB writer and the commit sequencer;
+// it persists a batch, THEN broadcasts a `commit` (P1/P2). Followers apply their own writes
+// immediately, forward row-state ops to the leader, and hold them unacked until the matching
+// commit (P4). All replication is idempotent full-ROW STATE (`put(pk,row)`/`tombstone(pk)`)
+// applied through a per-tab MIRROR (a JS Map per local table) that diffs incoming state against
+// known state and emits the correct engine add/edit/remove (§4.4, P3) — resend, replay, and
+// snapshot/stream overlap are all no-ops by construction.
+//
+// Browser globals are reached via structural typing (this package has no DOM lib — precedent
+// `client.ts:154-158`); the same structural seam (`PersistEnv`) is what the tests inject a fake
+// IDB/channel/locks environment through.
+import { localSchemaHash, persistedLocalTableNames, rowsEqual, tableSpec } from "@rindle/client";
+/** Delete a user's local-persistence database — the sanctioned LOGOUT hook (§3.2). Never called
+ *  implicitly; the old database otherwise remains on disk (fast re-login, and a privacy decision
+ *  the app owns). Close this tab's live client for `user` first; a SIBLING tab's connection is
+ *  released automatically (it closes on `versionchange` and degrades to broadcast-only), so a
+ *  multi-tab logout completes instead of parking behind the other tab forever. */
+export function deleteLocalPersistence(user, env) {
+    return (env ?? defaultEnv()).deleteDatabase(dbName(user));
+}
+/** Attach the persistence layer to a backend (standalone form — `createRindleClient` calls this
+ *  for you). The observer is wired SYNCHRONOUSLY, but the mirror starts empty: attach before the
+ *  first `writeLocal` (§5.2, a v1 constraint `createRindleClient` satisfies by construction).
+ *  Await `handle.ready` before first render if the app wants restored rows at first paint. */
+export function attachLocalPersistence(backend, schema, opts) {
+    return new LocalPersistLayer(backend, schema, opts);
+}
+function dbName(user) {
+    return `rindle-local:${user}`;
+}
+/** The channel is partitioned by schema hash (the lock + database stay per-user): a mixed-version
+ *  peer mid-deploy must never replicate old-shape rows into a new-schema engine — the width guard
+ *  cannot catch a same-width reshape (a column rename or retype), so cross-version traffic is made
+ *  structurally impossible instead. The old-version leader keeps the shared lock until it closes;
+ *  new-version tabs run local-first meanwhile and adopt their unacked ops at promotion (§4.5). */
+function channelName(user, schemaHash) {
+    return `${dbName(user)}::${schemaHash}`;
+}
+class LocalPersistLayer {
+    ready;
+    backend;
+    onError;
+    env;
+    /** Per PERSISTED local table (`local: true` — a `local: "session"` table stays outside the
+     *  plane, §5.4): pk extraction + width (from the same schema meta `tableSpec` reads, §5.3). */
+    tables = new Map();
+    schemaHash;
+    /** The §4.4 mirror: per PERSISTED local table, pkKey → engine row — the JS twin of the local
+     *  source. A `null` value is a PRE-RESTORE TOMBSTONE (§4.6 step 4): a remove issued before the
+     *  snapshot landed must not be resurrected by it (`has()` covers both shapes); swept once live. */
+    mirror = new Map();
+    /** `local: "session"` table names (§5.4) — inbound states naming one are dropped, never
+     *  funneled to the engine (M2 admits local tables, so the isolation guard lives here). */
+    sessionOnly = new Set();
+    /** This layer instance's identity on the channel (NOT the clientID — two clients in one tab are
+     *  two "tabs" here, §9). */
+    origin;
+    channel = null;
+    db = null;
+    // --- role / election state (§4.1–§4.2) ---
+    leader = false;
+    /** Leader-only: announcement broadcast; incoming `op`s are processed. Before this (mid-promotion)
+     *  ops are dropped — the sender re-sends on the `leader` announcement (§4.5). */
+    leaderLive = false;
+    releaseLock = null;
+    lockAbort = new AbortController();
+    epoch = 0;
+    /** Highest `leader`/`commit` epoch seen; commits below it are discarded (P6). */
+    highestEpoch = 0;
+    lseq = 0;
+    /** Leader-only: the serialized persist→broadcast chain (P1/P2 — one writer, one order). */
+    persistChain = Promise.resolve();
+    // --- follower state (P4) ---
+    opSeq = 0;
+    /** Ops applied locally + forwarded, held until the matching `commit` acks them (§4.5). */
+    unacked = new Map();
+    /** Per-pk hold-back (§4.2): `table\0pkKey` → the seq of this tab's LATEST uncommitted write to
+     *  that pk. While set, any other state for the pk (our own earlier echo, or a foreign write the
+     *  leader sequenced before ours) is stale relative to our tail — applying it would visibly
+     *  rewind the row and then snap it forward again. Cleared when the write's own commit applies. */
+    pendingByPk = new Map();
+    /** P9 bookkeeping: `table\0pkKey`s whose LAST commit was broadcast with `p: false` (the persist
+     *  failed or there is no IDB) — IDB does not reflect the coherent state for them. A leader
+     *  retries them from the mirror on later chain steps; a promotion REPAIRS them before diffing,
+     *  so the IDB gap is never misread as a persisted-but-unannounced remove. */
+    notInIdb = new Set();
+    // --- boot state (§4.6) ---
+    live = false;
+    bootBuffer = [];
+    /** Boot's meta verdict — the FALLBACK for the P7 decision when promotion's authoritative
+     *  re-read (under the lock) fails: anything but a clean boot `match` then fails CLOSED
+     *  (reset), because stamping the new hash over unverified rows would legitimize old-shape
+     *  data forever. `error` = boot couldn't read meta (nothing was restored). */
+    bootMeta = "error";
+    /** Resolves once the §4.6 restore has run. A field initializer (not a `start()` return) so it
+     *  exists BEFORE the lock request — an immediately-granted lock (solo mode / a free queue) must
+     *  still park its promotion behind the restore. */
+    restoreDone;
+    restored = new Promise((r) => {
+        this.restoreDone = r;
+    });
+    closed = false;
+    /** {@link PersistEnv.leaderElectionUnavailable}: the layer is attached but INERT. */
+    disabled;
+    constructor(backend, schema, opts) {
+        this.backend = backend;
+        this.env = opts.env ?? defaultEnv();
+        this.onError = opts.onError ?? ((e) => console.error("[rindle] local persistence:", e));
+        this.schemaHash = localSchemaHash(schema);
+        this.origin = mintOrigin();
+        for (const name of persistedLocalTableNames(schema)) {
+            const spec = tableSpec(schema.tables[name]);
+            this.tables.set(name, { pk: spec.primaryKey, width: spec.columns.length });
+            this.mirror.set(name, new Map());
+        }
+        // `local: "session"` tables (§5.4): local for every 201 rule, but OUTSIDE this plane — their
+        // writes are never forwarded/persisted, and an inbound state naming one (a mixed-version
+        // peer) must be dropped HERE: M2 would happily admit it (it IS local), which would break the
+        // per-tab isolation being ephemeral promises.
+        for (const name of Object.keys(schema.tables)) {
+            if (schema.tables[name].local === "session")
+                this.sessionOnly.add(name);
+        }
+        // The write-through tap (§5.1): committed origin writes → row state → mirror, then routed by
+        // role. Wired synchronously so no write can slip past the layer (the mirror starts empty).
+        backend.onLocalWrite((muts) => this.onOriginWrite(muts));
+        if (this.env.leaderElectionUnavailable) {
+            // Tabs without an exclusive lock would all self-promote: concurrent leaders over one
+            // database, P2 violated, permanent divergence. Run inert instead — local tables keep
+            // working, session-scoped (the 201 baseline).
+            this.disabled = true;
+            console.warn("[rindle] Web Locks unavailable — local-table persistence disabled (local tables are session-scoped).");
+            this.ready = Promise.resolve();
+            this.restoreDone();
+            return;
+        }
+        this.disabled = false;
+        if (opts.requestPersistentStorage)
+            this.env.requestPersistentStorage?.();
+        // §4.6 attach order: (1) channel first — start buffering; (2) queue for the lock; (3–5) open
+        // IDB, snapshot, replay (in start()).
+        this.channel = this.env.createChannel(channelName(opts.user, this.schemaHash));
+        this.channel?.onMessage((msg) => this.onMessage(msg));
+        this.env.requestLock(`rindle-local-leader:${opts.user}`, this.lockAbort.signal, () => this.onLockAcquired());
+        this.ready = this.start(opts.user);
+        void this.ready.then(this.restoreDone);
+    }
+    role() {
+        return this.leader ? "leader" : "follower";
+    }
+    // -------------------------------------------------------------------------------------------
+    // Boot: subscribe → snapshot → replay (§4.6)
+    // -------------------------------------------------------------------------------------------
+    async start(user) {
+        try {
+            this.db = await this.env.openDatabase(dbName(user));
+        }
+        catch (e) {
+            this.db = null;
+            this.onError(asError(e));
+        }
+        if (this.closed) {
+            // close() raced the open (it ran with db still null): release the fresh handle here or it
+            // holds the database open forever, blocking every later deleteLocalPersistence.
+            this.db?.close();
+            this.db = null;
+            return;
+        }
+        if (!this.db) {
+            console.warn("[rindle] IndexedDB unavailable — local tables are session-scoped (broadcast-only).");
+        }
+        let snapshot = [];
+        if (this.db) {
+            try {
+                const meta = await this.db.getMeta();
+                if (meta?.schemaHash === this.schemaHash) {
+                    this.bootMeta = "match";
+                    this.epoch = meta.epoch;
+                    this.highestEpoch = Math.max(this.highestEpoch, meta.epoch);
+                    snapshot = await this.db.getAllRows();
+                }
+                else {
+                    // P7: mismatch (or missing meta) ⇒ start empty. The on-disk CLEAR is deferred to
+                    // promotion (only the lock holder writes IDB — P2); until then we simply load nothing.
+                    this.bootMeta = "mismatch";
+                    this.epoch = meta?.epoch ?? 0;
+                }
+            }
+            catch (e) {
+                this.bootMeta = "error"; // nothing restored; promotion must fail CLOSED on this store
+                this.onError(asError(e));
+                snapshot = [];
+            }
+        }
+        if (this.closed) {
+            this.db?.close(); // same close()-race exit as above — never leak the connection
+            this.db = null;
+            return;
+        }
+        try {
+            this.applySnapshot(snapshot);
+        }
+        catch (e) {
+            this.onError(asError(e)); // degraded restore, never a broken client construction (P9)
+        }
+        // Replay the buffered stream (gap-free by P1: anything broadcast pre-subscribe is in the
+        // snapshot; anything after is in the buffer; the overlap is a mirror no-op, P3).
+        this.live = true;
+        for (const m of this.mirror.values()) {
+            for (const [k, v] of m)
+                if (v === null)
+                    m.delete(k); // sweep the pre-restore tombstones
+        }
+        const buffered = this.bootBuffer.splice(0);
+        for (const msg of buffered)
+            this.dispatch(msg);
+    }
+    /** §4.6 step 4: apply the IDB snapshot through the mirror, one engine batch per table (§5.3).
+     *  Skips any pkKey the mirror already knows — a row written this session is newer than the
+     *  snapshot, and a pre-restore remove left a `null` tombstone, so `has()` covers both. Records
+     *  whose table is not a current local table are dropped — table-set schema evolution is handled
+     *  by data, not DDL (§3.1); the leader's promotion sweep deletes them from disk. */
+    applySnapshot(snapshot) {
+        const byTable = new Map();
+        for (const rec of snapshot) {
+            const info = this.tables.get(rec.table);
+            if (!info)
+                continue; // stale table (dropped from the schema) — leader sweeps it at promotion
+            if (!validRow(rec.row, info.width)) {
+                this.onError(new Error(`local persistence: dropped a wrong-width row for "${rec.table}" (P7 shape guard)`));
+                continue;
+            }
+            if (this.mirror.get(rec.table).has(rec.pkKey))
+                continue; // this session already wrote (or removed) it — newer
+            let group = byTable.get(rec.table);
+            if (!group)
+                byTable.set(rec.table, (group = []));
+            group.push({ table: rec.table, pkKey: rec.pkKey, row: rec.row });
+        }
+        for (const states of byTable.values())
+            this.applyStates(states);
+    }
+    // -------------------------------------------------------------------------------------------
+    // Origin writes: the tap (§4.2 roles)
+    // -------------------------------------------------------------------------------------------
+    /** A committed `writeLocal` batch from THIS tab: derive row state, fold it into the mirror
+     *  synchronously (§4.4 — the engine already holds it), then route by role. Never throws (P9). */
+    onOriginWrite(muts) {
+        if (this.disabled || this.closed)
+            return;
+        try {
+            const states = this.statesFromMutations(muts);
+            if (!states.length)
+                return;
+            const seq = ++this.opSeq;
+            for (const s of states) {
+                const m = this.mirror.get(s.table);
+                if (s.row === null) {
+                    // Pre-live, a remove leaves a TOMBSTONE (`null`) so the §4.6 snapshot skip covers it;
+                    // once live the snapshot can't resurrect anything and plain deletion suffices.
+                    if (this.live)
+                        m.delete(s.pkKey);
+                    else
+                        m.set(s.pkKey, null);
+                }
+                else {
+                    m.set(s.pkKey, s.row);
+                }
+                this.pendingByPk.set(`${s.table}\0${s.pkKey}`, seq); // §4.2 hold-back until this commits
+            }
+            if (this.leader && this.leaderLive) {
+                this.sequence(this.origin, seq, states);
+            }
+            else {
+                // Follower (or leaderless / mid-boot): buffer unacked + forward. A leaderless op just
+                // sits; the next `leader` announcement triggers the re-send (§4.5).
+                this.unacked.set(seq, states);
+                this.channel?.post({ t: "op", origin: this.origin, seq, batch: states });
+            }
+        }
+        catch (e) {
+            this.onError(asError(e));
+        }
+    }
+    /** Mutation batch → idempotent row state (§4.3): add/edit → put(new) (a pk-changing edit becomes
+     *  tombstone(old) + put(new)); remove → tombstone. Later entries for one pk supersede earlier
+     *  ones by array order (applied in order everywhere). */
+    statesFromMutations(muts) {
+        const out = [];
+        for (const m of muts) {
+            const info = this.tables.get(m.table);
+            if (!info)
+                continue; // a `local: "session"` table (§5.4) — this tab's business only
+            if (m.op === "add") {
+                out.push({ table: m.table, pkKey: pkKeyOf(m.row, info.pk), row: m.row });
+            }
+            else if (m.op === "remove") {
+                out.push({ table: m.table, pkKey: pkKeyOf(m.row, info.pk), row: null });
+            }
+            else {
+                const oldKey = pkKeyOf(m.old, info.pk);
+                const newKey = pkKeyOf(m.new, info.pk);
+                if (oldKey !== newKey)
+                    out.push({ table: m.table, pkKey: oldKey, row: null });
+                out.push({ table: m.table, pkKey: newKey, row: m.new });
+            }
+        }
+        return out;
+    }
+    // -------------------------------------------------------------------------------------------
+    // The mirror applier (§4.4, P3) — the ONLY path replicated state takes into the engine
+    // -------------------------------------------------------------------------------------------
+    /** Apply row states through the mirror: diff against known state, emit the correct engine
+     *  delta, commit as ONE `applyLocalReplica` batch, and update the mirror at the engine's
+     *  post-commit anchor. Idempotent: matching state is a no-op. `staged` overlays the mirror
+     *  WITHIN the batch, so two states for one pk compose (add + edit), never collide.
+     *
+     *  `commit` names the commit being applied (absent for restore/promotion folds). It drives the
+     *  §4.2 per-pk hold-back: while THIS tab has a newer uncommitted write to a pk, every other
+     *  state for it — the echo of our own earlier write, or a foreign write the leader sequenced
+     *  before ours — is stale relative to our tail; applying it would visibly rewind the row and
+     *  snap it forward again (one full persist round-trip per keystroke on the draft-typing path).
+     *  Skipped states skip engine AND mirror, which therefore stay in lockstep; the hold clears
+     *  when the pending write's own commit arrives, and convergence is untouched (a foreign write
+     *  sequenced AFTER ours applies normally once the hold is gone). */
+    applyStates(states, commit) {
+        const muts = [];
+        const mirrorOps = [];
+        const staged = new Map(); // this batch's writes-so-far, by table\0pkKey
+        for (const s of states) {
+            const m = this.mirror.get(s.table);
+            if (!m) {
+                // A `local: "session"` table is OUTSIDE the plane (§5.4): drop silently — same posture
+                // as a stale-table snapshot record (a mixed-version peer mid-deploy is normal, §3.1).
+                if (this.sessionOnly.has(s.table))
+                    continue;
+                if (s.row !== null) {
+                    // Not a local table. Do NOT pre-filter: funnel it so `WasmBackend.writeLocal`'s M2
+                    // guard rejects it loudly (P8) — the batch dies whole, the mirror is untouched.
+                    muts.push({ op: "add", table: s.table, row: s.row });
+                }
+                continue;
+            }
+            const info = this.tables.get(s.table);
+            const key = `${s.table}\0${s.pkKey}`;
+            const pendingSeq = this.pendingByPk.get(key);
+            if (pendingSeq !== undefined) {
+                if (commit !== undefined && commit.origin === this.origin && commit.seq >= pendingSeq) {
+                    this.pendingByPk.delete(key); // our latest write to this pk is the one committing
+                }
+                else {
+                    continue; // §4.2 hold-back: a newer own write is still uncommitted
+                }
+            }
+            const cur = staged.has(key) ? staged.get(key) : (m.get(s.pkKey) ?? null);
+            if (s.row === null) {
+                if (cur) {
+                    muts.push({ op: "remove", table: s.table, row: cur });
+                    mirrorOps.push(() => m.delete(s.pkKey));
+                    staged.set(key, null);
+                }
+            }
+            else if (!validRow(s.row, info.width)) {
+                // Shape guard: a malformed replicated row must not reach the engine (wasm builds
+                // panic=abort) — same test as the snapshot/promotion ingress points, deliberately shared.
+                this.onError(new Error(`local persistence: dropped a malformed replicated row for "${s.table}"`));
+            }
+            else if (!cur) {
+                const row = s.row;
+                muts.push({ op: "add", table: s.table, row });
+                mirrorOps.push(() => m.set(s.pkKey, row));
+                staged.set(key, row);
+            }
+            else if (!rowsEqual(cur, s.row)) {
+                const row = s.row;
+                muts.push({ op: "edit", table: s.table, old: cur, new: row });
+                mirrorOps.push(() => m.set(s.pkKey, row));
+                staged.set(key, row);
+            }
+        }
+        // The mirror updates run at the engine's post-commit anchor — after `tx.commit()`, BEFORE
+        // subscriber delivery. A pre-commit rejection (M2) skips them with the engine untouched
+        // (loud, P8); a subscriber throwing during delivery re-raises AFTER them — either way
+        // mirror == engine. (Running them pre-delivery also means a subscriber that synchronously
+        // writeLocal's a row in this batch lands its fresher mirror entry AFTER ours — never under.)
+        if (muts.length) {
+            this.backend.applyLocalReplica(muts, () => {
+                for (const f of mirrorOps)
+                    f();
+            });
+        }
+    }
+    // -------------------------------------------------------------------------------------------
+    // The channel (§4.3)
+    // -------------------------------------------------------------------------------------------
+    onMessage(msg) {
+        if (this.closed || !msg || typeof msg !== "object")
+            return;
+        if (!this.live) {
+            this.bootBuffer.push(msg); // §4.6 step 1: buffer until the snapshot is in
+            return;
+        }
+        this.dispatch(msg);
+    }
+    dispatch(msg) {
+        try {
+            if (msg.t === "op") {
+                // Only a LIVE leader sequences ops; mid-promotion (lock held, not announced) they are
+                // dropped — the sender re-sends on the `leader` announcement (§4.5).
+                if (this.leader && this.leaderLive)
+                    this.sequence(msg.origin, msg.seq, msg.batch);
+            }
+            else if (msg.t === "commit") {
+                if (msg.epoch < this.highestEpoch)
+                    return; // stale epoch (P6)
+                this.highestEpoch = Math.max(this.highestEpoch, msg.epoch);
+                this.noteDurability(msg.batch, msg.p !== false); // P9 bookkeeping (promotion repairs it)
+                // Everyone applies, origin included (§4.2/P3) — modulo the per-pk hold-back, which skips
+                // states superseded by this tab's own uncommitted tail (see applyStates).
+                this.applyStates(msg.batch, { origin: msg.origin, seq: msg.seq });
+                if (msg.origin === this.origin)
+                    this.unacked.delete(msg.seq); // the ack (P4)
+            }
+            else if (msg.t === "leader") {
+                this.highestEpoch = Math.max(this.highestEpoch, msg.epoch);
+                // P4: a new leader means our unacked ops may never have been persisted — re-send them
+                // all, in seq order; mirror application makes any duplicate a no-op (P3).
+                this.resendUnacked();
+            }
+        }
+        catch (e) {
+            this.onError(asError(e));
+        }
+    }
+    // -------------------------------------------------------------------------------------------
+    // Leadership (§4.1, §4.5)
+    // -------------------------------------------------------------------------------------------
+    /** The lock callback: the returned promise HOLDS the lock until close() (§4.1). Promotion runs
+     *  after our own restore completes; ops arriving meanwhile are dropped and re-sent on the
+     *  announcement (§4.5). */
+    onLockAcquired() {
+        if (this.closed) {
+            // close() raced the grant (`abort()` no-ops once granted, and `releaseLock` was still
+            // null when close ran): resolve immediately, or the exclusive lock is held until the tab
+            // dies and every other tab for this user queues leaderless forever.
+            return Promise.resolve();
+        }
+        const held = new Promise((resolve) => {
+            this.releaseLock = resolve;
+        });
+        void this.promote();
+        return held;
+    }
+    async promote() {
+        try {
+            await this.restored;
+            if (this.closed)
+                return;
+            this.leader = true;
+            const pendingReset = await this.resetPending();
+            // P6: monotonic epochs — above both the persisted high-water and any announcement heard.
+            this.epoch = Math.max(this.epoch, this.highestEpoch) + 1;
+            this.highestEpoch = this.epoch;
+            if (this.db) {
+                if (pendingReset) {
+                    // P7, deferred from boot (P2 — only the leader writes): clear + new hash, one txn.
+                    await this.db.reset({ schemaHash: this.schemaHash, epoch: this.epoch });
+                    if (this.closed)
+                        return;
+                    this.notInIdb.clear(); // the store was just cleared; the seed below re-persists it all
+                    // Adopt our follower-era ops FIRST (their per-pk holds clear in original order), then
+                    // persist + announce the mirror itself: IDB was just cleared, so the "diff vs IDB"
+                    // below is vacuous — this session's live rows are all the data there is.
+                    this.adoptUnacked();
+                    const seed = this.mirrorStates();
+                    if (seed.length)
+                        this.sequence(this.origin, ++this.opSeq, seed);
+                }
+                else {
+                    await this.db.putMeta({ schemaHash: this.schemaHash, epoch: this.epoch });
+                    if (this.closed)
+                        return;
+                    await this.promotionDiff();
+                }
+            }
+            if (this.closed)
+                return;
+            // Adopt our OWN unacked ops (we were a follower): sequence + persist them ourselves, in
+            // seq order. Anything the old leader did persist re-persists identically (idempotent).
+            this.adoptUnacked();
+            // Announce LAST (§4.5 step 3): followers now re-send their unacked ops to us.
+            this.leaderLive = true;
+            this.channel?.post({ t: "leader", epoch: this.epoch });
+        }
+        catch (e) {
+            if (this.closed)
+                return;
+            this.onError(asError(e));
+            // Storage failed mid-promotion: stay leader (the lock is ours) in broadcast-only degrade —
+            // and STILL adopt our own unacked ops: no other tab can ever re-send them for us, and
+            // sequence() never throws (its persist failure is the P9 catch), so coherence survives
+            // even though this durability attempt didn't.
+            this.adoptUnacked();
+            this.leaderLive = true;
+            this.channel?.post({ t: "leader", epoch: this.epoch });
+        }
+    }
+    /** Adopt our follower-era unacked ops as leader: sequence + persist them ourselves, in seq
+     *  order (Map insertion order — seq is assigned at insert). Idempotent (the map is cleared). */
+    adoptUnacked() {
+        for (const [seq, batch] of this.unacked)
+            this.sequence(this.origin, seq, batch);
+        this.unacked.clear();
+    }
+    /** The P7 decision, made HERE — under the lock, where the read is authoritative (single
+     *  writer: no one can move meta between this read and our reset/putMeta). Boot's verdict alone
+     *  would be stale: an earlier same-version leader may have validly initialized or reset the
+     *  store since (its unannounced tail must then be diffed in, not wiped). If this read FAILS,
+     *  fall back to boot's verdict and fail CLOSED on anything but a clean boot match — the gate
+     *  must never stamp the new hash over unverified rows (that legitimizes old-shape data
+     *  forever; a wrongly-kept store self-heals via the promotion diff, a wrongly-stamped one
+     *  never does). */
+    async resetPending() {
+        if (!this.db)
+            return false;
+        try {
+            const meta = await this.db.getMeta();
+            if (meta?.schemaHash !== this.schemaHash)
+                return true;
+            // Matches (boot may have seen `error`/a pre-initialization store): nothing to clear. If
+            // boot restored nothing, the promotion diff below folds every persisted row into the live
+            // engine (the same P5 path that heals a dead leader's gap). Re-adopt the persisted epoch
+            // high-water for P6 monotonicity.
+            this.epoch = Math.max(this.epoch, meta.epoch);
+            return false;
+        }
+        catch (e) {
+            this.onError(asError(e));
+            return this.bootMeta !== "match";
+        }
+    }
+    /** P5: on promotion, IDB — not any tab's memory — is the durable source of truth. Re-read it and
+     *  diff against the mirror; every difference (excluding keys our OWN unacked ops touch, which are
+     *  newer by definition and re-sequenced right after) is a persisted-but-unannounced write from
+     *  the dead leader's P1 gap: fold it into the mirror/engine and rebroadcast it under the new
+     *  epoch. Records for tables no longer in the schema are swept from disk here (§3.1).
+     *
+     *  The P9 REPAIR runs first: for keys whose last commit never landed in IDB (`p: false`), the
+     *  mirror — not IDB — is the coherent truth; without the repair, the IDB gap would read as a
+     *  persisted-but-unannounced REMOVE below, and a one-off storage error on the old leader would
+     *  escalate into this promotion actively deleting committed, live rows from every tab. */
+    async promotionDiff() {
+        if (!this.db)
+            return;
+        await this.repairDurability();
+        const persisted = await this.db.getAllRows();
+        if (this.closed)
+            return;
+        const ownUnacked = new Set();
+        for (const batch of this.unacked.values()) {
+            for (const s of batch)
+                ownUnacked.add(`${s.table}\0${s.pkKey}`);
+        }
+        const diff = [];
+        const stale = [];
+        const seen = new Set();
+        for (const rec of persisted) {
+            const info = this.tables.get(rec.table);
+            if (!info) {
+                stale.push({ table: rec.table, pkKey: rec.pkKey });
+                continue;
+            }
+            const key = `${rec.table}\0${rec.pkKey}`;
+            seen.add(key);
+            if (ownUnacked.has(key))
+                continue;
+            if (!validRow(rec.row, info.width)) {
+                this.onError(new Error(`local persistence: dropped a malformed row for "${rec.table}" (promotion diff)`));
+                continue;
+            }
+            const cur = this.mirror.get(rec.table).get(rec.pkKey);
+            if (!cur || !rowsEqual(cur, rec.row))
+                diff.push({ table: rec.table, pkKey: rec.pkKey, row: rec.row });
+        }
+        // Mirror rows ABSENT from IDB (and not ours in flight): a persisted-but-unannounced REMOVE.
+        // (Sound because the repair above already re-persisted every key IDB was known to be missing.)
+        for (const [table, m] of this.mirror) {
+            for (const [pkKey, row] of m) {
+                if (row === null)
+                    continue; // a pre-restore tombstone (never reaches promotion, but cheap)
+                const key = `${table}\0${pkKey}`;
+                if (!seen.has(key) && !ownUnacked.has(key))
+                    diff.push({ table, pkKey, row: null });
+            }
+        }
+        if (diff.length) {
+            this.applyStates(diff); // fold into our own engine/mirror first (§4.5 step 2)
+            // Already persisted (it CAME from IDB) — broadcast straight, no re-persist needed.
+            this.channel?.post({
+                t: "commit",
+                epoch: this.epoch,
+                lseq: ++this.lseq,
+                origin: this.origin,
+                seq: 0,
+                batch: diff,
+                p: true,
+            });
+        }
+        if (stale.length)
+            await this.db.deleteRows(stale);
+    }
+    /** P9 repair: make IDB match the mirror for every key flagged un-persisted (`notInIdb`). The
+     *  mirror holds the coherent truth for them — a present row re-puts, an absent one deletes.
+     *  Idempotent; throws propagate to the caller (a failed repair keeps the flags for next time). */
+    async repairDurability() {
+        if (!this.db || this.notInIdb.size === 0)
+            return;
+        const repair = [];
+        for (const key of this.notInIdb) {
+            const i = key.indexOf("\0");
+            const table = key.slice(0, i);
+            const pkKey = key.slice(i + 1);
+            const m = this.mirror.get(table);
+            if (!m) {
+                this.notInIdb.delete(key); // the table left the plane — its records get swept anyway
+                continue;
+            }
+            repair.push({ table, pkKey, row: m.get(pkKey) ?? null });
+        }
+        if (repair.length)
+            await this.db.putBatch(repair);
+        for (const s of repair)
+            this.notInIdb.delete(`${s.table}\0${s.pkKey}`);
+    }
+    /** P9 bookkeeping, updated from every commit (our own chain and the channel): `persisted: false`
+     *  marks the batch's keys as missing from IDB until a later successful persist covers them. */
+    noteDurability(batch, persisted) {
+        for (const s of batch) {
+            const key = `${s.table}\0${s.pkKey}`;
+            if (persisted)
+                this.notInIdb.delete(key);
+            else
+                this.notInIdb.add(key);
+        }
+    }
+    /** The full mirror as row state (the post-reset seed). Pre-restore tombstones are excluded —
+     *  they mark "removed before the snapshot landed", not durable rows. */
+    mirrorStates() {
+        const out = [];
+        for (const [table, m] of this.mirror) {
+            for (const [pkKey, row] of m)
+                if (row !== null)
+                    out.push({ table, pkKey, row });
+        }
+        return out;
+    }
+    /** The leader's sequencer (§4.2): assign `(epoch, lseq)`, persist (ONE IDB txn), then broadcast
+     *  the `commit` (P1) and apply it locally through the mirror (a no-op for our own writes, which
+     *  the per-pk hold-back also shields from stale echoes). The chain serializes batches so IDB is
+     *  a fold of commits in `(epoch, lseq)` order (P2).
+     *
+     *  Deliberately NOT gated on `closed`: a queued step carries an already-committed write —
+     *  cancelling it on an orderly close would silently drop durable data and its broadcast.
+     *  close() drains this chain and only then releases the lock and the handles. */
+    sequence(origin, seq, batch) {
+        const epoch = this.epoch;
+        const lseq = ++this.lseq;
+        this.persistChain = this.persistChain.then(async () => {
+            let persisted = false;
+            try {
+                if (this.db) {
+                    await this.repairDurability(); // P9 backlog first, so IDB folds in commit order
+                    await this.db.putBatch(batch);
+                    persisted = true;
+                }
+            }
+            catch (e) {
+                this.onError(asError(e)); // durability degrades; coherence continues (P9)
+            }
+            this.noteDurability(batch, persisted);
+            this.channel?.post({ t: "commit", epoch, lseq, origin, seq, batch, p: persisted });
+            try {
+                this.applyStates(batch, { origin, seq });
+                if (origin === this.origin)
+                    this.unacked.delete(seq);
+            }
+            catch (e) {
+                this.onError(asError(e));
+            }
+        });
+    }
+    // -------------------------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------------------------
+    async flush() {
+        // Best-effort final forward (§9), regardless of role: a mid-promotion leader still holds
+        // un-adopted follower-era ops, and for a plain follower this is the last chance for a live
+        // leader to persist them. A live leader's buffer is empty — the re-post is then a no-op.
+        this.resendUnacked();
+        if (this.leader) {
+            await this.persistChain;
+            try {
+                await this.repairDurability(); // last-chance durability for P9-degraded batches
+            }
+            catch (e) {
+                this.onError(asError(e));
+            }
+        }
+    }
+    /** Re-post every unacked op, in seq order (Map insertion order — seq is assigned at insert). */
+    resendUnacked() {
+        for (const [seq, batch] of this.unacked) {
+            this.channel?.post({ t: "op", origin: this.origin, seq, batch });
+        }
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.lockAbort.abort(); // abandon a still-queued lock request
+        // A follower's final forward (the pagehide flush's guarantee, now on the orderly path too):
+        // re-post unacked ops while the channel is still open, so a live leader can persist them.
+        if (!this.leader)
+            this.resendUnacked();
+        const finish = () => {
+            this.releaseLock?.(); // release held leadership (P10)
+            this.channel?.close();
+            this.channel = null;
+            this.db?.close();
+            this.db = null;
+        };
+        if (this.leader) {
+            // Drain, then release: queued persist steps carry already-COMMITTED writes (engine + every
+            // tab's view have them) — cancelling would silently lose them from IDB and from every
+            // other tab; and handing the lock over before the last putBatch lands would let the next
+            // leader diff against a torn store. The chain never rejects (every step catches).
+            void this.persistChain
+                .then(() => this.repairDurability())
+                .catch((e) => this.onError(asError(e)))
+                .then(finish);
+        }
+        else {
+            finish();
+        }
+    }
+}
+// ---------------------------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------------------------
+/** `pkKey` (§3.1): JSON of the pk cells in schema pk order — a STRING deliberately (IDB keys
+ *  admit neither `null` nor `boolean`, both legal rindle pk cells). Non-finite numbers get a
+ *  NUL-prefixed tag: `JSON.stringify` folds NaN/±Infinity into `null`, which would collapse
+ *  engine-distinct rows onto one storage/replication key (a remove of either would tombstone
+ *  both). The NUL byte keeps a legitimate string cell from ever colliding with the tag. */
+function pkKeyOf(row, pk) {
+    return JSON.stringify(pk.map((i) => {
+        const v = row[i] ?? null;
+        return typeof v === "number" && !Number.isFinite(v) ? `\u0000n:${String(v)}` : v;
+    }));
+}
+/** The replicated-row shape guard, shared by ALL three ingress points (snapshot restore, live
+ *  commits, the promotion diff) so they can never drift: a malformed row must not reach the
+ *  engine (wasm builds panic=abort). */
+function validRow(row, width) {
+    return Array.isArray(row) && row.length === width;
+}
+function asError(e) {
+    return e instanceof Error ? e : new Error(String(e));
+}
+function mintOrigin() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return `${Math.random().toString(36).slice(2)}-${Math.random().toString(36).slice(2)}`;
+}
+const ROWS = "rows";
+const META = "meta";
+const META_KEY = "meta";
+/** Wrap one IDB transaction's completion as a promise (resolution == txn durably committed —
+ *  the exact anchor P1 needs). */
+function txnDone(txn) {
+    return new Promise((resolve, reject) => {
+        txn.oncomplete = () => resolve();
+        txn.onerror = () => reject(asError(txn.error ?? new Error("IndexedDB transaction failed")));
+        txn.onabort = () => reject(asError(txn.error ?? new Error("IndexedDB transaction aborted")));
+    });
+}
+function reqDone(req) {
+    return new Promise((resolve, reject) => {
+        req.onsuccess = () => resolve(req.result);
+        req.onerror = () => reject(asError(req.error ?? new Error("IndexedDB request failed")));
+    });
+}
+class IdbPersistDb {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async getMeta() {
+        const txn = this.db.transaction([META], "readonly");
+        const out = await reqDone(txn.objectStore(META).get(META_KEY));
+        return out;
+    }
+    putMeta(meta) {
+        const txn = this.db.transaction([META], "readwrite");
+        txn.objectStore(META).put(meta, META_KEY);
+        return txnDone(txn);
+    }
+    async getAllRows() {
+        const txn = this.db.transaction([ROWS], "readonly");
+        const out = await reqDone(txn.objectStore(ROWS).getAll());
+        return out;
+    }
+    putBatch(batch) {
+        const txn = this.db.transaction([ROWS], "readwrite");
+        const store = txn.objectStore(ROWS);
+        for (const s of batch) {
+            if (s.row === null)
+                store.delete([s.table, s.pkKey]);
+            else
+                store.put({ table: s.table, pkKey: s.pkKey, row: s.row });
+        }
+        return txnDone(txn);
+    }
+    reset(meta) {
+        const txn = this.db.transaction([ROWS, META], "readwrite");
+        txn.objectStore(ROWS).clear();
+        txn.objectStore(META).put(meta, META_KEY);
+        return txnDone(txn);
+    }
+    deleteRows(keys) {
+        const txn = this.db.transaction([ROWS], "readwrite");
+        const store = txn.objectStore(ROWS);
+        for (const k of keys)
+            store.delete([k.table, k.pkKey]);
+        return txnDone(txn);
+    }
+    close() {
+        this.db.close();
+    }
+}
+/** How long a BLOCKED IDB open may park before the layer degrades to broadcast-only: a pending
+ *  `deleteDatabase` (a sibling tab's logout) queues every later open behind it, and an old-version
+ *  connection with no `versionchange` handler can hold that queue indefinitely — client
+ *  construction must never hang on it. */
+const OPEN_BLOCKED_TIMEOUT_MS = 2000;
+/** The real-browser environment: IndexedDB + BroadcastChannel + `navigator.locks`, each reached
+ *  structurally and each degrading gracefully when absent (§3.2). */
+export function defaultEnv() {
+    const g = globalThis;
+    const locks = g.navigator?.locks;
+    return {
+        // Multi-context runtime with no exclusive lock (Firefox <96, Safari 15.1–15.3, Node): the
+        // solo-mode fallback below would make EVERY context a leader — the layer must run inert.
+        leaderElectionUnavailable: !locks && typeof g.BroadcastChannel === "function",
+        openDatabase(name) {
+            const idb = g.indexedDB;
+            if (!idb)
+                return Promise.resolve(null);
+            return new Promise((resolve) => {
+                let settled = false;
+                const settle = (db) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    resolve(db);
+                };
+                let req;
+                try {
+                    req = idb.open(name, 1);
+                }
+                catch {
+                    resolve(null); // some privacy modes throw synchronously — degrade (§3.2)
+                    return;
+                }
+                req.onupgradeneeded = () => {
+                    // Version 1 forever (§3.1): a fixed two-store shape, so a schema's table-set change
+                    // never needs an IDB version bump.
+                    const db = req.result;
+                    if (!db.objectStoreNames.contains(ROWS))
+                        db.createObjectStore(ROWS, { keyPath: ["table", "pkKey"] });
+                    if (!db.objectStoreNames.contains(META))
+                        db.createObjectStore(META);
+                };
+                req.onsuccess = () => {
+                    const db = req.result;
+                    // A sibling tab's deleteDatabase (logout) fires `versionchange` at every open
+                    // connection and then WAITS for them all to close: release ours so the delete (and
+                    // any open queued behind it) can proceed — this session degrades (P9), the logout
+                    // completes. Without this, one live tab wedges every other tab's logout forever.
+                    db.onversionchange = () => db.close();
+                    if (settled) {
+                        db.close(); // the blocked-open timeout already degraded us — don't hold a handle
+                        return;
+                    }
+                    settle(new IdbPersistDb(db));
+                };
+                req.onerror = () => settle(null); // unavailable → broadcast-only degrade (§3.2)
+                req.onblocked = () => {
+                    // Parked behind a pending delete (or an old-version connection): degrade after a
+                    // bounded wait rather than hanging client construction — never forever.
+                    setTimeout(() => settle(null), OPEN_BLOCKED_TIMEOUT_MS);
+                };
+            });
+        },
+        deleteDatabase(name) {
+            const idb = g.indexedDB;
+            if (!idb)
+                return Promise.resolve();
+            return reqDone(idb.deleteDatabase(name)).then(() => undefined);
+        },
+        createChannel(name) {
+            const BC = g.BroadcastChannel;
+            if (!BC)
+                return null;
+            const ch = new BC(name);
+            return {
+                post: (msg) => {
+                    try {
+                        ch.postMessage(msg);
+                    }
+                    catch {
+                        /* a closed/failed channel loses coherence, never the write path (P9) */
+                    }
+                },
+                onMessage: (handler) => {
+                    ch.onmessage = (ev) => handler(ev.data);
+                },
+                close: () => ch.close(),
+            };
+        },
+        requestLock(name, signal, onAcquired) {
+            if (!locks) {
+                // No Web Locks AND no BroadcastChannel (`leaderElectionUnavailable` gates the layer off
+                // otherwise): a provably single-context runtime — solo mode, safe by construction.
+                void onAcquired();
+                return;
+            }
+            void locks.request(name, { mode: "exclusive", signal }, onAcquired).catch(() => {
+                /* an aborted queued request (close before acquisition) — expected */
+            });
+        },
+        requestPersistentStorage() {
+            void g.navigator?.storage?.persist?.()?.catch?.(() => { });
+        },
+    };
+}
+//# sourceMappingURL=local-persist.js.map