@bjornpagen/bumbledb 0.6.0 → 0.8.0

package/dist/db.js

@@ -5,16 +5,19 @@
  * 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.
+ * LIFETIMES ARE DISPOSABLES, never `close()` (ruled 2026-07-23, R12): no
+ * value this module returns carries a close spelling — release is
+ * deterministic and scope-shaped in the language's own syntax. `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 scope-shaped both ways:
+ * `read(fn)` opens one before `fn` and closes it after unconditionally
+ * (the {@link ReadScope} handed to `fn` is invalidated the moment `fn`
+ * returns), and `using snap = db.read()` hands the caller the lifetime,
+ * released by the scope's own `Symbol.dispose` at scope exit. 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
@@ -35,10 +38,11 @@ import { isClosedMember, sealedFieldsOf } from "#closed.ts";
 import { exhumeStore } from "#exhume.ts";
 import { rosterOf } from "#fields.ts";
 import { lower } from "#lower.ts";
-import { factOf, handleOf, isFreshField, isMintedFresh, keyRowOf, recordOf, rowOf } from "#marshal.ts";
+import { factOf, handleOf, isFreshField, isInserted, keyRowOf, recordOf, rowOf } from "#marshal.ts";
 import { bridged, native } from "#native.ts";
 import { lowerQuery } from "#query/lower.ts";
 import { decodeAnswers, wireParams } from "#query/run.ts";
+import { isStatement } from "#statements.ts";
 /**
  * The runtime discriminant of {@link Abandon} values — a property probe is
  * how `writeWitnessed` distinguishes "abort without committing" from an
@@ -46,23 +50,43 @@ import { decodeAnswers, wireParams } from "#query/run.ts";
  */
 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 }`.
+ * Wraps a payload in the {@link Abandon} sentinel — the one way a write
+ * 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 }`, from `write` and `writeWitnessed`
+ * alike (R10).
  */
 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
