@bjornpagen/bumbledb 0.9.0 → 0.11.0

package/dist/db.js

@@ -2,35 +2,32 @@
  * `Db` — the living half of the SDK (PRD-07): open/create a store from a
  * `Schema`, write typed facts through delta transactions with race-free
  * final-state point reads, receive rejections as typed violation VALUES
- * keyed to statements, read through scoped snapshots, and run the witnessed
- * read-compute-write loop — all typed by the schema's relations record.
+ * keyed to statements, and read through scoped snapshots — 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. `Db` values
- * are CACHED per canonical path for the life of the process (a best-effort
- * exit hook closes the cached environments; correctness never depends on it
- * — the engine fsyncs every commit, so a process that dies without the hook
- * loses nothing that was committed). Snapshots are scope-shaped both ways:
- * `read(fn)` opens one before `fn` and closes it after unconditionally
- * (the {@link ReadScope} handed to `fn` is invalidated the moment `fn`
- * returns), and `using snap = db.read()` hands the caller the lifetime,
- * released by the scope's own `Symbol.dispose` at scope exit. Prepared
- * plans are plain values whose engine-side half is reclaimed by a GC
- * finalizer — reclamation only, never correctness.
+ * 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.
  *
  * PROCESS MODEL: one process, one exclusive-lock handle per store. The
- * cached `Db` value owns the LMDB environment's exclusive lock until
- * process exit; a second engine-level open of the same store (an aliased
- * path spelling, or another process) is refused by the engine. The
- * run-store process model (PRD-16) depends on this being true: resume =
- * reopen, which is either this process's cached value or a fresh process's
- * open.
+ * `Db` value owns the LMDB environment's exclusive lock until process
+ * exit (or until GC reclaims the native handle); a second engine-level
+ * open of the same store is refused by the engine (`EnvironmentLocked`),
+ * matching Rust. Resume = reopen in a fresh process, or hold the one `Db`
+ * this process already opened. The host owns composition; retry is host
+ * 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 — throw `@superbuilders/errors` wrapped errors instead.
+ * marshal shape, a moved generation on {@link Db.writeFrom} — throw
+ * `@superbuilders/errors` wrapped errors instead.
  */
 import * as path from "node:path";
 import * as errors from "@superbuilders/errors";
@@ -45,7 +42,7 @@ import { decodeAnswers, wireParams } from "#query/run.ts";
 import { isStatement } from "#statements.ts";
 /**
  * The runtime discriminant of {@link Abandon} values — a property probe is
- * how `writeWitnessed` distinguishes "abort without committing" from an
+ * 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");
@@ -53,7 +50,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 `writeWitnessed`
+ * to `{ ok: false, abandoned: payload }`, from `write` and `writeFrom`
  * alike (R10).
  */
 function abandon(payload) {
@@ -131,8 +128,8 @@ function impliedKeyEntries(theory) {
             if (isFreshField(declared.field)) {
                 entries.push({
                     kind: "functionality",
-                    statement: undefined,
-                    key: { owner: member.name, projection: [declared.name] }
+                    owner: member.name,
+                    projection: [declared.name]
                 });
             }
         }
@@ -141,8 +138,8 @@ function impliedKeyEntries(theory) {
         if (isClosedMember(member)) {
             entries.push({
                 kind: "functionality",
-                statement: undefined,
-                key: { owner: member.name, projection: ["id"] }
+                owner: member.name,
+                projection: ["id"]
             });
         }
     }
@@ -162,21 +159,22 @@ function declaredEntries(statement) {
                 {
                     kind: "functionality",
                     statement,
-                    key: { owner: data.owner.name, projection: data.projection }
+                    owner: data.owner.name,
+                    projection: data.projection
                 }
             ];
         }
         case "containment": {
-            if (data.bidirectional) {
-                return [
-                    { kind: "containment", statement, key: undefined, reversed: false },
-                    { kind: "containment", statement, key: undefined, reversed: true }
-                ];
-            }
-            return [{ kind: "containment", statement, key: undefined }];
+            return [{ kind: "containment", statement }];
+        }
+        case "mirrors": {
+            return [
+                { kind: "mirrors", statement, orientation: "written" },
+                { kind: "mirrors", statement, orientation: "mirrored" }
+            ];
         }
         case "capacity": {
-            return [{ kind: "capacity", statement, key: undefined }];
+            return [{ kind: "capacity", statement }];
         }
     }
 }
