@bjornpagen/bumbledb 0.14.0 → 0.17.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,56 @@
  * 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";
+/**
+ * The flat projector: every fact's cells land in ONE row-major
+ * `FactValue` array (length rows×arity) — no JS array per fact exists
+ * anywhere between the caller's objects and the native crossing
+ * (proposals/one-representation/20, V1) — and the row count is counted
+ * while projecting (the {@link FlatCollection} law: the stated count is
+ * what the bridge verifies against `rows × arity`, exactly, for every
+ * arity). The per-cell judgment is `cellOf` — the one cell judge `rowOf`
+ * also speaks (closed handle→id, well-formedness, interval shape) — and
+ * the missing-field refusal is `rowOf`'s, byte for byte; only the output
+ * form differs (flat, never per-row).
+ */
+function rowsOf(relation, facts) {
+    const data = relation.data;
+    const cells = [];
+    let rows = 0n;
+    for (const fact of facts) {
+        rows += 1n;
+        const record = recordOf(fact);
+        for (const declared of data.fields) {
+            const value = record[declared.name];
+            if (value === undefined) {
+                throw errors.new(`relation ${data.name}: fact is missing field ${declared.name}`);
+            }
+            cells.push(cellOf(`relation ${data.name} field ${declared.name}`, declared.field, value));
+        }
+    }
+    return { rows, cells };
+}
+function mutateCollection(relation, facts, apply) {
+    const flat = rowsOf(relation, facts);
+    const report = apply(flat.rows, flat.cells);
+    return Object.freeze({ submitted: report.submitted, changed: report.changed });
+}
 function freshRangeOf(wire) {
     if (wire.empty) {
         return Object.freeze({
@@ -74,70 +106,81 @@ function freshRangeOf(wire) {
         }
     });
 }
-/**
- * The runtime discriminant of {@link Abandon} values — a property probe is
- * how `write`/`writeFrom` distinguish "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 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`
- * alike (R10).
- */
 function abandon(payload) {
     return Object.freeze({ [abandonMark]: true, payload });
 }
-/**
- * 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 });
+    const outcome = Object.freeze({ tag: "abandoned", 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
- * `Params` type arguments load-bearing, so `execute` infers the typed rows
- * and the typed params object from the value alone — the query module's
- * `inferred` pattern, local to this module. A type-level carrier only:
- * values stay bare, nothing is asserted.
- */
+const witnessTypes = Symbol("bumbledb.witness.types");
 const preparedTypes = Symbol("bumbledb.prepared.types");
-/**
- * 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 decodeOffendingFact(member, relation, fact) {
+    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: Object.freeze(decoded) });
+}
+function violationFromEntry(entry, wire, facts) {
+    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
+    });
+}
 function materializedEntries(theory) {
     const entries = impliedKeyEntries(theory);
     for (const statement of theory.statements) {
@@ -145,13 +188,6 @@ function materializedEntries(theory) {
     }
     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)) {
@@ -179,12 +215,6 @@ function impliedKeyEntries(theory) {
     }
     return entries;
 }
-/**
- * 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;
     switch (data.kind) {
@@ -221,26 +251,9 @@ function declaredEntries(statement) {
 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) 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) {
     return isStatement(value);
 }
-/**
- * THE one selector dispatch of the `get` overload pair (primary-key vs
- * key-statement, `docs/architecture/70-api.md` § the freeze): judges the
- * middle argument once and hands the narrowed pieces to the chosen
- * continuation. `Db.get` and the read scope's `get` both dispatch through
- * here, so the two mismatch refusals speak with one voice and the symmetry
- * rule (`db.get(...) === db.read(snap => snap.get(...))`) holds by
- * construction.
- */
 function selectKeyRead(keyOrStatement, declaredKey, byStatement, byPrimary) {
     if (declaredKey !== undefined) {
         if (!isStatementValue(keyOrStatement)) {
@@ -253,16 +266,6 @@ function selectKeyRead(keyOrStatement, declaredKey, byStatement, byPrimary) {
     }
     return byPrimary(keyOrStatement);
 }
-/**
- * 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. 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);
     if (entries.length !== manifest.statements.length) {
@@ -312,16 +315,39 @@ 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();
-/** The private engine halves of this module's prepared values. */
+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;
+    }
+});
 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);