+ * Narrows a write 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 abandon outcome's trusted admission seam: the value's shape is the
+ * checkable half (the sentinel mark only {@link abandon} mints, and the
+ * outcome carrying that sentinel's own payload), and the sentinel's
+ * existence IS the proof `R` carries an `Abandon` arm — so the outcome is
+ * admitted at the conditional {@link AbandonedArm} face the type tier
+ * cannot resolve over an open `R`.
+ */
+function isAbandonedOutcome(outcome, sentinel) {
+    return isAbandon(sentinel) && outcome.abandoned === sentinel.payload;
+}
+/** Builds the abandoned write outcome from the callback's own sentinel (the R10 arm's one mint). */
+function abandonedOutcome(sentinel) {
+    const outcome = Object.freeze({ ok: false, abandoned: sentinel.payload });
+    if (!isAbandonedOutcome(outcome, sentinel)) {
+        throw errors.new("bumbledb abandon outcome construction incomplete");
+    }
+    return outcome;
+}
 /**
  * The module-private inference slot of {@link Prepared}: an optional symbol
  * property (never set at runtime) that keeps the prepared value's `Row` and
@@ -125,10 +149,10 @@ function impliedKeyEntries(theory) {
     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.
+ * One declared statement's materialized slots: a key or capacity statement
+ * 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;
@@ -151,8 +175,8 @@ function declaredEntries(statement) {
             }
             return [{ kind: "containment", statement, key: undefined }];
         }
-        case "window": {
-            return [{ kind: "cardinality", statement, key: undefined }];
+        case "capacity": {
+            return [{ kind: "capacity", statement, key: undefined }];
         }
     }
 }
@@ -167,16 +191,14 @@ function isThenable(value) {
 }
 /**
  * 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`.
+ * object) through the statement module's admission brand — a
+ * REPRESENTATION, never a shape probe: fact cell shapes are structurally
+ * OPEN (an interval value carrying an excess `kind` property is a legal
+ * cell), so no property probe could ever be sound here, but no host-built
+ * key object can spell the module-private brand symbol.
  */
 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;
+    return isStatement(value);
 }
 /**
  * THE one selector dispatch of the `get` overload pair (primary-key vs
@@ -213,7 +235,11 @@ function orientationOf(reversed) {
  * 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.
+ * silent misattribution of a violation to the wrong statement value. The
+ * declaration-ordinal law the query lowering leans on is verified in the
+ * same walks: relation ids and sealed field ids both equal declaration
+ * order, so a constructed `Tables` IS the proof and `prepare` inherits it
+ * structurally — never a silently misaddressed query.
  */
 function tablesOf(theory, manifest) {
     const entries = materializedEntries(theory);
@@ -236,6 +262,11 @@ function tablesOf(theory, manifest) {
         for (const field of relation.fields) {
             fieldIds.set(field.name, field.id);
         }
+        sealedFieldsOf(member).forEach(function verifyField(declared, fieldOrdinal) {
+            if (fieldIds.get(declared.name) !== fieldOrdinal) {
+                throw errors.new(`bumbledb manifest drift: ${relation.name}.${declared.name} has engine field id ${fieldIds.get(declared.name)}, its sealed ordinal is ${fieldOrdinal}`);
+            }
+        });
         let primaryKey;
         entries.forEach(function firstOwnedKey(entry, index) {
             if (primaryKey === undefined && entry.key !== undefined && entry.key.owner === relation.name) {
@@ -244,11 +275,15 @@ function tablesOf(theory, manifest) {
         });
         relations.set(relation.name, Object.freeze({ id: relation.id, member, fieldIds, primaryKey }));
     }
-    for (const name of Object.keys(theory.relations)) {
-        if (!relations.has(name)) {
+    Object.keys(theory.relations).forEach(function verifyRelation(name, ordinal) {
+        const entry = relations.get(name);
+        if (entry === undefined) {
             throw errors.new(`bumbledb manifest drift: schema relation ${name} is not in the manifest`);
         }
-    }
+        if (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`);
+        }
+    });
     return Object.freeze({ relations, statements: Object.freeze(entries) });
 }
 /** The private lifetime records of this module's read scopes. */
@@ -381,7 +416,7 @@ function openDb(handle, theory, manifest) {
             canonical: wire.canonical,
             direction: wire.direction,
             orientation: orientationOf(entry.reversed),
-            count: wire.count,
+            measure: wire.measure,
             facts: Object.freeze(wire.facts.map(offendingFactOf))
         });
     }
@@ -401,7 +436,7 @@ function openDb(handle, theory, manifest) {
             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");
+            throw errors.new("keyed get takes a key() statement — containments and capacity statements 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`);
@@ -454,10 +489,11 @@ function openDb(handle, theory, manifest) {
     /**
      * 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
+     * its callback returns (or the scope's own `Symbol.dispose` does, for a
+     * `using`-acquired scope), so a leaked scope is a typed refusal forever
      * after.
      */
-    function makeScope(state, generation) {
+    function makeScope(state) {
         function assertLive() {
             if (!state.live) {
                 throw errors.new("bumbledb read scope is invalidated — its owning read callback already returned");
@@ -494,12 +530,27 @@ function openDb(handle, theory, manifest) {
             });
             return decodeAnswers(plan.finds, rows);
         }
+        function explain(prepared, params) {
+            assertLive();
+            const plan = planOf(prepared);
+            const wire = wireParams(plan.params, recordOf(params));
+            return bridged("explain bumbledb prepared query", function callExplain() {
+                return native.preparedExplain(plan.handle, state.handle, wire);
+            });
+        }
+        /** The R12 teardown: invalidate, then close — idempotent through the state's close latch. */
+        function dispose() {
+            state.live = false;
+            closeScopeState(state);
+        }
         const scope = Object.freeze({
-            generation,
+            generation: state.generation,
             scan,
             get: reads.get,
             contains: reads.contains,
-            execute
+            execute,
+            explain,
+            [Symbol.dispose]: dispose
         });
         scopeStates.set(scope, state);
         return scope;
@@ -511,47 +562,48 @@ function openDb(handle, theory, manifest) {
      * 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). */
+    /**
+     * Opens one snapshot and its scope state (live until the owner flips
+     * it). The witnessed generation rides the snapshot open itself — one
+     * crossing carries both (finding 016), so the fault-pairing close
+     * branch a second `dbGeneration` call needed is structurally gone.
+     */
     function openScopeState() {
-        const snapHandle = bridged("open bumbledb snapshot", function openSnapshot() {
+        const opened = bridged("open bumbledb snapshot", function openSnapshot() {
             return native.dbSnapshot(handle);
         });
         liveSnapshots += 1;
-        return { handle: snapHandle, live: true, owner };
+        return { handle: opened.snapshot, generation: opened.generation, live: true, closed: false, owner };
     }
-    /** Closes a scope's snapshot after the owner invalidated it. */
+    /**
+     * Closes a scope's snapshot after the owner invalidated it — a LATCH:
+     * the snapshot closes exactly once, whichever of the owning call and
+     * the scope's own `Symbol.dispose` gets there first, so an early
+     * in-callback disposal never double-closes (and never double-counts
+     * the census).
+     */
     function closeScopeState(state) {
+        if (state.closed) {
+            return;
+        }
+        state.closed = true;
         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 scope = makeScope(state);
+        if (fn === undefined) {
+            /**
+             * The `using` acquisition (R12): the caller owns the lifetime —
+             * `using snap = db.read()` — and the scope's `Symbol.dispose`
+             * is the deterministic release, scope-shaped in the language's
+             * own syntax.
+             */
+            return scope;
+        }
         const result = errors.trySync(function runRead() {
             return fn(scope);
         });
@@ -586,6 +638,11 @@ function openDb(handle, theory, manifest) {
             return snap.execute(prepared, params);
         });
     }
+    function explain(prepared, params) {
+        return read(function explainInScope(snap) {
+            return snap.explain(prepared, params);
+        });
+    }
     /**
      * Builds one {@link Tx} over a transaction-handle thunk: `write` passes
      * an already-begun handle; `writeWitnessed` passes a LAZY thunk that
@@ -618,17 +675,18 @@ function openDb(handle, theory, manifest) {
             assertLive();
             const entry = resolveOrdinary(relation);
             const txHandle = resolveTx();
-            const values = recordOf(fact);
+            /** The one spread copy of the write path: `mintFreshCells` writes minted cells in place, and they must never land in the caller's own fact object. */
+            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);
+            const changed = bridged("bumbledb tx insert", function record() {
+                return native.txInsert(txHandle, entry.id, row);
             });
-            Object.freeze(fresh);
-            if (!isMintedFresh(relation, fresh)) {
-                throw errors.new(`relation ${relation.name}: minted fresh record is incomplete`);
+            const inserted = Object.freeze({ changed, ...fresh });
+            if (!isInserted(relation, inserted)) {
+                throw errors.new(`relation ${relation.name}: insert return record is incomplete`);
             }
-            return fresh;
+            return inserted;
         }
         function remove(relation, fact) {
             assertLive();
@@ -678,6 +736,18 @@ function openDb(handle, theory, manifest) {
             });
             throw errors.new("bumbledb write callback returned a thenable — the delta build is synchronous; an async callback is refused, nothing was committed");
         }
+        if (isAbandon(built.data)) {
+            /**
+             * The caller's explicit decline to commit (R10): the sentinel's
+             * contract is unconditional — roll back, nothing committed, not
+             * even an empty commit; commit is unreachable for a sentinel
+             * result.
+             */
+            bridged("abort bumbledb write transaction", function abort() {
+                native.txAbort(txHandle);
+            });
+            return abandonedOutcome(built.data);
+        }
         const committed = errors.trySync(function commitDelta() {
             return bridged("commit bumbledb write transaction", function commit() {
                 return native.txCommit(txHandle);
@@ -708,15 +778,10 @@ function openDb(handle, theory, manifest) {
         });
     }
     function write(fn) {
-        const begun = errors.trySync(function beginDelta() {
-            return bridged("begin bumbledb write transaction", function begin() {
-                return native.dbWriteBegin(handle);
-            });
+        const txHandle = bridged(`begin bumbledb write transaction (live snapshots: ${liveSnapshots})`, 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);
+        return runDelta(txHandle, fn);
     }
     /**
      * Commits an already-begun witnessed transaction and closes the
@@ -760,8 +825,7 @@ function openDb(handle, theory, manifest) {
      */
     function witnessedAttempt(fn) {
         const state = openScopeState();
-        const generation = generationForScope(state);
-        const scope = makeScope(state, generation);
+        const scope = makeScope(state);
         const pending = { tx: undefined };
         function beginWitnessed() {
             const witnessed = bridged("begin witnessed bumbledb write transaction", function begin() {
@@ -823,7 +887,7 @@ function openDb(handle, theory, manifest) {
         if (isAbandon(built.data)) {
             abortPending();
             closeScopeState(state);
-            return Object.freeze({ ok: false, abandoned: built.data.payload });
+            return abandonedOutcome(built.data);
         }
         const late = errors.trySync(function resolveCommitTx() {
             if (pending.tx === undefined) {
@@ -867,38 +931,10 @@ function openDb(handle, theory, manifest) {
         }
         throw errors.wrap(ErrWitnessedLivelock, `writeWitnessed livelock: the generation moved on all ${WITNESSED_ATTEMPT_CAP} attempts against schema ${theory.name}`);
     }
-    /**
-     * 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 = sealedFieldsOf(member).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);
@@ -939,6 +975,7 @@ function openDb(handle, theory, manifest) {
         get,
         contains,
         execute,
+        explain,
         write,
         writeWitnessed,
         prepare
@@ -987,6 +1024,24 @@ process.once("exit", function closeCachedStores() {
  * what the types claim.
  */
 const ErrNewtypeMismatch = errors.new("bumbledb newtypeMismatch: a statement pairs faces whose newtypes disagree — the faces of a dependency agree on their newtype, or neither carries one");
+/**
+ * `Tx.insert` returns the flattened `{ changed, ...fresh }` record (R11),
+ * where the spread wins: a FRESH field literally named `changed` would
+ * shadow the engine's changed-state report on every insert of its
+ * relation. No field name is reserved SILENTLY — the one unspeakable
+ * spelling is refused here at admission, before any store is touched.
+ * Supplied (non-fresh) fields named `changed` never enter the return
+ * record and stay legal.
+ */
+function refuseShadowedChanged(theory) {
+    for (const [name, member] of Object.entries(theory.relations)) {
+        for (const declared of sealedFieldsOf(member)) {
+            if (declared.name === "changed" && isFreshField(declared.field)) {
+                throw errors.new(`relation ${name}: a fresh field named "changed" would shadow tx.insert's changed-state report in its { changed, ...fresh } return (R11) — rename the fresh field; a supplied field named "changed" stays legal (only fresh cells ride the return)`);
+            }
+        }
+    }
+}
 /**
  * The one admission path both verbs share: canonical-path cache lookup
  * first (a hit returns the SAME `Db` value for the identical theory, a
@@ -1000,6 +1055,7 @@ const ErrNewtypeMismatch = errors.new("bumbledb newtypeMismatch: a statement pai
  * the engine's message intact.
  */
 function admit(verb, storePath, theory) {
+    refuseShadowedChanged(theory);
     const canonical = path.resolve(storePath);
     const cached = openStores.get(canonical);
     if (cached !== undefined) {
@@ -1064,12 +1120,12 @@ const Db = Object.freeze({
      * 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).
+     * applied here. The value is NOT cached and is a DISPOSABLE lifetime
+     * (R12) — `using exhumed = await Db.exhume(path)` releases the engine
+     * handle and the store's exclusive lock at scope exit, so a same-path
+     * reopen never waits on GC. 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));