@@ -221,16 +219,6 @@ function selectKeyRead(keyOrStatement, declaredKey, byStatement, byPrimary) {
     }
     return byPrimary(keyOrStatement);
 }
-/** Maps a slot's reversal flag to the violation's `orientation` payload. */
-function orientationOf(reversed) {
-    if (reversed === undefined) {
-        return undefined;
-    }
-    if (reversed) {
-        return "mirrored";
-    }
-    return "written";
-}
 /**
  * Builds the id-resolution tables from the manifest, verifying the SDK's
  * positional mirror against the engine's reported order — any drift
@@ -248,9 +236,13 @@ function tablesOf(theory, manifest) {
     }
     manifest.statements.forEach(function verifySlot(statement, index) {
         const entry = entries[index];
-        if (entry === undefined || statement.id !== index || entry.kind !== statement.kind) {
+        if (entry === undefined || statement.id !== index) {
             throw errors.new(`bumbledb manifest drift: statement ${statement.id} is ${statement.kind}, the SDK mirror at ${index} expected ${entry?.kind}`);
         }
+        const engineKind = entry.kind === "mirrors" ? "containment" : entry.kind;
+        if (engineKind !== statement.kind) {
+            throw errors.new(`bumbledb manifest drift: statement ${statement.id} is ${statement.kind}, the SDK mirror at ${index} expected ${engineKind}`);
+        }
     });
     const relations = new Map();
     for (const relation of manifest.relations) {
@@ -269,8 +261,8 @@ function tablesOf(theory, manifest) {
         });
         let primaryKey;
         entries.forEach(function firstOwnedKey(entry, index) {
-            if (primaryKey === undefined && entry.key !== undefined && entry.key.owner === relation.name) {
-                primaryKey = Object.freeze({ statementId: index, projection: entry.key.projection });
+            if (primaryKey === undefined && entry.kind === "functionality" && entry.owner === relation.name) {
+                primaryKey = Object.freeze({ statementId: index, projection: entry.projection });
             }
         });
         relations.set(relation.name, Object.freeze({ id: relation.id, member, fieldIds, primaryKey }));
@@ -305,34 +297,11 @@ const planReclaimer = new FinalizationRegistry(function reclaimPlan(handle) {
     }
 });
 /**
- * The internal retry signal a lazily-witnessed transaction throws when the
- * engine reports a moved generation at begin: `writeWitnessed` catches it
- * by identity (through cause chains, via `errors.is`) and reruns the whole
- * callback on a fresh snapshot. It never escapes the SDK.
- */
-const generationMovedSignal = errors.new("bumbledb witnessed generation moved");
-/**
- * The witnessed loop's attempt cap — a generous power of two. Benign
- * self-inflicted contention (the host's own commits landing between an
- * attempt's snapshot and its witnessed begin) converges in a handful of
- * retries because each rerun reads a FRESHER snapshot; a workload that moves
- * the generation on EVERY one of this many consecutive attempts is not
- * converging and never will (see {@link ErrWitnessedLivelock}).
+ * 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 WITNESSED_ATTEMPT_CAP = 64;
-/**
- * The typed livelock refusal `writeWitnessed` throws past
- * {@link WITNESSED_ATTEMPT_CAP} attempts: every attempt found the generation
- * moved, which is only sustainable when the callback ITSELF (even
- * indirectly) issues an interleaved plain `db.write` before its first tx
- * verb on every attempt — each rerun then re-moves the generation it is
- * about to witness, forever. That is host-policy pathology, not engine
- * judgment (the engine ships the error, never a loop), so it THROWS rather
- * than returning a result arm. Match with `errors.is`; the remedy is to
- * move the interleaved write out of the callback (or make it first-attempt
- * only — the delta belongs on `tx`, premise reads on `snap`).
- */
-const ErrWitnessedLivelock = errors.new("bumbledb writeWitnessed livelock: the generation moved on every attempt — the callback itself commits an interleaved write each try, so no snapshot can ever stay current");
+const ErrGenerationMoved = errors.new("bumbledb generationMoved: a state-changing commit landed since the witness snapshot");
 /**
  * Fills one insert's omitted fresh cells through the engine's
  * alloc-then-insert dyn lane (there is no insert-with-omitted-fields wire
@@ -410,15 +379,32 @@ function openDb(handle, theory, manifest) {
         if (entry === undefined) {
             throw errors.new(`bumbledb violation cites unknown statement id ${wire.statementId}`);
         }
-        return Object.freeze({
-            statement: entry.statement,
-            kind: wire.kind,
-            canonical: wire.canonical,
-            direction: wire.direction,
-            orientation: orientationOf(entry.reversed),
-            measure: wire.measure,
-            facts: Object.freeze(wire.facts.map(offendingFactOf))
-        });
+        const facts = Object.freeze(wire.facts.map(offendingFactOf));
+        const statement = entry.statement;
+        const canonical = wire.canonical;
+        if (entry.kind === "functionality") {
+            return Object.freeze({ kind: "functionality", 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, 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,
+                canonical,
+                direction: wire.direction,
+                orientation: entry.orientation,
+                facts
+            });
+        }
+        return Object.freeze({ kind: "containment", statement, canonical, direction: wire.direction, facts });
     }
     /**
      * Resolves a key-statement-selected read: the statement must be the
@@ -435,13 +421,13 @@ function openDb(handle, theory, manifest) {
         if (entry === undefined) {
             throw errors.new(`keyed get statement is not a declared statement of schema ${theory.name} — statement identity is the membership rule`);
         }
-        if (entry.kind !== "functionality" || entry.key === undefined) {
+        if (entry.kind !== "functionality") {
             throw errors.new("keyed get takes a key() statement — containments and capacity statements key nothing");
         }
-        if (entry.key.owner !== relation.name) {
-            throw errors.new(`keyed get statement keys ${entry.key.owner}, not ${relation.name} — the statement must be a declared key of the relation it reads`);
+        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.key.projection });
+        return Object.freeze({ statementId, projection: entry.projection });
     }
     function pointReadsOf(assertLive, reads) {
         function contains(relation, fact) {
@@ -530,14 +516,6 @@ function openDb(handle, theory, manifest) {
             });
             return decodeAnswers(plan.finds, rows);
         }
-        function explain(prepared, params) {
-            assertLive();
-            const plan = planOf(prepared);
-            const wire = wireParams(plan.params, recordOf(params));
-            return bridged("explain bumbledb prepared query", function callExplain() {
-                return native.preparedExplain(plan.handle, state.handle, wire);
-            });
-        }
         /** The R12 teardown: invalidate, then close — idempotent through the state's close latch. */
         function dispose() {
             state.live = false;
@@ -549,7 +527,6 @@ function openDb(handle, theory, manifest) {
             get: reads.get,
             contains: reads.contains,
             execute,
-            explain,
             [Symbol.dispose]: dispose
         });
         scopeStates.set(scope, state);
