@bjornpagen/bumbledb 0.1.0

package/dist/db.js

@@ -0,0 +1,1016 @@
+/**
+ * `Db` — the living half of the SDK (PRD-07): open/create a store from a
+ * `Schema`, write typed facts through delta transactions with race-free
+ * final-state point reads, receive rejections as typed violation VALUES
+ * keyed to statements, read through scoped snapshots, and run the witnessed
+ * read-compute-write loop — all typed by the schema's relations record.
+ *
+ * ZERO CLOSABLES: no value this module returns carries a close, dispose, or
+ * release spelling. `Db` values are CACHED per canonical path for the life
+ * of the process (a best-effort exit hook closes the cached environments;
+ * correctness never depends on it — the engine fsyncs every commit, so a
+ * process that dies without the hook loses nothing that was committed).
+ * Snapshots are internal: `read(fn)` opens one before `fn` and closes it
+ * after unconditionally, and the {@link ReadScope} handed to `fn` is
+ * invalidated the moment `fn` returns. Prepared plans are plain values whose
+ * engine-side half is reclaimed by a GC finalizer — reclamation only, never
+ * correctness.
+ *
+ * PROCESS MODEL: one process, one exclusive-lock handle per store. The
+ * cached `Db` value owns the LMDB environment's exclusive lock until
+ * process exit; a second engine-level open of the same store (an aliased
+ * path spelling, or another process) is refused by the engine. The
+ * run-store process model (PRD-16) depends on this being true: resume =
+ * reopen, which is either this process's cached value or a fresh process's
+ * open.
+ *
+ * REJECTION IS DATA: a rejected commit is a domain outcome (it becomes the
+ * LLM repair prompt downstream), returned as a {@link WriteResult} carrying
+ * {@link Violation} values. Genuine failures — I/O, used-after-scope,
+ * marshal shape — throw `@superbuilders/errors` wrapped errors instead.
+ */
+import * as path from "node:path";
+import * as errors from "@superbuilders/errors";
+import { phantom } from "#brand.ts";
+import { exhumeStore } from "#exhume.ts";
+import { lower } from "#lower.ts";
+import { factOf, isMintedFresh, keyRowOf, recordOf, rowOf } from "#marshal.ts";
+import { native } from "#native.ts";
+import { lowerQuery } from "#query/lower.ts";
+import { decodeAnswers, wireParams } from "#query/run.ts";
+/**
+ * The runtime discriminant of {@link Abandon} values — a property probe is
+ * how `writeWitnessed` distinguishes "abort without committing" from an
+ * ordinary callback result, never a guess about the host's own value shapes.
+ */
+const abandonMark = Symbol("bumbledb.abandon");
+/**
+ * Wraps a payload in the {@link Abandon} sentinel — the one way a
+ * `writeWitnessed` callback declines to commit: `return abandon(payload)`
+ * aborts the delta (nothing is committed, not even an empty commit) and the
+ * write resolves to `{ ok: false, abandoned: payload }`.
+ */
+function abandon(payload) {
+    return Object.freeze({ [abandonMark]: true, payload });
+}
+/**
+ * Narrows a `writeWitnessed` callback result to the abandon sentinel. The
+ * probe is the private {@link abandonMark} symbol only {@link abandon} sets,
+ * and `R`'s `Abandon` arm is the only way a sentinel can flow out of the
+ * callback — so the narrowed payload type is sound by construction.
+ */
+function isAbandon(value) {
+    return typeof value === "object" && value !== null && abandonMark in value;
+}
+/**
+ * The bridge guard: runs one native call and wraps anything it throws —
+ * marshal-shape refusals and handle-lifecycle refusals cross as genuine
+ * typed failures, never bare foreign errors.
+ */
+function bridged(context, run) {
+    const result = errors.trySync(run);
+    if (result.error) {
+        throw errors.wrap(result.error, context);
+    }
+    return result.data;
+}
+/**
+ * Mirrors the engine's materialized statement order
+ * (`SchemaDescriptor::materialized_statements`, pinned by the fingerprint):
+ * one auto-key per fresh field (relation declaration order, then field
+ * order), one closed auto-key per closed relation (declaration order),
+ * then the declared statements in declaration order — a `mirrors`
+ * statement occupying TWO adjacent slots (the engine lowers `==` to two
+ * containments, `source <= target` first), both owned by the one SDK
+ * value. This positional match is how statement ids resolve back to SDK
+ * statement values without the engine ever learning a wire format.
+ */
+function materializedEntries(theory) {
+    const entries = impliedKeyEntries(theory);
+    for (const statement of theory.statements) {
+        entries.push(...declaredEntries(statement));
+    }
+    return entries;
+}
+/**
+ * The engine-materialized implied keys, in the engine's pinned order: one
+ * auto-key per fresh field (relation declaration order, then field order),
+ * then one closed auto-key `R(id) -> R` per closed relation (declaration
+ * order). These slots carry no SDK statement value — the engine owns them
+ * (`schema()` rejects an explicit duplicate).
+ */
+function impliedKeyEntries(theory) {
+    const entries = [];
+    for (const member of Object.values(theory.relations)) {
+        if ("handles" in member.data) {
+            continue;
+        }
+        for (const declared of member.data.fields) {
+            if (declared.field.minted) {
+                entries.push({
+                    kind: "functionality",
+                    statement: undefined,
+                    key: { owner: member.name, projection: [declared.name] }
+                });
+            }
+        }
+    }
+    for (const member of Object.values(theory.relations)) {
+        if ("handles" in member.data) {
+            entries.push({
+                kind: "functionality",
+                statement: undefined,
+                key: { owner: member.name, projection: ["id"] }
+            });
+        }
+    }
+    return entries;
+}
+/**
+ * One declared statement's materialized slots: a key or window occupies
+ * one, a `mirrors` occupies two adjacent slots (the engine lowers `==` to
+ * two containments, `source <= target` first), both owned by the one SDK
+ * value.
+ */
+function declaredEntries(statement) {
+    const data = statement.data;
+    switch (data.kind) {
+        case "key": {
+            return [
+                {
+                    kind: "functionality",
+                    statement,
+                    key: { owner: data.owner.name, projection: data.projection }
+                }
+            ];
+        }
+        case "containment": {
+            if (data.bidirectional) {
+                return [
+                    { kind: "containment", statement, key: undefined, reversed: false },
+                    { kind: "containment", statement, key: undefined, reversed: true }
+                ];
+            }
+            return [{ kind: "containment", statement, key: undefined }];
+        }
+        case "window": {
+            return [{ kind: "cardinality", statement, key: undefined }];
+        }
+    }
+}
+/**
+ * Narrows a callback result to a thenable — the async-callback probe both
+ * commit sites share: an `async` build callback typechecks (`Promise<void>`
+ * is assignable where a `void` return is expected), so the refusal has to
+ * be a runtime probe on the returned value.
+ */
+function isThenable(value) {
+    return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
+}
+/**
+ * Narrows a keyed-get middle argument to a statement value (vs a key
+ * object): only statement values carry `data.kind` — no fact cell shape
+ * (bool, bigint, string, bytes, `{ start, end }`) ever does, so the probe
+ * never misreads a key object whose relation declares a field named `data`.
+ */
+function isStatementValue(value) {
+    if (typeof value !== "object" || !("data" in value)) {
+        return false;
+    }
+    const data = value.data;
+    return typeof data === "object" && data !== null && "kind" in data;
+}
+/** Maps a slot's reversal flag to the violation's `orientation` payload. */
+function orientationOf(reversed) {
+    if (reversed === undefined) {
+        return undefined;
+    }
+    if (reversed) {
+        return "mirrored";
+    }
+    return "written";
+}
+/**
+ * Builds the id-resolution tables from the manifest, verifying the SDK's
+ * positional mirror against the engine's reported order — any drift
+ * (count, kind, id, or membership) is a construction-time failure, never a
+ * silent misattribution of a violation to the wrong statement value.
+ */
+function tablesOf(theory, manifest) {
+    const entries = materializedEntries(theory);
+    if (entries.length !== manifest.statements.length) {
+        throw errors.new(`bumbledb manifest drift: the SDK lowering yields ${entries.length} materialized statements, the engine reports ${manifest.statements.length}`);
+    }
+    manifest.statements.forEach(function verifySlot(statement, index) {
+        const entry = entries[index];
+        if (entry === undefined || statement.id !== index || entry.kind !== statement.kind) {
+            throw errors.new(`bumbledb manifest drift: statement ${statement.id} is ${statement.kind}, the SDK mirror at ${index} expected ${entry?.kind}`);
+        }
+    });
+    const relations = new Map();
+    for (const relation of manifest.relations) {
+        const member = theory.relations[relation.name];
+        if (member === undefined) {
+            throw errors.new(`bumbledb manifest drift: relation ${relation.name} is not in schema ${theory.name}`);
+        }
+        const fieldIds = new Map();
+        for (const field of relation.fields) {
+            fieldIds.set(field.name, field.id);
+        }
+        let primaryKey;
+        entries.forEach(function firstOwnedKey(entry, index) {
+            if (primaryKey === undefined && entry.key !== undefined && entry.key.owner === relation.name) {
+                primaryKey = Object.freeze({ statementId: index, projection: entry.key.projection });
+            }
+        });
+        relations.set(relation.name, Object.freeze({ id: relation.id, member, fieldIds, primaryKey }));
+    }
+    for (const name of Object.keys(theory.relations)) {
+        if (!relations.has(name)) {
+            throw errors.new(`bumbledb manifest drift: schema relation ${name} is not in the manifest`);
+        }
+    }
+    return Object.freeze({ relations, statements: Object.freeze(entries) });
+}
+/** The private lifetime records of this module's read scopes. */
+const scopeStates = new WeakMap();
+/** The private engine halves of this module's prepared values. */
+const preparedPlans = new WeakMap();
+/**
+ * Reclaims the engine-side plan of a garbage-collected {@link Prepared}
+ * value. RECLAMATION ONLY, never correctness: a plan the collector never
+ * visits is idle engine memory until process exit, and a failure to close
+ * is swallowed (there is no one left to care — the owning value is gone).
+ */
+const planReclaimer = new FinalizationRegistry(function reclaimPlan(handle) {
+    const closed = errors.trySync(function closePlan() {
+        native.preparedClose(handle);
+    });
+    if (closed.error) {
+        return;
+    }
+});
+/**
+ * The internal retry signal a lazily-witnessed transaction throws when the
+ * engine reports a moved generation at begin: `writeWitnessed` catches it
+ * by identity (through cause chains, via `errors.is`) and reruns the whole
+ * callback on a fresh snapshot. It never escapes the SDK.
+ */
+const generationMovedSignal = errors.new("bumbledb witnessed generation moved");
+/**
+ * Fills one insert's omitted fresh cells through the engine's
+ * alloc-then-insert dyn lane (there is no insert-with-omitted-fields wire
+ * spelling) and collects every fresh cell — minted or resupplied — for the
+ * insert's return. Mutates `values` in place with the minted cells.
+ */
+function mintFreshCells(txHandle, entry, relation, values) {
+    const fresh = {};
+    for (const declared of relation.data.fields) {
+        if (!declared.field.minted) {
+            continue;
+        }
+        let cell = values[declared.name];
+        if (cell === undefined) {
+            const fieldId = entry.fieldIds.get(declared.name);
+            if (fieldId === undefined) {
+                throw errors.new(`bumbledb manifest drift: relation ${relation.name} has no field id for ${declared.name}`);
+            }
+            cell = bridged("bumbledb tx alloc", function mint() {
+                return native.txAlloc(txHandle, entry.id, fieldId);
+            });
+            values[declared.name] = cell;
+        }
+        if (typeof cell !== "bigint") {
+            throw errors.new(`relation ${relation.name} field ${declared.name}: a fresh cell is a u64 bigint, got ${typeof cell}`);
+        }
+        fresh[declared.name] = cell;
+    }
+    return fresh;
+}
+/**
+ * Constructs one open `Db` over an already-admitted handle: builds the
+ * id-resolution tables once and closes over them — the `Db` owns handle
+ * and tables and nothing else. Handle lifetime is the process's: the store
+ * cache holds the environment handle until the exit hook closes it.
+ */
+function openDb(handle, theory, manifest) {
+    const tables = tablesOf(theory, manifest);
+    /** This store's identity token: read scopes and prepared values carry it, so cross-store use is a typed refusal. */
+    const owner = Object.freeze({});
+    function isMemberName(name) {
+        return tables.relations.has(name);
+    }
+    function resolveOrdinary(relation) {
+        const entry = tables.relations.get(relation.name);
+        if (entry === undefined || entry.member !== relation) {
+            throw errors.new(`relation ${relation.name} is not a member of schema ${theory.name}`);
+        }
+        if ("handles" in relation.data) {
+            throw errors.new(`relation ${relation.name} is closed — its extension is schema data (axioms), never scanned or written`);
+        }
+        return entry;
+    }
+    function offendingFactOf(fact) {
+        if (!isMemberName(fact.relation)) {
+            throw errors.new(`bumbledb violation cites unknown relation ${fact.relation}`);
+        }
+        const decoded = {};
+        for (const cell of fact.fields) {
+            decoded[cell.name] = cell.value;
+        }
+        return Object.freeze({ relation: fact.relation, fact: Object.freeze(decoded) });
+    }
+    function violationOf(wire) {
+        const entry = tables.statements[wire.statementId];
+        if (entry === undefined) {
+            throw errors.new(`bumbledb violation cites unknown statement id ${wire.statementId}`);
+        }
+        return Object.freeze({
+            statement: entry.statement,
+            kind: wire.kind,
+            canonical: wire.canonical,
+            direction: wire.direction,
+            orientation: orientationOf(entry.reversed),
+            count: wire.count,
+            facts: Object.freeze(wire.facts.map(offendingFactOf))
+        });
+    }
+    /**
+     * Resolves a key-statement-selected read: the statement must be the
+     * IDENTICAL `key()` value this schema declared (identity is the
+     * membership rule) and must key `relation` — its materialized statement
+     * id comes from the positional mirror, so the engine point-reads through
+     * exactly the declared projection.
+     */
+    function declaredKeyOf(relation, statement) {
+        const statementId = tables.statements.findIndex(function byIdentity(candidate) {
+            return candidate.statement === statement;
+        });
+        const entry = tables.statements[statementId];
+        if (entry === undefined) {
+            throw errors.new(`keyed get statement is not a declared statement of schema ${theory.name} — statement identity is the membership rule`);
+        }
+        if (entry.kind !== "functionality" || entry.key === undefined) {
+            throw errors.new("keyed get takes a key() statement — containments and windows key nothing");
+        }
+        if (entry.key.owner !== relation.name) {
+            throw errors.new(`keyed get statement keys ${entry.key.owner}, not ${relation.name} — the statement must be a declared key of the relation it reads`);
+        }
+        return Object.freeze({ statementId, projection: entry.key.projection });
+    }
+    function pointReadsOf(assertLive, reads) {
+        function contains(relation, fact) {
+            assertLive();
+            const entry = resolveOrdinary(relation);
+            return reads.contains(entry.id, rowOf(relation.data, recordOf(fact)));
+        }
+        /** One keyed point read through an already-resolved key, decoded to a fact (`undefined` on a miss). */
+        function readThroughKey(relation, entry, selected, key) {
+            const row = reads.get(entry.id, selected.statementId, keyRowOf(relation.data, selected.projection, key));
+            if (row === null) {
+                return undefined;
+            }
+            return factOf(relation, row);
+        }
+        function get(relation, keyOrStatement, declaredKey) {
+            assertLive();
+            const entry = resolveOrdinary(relation);
+            if (declaredKey !== undefined) {
+                if (!isStatementValue(keyOrStatement)) {
+                    throw errors.new("keyed get takes a key() statement value as its second argument");
+                }
+                const selected = declaredKeyOf(relation, keyOrStatement);
+                return readThroughKey(relation, entry, selected, recordOf(declaredKey));
+            }
+            if (isStatementValue(keyOrStatement)) {
+                throw errors.new("keyed get with a statement selector also takes the key object — get(relation, keyStatement, key)");
+            }
+            const primaryKey = entry.primaryKey;
+            if (primaryKey === undefined) {
+                throw errors.new(`relation ${relation.name} has no candidate key — keyed get requires a fresh field or a declared key statement`);
+            }
+            return readThroughKey(relation, entry, primaryKey, recordOf(keyOrStatement));
+        }
+        return { contains, get };
+    }
+    /**
+     * Resolves a prepared value's private plan, refusing foreign objects
+     * and prepared values of other stores as typed errors.
+     */
+    function planOf(prepared) {
+        const plan = preparedPlans.get(prepared);
+        if (plan === undefined) {
+            throw errors.new("bumbledb execute target is not a prepared value of this SDK");
+        }
+        if (plan.owner !== owner) {
+            throw errors.new(`bumbledb prepared value was prepared by a different store than this one (schema ${theory.name})`);
+        }
+        return plan;
+    }
+    /**
+     * Builds one {@link ReadScope} over a live scope state. Every verb
+     * asserts liveness first: the owning call flips `state.live` the moment
+     * its callback returns, so a leaked scope is a typed refusal forever
+     * after.
+     */
+    function makeScope(state, generation) {
+        function assertLive() {
+            if (!state.live) {
+                throw errors.new("bumbledb read scope is invalidated — its owning read callback already returned");
+            }
+        }
+        const reads = pointReadsOf(assertLive, {
+            contains(relationId, row) {
+                return bridged("bumbledb snapshot contains", function readContains() {
+                    return native.snapshotContains(state.handle, relationId, row);
+                });
+            },
+            get(relationId, statementId, key) {
+                return bridged("bumbledb snapshot get", function readGet() {
+                    return native.snapshotGet(state.handle, relationId, statementId, key);
+                });
+            }
+        });
+        function scan(relation) {
+            assertLive();
+            const entry = resolveOrdinary(relation);
+            const rows = bridged("bumbledb snapshot scan", function readScan() {
+                return native.snapshotScan(state.handle, entry.id);
+            });
+            return rows.map(function decodeRow(row) {
+                return factOf(relation, row);
+            });
+        }
+        function execute(prepared, params) {
+            assertLive();
+            const plan = planOf(prepared);
+            const wire = wireParams(plan.params, recordOf(params));
+            const rows = bridged("execute bumbledb prepared query", function callExecute() {
+                return native.preparedExecute(plan.handle, state.handle, wire);
+            });
+            return decodeAnswers(plan.select, rows);
+        }
+        const scope = Object.freeze({
+            generation,
+            scan,
+            get: reads.get,
+            contains: reads.contains,
+            execute
+        });
+        scopeStates.set(scope, state);
+        return scope;
+    }
+    /**
+     * Live-handle accounting (diagnostic law, prod EINVAL 2026-07-17): every
+     * snapshot open/close is counted so a write-begin failure can report how
+     * many read handles were live at the fault — a leaked scope is invisible
+     * until the exact moment it matters, so the failure carries the census.
+     */
+    let liveSnapshots = 0;
+    /** Opens one snapshot and its scope state (live until the owner flips it). */
+    function openScopeState() {
+        const snapHandle = bridged("open bumbledb snapshot", function openSnapshot() {
+            return native.dbSnapshot(handle);
+        });
+        liveSnapshots += 1;
+        return { handle: snapHandle, live: true, owner };
+    }
+    /** Closes a scope's snapshot after the owner invalidated it. */
+    function closeScopeState(state) {
+        bridged("close bumbledb snapshot", function closeSnapshot() {
+            native.snapshotClose(state.handle);
+        });
+        liveSnapshots -= 1;
+    }
+    /**
+     * Reads the committed generation for a just-opened scope, closing the
+     * scope's snapshot when the read faults: `dbGeneration` opens a transient
+     * engine read txn, so reader-table exhaustion is precisely the state in
+     * which it throws — with one snapshot already open. An unpaired fault
+     * here would park a snapshot worker and consume one of the engine's
+     * reader slots FOREVER (and undercount the liveSnapshots census), each
+     * fault ratcheting toward ReadersFull-for-the-process's-lifetime.
+     */
+    function generationForScope(state) {
+        const generation = errors.trySync(function readGeneration() {
+            return bridged("read bumbledb generation", function callGeneration() {
+                return native.dbGeneration(handle);
+            });
+        });
+        if (generation.error) {
+            state.live = false;
+            closeScopeState(state);
+            throw generation.error;
+        }
+        return generation.data;
+    }
+    function read(fn) {
+        const state = openScopeState();
+        const generation = generationForScope(state);
+        const scope = makeScope(state, generation);
+        const result = errors.trySync(function runRead() {
+            return fn(scope);
+        });
+        state.live = false;
+        closeScopeState(state);
+        if (result.error) {
+            throw errors.wrap(result.error, "bumbledb read");
+        }
+        return result.data;
+    }
+    function scan(relation) {
+        return read(function scanInScope(snap) {
+            return snap.scan(relation);
+        });
+    }
+    function get(relation, keyOrStatement, declaredKey) {
+        return read(function getInScope(snap) {
+            if (declaredKey !== undefined) {
+                if (!isStatementValue(keyOrStatement)) {
+                    throw errors.new("keyed get takes a key() statement value as its second argument");
+                }
+                return snap.get(relation, keyOrStatement, declaredKey);
+            }
+            if (isStatementValue(keyOrStatement)) {
+                throw errors.new("keyed get with a statement selector also takes the key object — get(relation, keyStatement, key)");
+            }
+            return snap.get(relation, keyOrStatement);
+        });
+    }
+    function contains(relation, fact) {
+        return read(function containsInScope(snap) {
+            return snap.contains(relation, fact);
+        });
+    }
+    function execute(prepared, params) {
+        return read(function executeInScope(snap) {
+            return snap.execute(prepared, params);
+        });
+    }
+    /**
+     * Builds one {@link Tx} over a transaction-handle thunk: `write` passes
+     * an already-begun handle; `writeWitnessed` passes a LAZY thunk that
+     * begins the witnessed transaction on the first delta verb (so premise
+     * reads and the host's own interleaved writes can precede it) and
+     * throws {@link generationMovedSignal} when the witness is stale.
+     */
+    function makeTx(resolveTx) {
+        const txState = { spent: false };
+        function assertLive() {
+            if (txState.spent) {
+                throw errors.new("bumbledb write transaction is spent");
+            }
+        }
+        const reads = pointReadsOf(assertLive, {
+            contains(relationId, row) {
+                const txHandle = resolveTx();
+                return bridged("bumbledb tx contains", function readContains() {
+                    return native.txContains(txHandle, relationId, row);
+                });
+            },
+            get(relationId, statementId, key) {
+                const txHandle = resolveTx();
+                return bridged("bumbledb tx get", function readGet() {
+                    return native.txGet(txHandle, relationId, statementId, key);
+                });
+            }
+        });
+        function insert(relation, fact) {
+            assertLive();
+            const entry = resolveOrdinary(relation);
+            const txHandle = resolveTx();
+            const values = recordOf(fact);
+            const fresh = mintFreshCells(txHandle, entry, relation, values);
+            const row = rowOf(relation.data, values);
+            bridged("bumbledb tx insert", function record() {
+                native.txInsert(txHandle, entry.id, row);
+            });
+            Object.freeze(fresh);
+            if (!isMintedFresh(relation, fresh)) {
+                throw errors.new(`relation ${relation.name}: minted fresh record is incomplete`);
+            }
+            return fresh;
+        }
+        function remove(relation, fact) {
+            assertLive();
+            const entry = resolveOrdinary(relation);
+            const txHandle = resolveTx();
+            const row = rowOf(relation.data, recordOf(fact));
+            return bridged("bumbledb tx delete", function record() {
+                return native.txDelete(txHandle, entry.id, row);
+            });
+        }
+        const tx = Object.freeze({
+            insert,
+            delete: remove,
+            contains: reads.contains,
+            get: reads.get
+        });
+        function spend() {
+            txState.spent = true;
+        }
+        return { tx, spend };
+    }
+    function runDelta(txHandle, fn) {
+        const made = makeTx(function resolveTx() {
+            return txHandle;
+        });
+        const built = errors.trySync(function buildDelta() {
+            return fn(made.tx);
+        });
+        made.spend();
+        if (built.error) {
+            bridged("abort bumbledb write transaction", function abort() {
+                native.txAbort(txHandle);
+            });
+            throw errors.wrap(built.error, "build write delta");
+        }
+        if (isThenable(built.data)) {
+            /**
+             * An `async` callback TYPECHECKS (Promise<void> is assignable where
+             * a `void` return is expected) but its body runs after the tx is
+             * spent: committing here would be a silent EMPTY commit reported
+             * ok while the callback's real inserts throw "spent" as unhandled
+             * rejections. Refused typed instead — abort, nothing committed
+             * (the same one-writer law as the thrown-callback path).
+             */
+            bridged("abort bumbledb write transaction", function abort() {
+                native.txAbort(txHandle);
+            });
+            throw errors.new("bumbledb write callback returned a thenable — the delta build is synchronous; an async callback is refused, nothing was committed");
+        }
+        const committed = errors.trySync(function commitDelta() {
+            return bridged("commit bumbledb write transaction", function commit() {
+                return native.txCommit(txHandle);
+            });
+        });
+        if (committed.error) {
+            /**
+             * A THROWN commit (engine I/O failure, bridge fault) must never
+             * leave the write transaction live: LMDB holds one writer per
+             * environment, and a leaked handle turns every later begin into
+             * EINVAL for the process's lifetime. The abort is best-effort —
+             * the native side may already have consumed the handle.
+             */
+            const aborted = errors.trySync(function abortAfterFailedCommit() {
+                native.txAbort(txHandle);
+            });
+            if (aborted.error) {
+            }
+            throw errors.wrap(committed.error, "commit bumbledb write transaction");
+        }
+        const outcome = committed.data;
+        if (outcome.ok) {
+            return Object.freeze({ ok: true, generation: outcome.generation });
+        }
+        return Object.freeze({
+            ok: false,
+            violations: Object.freeze(outcome.violations.map(violationOf))
+        });
+    }
+    function write(fn) {
+        const begun = errors.trySync(function beginDelta() {
+            return bridged("begin bumbledb write transaction", function begin() {
+                return native.dbWriteBegin(handle);
+            });
+        });
+        if (begun.error) {
+            throw errors.wrap(begun.error, `begin bumbledb write transaction (live snapshots at fault: ${liveSnapshots})`);
+        }
+        return runDelta(begun.data, fn);
+    }
+    /**
+     * Commits an already-begun witnessed transaction and closes the
+     * attempt's snapshot: the committed generation, or the engine's
+     * complete violation set as data.
+     */
+    function commitWitnessed(state, txHandle) {
+        const committed = errors.trySync(function commitWitnessedDelta() {
+            return bridged("commit bumbledb witnessed write transaction", function commit() {
+                return native.txCommit(txHandle);
+            });
+        });
+        if (committed.error) {
+            /** Same one-writer law as `runDelta`: a thrown commit aborts before rethrowing. */
+            const aborted = errors.trySync(function abortAfterFailedCommit() {
+                native.txAbort(txHandle);
+            });
+            if (aborted.error) {
+            }
+            closeScopeState(state);
+            throw errors.wrap(committed.error, "commit bumbledb witnessed write transaction");
+        }
+        const outcome = committed.data;
+        closeScopeState(state);
+        if (outcome.ok) {
+            return Object.freeze({ ok: true, generation: outcome.generation });
+        }
+        return Object.freeze({
+            ok: false,
+            violations: Object.freeze(outcome.violations.map(violationOf))
+        });
+    }
+    /**
+     * One attempt of the witnessed loop: fresh snapshot, the callback over
+     * its scope and a LAZILY-begun witnessed transaction (the first delta
+     * verb begins it, so premise reads and the host's own interleaved
+     * writes can precede the witness check), then the witnessed commit —
+     * or the abandon abort, which never issues a commit. Returns
+     * `undefined` exactly when the generation moved and the whole callback
+     * must rerun on a fresh snapshot.
+     */
+    function witnessedAttempt(fn) {
+        const state = openScopeState();
+        const generation = generationForScope(state);
+        const scope = makeScope(state, generation);
+        const pending = { tx: undefined };
+        function beginWitnessed() {
+            const witnessed = bridged("begin witnessed bumbledb write transaction", function begin() {
+                return native.dbWriteFrom(handle, state.handle);
+            });
+            if (!witnessed.ok) {
+                return undefined;
+            }
+            return witnessed.tx;
+        }
+        const made = makeTx(function resolveWitnessedTx() {
+            if (pending.tx === undefined) {
+                const begun = beginWitnessed();
+                if (begun === undefined) {
+                    throw generationMovedSignal;
+                }
+                pending.tx = begun;
+            }
+            return pending.tx;
+        });
+        const built = errors.trySync(function computeWitnessed() {
+            return fn(scope, made.tx);
+        });
+        made.spend();
+        state.live = false;
+        /**
+         * Aborts the pending transaction if one was begun. A faulted abort
+         * still closes the attempt's snapshot BEFORE rethrowing — every
+         * openScopeState is paired with closeScopeState on every exit, or a
+         * reader slot and its snapshot worker leak for the process's lifetime.
+         */
+        function abortPending() {
+            const txHandle = pending.tx;
+            if (txHandle === undefined) {
+                return;
+            }
+            const aborted = errors.trySync(function abort() {
+                native.txAbort(txHandle);
+            });
+            if (aborted.error) {
+                closeScopeState(state);
+                throw errors.wrap(aborted.error, "abort bumbledb witnessed write transaction");
+            }
+        }
+        if (built.error) {
+            abortPending();
+            closeScopeState(state);
+            if (errors.is(built.error, generationMovedSignal)) {
+                return undefined;
+            }
+            throw errors.wrap(built.error, "build witnessed write delta");
+        }
+        if (isThenable(built.data)) {
+            /** The same async-callback refusal as `runDelta` — a thenable means the real delta build races the commit; nothing is committed. */
+            abortPending();
+            closeScopeState(state);
+            throw errors.new("bumbledb writeWitnessed callback returned a thenable — the delta build is synchronous; an async callback is refused, nothing was committed");
+        }
+        if (isAbandon(built.data)) {
+            abortPending();
+            closeScopeState(state);
+            return Object.freeze({ ok: false, abandoned: built.data.payload });
+        }
+        const late = errors.trySync(function resolveCommitTx() {
+            if (pending.tx === undefined) {
+                return beginWitnessed();
+            }
+            return pending.tx;
+        });
+        if (late.error) {
+            /** A faulted late begin must not leak the attempt's snapshot either. */
+            closeScopeState(state);
+            throw late.error;
+        }
+        const txHandle = late.data;
+        if (txHandle === undefined) {
+            closeScopeState(state);
+            return undefined;
+        }
+        return commitWitnessed(state, txHandle);
+    }
+    function writeWitnessed(fn) {
+        for (;;) {
+            const attempt = witnessedAttempt(fn);
+            if (attempt !== undefined) {
+                return attempt;
+            }
+        }
+    }
+    /**
+     * Verifies the declaration-ordinal law the query lowering leans on
+     * against the live manifest tables: relation ids and sealed field ids
+     * both equal declaration order (`dbManifest` is the engine's own
+     * pinning of it). Any drift is a construction-time failure here, never
+     * a silently misaddressed query.
+     */
+    function assertOrdinalAlignment() {
+        Object.keys(theory.relations).forEach(function verifyRelation(name, ordinal) {
+            const entry = tables.relations.get(name);
+            if (entry === undefined || entry.id !== ordinal) {
+                throw errors.new(`bumbledb manifest drift: relation ${name} has engine id ${entry?.id}, its declaration ordinal is ${ordinal} — query lowering depends on declaration order = ids`);
+            }
+            const member = theory.relations[name];
+            if (member === undefined) {
+                throw errors.new(`bumbledb manifest drift: schema ${theory.name} lost relation ${name}`);
+            }
+            const sealed = "handles" in member.data
+                ? [
+                    "id",
+                    ...member.data.columns.map(function columnName(column) {
+                        return column.name;
+                    })
+                ]
+                : member.data.fields.map(function fieldName(declared) {
+                    return declared.name;
+                });
+            sealed.forEach(function verifyField(fieldName, fieldOrdinal) {
+                if (entry.fieldIds.get(fieldName) !== fieldOrdinal) {
+                    throw errors.new(`bumbledb manifest drift: ${name}.${fieldName} has engine field id ${entry.fieldIds.get(fieldName)}, its sealed ordinal is ${fieldOrdinal}`);
+                }
+            });
+        });
+    }
+    function prepare(q) {
+        if (q.schema !== theory) {
+            throw errors.new(`query was built against schema ${q.schema.name}, not the identical schema value this store opened with — schema identity is the membership rule`);
+        }
+        assertOrdinalAlignment();
+        const program = lowerQuery(q);
+        const outcome = bridged("prepare bumbledb program", function callPrepare() {
+            return native.dbPrepare(handle, program);
+        });
+        if (!outcome.ok) {
+            throw errors.new(`bumbledb ${outcome.kind} (prepare): ${outcome.message}`);
+        }
+        const preparedHandle = outcome.prepared;
+        function staleness(snap) {
+            const snapState = scopeStates.get(snap);
+            if (snapState === undefined) {
+                throw errors.new("bumbledb staleness witness is not a read scope of this SDK");
+            }
+            if (snapState.owner !== owner) {
+                throw errors.new(`bumbledb read scope belongs to a different store than this prepared value (schema ${theory.name})`);
+            }
+            if (!snapState.live) {
+                throw errors.new("bumbledb read scope is invalidated — its owning read callback already returned");
+            }
+            return bridged("read bumbledb prepared staleness", function callStaleness() {
+                return native.preparedStaleness(preparedHandle, snapState.handle);
+            });
+        }
+        const prepared = Object.freeze({ staleness });
+        preparedPlans.set(prepared, Object.freeze({
+            handle: preparedHandle,
+            owner,
+            params: q.data.registry.params,
+            select: q.data.select
+        }));
+        planReclaimer.register(prepared, preparedHandle);
+        return prepared;
+    }
+    return Object.freeze({
+        schema: theory,
+        read,
+        scan,
+        get,
+        contains,
+        execute,
+        write,
+        writeWitnessed,
+        prepare
+    });
+}
+/**
+ * The per-process store cache, keyed by canonical path
+ * (`node:path.resolve` — absolute and normalized). Symlink aliasing is
+ * deliberately not resolved here: an aliased spelling misses the cache and
+ * reaches the engine, whose exclusive lock refuses a second live handle on
+ * the same store — the backstop that keeps "one store, one handle" true.
+ */
+const openStores = new Map();
+/**
+ * The in-process fingerprint check and its typing proof in one probe:
+ * theory identity (`===`) implies `Rels` identity, because a cache entry's
+ * `db` was constructed from that very theory value — so a hit narrows the
+ * entry's `db` to `Db<Rels>` with no assertion anywhere.
+ */
+function holdsTheory(entry, theory) {
+    return entry.theory === theory;
+}
+/**
+ * The best-effort exit hook: closes every cached environment so LMDB
+ * releases its locks tidily on a clean exit. CORRECTNESS NEVER RESTS HERE —
+ * the engine fsyncs every commit, so a process killed before (or during)
+ * this hook loses nothing that was committed.
+ */
+process.once("exit", function closeCachedStores() {
+    for (const cached of openStores.values()) {
+        const closed = errors.trySync(function closeEnvironment() {
+            native.dbClose(cached.handle);
+        });
+        if (closed.error) {
+        }
+    }
+});
+/**
+ * The one admission path both verbs share: canonical-path cache lookup
+ * first (a hit returns the SAME `Db` value for the identical theory, a
+ * typed fingerprint error for a different one, and a typed refusal for
+ * `create` — the store a cache entry proves initialized is exactly what
+ * create refuses). On a miss: lower the theory, run one bridge call, and
+ * wrap the two domain refusals — `schemaError` (spec resolution + schema
+ * validation, every issue in one message) and `fingerprintMismatch` (a
+ * different theory cannot open the store) — into typed errors carrying the
+ * engine's message intact.
+ */
+function admit(verb, storePath, theory) {
+    const canonical = path.resolve(storePath);
+    const cached = openStores.get(canonical);
+    if (cached !== undefined) {
+        if (verb === "create") {
+            throw errors.new(`create bumbledb store at ${canonical}: the store is already open in this process — create refuses an already-initialized directory`);
+        }
+        if (!holdsTheory(cached, theory)) {
+            throw errors.new(`bumbledb fingerprintMismatch (open ${canonical}): the cached store was opened with schema ${cached.theory.name}, not this theory value — schema identity is the membership rule`);
+        }
+        return cached.db;
+    }
+    const spec = lower(theory);
+    const opened = bridged(`${verb} bumbledb store at ${canonical}`, function callBridge() {
+        if (verb === "create") {
+            return native.dbCreate(canonical, spec);
+        }
+        return native.dbOpen(canonical, spec);
+    });
+    if (!opened.ok) {
+        throw errors.new(`bumbledb ${opened.kind} (${verb} ${canonical}): ${opened.message}`);
+    }
+    const manifest = bridged("fetch bumbledb manifest", function fetchManifest() {
+        return native.dbManifest(opened.db);
+    });
+    const db = openDb(opened.db, theory, manifest);
+    openStores.set(canonical, Object.freeze({ theory, db, handle: opened.db }));
+    return db;
+}
+/**
+ * The store lifecycle — `Db.create(path, schema)` / `Db.open(path, schema)`.
+ * Create refuses an already-initialized directory; open verifies format
+ * version, store kind, and the schema fingerprint. Both return values
+ * CACHED per canonical path: a second open of the same path with the
+ * identical theory value returns the SAME `Db`, and a different theory on
+ * a cached path is a typed fingerprint error. There is no close anywhere:
+ * the process owns every cached environment until exit (a best-effort exit
+ * hook closes them; durability is the engine's per-commit fsync). One
+ * store kind exists: durable — resume = reopen, meaning this process's
+ * cached value or a fresh process's open.
+ */
+const Db = Object.freeze({
+    /** Creates a fresh durable store at `path` from the schema; the value is cached for every later open. */
+    async create(path, theory) {
+        return admit("create", path, theory);
+    },
+    /**
+     * Opens an existing durable store at `path` with the same theory — the
+     * cached value when this process already holds it. A fingerprint-matching
+     * open also BACK-FILLS the store's persisted schema descriptor when it is
+     * absent (self-describing stores, engine 50-storage.md § the `_meta`
+     * block), so a legacy store becomes exhumable after one ordinary open —
+     * adoption is automatic, never a separate verb.
+     */
+    async open(path, theory) {
+        return admit("open", path, theory);
+    },
+    /**
+     * Opens a store READ-ONLY from its own persisted descriptor — the SDK's
+     * one schema-independent read path (no theory, no fingerprint check; the
+     * store rebirth tool's entry). Lives beside `open`/`create` so the path
+     * law stays in one place: the same `node:path.resolve` canonicalization,
+     * applied here. The value is NOT cached and carries no close: the
+     * engine-side handle (and the store's exclusive lock) is reclaimed by GC
+     * — reclamation only, never correctness. A store not yet adopted rejects
+     * with the typed `ErrExhumeNoDescriptor` (the remedy: one
+     * fingerprint-matching `Db.open` under the creating schema back-fills
+     * the descriptor).
+     */
+    async exhume(storePath) {
+        return exhumeStore(path.resolve(storePath));
+    }
+});
+export { abandon, Db };
+//# sourceMappingURL=db.js.map