@bjornpagen/bumbledb-log 0.20.0 → 0.20.2

package/dist/replica.js

@@ -0,0 +1,820 @@
+/**
+ * The replica: a local store that is a materialized view of the
+ * braids' prefixes, plus the loop that keeps it current. Disposable by
+ * construction — the sidecar is a floor cache with one wholeness
+ * check; recovery IS the catch-up loop (L10). Generation is a total
+ * function of the chain: Settled sums the vector, Pending is that sum
+ * plus one. A replica that finds no manifest refuses; only a writer
+ * births a store.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { factOf, internalBlake3, Db as SdkDb } from "@bjornpagen/bumbledb";
+import * as errors from "@superbuilders/errors";
+import { parse } from "#braids.ts";
+import { bytesEqual, digest32, hex32, saturatingAddU64 } from "#bytes.ts";
+import { chainGeneration, chainSum, readSidecar, writeSidecar } from "#chain.ts";
+import { decodeBatch, encodeBatch, verifyChain } from "#codec.ts";
+import { descriptorOf } from "#descriptor.ts";
+import { ErrRefused, ErrReplayDiverged, refuse, refuseManifestMissing, wrapStore } from "#errors.ts";
+import { CKPT_SCRATCH_LEASE, checkpointMdbKey, ckptDocKey, generation, LEASE_NAMESPACE, logKey, manifestKey, parseCkptScratch, TEMP_NAMESPACE } from "#keys.ts";
+import { auditCatalog, parseCheckpoint, parseManifest } from "#manifest.ts";
+import { Vector } from "#vector.ts";
+const ZERO_HASH = digest32(new Uint8Array(32));
+/** The gc-safety heartbeat cadence: every N-th pass re-reads the manifest. */
+const HEARTBEAT_PASSES = 16;
+/** The re-poll cadence of waitFor, its one consumer — the
+ *  machine-constants table's `wait_for_poll_ms` fact. */
+const WAIT_FOR_POLL_MS = 10;
+const cores = new WeakMap();
+function coreOf(replica) {
+    const core = cores.get(replica);
+    if (core === undefined) {
+        throw errors.new("not a replica of this driver");
+    }
+    return core;
+}
+/** One asynchronous door per replica: refreshes, commits, and disposal serialize. */
+function withGate(core, body) {
+    const run = core.gate.then(body, body);
+    core.gate = run.then(function absorb() {
+        return undefined;
+    }, function absorbFailure() {
+        return undefined;
+    });
+    return run;
+}
+function blake3Digest(bytes) {
+    return digest32(new Uint8Array(internalBlake3(bytes)));
+}
+function sidecarPath(core) {
+    return path.join(core.dir, "chain");
+}
+let storeSequence = 0;
+/** LMDB registers environments per canonical path for the life of the
+ *  process and the engine has no close verb, so a store path is never
+ *  reused: every bootstrap gets a fresh name and discards leave the old
+ *  environment to GC. */
+function freshStoreName() {
+    storeSequence += 1;
+    return `store-${process.pid.toString(36)}-${Date.now().toString(36)}-${storeSequence}`;
+}
+function storePath(core) {
+    return path.join(core.dir, core.storeName);
+}
+/** A wire braid id is a braid of this theory or a typed refuse. */
+function braidOf(theory, raw) {
+    const id = Number.parseInt(raw.slice(1), 16);
+    const parsed = parse(theory, id);
+    if (parsed === undefined) {
+        refuse({ kind: "UnknownBraid" }, `unknown braid ${raw}`);
+    }
+    return parsed;
+}
+function zeroChain(descriptor) {
+    const chain = new Map();
+    for (const id of descriptor.braidMembers.keys()) {
+        chain.set(id, { g: generation(0n), prev: ZERO_HASH, ts: 0n });
+    }
+    return chain;
+}
+function entriesOf(core) {
+    return core.chain.entries;
+}
+function chainEntry(core, braid) {
+    const id = braidOf(core.theory, braid);
+    const entry = entriesOf(core).get(id);
+    if (entry === undefined) {
+        throw errors.new(`braid ${id} is not derived from this theory`);
+    }
+    return entry;
+}
+function generationOf(core) {
+    return core.db.read(function readGeneration(instance) {
+        return instance.generation;
+    });
+}
+/** The opened store's catalog digest — the engine handle's computed claim. */
+function catalogDigestOf(core) {
+    return digest32(core.db.catalogDigest());
+}
+function holdPending(core, batch, ops, ts) {
+    const held = { braid: batch.braid, slot: batch.slot, bytes: batch.bytes, ops, ts };
+    core.chain = { tag: "pending", entries: entriesOf(core), batch: held };
+}
+function pendingOf(core) {
+    if (core.chain.tag !== "pending") {
+        return null;
+    }
+    return core.chain.batch;
+}
+function settleHeld(core) {
+    core.chain = { tag: "settled", entries: entriesOf(core) };
+}
+/** The local vector equals the published checkpoint vector and the
+ *  chain is Settled — the seed/open floor the catalog claim is audited
+ *  against. */
+function atCheckpointFloor(core) {
+    if (core.checkpoint === null || core.chain.tag === "pending") {
+        return false;
+    }
+    for (const [braid, head] of core.checkpoint.braids) {
+        if (chainEntry(core, braid).g !== head.g) {
+            return false;
+        }
+    }
+    return true;
+}
+async function persistSidecar(core) {
+    await writeSidecar(core.descriptor.codec, sidecarPath(core), core.chain);
+}
+/** Writes the checkpoint store file and fsyncs the file and its parent
+ *  directory — the mdb is durable before the sidecar. */
+async function writeCheckpointMdb(dir, bytes) {
+    const data = path.join(dir, "data.mdb");
+    const handle = await fs.open(data, "w");
+    const written = await errors.try((async function writeAll() {
+        await handle.writeFile(bytes);
+        await handle.sync();
+    })());
+    await handle.close();
+    if (written.error) {
+        throw errors.wrap(written.error, `write checkpoint store ${data}`);
+    }
+    const parent = await fs.open(dir, "r");
+    const synced = await errors.try(parent.sync());
+    await parent.close();
+    if (synced.error) {
+        throw errors.wrap(synced.error, `fsync checkpoint store directory ${dir}`);
+    }
+}
+async function settle(core) {
+    settleHeld(core);
+    await persistSidecar(core);
+}
+async function clearPending(core) {
+    await settle(core);
+}
+function disposed(core) {
+    if (core.closed) {
+        throw errors.new("replica is disposed");
+    }
+}
+function adoptChain(core, chain) {
+    const entries = new Map();
+    for (const [raw, entry] of chain.entries) {
+        entries.set(braidOf(core.theory, raw), entry);
+    }
+    for (const id of core.descriptor.braidMembers.keys()) {
+        if (!entries.has(id)) {
+            entries.set(id, { g: generation(0n), prev: ZERO_HASH, ts: 0n });
+        }
+    }
+    if (chain.tag === "pending") {
+        const held = {
+            braid: braidOf(core.theory, chain.batch.braid),
+            slot: chain.batch.slot,
+            bytes: chain.batch.bytes,
+            ops: null,
+            ts: null
+        };
+        core.chain = { tag: "pending", entries, batch: held };
+    }
+    else {
+        core.chain = { tag: "settled", entries };
+    }
+}
+/** One `db.write` applying ops in listed order, rows in listed order.
+ *  The positional row → named fact lift is the engine's `factOf` —
+ *  closed-ref handles included. */
+function applyOps(core, ops) {
+    return core.db.write(function applyBatch(tx) {
+        for (const op of ops) {
+            const member = core.theory.relations[op.relation];
+            if (member === undefined) {
+                throw errors.new(`batch op cites unknown relation ${op.relation}`);
+            }
+            const relation = member;
+            const facts = op.rows.map(function liftRow(row) {
+                return factOf(relation, row);
+            });
+            if (op.op === "insert") {
+                tx.insert(relation, facts);
+            }
+            else {
+                tx.delete(relation, facts);
+            }
+        }
+        return 0;
+    });
+}
+/**
+ * Decode, verify the chain, `db.write` the batch, then refuse a
+ * first-applied no-op against the identity. The sidecar advances
+ * only after that check; a rejected replay is phase-scoped:
+ * discard before the store has proven itself whole,
+ * `ErrReplayDiverged` after.
+ */
+async function applySlot(core, braid, slot, bytes, phase) {
+    const decoded = decodeBatch(core.descriptor, bytes);
+    const entry = chainEntry(core, braid);
+    verifyChain(decoded.header, braid, slot, { g: entry.g, prev: entry.prev, ts: entry.ts });
+    const outcome = applyOps(core, decoded.ops);
+    if (outcome.tag === "rejected") {
+        if (phase === "open") {
+            return { tag: "discard" };
+        }
+        throw errors.wrap(ErrReplayDiverged, `braid ${braid} slot ${slot} writer ${decoded.header.writer}`);
+    }
+    const identity = chainSum(core.chain) - entry.g + slot;
+    if (outcome.value.generation < identity) {
+        refuse({ kind: "NoOpSlot", braid, slot, writer: decoded.header.writer }, `braid ${braid} slot ${slot}: a first-applied slot changed nothing — publish-law violation by writer ${decoded.header.writer}`);
+    }
+    entriesOf(core).set(braid, { g: slot, prev: blake3Digest(bytes), ts: decoded.header.timestamp });
+    await persistSidecar(core);
+    return { tag: "applied", generation: outcome.value.generation };
+}
+/**
+ * The published checkpoint vector is the one floor: a slot at or
+ * below it is retired, and a create must not touch the store.
+ */
+function belowFloor(core, braid, slot) {
+    const id = braidOf(core.theory, braid);
+    if (core.checkpoint === null) {
+        return false;
+    }
+    const floor = core.checkpoint.braids.get(id);
+    if (floor === undefined) {
+        return false;
+    }
+    return slot <= floor.g;
+}
+/**
+ * The gc floor rule: below the current checkpoint's vector a 404 is a
+ * collected hole, at or above it the honest tip.
+ */
+function holeAt(core, braid, next) {
+    return belowFloor(core, braid, next);
+}
+function foldPending(sum, generation, occupant, pendingBytes, covered) {
+    if (covered) {
+        return { tag: "below-floor" };
+    }
+    if (occupant !== null && bytesEqual(occupant, pendingBytes)) {
+        return { tag: "ours" };
+    }
+    if (occupant !== null) {
+        return generation === sum ? { tag: "theirs-unapplied" } : { tag: "theirs-applied" };
+    }
+    if (generation === sum) {
+        return { tag: "absent-unapplied" };
+    }
+    if (generation === saturatingAddU64(sum, 1n)) {
+        return { tag: "absent-applied" };
+    }
+    return { tag: "phantom" };
+}
+function isCorruption(error) {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    return errors.is(error, ErrReplayDiverged) || errors.is(error, ErrRefused);
+}
+/**
+ * One braid, one slot. Catch-up, refresh, waitFor, and open all call
+ * this; a hot braid cannot drain past one step per round.
+ */
+async function stepBraid(core, braid, phase) {
+    disposed(core);
+    const id = braidOf(core.theory, braid);
+    const wedged = core.wedged.get(id);
+    if (wedged !== undefined) {
+        return { tag: "wedged", braid: id, cause: wedged };
+    }
+    const next = generation(chainEntry(core, id).g + 1n);
+    const fetched = await core.store.get(logKey(core.prefix, id, next));
+    if (fetched === null) {
+        if (holeAt(core, id, next)) {
+            return { tag: "reseed", cause: "gap-below-floor" };
+        }
+        return { tag: "tip" };
+    }
+    const chain = core.chain;
+    if (chain.tag === "pending" && id === chain.batch.braid && next === chain.batch.slot) {
+        if (!bytesEqual(fetched.bytes, chain.batch.bytes)) {
+            return { tag: "reseed", cause: "lost-pending-fork" };
+        }
+        await settle(core);
+    }
+    const applied = await errors.try(applySlot(core, id, next, fetched.bytes, phase));
+    if (applied.error) {
+        if (phase === "steady" && isCorruption(applied.error)) {
+            core.wedged.set(id, applied.error.message);
+            return { tag: "wedged", braid: id, cause: applied.error.message };
+        }
+        throw applied.error;
+    }
+    if (applied.data.tag === "discard") {
+        return { tag: "reseed", cause: "rejected-in-open" };
+    }
+    return { tag: "applied" };
+}
+/**
+ * One pass: heartbeat, one slot per braid, wholeness, disposed. The
+ * same function refresh, waitFor, catch-up, and open execute.
+ */
+async function runPass(core, braids, phase) {
+    disposed(core);
+    core.passes += 1;
+    if (core.passes % HEARTBEAT_PASSES === 0) {
+        await refreshManifest(core);
+    }
+    const remaining = new Set(braids);
+    while (remaining.size > 0) {
+        disposed(core);
+        let progressed = false;
+        for (const braid of braids) {
+            if (!remaining.has(braid)) {
+                continue;
+            }
+            const step = await stepBraid(core, braid, phase);
+            if (step.tag === "applied") {
+                progressed = true;
+            }
+            else if (step.tag === "tip" || step.tag === "wedged") {
+                remaining.delete(braid);
+            }
+            else {
+                return { tag: "reseed", cause: step.cause };
+            }
+        }
+        if (!progressed) {
+            break;
+        }
+    }
+    if (!wholenessHolds(core)) {
+        return { tag: "reseed", cause: "wholeness" };
+    }
+    for (const [braid, cause] of core.wedged) {
+        return { tag: "wedged", braid, cause };
+    }
+    return { tag: "advanced", vector: vectorOf(core) };
+}
+function allBraids(core) {
+    return [...core.descriptor.braidMembers.keys()];
+}
+function wholenessHolds(core) {
+    return generationOf(core) === chainGeneration(core.chain);
+}
+async function adoptManifest(core, bytes, etag) {
+    const manifest = parseManifest(bytes);
+    if (!bytesEqual(manifest.fingerprint, digest32(core.descriptor.fingerprintBytes))) {
+        refuse({
+            kind: "FingerprintMismatch",
+            carried: hex32(manifest.fingerprint),
+            expected: core.descriptor.fingerprint
+        }, "the store's manifest names a different theory");
+    }
+    if (manifest.checkpoint === null) {
+        core.checkpoint = null;
+        core.checkpointDigest = null;
+    }
+    else if (core.checkpointDigest === null || !bytesEqual(manifest.checkpoint, core.checkpointDigest)) {
+        const facts = await core.store.get(ckptDocKey(core.prefix, manifest.checkpoint));
+        if (facts === null) {
+            throw errors.new(`manifest points at absent checkpoint ${hex32(manifest.checkpoint)}`);
+        }
+        // The codec-backed parseCheckpoint judges the braid set against the
+        // sealed handle — an unknown or drifted braid refuses at parse.
+        core.checkpoint = parseCheckpoint(core.descriptor.codec, facts.bytes);
+        core.checkpointDigest = manifest.checkpoint;
+    }
+    // The pointer is adopted only after the checkpoint it names is in
+    // hand. A failed fetch leaves the old etag and the old floor (40/67).
+    core.manifestEtag = etag;
+}
+/** A replica never births a manifest. Absence is ManifestMissing. */
+async function refreshManifest(core) {
+    if (core.manifestEtag !== null) {
+        const poll = await core.store.getIfChanged(manifestKey(core.prefix), core.manifestEtag);
+        if (poll.tag === "unchanged") {
+            return;
+        }
+        await adoptManifest(core, poll.fetched.bytes, poll.fetched.etag);
+        return;
+    }
+    const fetched = await core.store.get(manifestKey(core.prefix));
+    if (fetched === null) {
+        refuseManifestMissing("the store has no manifest");
+    }
+    await adoptManifest(core, fetched.bytes, fetched.etag);
+}
+/** Bootstraps a fresh local store: from the current checkpoint when one
+ *  exists, else `Db.create` at the zero vector. Always holds Settled —
+ *  a prior Pending arm cannot survive beside the new vector. */
+async function initializeStore(core) {
+    core.storeName = freshStoreName();
+    const target = storePath(core);
+    await fs.rm(target, { recursive: true, force: true });
+    await fs.mkdir(core.dir, { recursive: true });
+    if (core.checkpoint !== null && core.checkpointDigest !== null) {
+        const mdb = await core.store.get(checkpointMdbKey(core.prefix, core.checkpointDigest));
+        if (mdb === null) {
+            throw errors.new(`checkpoint ${hex32(core.checkpointDigest)} names an absent .mdb`);
+        }
+        await fs.mkdir(target, { recursive: true });
+        await writeCheckpointMdb(target, mdb.bytes);
+        core.db = await SdkDb.open(target, core.theory);
+        core.chain = {
+            tag: "settled",
+            entries: new Map([...core.checkpoint.braids.entries()].map(function seed([raw, head]) {
+                const braid = braidOf(core.theory, raw);
+                return [braid, { g: head.g, prev: head.hash, ts: head.ts }];
+            }))
+        };
+        const opened = generationOf(core);
+        if (opened !== chainGeneration(core.chain)) {
+            throw errors.new(`checkpoint store opened at generation ${opened}, chain generation is ${chainGeneration(core.chain)}`);
+        }
+        auditCatalog(core.checkpoint, catalogDigestOf(core));
+        core.provenance = { tag: "checkpoint-seeded", catalog: core.checkpointDigest };
+        await persistSidecar(core);
+        return;
+    }
+    const created = await SdkDb.create(target, core.theory);
+    if (created.tag === "rejected") {
+        throw errors.new("the theory's ground axioms were rejected at bootstrap");
+    }
+    core.db = created.value;
+    core.chain = { tag: "settled", entries: zeroChain(core.descriptor) };
+    core.provenance = { tag: "bootstrapped" };
+    await persistSidecar(core);
+}
+/** The scream tracks the set of repair signatures; a recurrence alarms. */
+function screamOf(context) {
+    const seen = new Set();
+    let attempts = 0;
+    return {
+        attempt(signature) {
+            attempts += 1;
+            if (seen.has(signature)) {
+                console.error(`bumbledb-log alarm: ${context} repair signature recurs: ${signature}`);
+            }
+            else {
+                seen.add(signature);
+            }
+            if (attempts % 8 === 0) {
+                console.error(`bumbledb-log warning: ${context} repair attempt ${attempts}: ${signature}`);
+            }
+        }
+    };
+}
+/** The disposable law: the directory is cache, never truth. The local
+ *  LMDB path rotates because the engine has no close verb — the old
+ *  environment is left for GC while the fresh pull takes a new path.
+ *  initializeStore writes Settled, so the open-identity is
+ *  chainGeneration(core.chain) — there is no addend a reader can skip. */
+async function discardAndReopen(core) {
+    const scream = screamOf("replica discard-and-re-pull");
+    for (;;) {
+        const old = storePath(core);
+        await fs.rm(old, { recursive: true, force: true });
+        core.wedged.clear();
+        await initializeStore(core);
+        const outcome = await runPass(core, allBraids(core), "open");
+        if (outcome.tag === "reseed") {
+            scream.attempt(outcome.cause);
+            continue;
+        }
+        if (outcome.tag === "refused") {
+            throw errors.wrap(ErrRefused, outcome.detail);
+        }
+        if (generationOf(core) === chainGeneration(core.chain)) {
+            return;
+        }
+        scream.attempt("wholeness");
+    }
+}
+async function newestStoreDir(dir) {
+    const listed = await errors.try(fs.readdir(dir));
+    if (listed.error) {
+        return null;
+    }
+    let newest = null;
+    let newestAt = -1;
+    for (const name of listed.data) {
+        if (!name.startsWith("store-")) {
+            continue;
+        }
+        const stat = await errors.try(fs.stat(path.join(dir, name)));
+        if (stat.error === undefined && stat.data.mtimeMs > newestAt) {
+            newestAt = stat.data.mtimeMs;
+            newest = name;
+        }
+    }
+    return newest;
+}
+/**
+ * Open reclaims the reserved `~tmp`/`~lease` namespace. The known
+ * document `{dir}/~lease/ckpt-scratch` names a crash-stranded
+ * candidate; when that digest is not the live head the ckpt pair is
+ * deleted with the lease.
+ */
+async function sweepReservedKeys(core) {
+    const lease = path.join(core.dir, LEASE_NAMESPACE, CKPT_SCRATCH_LEASE);
+    const read = await errors.try(fs.readFile(lease));
+    if (read.error === undefined) {
+        const digest = parseCkptScratch(read.data);
+        if (digest !== null && (core.checkpointDigest === null || !bytesEqual(digest, core.checkpointDigest))) {
+            await core.store.delete(ckptDocKey(core.prefix, digest));
+            await core.store.delete(checkpointMdbKey(core.prefix, digest));
+        }
+    }
+    await fs.rm(path.join(core.dir, TEMP_NAMESPACE), { recursive: true, force: true });
+    await fs.rm(path.join(core.dir, LEASE_NAMESPACE), { recursive: true, force: true });
+}
+/** The disposable law says cache directories do not hoard corpses: every
+ *  rotated `store-*` LMDB dir except the adopted one is dead — left by a
+ *  crashed process or a prior rotation — and is swept at open. */
+async function sweepRotations(core) {
+    const listed = await errors.try(fs.readdir(core.dir));
+    if (listed.error) {
+        return;
+    }
+    for (const name of listed.data) {
+        if (!name.startsWith("store-") || name === core.storeName) {
+            continue;
+        }
+        await fs.rm(path.join(core.dir, name), { recursive: true, force: true });
+    }
+}
+/**
+ * Pending recovery: apply the resurrected batch. A batch rejected here
+ * was never acked; a born-no-op settles; anything else stays Pending
+ * so generation(chain) accounts for the unpublished apply.
+ */
+async function resolvePendingAtOpen(core) {
+    const chain = core.chain;
+    if (chain.tag === "settled") {
+        return;
+    }
+    // A slot the floor already covers is published (`Clear`), not re-judged (46).
+    if (foldPending(chainSum(core.chain), generationOf(core), null, chain.batch.bytes, belowFloor(core, chain.batch.braid, chain.batch.slot)).tag === "below-floor") {
+        await settle(core);
+        return;
+    }
+    const decoded = errors.trySync(function decodePending() {
+        return decodeBatch(core.descriptor, chain.batch.bytes);
+    });
+    if (decoded.error) {
+        await settle(core);
+        return;
+    }
+    const outcome = applyOps(core, decoded.data.ops);
+    if (outcome.tag === "rejected") {
+        await settle(core);
+        return;
+    }
+    // Store matches chainGeneration of the held Pending (sum+1) when the
+    // apply is in the db — just now, or already. A born-no-op leaves the
+    // store at the Settled generation, so the identity fails and we settle.
+    if (generationOf(core) !== chainGeneration(core.chain)) {
+        await settle(core);
+        return;
+    }
+    holdPending(core, chain.batch, decoded.data.ops, decoded.data.header.timestamp);
+}
+/**
+ * Pending resurrection through a cold re-pull: the store directory was
+ * unopenable (or discarded), so the sidecar's pending is resolved
+ * against a freshly caught-up store — a byte-equal published slot
+ * absorbs it (L10's idempotent replay), and everything else takes the
+ * one loss path's re-judgment at the tip. A slot the floor already
+ * covers is published (`Clear`), not re-judged (46).
+ */
+async function resolveColdPending(core, pending) {
+    const braid = braidOf(core.theory, pending.braid);
+    if (foldPending(chainSum(core.chain), generationOf(core), null, pending.bytes, belowFloor(core, braid, pending.slot))
+        .tag === "below-floor") {
+        await settle(core);
+        return;
+    }
+    const decoded = errors.trySync(function decodePending() {
+        return decodeBatch(core.descriptor, pending.bytes);
+    });
+    if (decoded.error) {
+        return;
+    }
+    const slot = decoded.data.header.braidGen;
+    if (entriesOf(core).has(braid) && chainEntry(core, braid).g >= slot) {
+        const published = await core.store.get(logKey(core.prefix, braid, slot));
+        if (published !== null && bytesEqual(published.bytes, pending.bytes)) {
+            return;
+        }
+    }
+    const before = generationOf(core);
+    const outcome = applyOps(core, decoded.data.ops);
+    if (outcome.tag === "accepted" && outcome.value.generation > before) {
+        holdPending(core, { ...pending, braid }, decoded.data.ops, decoded.data.header.timestamp);
+        await readdressPending(core, decoded.data.ops, decoded.data.header.writer);
+    }
+}
+async function openCore(options) {
+    const descriptor = descriptorOf(options.theory);
+    const core = {
+        store: options.store,
+        prefix: options.prefix,
+        dir: path.resolve(options.dir),
+        theory: options.theory,
+        descriptor,
+        db: undefined,
+        chain: { tag: "settled", entries: zeroChain(descriptor) },
+        manifestEtag: null,
+        checkpoint: null,
+        checkpointDigest: null,
+        passes: 0,
+        closed: false,
+        storeName: freshStoreName(),
+        gate: Promise.resolve(),
+        wedged: new Map(),
+        provenance: { tag: "bootstrapped" }
+    };
+    await fs.mkdir(core.dir, { recursive: true });
+    const fetched = await core.store.get(manifestKey(core.prefix));
+    if (fetched === null) {
+        refuseManifestMissing("the store has no manifest");
+    }
+    await adoptManifest(core, fetched.bytes, fetched.etag);
+    const existing = await newestStoreDir(core.dir);
+    const sidecar = await readSidecar(descriptor.codec, sidecarPath(core));
+    let opened = false;
+    let coldPending = null;
+    if (sidecar.tag === "fault") {
+        throw wrapStore(sidecar.io, `read sidecar ${sidecarPath(core)}`);
+    }
+    // The codec-backed readSidecar judges every braid against the sealed
+    // handle — a foreign braid is a corrupt sidecar, and a corrupt
+    // sidecar is discarded cache (the disposable law), never adopted.
+    if (existing !== null && sidecar.tag === "read") {
+        core.storeName = existing;
+        const openedDb = await errors.try(SdkDb.open(storePath(core), options.theory));
+        if (openedDb.error === undefined) {
+            core.db = openedDb.data;
+            adoptChain(core, sidecar.chain);
+            core.provenance = { tag: "sidecar-resumed", floor: vectorOf(core) };
+            opened = true;
+        }
+    }
+    if (!opened) {
+        if (sidecar.tag === "read" && sidecar.chain.tag === "pending") {
+            coldPending = sidecar.chain.batch;
+        }
+        await initializeStore(core);
+    }
+    if (opened) {
+        await resolvePendingAtOpen(core);
+    }
+    const outcome = await runPass(core, allBraids(core), "open");
+    if (outcome.tag === "reseed" || outcome.tag === "refused" || !wholenessHolds(core)) {
+        coldPending = core.chain.tag === "pending" ? core.chain.batch : coldPending;
+        await discardAndReopen(core);
+    }
+    if (coldPending !== null) {
+        await resolveColdPending(core, coldPending);
+    }
+    if (atCheckpointFloor(core)) {
+        auditCatalog(core.checkpoint, catalogDigestOf(core));
+    }
+    await sweepRotations(core);
+    await sweepReservedKeys(core);
+    return core;
+}
+/**
+ * The steady-state discard route: a contested pending slot surrenders
+ * the directory. The pending batch rides in memory — the sidecar is
+ * not settled ahead of the re-judgment — and takes the one loss path
+ * at the fresh tip.
+ */
+async function repairDiscard(core) {
+    const coldPending = core.chain.tag === "pending" ? core.chain.batch : null;
+    await discardAndReopen(core);
+    if (coldPending !== null) {
+        await resolveColdPending(core, coldPending);
+    }
+}
+/**
+ * Re-addresses an applied-but-unpublished batch at the braid's current
+ * tip: fresh slot, `prev` citing the new predecessor, timestamp
+ * re-clamped — the ops are exactly the recorded ops the re-judgment
+ * just accepted. Publication itself retries on the next commit (60).
+ */
+async function readdressPending(core, ops, writerId) {
+    const first = ops[0];
+    if (first === undefined) {
+        await settle(core);
+        return;
+    }
+    const relation = core.descriptor.relationByName.get(first.relation);
+    const raw = relation === undefined ? undefined : core.descriptor.braidOfRelation.get(relation.id);
+    if (raw === undefined) {
+        await settle(core);
+        return;
+    }
+    const braid = braidOf(core.theory, raw);
+    const entry = chainEntry(core, braid);
+    const timestamp = maxBigint(BigInt(Date.now()), entry.ts);
+    const bytes = encodeBatch(core.descriptor, {
+        braid,
+        braidGen: generation(entry.g + 1n),
+        prev: entry.prev,
+        writer: writerId,
+        timestamp
+    }, ops);
+    holdPending(core, { braid, slot: generation(entry.g + 1n), bytes }, ops, timestamp);
+    await persistSidecar(core);
+}
+function maxBigint(a, b) {
+    return a > b ? a : b;
+}
+function vectorOf(core) {
+    const vector = new Map();
+    for (const [id, entry] of core.chain.entries) {
+        vector.set(id, entry.g);
+    }
+    return vector;
+}
+async function refreshPass(core, braid) {
+    const braids = braid === undefined ? allBraids(core) : [braidOf(core.theory, braid)];
+    const outcome = await runPass(core, braids, "steady");
+    if (outcome.tag === "reseed") {
+        await repairDiscard(core);
+        return { tag: "reseed", cause: outcome.cause };
+    }
+    return outcome;
+}
+/** waitFor is refresh with a verdict: the same pass, then the full
+ *  Waited sum. A braid the target needs that is wedged below it returns
+ *  Wedged — no refresh will ever reach the target — and a heartbeat
+ *  refusal returns Refused. */
+async function waitForVector(core, target) {
+    for (;;) {
+        disposed(core);
+        const have = vectorOf(core);
+        for (const [braid, wanted] of target) {
+            const cause = core.wedged.get(braid);
+            const at = have.get(braid);
+            if (cause !== undefined && at !== undefined && at < wanted) {
+                return { tag: "wedged", braid, cause };
+            }
+        }
+        if (Vector.from(have).dominates(Vector.from(target))) {
+            return { tag: "reached", vector: have };
+        }
+        const outcome = await withGate(core, async function waitPass() {
+            disposed(core);
+            return refreshPass(core);
+        });
+        if (outcome.tag === "refused") {
+            return { tag: "refused", detail: outcome.detail };
+        }
+        await new Promise(function later(resolve) {
+            setTimeout(resolve, WAIT_FOR_POLL_MS);
+        });
+    }
+}
+async function openReplica(options) {
+    const core = await openCore(options);
+    const replica = {
+        get db() {
+            disposed(core);
+            return core.db;
+        },
+        get vector() {
+            return vectorOf(core);
+        },
+        async refresh(braid) {
+            return withGate(core, async function refreshBody() {
+                disposed(core);
+                await refreshPass(core, braid);
+                return vectorOf(core);
+            });
+        },
+        async waitFor(vector) {
+            const target = new Map();
+            for (const [braid, wanted] of vector) {
+                target.set(braidOf(core.theory, braid), wanted);
+            }
+            return waitForVector(core, target);
+        },
+        async [Symbol.asyncDispose]() {
+            await withGate(core, async function disposeBody() {
+                core.closed = true;
+                await persistSidecar(core);
+            });
+        }
+    };
+    cores.set(replica, core);
+    return replica;
+}
+export { applyOps, belowFloor, chainEntry, clearPending, coreOf, discardAndReopen, entriesOf, foldPending, generationOf, holdPending, maxBigint, openReplica, pendingOf, persistSidecar, readdressPending, withGate, ZERO_HASH };
+//# sourceMappingURL=replica.js.map