@@ -638,17 +615,9 @@ function openDb(handle, theory, manifest) {
             return snap.execute(prepared, params);
         });
     }
-    function explain(prepared, params) {
-        return read(function explainInScope(snap) {
-            return snap.explain(prepared, params);
-        });
-    }
     /**
-     * Builds one {@link Tx} over a transaction-handle thunk: `write` passes
-     * an already-begun handle; `writeWitnessed` passes a LAZY thunk that
-     * begins the witnessed transaction on the first delta verb (so premise
-     * reads and the host's own interleaved writes can precede it) and
-     * throws {@link generationMovedSignal} when the witness is stale.
+     * Builds one {@link Tx} over a transaction-handle thunk: `write` and
+     * `writeFrom` pass an already-begun handle.
      */
     function makeTx(resolveTx) {
         const txState = { spent: false };
@@ -784,181 +753,42 @@ function openDb(handle, theory, manifest) {
         return runDelta(txHandle, fn);
     }
     /**
-     * Commits an already-begun witnessed transaction and closes the
-     * attempt's snapshot: the committed generation, or the engine's
-     * complete violation set as data.
+     * 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 commitWitnessed(state, txHandle) {
-        const committed = errors.trySync(function commitWitnessedDelta() {
-            return bridged("commit bumbledb witnessed write transaction", function commit() {
-                return native.txCommit(txHandle);
-            });
-        });
-        if (committed.error) {
-            /** Same one-writer law as `runDelta`: a thrown commit aborts before rethrowing. */
-            const aborted = errors.trySync(function abortAfterFailedCommit() {
-                native.txAbort(txHandle);
-            });
-            if (aborted.error) {
-            }
-            closeScopeState(state);
-            throw errors.wrap(committed.error, "commit bumbledb witnessed write transaction");
+    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");
         }
