@bjornpagen/bumbledb 0.14.0 → 0.15.0

package/dist/db.js

@@ -2,18 +2,16 @@
  * `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, and read through scoped snapshots — all typed by
- * the schema's relations record.
+ * keyed to statements, and read through a synchronous instance callback —
+ * all typed by the schema's relations record.
  *
- * 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. 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.
+ * A store read is one callback: `db.read((instance, witness) => …)`. The
+ * instance is invalid the moment the callback returns; the witness is a
+ * cloneable token and may escape. There is no handle-shaped read and no
+ * `using snap = db.read()`. Builder, owned instance, and witness
+ * implement `Symbol.dispose`. 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
  * `Db` value owns the LMDB environment's exclusive lock until process
@@ -24,22 +22,61 @@
  * policy.
  *
  * 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, a moved generation on {@link Db.writeFrom} — throw
- * `@superbuilders/errors` wrapped errors instead.
+ * LLM repair prompt downstream), returned as a {@link WriteOutcome}
+ * carrying {@link Violation} values. A moved generation on
+ * {@link Db.writeFrom} is the `{ tag: "moved" }` arm, not an exception.
+ * Genuine failures — I/O, used-after-scope, spent handle, marshal shape —
+ * throw `@superbuilders/errors` wrapped errors instead.
  */
 import * as path from "node:path";
 import * as errors from "@superbuilders/errors";
 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, keyRowOf, recordOf, rowOf } from "#marshal.ts";
-import { bridged, native } from "#native.ts";
+import { cellOf, factOf, handleOf, isFreshField, keyRowOf, recordOf, rowOf } from "#marshal.ts";
+import { bridged, bridgedAsync, errorFromThrow, native } from "#native.ts";
 import { lowerQuery } from "#query/lower.ts";
 import { decodeAnswers, wireParams } from "#query/run.ts";
 import { isStatement } from "#statements.ts";
+function isColumnBatch(value) {
+    return !(Symbol.iterator in value);
+}
+function rowsOf(relation, facts) {
+    const rows = [];
+    for (const fact of facts) {
+        rows.push(rowOf(relation.data, recordOf(fact)));
+    }
+    return rows;
+}
+/**
+ * Lowers a column batch to per-field wire arrays in sealed field order.
+ * Allocates one array per field — never a JS array per row.
+ */
+function columnsOf(relation, batch) {
+    const record = recordOf(batch);
+    let count;
+    return relation.data.fields.map(function marshalColumn(declared) {
+        const raw = record[declared.name];
+        if (!Array.isArray(raw)) {
+            throw errors.new(`relation ${relation.name}: column ${declared.name} is not an array`);
+        }
+        if (count === undefined) {
+            count = raw.length;
+        }
+        else if (raw.length !== count) {
+            throw errors.new(`relation ${relation.name}: column ${declared.name} has length ${raw.length}, expected ${count}`);
+        }
+        return raw.map(function marshalCell(value) {
+            return cellOf(`relation ${relation.name} field ${declared.name}`, declared.field, value);
+        });
+    });
+}
+function mutateCollection(relation, facts, applyRows, applyColumns) {
+    const report = isColumnBatch(facts)
+        ? applyColumns(columnsOf(relation, facts))
+        : applyRows(rowsOf(relation, facts));
+    return Object.freeze({ submitted: report.submitted, changed: report.changed });
+}
 function freshRangeOf(wire) {
     if (wire.empty) {
         return Object.freeze({
@@ -84,7 +121,7 @@ const abandonMark = Symbol("bumbledb.abandon");
  * 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 `writeFrom`
+ * to `{ tag: "abandoned", abandoned: payload }`, from `write` and `writeFrom`
  * alike (R10).
  */
 function abandon(payload) {
@@ -112,12 +149,13 @@ function isAbandonedOutcome(outcome, sentinel) {
 }
 /** 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 });
+    const outcome = Object.freeze({ tag: "abandoned", abandoned: sentinel.payload });
     if (!isAbandonedOutcome(outcome, sentinel)) {
         throw errors.new("bumbledb abandon outcome construction incomplete");
     }
     return outcome;
 }
+const witnessTypes = Symbol("bumbledb.witness.types");
 /**
  * The module-private inference slot of {@link Prepared}: an optional symbol
  * property (never set at runtime) that keeps the prepared value's `Row` and
@@ -312,8 +350,38 @@ function tablesOf(theory, manifest) {
     });
     return Object.freeze({ relations, statements: Object.freeze(entries) });
 }
-/** The private lifetime records of this module's read scopes. */
-const scopeStates = new WeakMap();
+function tablesFromTheory(theory) {
+    const entries = materializedEntries(theory);
+    const relations = new Map();
+    Object.keys(theory.relations).forEach(function byOrdinal(name, ordinal) {
+        const member = theory.relations[name];
+        if (member === undefined) {
+            throw errors.new(`bumbledb theory has no relation ${name}`);
+        }
+        const fieldIds = new Map();
+        sealedFieldsOf(member).forEach(function byField(declared, fieldOrdinal) {
+            fieldIds.set(declared.name, fieldOrdinal);
+        });
+        let primaryKey;
+        entries.forEach(function firstOwnedKey(entry, index) {
+            if (primaryKey === undefined && entry.kind === "functionality" && entry.owner === name) {
+                primaryKey = Object.freeze({ statementId: index, projection: entry.projection });
+            }
+        });
+        relations.set(name, Object.freeze({ id: ordinal, member, fieldIds, primaryKey }));
+    });
+    return Object.freeze({ relations, statements: Object.freeze(entries) });
+}
+const instanceStates = new WeakMap();
+const witnessStates = new WeakMap();
+const witnessReclaimer = new FinalizationRegistry(function reclaimWitness(handle) {
+    const closed = errors.trySync(function closeWitness() {
+        native.witnessClose(handle);
+    });
+    if (closed.error) {
+        return;
+    }
+});
 /** The private engine halves of this module's prepared values. */
 const preparedPlans = new WeakMap();
 /**
@@ -330,12 +398,208 @@ const planReclaimer = new FinalizationRegistry(function reclaimPlan(handle) {
         return;
     }
 });
-/**
- * The typed generation-moved refusal `writeFrom` throws when a
- * state-changing commit landed since the witness snapshot: retry is host
- * policy. Match with `errors.is`.
- */
-const ErrGenerationMoved = errors.new("bumbledb generationMoved: a state-changing commit landed since the witness snapshot");
+const ErrAsyncCallback = errors.new("bumbledb asyncCallback: a read or write callback returned a thenable — the callback is synchronous");
+const ErrSpentHandle = errors.new("bumbledb spentHandle: a consumed builder, instance, or witness was used");
+const ErrUseAfterScope = errors.new("bumbledb useAfterScope: a stashed read instance or write transaction was used after its callback returned");
+const ErrForeignPrepared = errors.new("bumbledb foreignPrepared: a prepared query met a foreign instance");
+const ErrForeignWitness = errors.new("bumbledb foreignWitness: a witness met a foreign store");
+function catalogMethods(theory, tables, owner, assertLive, ops) {
+    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 (isClosedMember(relation)) {
+            throw errors.new(`relation ${relation.name} is closed — its extension is schema data (axioms), never scanned or written`);
+        }
+        return entry;
+    }
+    function declaredKeyOf(relation, statement) {
+        const statementId = tables.statements.findIndex(function byIdentity(candidate) {
+            return "statement" in candidate && 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") {
+            throw errors.new("keyed get takes a key() statement — containments and capacity statements key nothing");
+        }
+        if (entry.owner !== relation.name) {
+            throw errors.new(`keyed get statement keys ${entry.owner}, not ${relation.name} — the statement must be a declared key of the relation it reads`);
+        }
+        return Object.freeze({ statementId, projection: entry.projection });
+    }
+    function planOf(prepared) {
+        const plan = preparedPlans.get(prepared);
+        if (plan === undefined) {
+            throw errors.wrap(ErrForeignPrepared, "bumbledb execute target is not a prepared value of this SDK");
+        }
+        if (plan.owner !== owner) {
+            throw errors.wrap(ErrForeignPrepared, `bumbledb prepared value was prepared by a different store than this one (schema ${theory.name})`);
+        }
+        return plan;
+    }
+    function contains(relation, fact) {
+        assertLive();
+        const entry = resolveOrdinary(relation);
+        return bridged("bumbledb instance contains", function readContains() {
+            return ops.contains(entry.id, rowOf(relation.data, recordOf(fact)));
+        });
+    }
+    function get(relation, keyOrStatement, declaredKey) {
+        assertLive();
+        const entry = resolveOrdinary(relation);
+        return selectKeyRead(keyOrStatement, declaredKey, function byStatement(statement, key) {
+            const selected = declaredKeyOf(relation, statement);
+            const row = bridged("bumbledb instance get", function readGet() {
+                return ops.get(entry.id, selected.statementId, keyRowOf(relation.data, selected.projection, recordOf(key)));
+            });
+            return row === null ? undefined : factOf(relation, row);
+        }, function byPrimary(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`);
+            }
+            const row = bridged("bumbledb instance get", function readGet() {
+                return ops.get(entry.id, primaryKey.statementId, keyRowOf(relation.data, primaryKey.projection, recordOf(key)));
+            });
+            return row === null ? undefined : factOf(relation, row);
+        });
+    }
+    function scan(relation) {
+        assertLive();
+        const entry = resolveOrdinary(relation);
+        const rows = bridged("bumbledb instance scan", function readScan() {
+            return ops.scan(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 ops.execute(plan.handle, wire);
+        });
+        return decodeAnswers(plan.finds, rows);
+    }
+    function prepare(q) {
+        assertLive();
+        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`);
+        }
+        const queryIr = lowerQuery(q);
+        const outcome = bridged("prepare bumbledb query", function callPrepare() {
+            return ops.prepare(queryIr);
+        });
+        if (!outcome.ok) {
+            throwPrepareRefusal(outcome.message);
+        }
+        const prepared = Object.freeze({});
+        preparedPlans.set(prepared, Object.freeze({
+            handle: outcome.prepared,
+            owner,
+            params: q.data.params,
+            finds: q.data.finds
+        }));
+        planReclaimer.register(prepared, outcome.prepared);
+        return prepared;
+    }
+    return { scan, get, contains, execute, prepare };
+}
+function ordinaryEntry(tables, theory, 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 (isClosedMember(relation)) {
+        throw errors.new(`relation ${relation.name} is closed — its extension is schema data (axioms), never scanned or written`);
+    }
+    return entry;
+}
+function overlayMethods(theory, tables, assertLive, reads) {
+    function declaredKeyOf(relation, statement) {
+        const statementId = tables.statements.findIndex(function byIdentity(candidate) {
+            return "statement" in candidate && 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") {
+            throw errors.new("keyed get takes a key() statement — containments and capacity statements key nothing");
+        }
+        if (entry.owner !== relation.name) {
+            throw errors.new(`keyed get statement keys ${entry.owner}, not ${relation.name} — the statement must be a declared key of the relation it reads`);
+        }
+        return Object.freeze({ statementId, projection: entry.projection });
+    }
+    function contains(relation, fact) {
+        assertLive();
+        const entry = ordinaryEntry(tables, theory, relation);
+        return reads.contains(entry.id, rowOf(relation.data, recordOf(fact)));
+    }
+    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 = ordinaryEntry(tables, theory, relation);
+        return selectKeyRead(keyOrStatement, declaredKey, function byStatement(statement, key) {
+            return readThroughKey(relation, entry, declaredKeyOf(relation, statement), recordOf(key));
+        }, function byPrimary(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(key));
+        });
+    }
+    return { contains, get };
+}
+function createReadInstance(nativeHandle, theory, tables, owner) {
+    const state = { handle: nativeHandle, live: true, owner };
+    function assertLive() {
+        if (!state.live) {
+            throw errors.wrap(ErrUseAfterScope, "bumbledb read instance is invalidated — its owning callback already returned");
+        }
+    }
+    const methods = catalogMethods(theory, tables, owner, assertLive, {
+        scan(relationId) {
+            return native.instanceScan(state.handle, relationId);
+        },
+        contains(relationId, values) {
+            return native.instanceContains(state.handle, relationId, values);
+        },
+        get(relationId, statementId, keyValues) {
+            return native.instanceGet(state.handle, relationId, statementId, keyValues);
+        },
+        prepare(query) {
+            return native.instancePrepare(state.handle, query);
+        },
+        execute(prepared, params) {
+            return native.preparedExecute(prepared, state.handle, params);
+        }
+    });
+    const instance = Object.freeze({
+        get generation() {
+            assertLive();
+            return bridged("bumbledb instance generation", function readGeneration() {
+                return native.instanceGeneration(state.handle);
+            });
+        },
+        ...methods
+    });
+    instanceStates.set(instance, state);
+    return instance;
+}
 /**
  * Constructs one open `Db` over an already-admitted handle: builds the
  * id-resolution tables once and closes over them — the `Db` owns handle
@@ -476,172 +740,88 @@ function openDb(handle, theory, manifest) {
         }
         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;
+    function pinPrepared(preparedHandle, q) {
+        const prepared = Object.freeze({});
+        preparedPlans.set(prepared, Object.freeze({
+            handle: preparedHandle,
+            owner,
+            params: q.data.params,
+            finds: q.data.finds
+        }));
+        planReclaimer.register(prepared, preparedHandle);
+        return prepared;
     }
-    /**
-     * 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 (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) {
-        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 makeWitness(nativeHandle) {
+        const state = { handle: nativeHandle, spent: false, owner };
+        const witness = Object.freeze({
+            [Symbol.dispose]() {
+                if (state.spent) {
+                    return;
+                }
+                state.spent = true;
+                bridged("close bumbledb witness", function closeWitness() {
+                    native.witnessClose(nativeHandle);
                 });
             }
         });
-        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.finds, rows);
-        }
-        /** 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: state.generation,
-            scan,
-            get: reads.get,
-            contains: reads.contains,
-            execute,
-            [Symbol.dispose]: dispose
-        });
-        scopeStates.set(scope, state);
-        return scope;
+        witnessStates.set(witness, state);
+        witnessReclaimer.register(witness, nativeHandle);
+        return witness;
     }
-    /**
-     * 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). 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 opened = bridged("open bumbledb snapshot", function openSnapshot() {
-            return native.dbSnapshot(handle);
-        });
-        liveSnapshots += 1;
-        return { handle: opened.snapshot, generation: opened.generation, live: true, closed: false, owner };
+    function makeInstance(nativeHandle) {
+        return createReadInstance(nativeHandle, theory, tables, owner);
     }
-    /**
-     * 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;
-    }
-    function read(fn) {
-        const state = openScopeState();
-        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);
-        });
-        state.live = false;
-        closeScopeState(state);
-        if (result.error) {
-            throw errors.wrap(result.error, "bumbledb read");
-        }
-        return result.data;
+    function read(body) {
+        let captured;
+        const result = bridged("bumbledb read", function runRead() {
+            return native.dbRead(handle, function onRead(nativeInstance, nativeWitness) {
+                const instance = makeInstance(nativeInstance);
+                const witness = makeWitness(nativeWitness);
+                const value = body(instance, witness);
+                const state = instanceStates.get(instance);
+                if (state !== undefined) {
+                    state.live = false;
+                }
+                if (isThenable(value)) {
+                    throw errors.wrap(ErrAsyncCallback, "bumbledb read callback returned a thenable");
+                }
+                captured = value;
+                return value;
+            });
+        });
+        return (captured ?? result);
     }
     function scan(relation) {
-        return read(function scanInScope(snap) {
-            return snap.scan(relation);
+        return read(function scanInScope(instance) {
+            return instance.scan(relation);
         });
     }
     function get(relation, keyOrStatement, declaredKey) {
-        return read(function getInScope(snap) {
-            return selectKeyRead(keyOrStatement, declaredKey, function byStatement(statement, key) {
-                return snap.get(relation, statement, key);
+        let found;
+        read(function getInScope(instance) {
+            found = selectKeyRead(keyOrStatement, declaredKey, function byStatement(statement, key) {
+                return instance.get(relation, statement, key);
             }, function byPrimary(key) {
-                return snap.get(relation, key);
+                return instance.get(relation, key);
             });
         });
+        return found;
     }
     function contains(relation, fact) {
-        return read(function containsInScope(snap) {
-            return snap.contains(relation, fact);
+        return read(function containsInScope(instance) {
+            return instance.contains(relation, fact);
         });
     }
     function execute(prepared, params) {
-        return read(function executeInScope(snap) {
-            return snap.execute(prepared, params);
+        return read(function executeInScope(instance) {
+            return instance.execute(prepared, params);
         });
     }
-    /**
-     * Builds one {@link Tx} over a transaction-handle thunk: `write` and
-     * `writeFrom` pass an already-begun handle.
-     */
     function makeTx(resolveTx) {
         const txState = { spent: false };
         function assertLive() {
             if (txState.spent) {
-                throw errors.new("bumbledb write transaction is spent");
+                throw errors.wrap(ErrUseAfterScope, "bumbledb write transaction is spent");
             }
         }
         const reads = pointReadsOf(assertLive, {
@@ -660,27 +840,24 @@ function openDb(handle, theory, manifest) {
         });
         function insert(relation, facts) {
             assertLive();
-            const rows = [];
-            for (const fact of facts) {
-                rows.push(rowOf(relation.data, recordOf(fact)));
-            }
             const entry = resolveOrdinary(relation);
             const txHandle = resolveTx();
-            const report = bridged("bumbledb tx insert", function record() {
-                return native.txInsert(txHandle, entry.id, rows);
+            return mutateCollection(relation, facts, function applyRows(rows) {
+                return bridged("bumbledb tx insert", function record() {
+                    return native.txInsert(txHandle, entry.id, rows);
+                });
+            }, function applyColumns(columns) {
+                return bridged("bumbledb tx insert", function recordColumns() {
+                    return native.txInsertColumns(txHandle, entry.id, columns);
+                });
             });
-            return Object.freeze({ submitted: report.submitted, changed: report.changed });
         }
         function remove(relation, facts) {
             assertLive();
-            const rows = [];
-            for (const fact of facts) {
-                rows.push(rowOf(relation.data, recordOf(fact)));
-            }
             const entry = resolveOrdinary(relation);
             const txHandle = resolveTx();
             const report = bridged("bumbledb tx delete", function record() {
-                return native.txDelete(txHandle, entry.id, rows);
+                return native.txDelete(txHandle, entry.id, rowsOf(relation, facts));
             });
             return Object.freeze({ submitted: report.submitted, changed: report.changed });
         }
@@ -715,104 +892,80 @@ function openDb(handle, theory, manifest) {
         }
         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");
-        }
-        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);
+    function mapNativeWrite(nativeOutcome, built) {
+        if (nativeOutcome.tag === "moved") {
+            return Object.freeze({
+                tag: "moved",
+                witnessed: nativeOutcome.witnessed,
+                current: nativeOutcome.current
             });
-            return abandonedOutcome(built.data);
         }
-        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 (nativeOutcome.tag === "rejected") {
+            return Object.freeze({
+                tag: "rejected",
+                violations: Object.freeze(nativeOutcome.violations.map(violationOf))
             });
-            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 });
+        if (nativeOutcome.tag === "abandoned") {
+            if (built === undefined || !isAbandon(built)) {
+                throw errors.new("bumbledb write abandoned without an abandon sentinel");
+            }
+            return abandonedOutcome(built);
         }
         return Object.freeze({
-            ok: false,
-            violations: Object.freeze(outcome.violations.map(violationOf))
+            tag: "accepted",
+            value: Object.freeze({
+                value: built,
+                generation: nativeOutcome.generation
+            })
         });
     }
-    function write(fn) {
-        const txHandle = bridged(`begin bumbledb write transaction (live snapshots: ${liveSnapshots})`, function begin() {
-            return native.dbWriteBegin(handle);
+    function runWrite(invoke, fn) {
+        let built;
+        const nativeOutcome = bridged("bumbledb write", function callWrite() {
+            return invoke(function onWrite(txHandle) {
+                const made = makeTx(function resolveTx() {
+                    return txHandle;
+                });
+                const result = errors.trySync(function buildDelta() {
+                    return fn(made.tx);
+                });
+                made.spend();
+                if (result.error) {
+                    throw errors.wrap(result.error, "build write delta");
+                }
+                if (isThenable(result.data)) {
+                    throw errors.wrap(ErrAsyncCallback, "bumbledb write callback returned a thenable");
+                }
+                built = result.data;
+                return !isAbandon(result.data);
+            });
         });
-        return runDelta(txHandle, fn);
+        return mapNativeWrite(nativeOutcome, built);
     }
-    /**
-     * One-shot write from a live snapshot this store owns. Begins immediately;
-     * a moved generation throws {@link ErrGenerationMoved} and `fn` never
-     * runs. The snapshot stays owned by the caller's read callback.
-     */
-    function writeFrom(snap, fn) {
-        const snapState = scopeStates.get(snap);
-        if (snapState === undefined) {
-            throw errors.new("bumbledb writeFrom witness is not a read scope of this SDK");
+    function write(fn) {
+        const outcome = runWrite(function invoke(callback) {
+            return native.dbWrite(handle, callback);
+        }, fn);
+        if (outcome.tag === "moved") {
+            throw errors.new("bumbledb write reported moved — unconditional writes cannot move");
         }
-        if (snapState.owner !== owner) {
-            throw errors.new(`bumbledb writeFrom snapshot belongs to a different store (schema ${theory.name})`);
+        return outcome;
+    }
+    function writeFrom(witness, fn) {
+        const state = witnessStates.get(witness);
+        if (state === undefined) {
+            throw errors.wrap(ErrForeignWitness, "bumbledb writeFrom witness is not a witness of this SDK");
         }
-        if (!snapState.live) {
-            throw errors.new("bumbledb writeFrom snapshot is invalidated — its owning read callback already returned");
+        if (state.owner !== owner) {
+            throw errors.wrap(ErrForeignWitness, `bumbledb writeFrom witness belongs to a different store (schema ${theory.name})`);
         }
-        const witnessed = bridged("begin witnessed bumbledb write transaction", function begin() {
-            return native.dbWriteFrom(handle, snapState.handle);
-        });
-        if (!witnessed.ok) {
-            throw errors.wrap(ErrGenerationMoved, `writeFrom: generation moved (witnessed ${witnessed.witnessed} current ${witnessed.current}) against schema ${theory.name}`);
+        if (state.spent) {
+            throw errors.wrap(ErrSpentHandle, "bumbledb writeFrom witness has been disposed");
         }
-        return runDelta(witnessed.tx, fn);
+        return runWrite(function invoke(callback) {
+            return native.dbWriteFrom(handle, state.handle, callback);
+        }, fn);
     }
     function prepare(q) {
         if (q.schema !== theory) {
@@ -823,18 +976,9 @@ function openDb(handle, theory, manifest) {
             return native.dbPrepare(handle, queryIr);
         });
         if (!outcome.ok) {
-            throw errors.new(`bumbledb ${outcome.kind} (prepare): ${outcome.message}`);
+            throwPrepareRefusal(outcome.message);
         }
-        const preparedHandle = outcome.prepared;
-        const prepared = Object.freeze({});
-        preparedPlans.set(prepared, Object.freeze({
-            handle: preparedHandle,
-            owner,
-            params: q.data.params,
-            finds: q.data.finds
-        }));
-        planReclaimer.register(prepared, preparedHandle);
-        return prepared;
+        return pinPrepared(outcome.prepared, q);
     }
     return Object.freeze({
         schema: theory,
@@ -859,78 +1003,340 @@ function openDb(handle, theory, manifest) {
  * 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");
-/**
- * The one admission path both verbs share: lower the theory, run one
- * bridge call, and wrap the domain refusals — `schemaError` (spec
- * resolution + schema validation, every issue in one message),
- * `newtypeMismatch` (the coherence wall, {@link ErrNewtypeMismatch}),
- * and `fingerprintMismatch` (a different theory cannot open the store)
- * — into typed errors carrying the engine's message intact.
- * Environment failures (a second live writer on the same path, IO)
- * throw from the bridge; the engine's `EnvironmentLocked` message is
- * "another live handle holds this environment's lock".
- */
-function admit(verb, storePath, theory) {
+const ErrSchemaError = errors.new("bumbledb schemaError: the declaration failed validation");
+const ErrFingerprintMismatch = errors.new("bumbledb fingerprintMismatch: the store's schema does not match this theory");
+const ErrIrError = errors.new("bumbledb irError: the query failed validation");
+function throwOpenRefusal(verb, canonical, kind, message) {
+    const detail = `${verb} ${canonical}: ${message}`;
+    if (kind === "newtypeMismatch") {
+        throw errors.wrap(ErrNewtypeMismatch, detail);
+    }
+    if (kind === "schemaError") {
+        throw errors.wrap(ErrSchemaError, detail);
+    }
+    throw errors.wrap(ErrFingerprintMismatch, detail);
+}
+function throwPrepareRefusal(message) {
+    throw errors.wrap(ErrIrError, `prepare: ${message}`);
+}
+function openFromHandle(dbHandle, theory) {
+    const manifest = bridged("fetch bumbledb manifest", function fetchManifest() {
+        return native.dbManifest(dbHandle);
+    });
+    return openDb(dbHandle, theory, manifest);
+}
+async function createStore(storePath, theory) {
     const canonical = path.resolve(storePath);
     const spec = lower(theory);
-    const opened = bridged(`${verb} bumbledb store at ${canonical}`, function callBridge() {
-        if (verb === "create") {
-            return native.dbCreate(canonical, spec);
+    const created = await bridgedAsync(`create bumbledb store at ${canonical}`, function callBridge() {
+        return native.dbCreate(canonical, spec);
+    });
+    if (created.tag === "schemaError" || created.tag === "newtypeMismatch") {
+        throwOpenRefusal("create", canonical, created.tag, created.message);
+    }
+    if (created.tag === "rejected") {
+        return Object.freeze({
+            tag: "rejected",
+            violations: Object.freeze(created.violations.map(function mapWire(wire) {
+                return mapViolationWithoutStore(theory, wire);
+            }))
+        });
+    }
+    return Object.freeze({ tag: "accepted", value: openFromHandle(created.db, theory) });
+}
+function mapViolationWithoutStore(theory, wire) {
+    const entries = materializedEntries(theory);
+    const entry = entries[wire.statementId];
+    if (entry === undefined) {
+        throw errors.new(`bumbledb violation cites unknown statement id ${wire.statementId}`);
+    }
+    function offending(fact) {
+        const member = theory.relations[fact.relation];
+        if (member === undefined || !(fact.relation in theory.relations)) {
+            throw errors.new(`bumbledb violation cites unknown relation ${fact.relation}`);
         }
+        const declared = sealedFieldsOf(member);
+        const decoded = {};
+        for (const cell of fact.fields) {
+            const cited = declared.find(function byName(candidate) {
+                return candidate.name === cell.name;
+            });
+            const roster = rosterOf(cited?.field);
+            decoded[cell.name] =
+                roster !== undefined
+                    ? handleOf(`violation fact ${fact.relation} field ${cell.name}`, roster, cell.value)
+                    : cell.value;
+        }
+        return Object.freeze({ relation: fact.relation, fact: Object.freeze(decoded) });
+    }
+    const facts = Object.freeze(wire.facts.map(offending));
+    const canonical = wire.canonical;
+    if (entry.kind === "functionality") {
+        if (!("statement" in entry)) {
+            return Object.freeze({ kind: "functionality", statement: undefined, canonical, facts });
+        }
+        return Object.freeze({ kind: "functionality", statement: entry.statement, canonical, facts });
+    }
+    if (entry.kind === "capacity") {
+        if (wire.kind !== "capacity") {
+            throw errors.new(`bumbledb violation ${wire.statementId} is a capacity slot without a measure`);
+        }
+        return Object.freeze({
+            kind: "capacity",
+            statement: entry.statement,
+            canonical,
+            measure: wire.measure,
+            facts
+        });
+    }
+    if (wire.kind !== "containment") {
+        throw errors.new(`bumbledb violation ${wire.statementId} is a containment slot without a direction`);
+    }
+    if (entry.kind === "mirrors") {
+        return Object.freeze({
+            kind: "containment",
+            statement: entry.statement,
+            canonical,
+            direction: wire.direction,
+            orientation: entry.orientation,
+            facts
+        });
+    }
+    return Object.freeze({
+        kind: "containment",
+        statement: entry.statement,
+        canonical,
+        direction: wire.direction,
+        facts
+    });
+}
+async function openStore(storePath, theory) {
+    const canonical = path.resolve(storePath);
+    const spec = lower(theory);
+    const opened = await bridgedAsync(`open bumbledb store at ${canonical}`, function callBridge() {
         return native.dbOpen(canonical, spec);
     });
     if (!opened.ok) {
-        if (opened.kind === "newtypeMismatch") {
-            throw errors.wrap(ErrNewtypeMismatch, `${verb} ${canonical}: ${opened.message}`);
+        throwOpenRefusal("open", canonical, opened.kind, opened.message);
+    }
+    return openFromHandle(opened.db, theory);
+}
+const ownedRecords = new WeakMap();
+const builderRecords = new WeakMap();
+const ownedReclaimer = new FinalizationRegistry(function reclaimOwned(handle) {
+    const closed = errors.trySync(function closeOwned() {
+        native.ownedInstanceClose(handle);
+    });
+    if (closed.error) {
+        return;
+    }
+});
+const builderReclaimer = new FinalizationRegistry(function reclaimBuilder(handle) {
+    const closed = errors.trySync(function closeBuilder() {
+        native.instanceBuilderClose(handle);
+    });
+    if (closed.error) {
+        return;
+    }
+});
+function wrapOwned(nativeHandle, theory) {
+    const owner = Object.freeze({});
+    const rec = { handle: nativeHandle, theory, spent: false, owner };
+    const tables = tablesFromTheory(theory);
+    function assertLive() {
+        if (rec.spent) {
+            throw errors.wrap(ErrSpentHandle, "bumbledb owned instance has been disposed");
         }
-        throw errors.new(`bumbledb ${opened.kind} (${verb} ${canonical}): ${opened.message}`);
     }
-    const manifest = bridged("fetch bumbledb manifest", function fetchManifest() {
-        return native.dbManifest(opened.db);
+    const methods = catalogMethods(theory, tables, owner, assertLive, {
+        scan(relationId) {
+            return native.ownedScan(nativeHandle, relationId);
+        },
+        contains(relationId, values) {
+            return native.ownedContains(nativeHandle, relationId, values);
+        },
+        get(relationId, statementId, keyValues) {
+            return native.ownedGet(nativeHandle, relationId, statementId, keyValues);
+        },
+        prepare(query) {
+            return native.ownedPrepare(nativeHandle, query);
+        },
+        execute(prepared, params) {
+            return native.ownedExecute(prepared, nativeHandle, params);
+        }
+    });
+    const instance = Object.freeze({
+        ...methods,
+        [Symbol.dispose]() {
+            if (rec.spent) {
+                return;
+            }
+            try {
+                native.ownedInstanceClose(nativeHandle);
+            }
+            catch (caught) {
+                const error = errorFromThrow(caught);
+                if (/leased for publish/.test(error.message)) {
+                    throw errors.wrap(ErrSpentHandle, "bumbledb owned instance is leased for publish");
+                }
+                throw errors.wrap(error, "close bumbledb owned instance");
+            }
+            rec.spent = true;
+            ownedReclaimer.unregister(instance);
+        }
+    });
+    ownedRecords.set(instance, rec);
+    ownedReclaimer.register(instance, nativeHandle, instance);
+    return instance;
+}
+function wrapBuilder(nativeHandle, theory) {
+    const rec = { handle: nativeHandle, theory, spent: false };
+    const tables = tablesFromTheory(theory);
+    function assertLive() {
+        if (rec.spent) {
+            throw errors.wrap(ErrSpentHandle, "bumbledb instance builder has been spent");
+        }
+    }
+    const overlay = overlayMethods(theory, tables, assertLive, {
+        contains(relationId, row) {
+            return bridged("bumbledb builder contains", function readContains() {
+                return native.instanceBuilderContains(nativeHandle, relationId, row);
+            });
+        },
+        get(relationId, statementId, key) {
+            return bridged("bumbledb builder get", function readGet() {
+                return native.instanceBuilderGet(nativeHandle, relationId, statementId, key);
+            });
+        }
     });
-    return openDb(opened.db, theory, manifest);
+    const builder = Object.freeze({
+        load(relation, facts) {
+            assertLive();
+            const entry = ordinaryEntry(tables, theory, relation);
+            return mutateCollection(relation, facts, function applyRows(rows) {
+                return bridged("bumbledb builder load", function loadRows() {
+                    return native.instanceBuilderLoad(nativeHandle, entry.id, rows);
+                });
+            }, function applyColumns(columns) {
+                return bridged("bumbledb builder load", function loadColumns() {
+                    return native.instanceBuilderLoadColumns(nativeHandle, entry.id, columns);
+                });
+            });
+        },
+        delete(relation, facts) {
+            assertLive();
+            const entry = ordinaryEntry(tables, theory, relation);
+            const report = bridged("bumbledb builder delete", function remove() {
+                return native.instanceBuilderDelete(nativeHandle, entry.id, rowsOf(relation, facts));
+            });
+            return Object.freeze({ submitted: report.submitted, changed: report.changed });
+        },
+        reserve(relation, field, count) {
+            assertLive();
+            const entry = ordinaryEntry(tables, theory, relation);
+            const declared = relation.data.fields.find(function byName(candidate) {
+                return candidate.name === field;
+            });
+            if (declared === undefined || !isFreshField(declared.field)) {
+                throw errors.new(`relation ${relation.name}: field ${field} is not a fresh cell`);
+            }
+            const fieldId = entry.fieldIds.get(field);
+            if (fieldId === undefined) {
+                throw errors.new(`bumbledb manifest drift: relation ${relation.name} has no field id for ${field}`);
+            }
+            const range = bridged("bumbledb builder reserve", function mint() {
+                return native.instanceBuilderReserve(nativeHandle, entry.id, fieldId, count);
+            });
+            return freshRangeOf(range);
+        },
+        contains: overlay.contains,
+        get: overlay.get,
+        async admit() {
+            if (rec.spent) {
+                throw errors.wrap(ErrSpentHandle, "bumbledb instance builder has been spent");
+            }
+            rec.spent = true;
+            builderReclaimer.unregister(builder);
+            let outcome;
+            try {
+                outcome = await native.instanceBuilderAdmit(nativeHandle);
+            }
+            catch (caught) {
+                throw errors.wrap(errorFromThrow(caught), "admit bumbledb instance");
+            }
+            if (outcome.tag === "rejected") {
+                return Object.freeze({
+                    tag: "rejected",
+                    violations: Object.freeze(outcome.violations.map(function mapWire(wire) {
+                        return mapViolationWithoutStore(theory, wire);
+                    }))
+                });
+            }
+            return Object.freeze({
+                tag: "accepted",
+                value: wrapOwned(outcome.value, theory)
+            });
+        },
+        [Symbol.dispose]() {
+            if (rec.spent) {
+                return;
+            }
+            rec.spent = true;
+            builderReclaimer.unregister(builder);
+            bridged("close bumbledb instance builder", function closeBuilder() {
+                native.instanceBuilderClose(nativeHandle);
+            });
+        }
+    });
+    builderRecords.set(builder, rec);
+    builderReclaimer.register(builder, nativeHandle, builder);
+    return builder;
 }
+const InstanceBuilder = Object.freeze({
+    create(theory) {
+        const spec = lower(theory);
+        const handle = bridged("create bumbledb instance builder", function make() {
+            return native.instanceBuilderNew(spec);
+        });
+        return wrapBuilder(handle, theory);
+    }
+});
 /**
  * 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. A second live handle
- * on the same path is the engine's `EnvironmentLocked`. There is no close
- * anywhere: the process owns the environment until GC/exit (durability is
- * the engine's per-commit fsync). One store kind exists: durable —
- * resume = reopen in a fresh process, or hold the `Db` this process opened.
+ * version and the schema fingerprint. A second live handle on the same
+ * path is the engine's `EnvironmentLocked`. There is no close anywhere:
+ * the process owns the environment until GC/exit (durability is the
+ * engine's per-commit fsync). Resume = reopen in a fresh process, or
+ * hold the `Db` this process opened.
  */
 const Db = Object.freeze({
     /** Creates a fresh durable store at `path` from the schema. */
-    async create(path, theory) {
-        return admit("create", path, theory);
+    async create(storePath, theory) {
+        return createStore(storePath, theory);
     },
     /**
      * Opens an existing durable store at `path` with the same theory.
-     * 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. A second open of a still-live path is
-     * `EnvironmentLocked`.
+     * Format 8 open never back-fills a descriptor. A second open of a
+     * still-live path is `EnvironmentLocked`.
      */
-    async open(path, theory) {
-        return admit("open", path, theory);
+    async open(storePath, theory) {
+        return openStore(storePath, 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 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));
+    async fromInstance(storePath, instance) {
+        const rec = ownedRecords.get(instance);
+        if (rec === undefined) {
+            throw errors.wrap(ErrSpentHandle, "bumbledb fromInstance target is not an owned instance of this SDK");
+        }
+        if (rec.spent) {
+            throw errors.wrap(ErrSpentHandle, "bumbledb fromInstance target has been disposed");
+        }
+        const canonical = path.resolve(storePath);
+        const dbHandle = await bridgedAsync(`publish bumbledb instance at ${canonical}`, function publish() {
+            return native.dbFromInstance(canonical, rec.handle);
+        });
+        return openFromHandle(dbHandle, rec.theory);
     }
 });
-export { abandon, Db, ErrGenerationMoved, ErrNewtypeMismatch };
+export { abandon, Db, ErrAsyncCallback, ErrForeignPrepared, ErrForeignWitness, ErrFingerprintMismatch, ErrIrError, ErrNewtypeMismatch, ErrSchemaError, ErrSpentHandle, ErrUseAfterScope, InstanceBuilder };
 //# sourceMappingURL=db.js.map