@@ -330,130 +356,219 @@ 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");
-/**
- * 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}`);
+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 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 (isClosedMember(relation)) {
-            throw errors.new(`relation ${relation.name} is closed — its extension is schema data (axioms), never scanned or written`);
+        if (plan.owner !== owner) {
+            throw errors.wrap(ErrForeignPrepared, `bumbledb prepared value was prepared by a different store than this one (schema ${theory.name})`);
         }
-        return entry;
+        return plan;
     }
-    function offendingFactOf(fact) {
-        const entry = tables.relations.get(fact.relation);
-        if (entry === undefined || !isMemberName(fact.relation)) {
-            throw errors.new(`bumbledb violation cites unknown relation ${fact.relation}`);
-        }
-        const declared = sealedFieldsOf(entry.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) });
+    function contains(relation, fact) {
+        assertLive();
+        const entry = ordinaryEntry(tables, theory, relation);
+        return bridged("bumbledb instance contains", function readContains() {
+            return ops.contains(entry.id, rowOf(relation.data, recordOf(fact)));
+        });
     }
-    function violationOf(wire) {
-        const entry = tables.statements[wire.statementId];
-        if (entry === undefined) {
-            throw errors.new(`bumbledb violation cites unknown statement id ${wire.statementId}`);
-        }
-        const facts = Object.freeze(wire.facts.map(offendingFactOf));
-        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`);
+    function get(relation, keyOrStatement, declaredKey) {
+        assertLive();
+        const entry = ordinaryEntry(tables, theory, relation);
+        return selectKeyRead(keyOrStatement, declaredKey, function byStatement(statement, key) {
+            const selected = declaredKeyOf(tables, theory, 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`);
             }
-            return Object.freeze({
-                kind: "capacity",
-                statement: entry.statement,
-                canonical,
-                measure: wire.measure,
-                facts
+            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 = ordinaryEntry(tables, theory, 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 count(relation) {
+        assertLive();
+        const entry = ordinaryEntry(tables, theory, relation);
+        return bridged("bumbledb instance count", function readCount() {
+            return ops.count(entry.id);
+        });
+    }
+    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`);
         }
-        if (wire.kind !== "containment") {
-            throw errors.new(`bumbledb violation ${wire.statementId} is a containment slot without a direction`);
+        const queryIr = lowerQuery(q);
+        const outcome = bridged("prepare bumbledb query", function callPrepare() {
+            return ops.prepare(queryIr);
+        });
+        if (!outcome.ok) {
+            throwPrepareRefusal(outcome.message);
         }
-        if (entry.kind === "mirrors") {
-            return Object.freeze({
-                kind: "containment",
-                statement: entry.statement,
-                canonical,
-                direction: wire.direction,
-                orientation: entry.orientation,
-                facts
-            });
+        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, count, 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 declaredKeyOf(tables, theory, 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 overlayMethods(theory, tables, assertLive, reads) {
+    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 Object.freeze({
-            kind: "containment",
-            statement: entry.statement,
-            canonical,
-            direction: wire.direction,
-            facts
-        });
+        return factOf(relation, row);
     }
-    /**
-     * 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 "statement" in candidate && candidate.statement === statement;
+    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(tables, theory, 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));
         });
-        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`);
+    }
+    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");
         }
-        if (entry.kind !== "functionality") {
-            throw errors.new("keyed get takes a key() statement — containments and capacity statements key nothing");
+    }
+    const methods = catalogMethods(theory, tables, owner, assertLive, {
+        scan(relationId) {
+            return native.instanceScan(state.handle, relationId);
+        },
+        count(relationId) {
+            return native.instanceCount(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);
         }
-        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`);
+    });
+    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;
+}
+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 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({ statementId, projection: entry.projection });
+        const facts = Object.freeze(wire.facts.map(function offending(fact) {
+            const rel = tables.relations.get(fact.relation);
+            if (rel === undefined || !isMemberName(fact.relation)) {
+                throw errors.new(`bumbledb violation cites unknown relation ${fact.relation}`);
+            }
+            return decodeOffendingFact(rel.member, fact.relation, fact);
+        }));
+        return violationFromEntry(entry, wire, facts);
     }
     function pointReadsOf(assertLive, reads) {
         function contains(relation, fact) {
             assertLive();
-            const entry = resolveOrdinary(relation);
+            const entry = ordinaryEntry(tables, theory, 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) {
@@ -463,9 +578,9 @@ function openDb(handle, theory, manifest) {
         }
         function get(relation, keyOrStatement, declaredKey) {
             assertLive();
-            const entry = resolveOrdinary(relation);
+            const entry = ordinaryEntry(tables, theory, relation);
             return selectKeyRead(keyOrStatement, declaredKey, function byStatement(statement, key) {
-                return readThroughKey(relation, entry, declaredKeyOf(relation, statement), recordOf(key));
+                return readThroughKey(relation, entry, declaredKeyOf(tables, theory, relation, statement), recordOf(key));
             }, function byPrimary(key) {
                 const primaryKey = entry.primaryKey;
                 if (primaryKey === undefined) {
@@ -476,172 +591,62 @@ 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;
-    }
-    /**
-     * 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 };
-    }
-    /**
-     * 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;
+        witnessStates.set(witness, state);
+        witnessReclaimer.register(witness, nativeHandle);
+        return witness;
     }
-    function scan(relation) {
-        return read(function scanInScope(snap) {
-            return snap.scan(relation);
-        });
+    function makeInstance(nativeHandle) {
+        return createReadInstance(nativeHandle, theory, tables, owner);
     }
-    function get(relation, keyOrStatement, declaredKey) {
-        return read(function getInScope(snap) {
-            return selectKeyRead(keyOrStatement, declaredKey, function byStatement(statement, key) {
-                return snap.get(relation, statement, key);
-            }, function byPrimary(key) {
-                return snap.get(relation, key);
+    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 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` 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,33 +665,27 @@ 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 entry = ordinaryEntry(tables, theory, relation);
             const txHandle = resolveTx();
-            const report = bridged("bumbledb tx insert", function record() {
-                return native.txInsert(txHandle, entry.id, rows);
+            return mutateCollection(relation, facts, function applyCells(rows, cells) {
+                return bridged("bumbledb tx insert", function record() {
+                    return native.txInsert(txHandle, entry.id, rows, cells);
+                });
             });
-            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 entry = ordinaryEntry(tables, theory, relation);
             const txHandle = resolveTx();
+            const flat = rowsOf(relation, facts);
             const report = bridged("bumbledb tx delete", function record() {
-                return native.txDelete(txHandle, entry.id, rows);
+                return native.txDelete(txHandle, entry.id, flat.rows, flat.cells);
             });
             return Object.freeze({ submitted: report.submitted, changed: report.changed });
         }
         function reserve(relation, field, count) {
             assertLive();
-            const entry = resolveOrdinary(relation);
+            const entry = ordinaryEntry(tables, theory, relation);
             const declared = relation.data.fields.find(function byName(candidate) {
                 return candidate.name === field;
             });
@@ -715,104 +714,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);
-        });
-        return runDelta(txHandle, fn);
-    }
-    /**
-     * 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");
-        }
-        if (snapState.owner !== owner) {
-            throw errors.new(`bumbledb writeFrom snapshot belongs to a different store (schema ${theory.name})`);
-        }
-        if (!snapState.live) {
-            throw errors.new("bumbledb writeFrom snapshot is invalidated — its owning read callback already returned");
-        }
-        const witnessed = bridged("begin witnessed bumbledb write transaction", function begin() {
-            return native.dbWriteFrom(handle, snapState.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);
+            });
         });
-        if (!witnessed.ok) {
-            throw errors.wrap(ErrGenerationMoved, `writeFrom: generation moved (witnessed ${witnessed.witnessed} current ${witnessed.current}) against schema ${theory.name}`);
+        return mapNativeWrite(nativeOutcome, built);
+    }
+    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");
+        }
+        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 (state.owner !== owner) {
+            throw errors.wrap(ErrForeignWitness, `bumbledb writeFrom witness belongs to a different store (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,114 +798,296 @@ 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,
         read,
-        scan,
-        get,
-        contains,
-        execute,
         write,
         writeFrom,
         prepare
     });
 }
-/**
- * The engine twin of the schema-level class wall, as a matchable value
- * (`errors.is`): the shared lowering rejected a spec whose statement pairs
- * faces with disagreeing newtype labels — the faces of a dependency agree
- * on their newtype, or neither carries one. UNREACHABLE through the typed
- * builder (the SDK computes every label from the laws, so its lowered
- * specs cohere by construction); a raw spec handed to the bridge is the
- * one road here, and the runtime referee that proves the engine judges
- * 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}`);
+    }
+    const facts = Object.freeze(wire.facts.map(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}`);
         }
+        return decodeOffendingFact(member, fact.relation, fact);
+    }));
+    return violationFromEntry(entry, wire, 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);
+        },
+        count(relationId) {
+            return native.ownedCount(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);
+            });
+        }
+    });
+    const builder = Object.freeze({
+        load(relation, facts) {
+            assertLive();
+            const entry = ordinaryEntry(tables, theory, relation);
+            return mutateCollection(relation, facts, function applyCells(rows, cells) {
+                return bridged("bumbledb builder load", function loadCells() {
+                    return native.instanceBuilderLoad(nativeHandle, entry.id, rows, cells);
+                });
+            });
+        },
+        delete(relation, facts) {
+            assertLive();
+            const entry = ordinaryEntry(tables, theory, relation);
+            const flat = rowsOf(relation, facts);
+            const report = bridged("bumbledb builder delete", function remove() {
+                return native.instanceBuilderDelete(nativeHandle, entry.id, flat.rows, flat.cells);
+            });
+            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);
+            });
+        }
     });
-    return openDb(opened.db, theory, manifest);
+    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`.
-     */
-    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, ErrFingerprintMismatch, ErrForeignPrepared, ErrForeignWitness, ErrIrError, ErrNewtypeMismatch, ErrSchemaError, ErrSpentHandle, ErrUseAfterScope, InstanceBuilder };
 //# sourceMappingURL=db.js.map