-        const outcome = committed.data;
-        closeScopeState(state);
-        if (outcome.ok) {
-            return Object.freeze({ ok: true, generation: outcome.generation });
+        if (snapState.owner !== owner) {
+            throw errors.new(`bumbledb writeFrom snapshot belongs to a different store (schema ${theory.name})`);
         }
-        return Object.freeze({
-            ok: false,
-            violations: Object.freeze(outcome.violations.map(violationOf))
-        });
-    }
-    /**
-     * One attempt of the witnessed loop: fresh snapshot, the callback over
-     * its scope and a LAZILY-begun witnessed transaction (the first delta
-     * verb begins it, so premise reads and the host's own interleaved
-     * writes can precede the witness check), then the witnessed commit —
-     * or the abandon abort, which never issues a commit. Returns
-     * `undefined` exactly when the generation moved and the whole callback
-     * must rerun on a fresh snapshot.
-     */
-    function witnessedAttempt(fn) {
-        const state = openScopeState();
-        const scope = makeScope(state);
-        const pending = { tx: undefined };
-        function beginWitnessed() {
-            const witnessed = bridged("begin witnessed bumbledb write transaction", function begin() {
-                return native.dbWriteFrom(handle, state.handle);
-            });
-            if (!witnessed.ok) {
-                return undefined;
-            }
-            return witnessed.tx;
+        if (!snapState.live) {
+            throw errors.new("bumbledb writeFrom snapshot is invalidated — its owning read callback already returned");
         }
-        const made = makeTx(function resolveWitnessedTx() {
-            if (pending.tx === undefined) {
-                const begun = beginWitnessed();
-                if (begun === undefined) {
-                    throw generationMovedSignal;
-                }
-                pending.tx = begun;
-            }
-            return pending.tx;
+        const witnessed = bridged("begin witnessed bumbledb write transaction", function begin() {
+            return native.dbWriteFrom(handle, snapState.handle);
         });
-        const built = errors.trySync(function computeWitnessed() {
-            return fn(scope, made.tx);
-        });
-        made.spend();
-        state.live = false;
-        /**
-         * Aborts the pending transaction if one was begun. A faulted abort
-         * still closes the attempt's snapshot BEFORE rethrowing — every
-         * openScopeState is paired with closeScopeState on every exit, or a
-         * reader slot and its snapshot worker leak for the process's lifetime.
-         */
-        function abortPending() {
-            const txHandle = pending.tx;
-            if (txHandle === undefined) {
-                return;
-            }
-            const aborted = errors.trySync(function abort() {
-                native.txAbort(txHandle);
-            });
-            if (aborted.error) {
-                closeScopeState(state);
-                throw errors.wrap(aborted.error, "abort bumbledb witnessed write transaction");
-            }
-        }
-        if (built.error) {
-            abortPending();
-            closeScopeState(state);
-            if (errors.is(built.error, generationMovedSignal)) {
-                return undefined;
-            }
-            throw errors.wrap(built.error, "build witnessed write delta");
-        }
-        if (isThenable(built.data)) {
-            /** The same async-callback refusal as `runDelta` — a thenable means the real delta build races the commit; nothing is committed. */
-            abortPending();
-            closeScopeState(state);
-            throw errors.new("bumbledb writeWitnessed callback returned a thenable — the delta build is synchronous; an async callback is refused, nothing was committed");
-        }
-        if (isAbandon(built.data)) {
-            abortPending();
-            closeScopeState(state);
-            return abandonedOutcome(built.data);
-        }
-        const late = errors.trySync(function resolveCommitTx() {
-            if (pending.tx === undefined) {
-                return beginWitnessed();
-            }
-            return pending.tx;
-        });
-        if (late.error) {
-            /** A faulted late begin must not leak the attempt's snapshot either. */
-            closeScopeState(state);
-            throw late.error;
-        }
-        const txHandle = late.data;
-        if (txHandle === undefined) {
-            closeScopeState(state);
-            return undefined;
+        if (!witnessed.ok) {
+            throw errors.wrap(ErrGenerationMoved, `writeFrom: generation moved (witnessed ${witnessed.witnessed} current ${witnessed.current}) against schema ${theory.name}`);
         }
-        return commitWitnessed(state, txHandle);
-    }
-    /**
-     * The witnessed retry loop. What it retries: the benign race — the
-     * host's OWN interleaved commit landing between an attempt's snapshot
-     * and its witnessed begin (every writer shares this handle, so a move
-     * is always self-inflicted) — by rerunning the WHOLE callback on a
-     * fresh snapshot, which converges because each rerun witnesses a
-     * strictly newer generation. What it refuses: the pathology where the
-     * callback itself (even indirectly) issues a plain `db.write` before
-     * its first tx verb, moving the generation on EVERY attempt — an
-     * unbounded loop would spin forever with no diagnostic, so past
-     * {@link WITNESSED_ATTEMPT_CAP} attempts the loop throws the typed
-     * {@link ErrWitnessedLivelock} instead (the engine's ruling: the
-     * error, never a loop — retry is host policy, and this is the host
-     * policy's own honesty bound).
-     */
-    function writeWitnessed(fn) {
-        for (let attempts = 0; attempts < WITNESSED_ATTEMPT_CAP; attempts += 1) {
-            const attempt = witnessedAttempt(fn);
-            if (attempt !== undefined) {
-                return attempt;
-            }
-        }
-        throw errors.wrap(ErrWitnessedLivelock, `writeWitnessed livelock: the generation moved on all ${WITNESSED_ATTEMPT_CAP} attempts against schema ${theory.name}`);
+        return runDelta(witnessed.tx, fn);
     }
     function prepare(q) {
         if (q.schema !== theory) {
             throw errors.new(`query was built against schema ${q.schema.name}, not the identical schema value this store opened with — schema identity is the membership rule`);
         }
-        const program = lowerQuery(q);
-        const outcome = bridged("prepare bumbledb program", function callPrepare() {
-            return native.dbPrepare(handle, program);
+        const queryIr = lowerQuery(q);
+        const outcome = bridged("prepare bumbledb query", function callPrepare() {
+            return native.dbPrepare(handle, queryIr);
         });
         if (!outcome.ok) {
             throw errors.new(`bumbledb ${outcome.kind} (prepare): ${outcome.message}`);
         }
         const preparedHandle = outcome.prepared;
-        function staleness(snap) {
-            const snapState = scopeStates.get(snap);
-            if (snapState === undefined) {
-                throw errors.new("bumbledb staleness witness is not a read scope of this SDK");
-            }
-            if (snapState.owner !== owner) {
-                throw errors.new(`bumbledb read scope belongs to a different store than this prepared value (schema ${theory.name})`);
-            }
-            if (!snapState.live) {
-                throw errors.new("bumbledb read scope is invalidated — its owning read callback already returned");
-            }
-            return bridged("read bumbledb prepared staleness", function callStaleness() {
-                return native.preparedStaleness(preparedHandle, snapState.handle);
-            });
-        }
-        const prepared = Object.freeze({ staleness });
+        const prepared = Object.freeze({});
         preparedPlans.set(prepared, Object.freeze({
             handle: preparedHandle,
             owner,
@@ -975,44 +805,11 @@ function openDb(handle, theory, manifest) {
         get,
         contains,
         execute,
-        explain,
         write,
-        writeWitnessed,
+        writeFrom,
         prepare
     });
 }
-/**
- * The per-process store cache, keyed by canonical path
- * (`node:path.resolve` — absolute and normalized). Symlink aliasing is
- * deliberately not resolved here: an aliased spelling misses the cache and
- * reaches the engine, whose exclusive lock refuses a second live handle on
- * the same store — the backstop that keeps "one store, one handle" true.
- */
-const openStores = new Map();
-/**
- * The in-process fingerprint check and its typing proof in one probe:
- * theory identity (`===`) implies `Rels` identity, because a cache entry's
- * `db` was constructed from that very theory value — so a hit narrows the
- * entry's `db` to `Db<Rels>` with no assertion anywhere.
- */
-function holdsTheory(entry, theory) {
-    return entry.theory === theory;
-}
-/**
- * The best-effort exit hook: closes every cached environment so LMDB
- * releases its locks tidily on a clean exit. CORRECTNESS NEVER RESTS HERE —
- * the engine fsyncs every commit, so a process killed before (or during)
- * this hook loses nothing that was committed.
- */
-process.once("exit", function closeCachedStores() {
-    for (const cached of openStores.values()) {
-        const closed = errors.trySync(function closeEnvironment() {
-            native.dbClose(cached.handle);
-        });
-        if (closed.error) {
-        }
-    }
-});
 /**
  * The engine twin of the schema-level class wall, as a matchable value
  * (`errors.is`): the shared lowering rejected a spec whose statement pairs
@@ -1043,30 +840,19 @@ function refuseShadowedChanged(theory) {
     }
 }
 /**
- * The one admission path both verbs share: canonical-path cache lookup
- * first (a hit returns the SAME `Db` value for the identical theory, a
- * typed fingerprint error for a different one, and a typed refusal for
- * `create` — the store a cache entry proves initialized is exactly what
- * create refuses). On a miss: lower the theory, run one bridge call, and
- * wrap the 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.
+ * 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) {
     refuseShadowedChanged(theory);
     const canonical = path.resolve(storePath);
-    const cached = openStores.get(canonical);
-    if (cached !== undefined) {
-        if (verb === "create") {
-            throw errors.new(`create bumbledb store at ${canonical}: the store is already open in this process — create refuses an already-initialized directory`);
-        }
-        if (!holdsTheory(cached, theory)) {
-            throw errors.new(`bumbledb fingerprintMismatch (open ${canonical}): the cached store was opened with schema ${cached.theory.name}, not this theory value — schema identity is the membership rule`);
-        }
-        return cached.db;
-    }
     const spec = lower(theory);
     const opened = bridged(`${verb} bumbledb store at ${canonical}`, function callBridge() {
         if (verb === "create") {
@@ -1083,34 +869,30 @@ function admit(verb, storePath, theory) {
     const manifest = bridged("fetch bumbledb manifest", function fetchManifest() {
         return native.dbManifest(opened.db);
     });
-    const db = openDb(opened.db, theory, manifest);
-    openStores.set(canonical, Object.freeze({ theory, db, handle: opened.db }));
-    return db;
+    return openDb(opened.db, theory, manifest);
 }
 /**
  * The store lifecycle — `Db.create(path, schema)` / `Db.open(path, schema)`.
  * Create refuses an already-initialized directory; open verifies format
- * version, store kind, and the schema fingerprint. Both return values
- * CACHED per canonical path: a second open of the same path with the
- * identical theory value returns the SAME `Db`, and a different theory on
- * a cached path is a typed fingerprint error. There is no close anywhere:
- * the process owns every cached environment until exit (a best-effort exit
- * hook closes them; durability is the engine's per-commit fsync). One
- * store kind exists: durable — resume = reopen, meaning this process's
- * cached value or a fresh process's open.
+ * 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.
  */
 const Db = Object.freeze({
-    /** Creates a fresh durable store at `path` from the schema; the value is cached for every later open. */
+    /** Creates a fresh durable store at `path` from the schema. */
     async create(path, theory) {
         return admit("create", path, theory);
     },
     /**
-     * Opens an existing durable store at `path` with the same theory — the
-     * cached value when this process already holds it. A fingerprint-matching
-     * open also BACK-FILLS the store's persisted schema descriptor when it is
-     * absent (self-describing stores, engine 50-storage.md § the `_meta`
-     * block), so a legacy store becomes exhumable after one ordinary open —
-     * adoption is automatic, never a separate verb.
+     * 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);
@@ -1131,5 +913,5 @@ const Db = Object.freeze({
         return exhumeStore(path.resolve(storePath));
     }
 });
-export { abandon, Db, ErrNewtypeMismatch, ErrWitnessedLivelock, WITNESSED_ATTEMPT_CAP };
+export { abandon, Db, ErrGenerationMoved, ErrNewtypeMismatch };
 //# sourceMappingURL=db.js.map