@bjornpagen/bumbledb 0.6.0 → 0.7.0

package/src/db.ts

@@ -5,16 +5,19 @@
  * keyed to statements, read through scoped snapshots, and run the witnessed
  * read-compute-write loop — all typed by the schema's relations record.
  *
- * ZERO CLOSABLES: no value this module returns carries a close, dispose, or
- * release spelling. `Db` values are CACHED per canonical path for the life
- * of the process (a best-effort exit hook closes the cached environments;
- * correctness never depends on it — the engine fsyncs every commit, so a
- * process that dies without the hook loses nothing that was committed).
- * Snapshots are internal: `read(fn)` opens one before `fn` and closes it
- * after unconditionally, and the {@link ReadScope} handed to `fn` is
- * invalidated the moment `fn` returns. Prepared plans are plain values whose
- * engine-side half is reclaimed by a GC finalizer — reclamation only, never
- * correctness.
+ * LIFETIMES ARE DISPOSABLES, never `close()` (ruled 2026-07-23, R12): no
+ * value this module returns carries a close spelling — release is
+ * deterministic and scope-shaped in the language's own syntax. `Db` values
+ * are CACHED per canonical path for the life of the process (a best-effort
+ * exit hook closes the cached environments; correctness never depends on it
+ * — the engine fsyncs every commit, so a process that dies without the hook
+ * loses nothing that was committed). Snapshots are scope-shaped both ways:
+ * `read(fn)` opens one before `fn` and closes it after unconditionally
+ * (the {@link ReadScope} handed to `fn` is invalidated the moment `fn`
+ * returns), and `using snap = db.read()` hands the caller the lifetime,
+ * released by the scope's own `Symbol.dispose` at scope exit. Prepared
+ * plans are plain values whose engine-side half is reclaimed by a GC
+ * finalizer — reclamation only, never correctness.
  *
  * PROCESS MODEL: one process, one exclusive-lock handle per store. The
  * cached `Db` value owns the LMDB environment's exclusive lock until
@@ -41,7 +44,7 @@ import {
 	factOf,
 	handleOf,
 	isFreshField,
-	isMintedFresh,
+	isInserted,
 	type KeyFact,
 	keyRowOf,
 	type Minted,
@@ -51,6 +54,7 @@ import {
 
 import type {
 	DbHandle,
+	Explain,
 	FactValue,
 	Manifest,
 	PreparedHandle,
@@ -69,7 +73,7 @@ import { decodeAnswers, wireParams } from "#query/run.ts"
 import type { ParamEntry, ParamsRecord } from "#query/scope.ts"
 import type { AnyRelation, Fact, InsertFact } from "#relation.ts"
 import type { AnySchema, Schema, SchemaRelation, SchemaRelations } from "#schema.ts"
-import type { KeyStatement, Statement } from "#statements.ts"
+import { isStatement, type KeyStatement, type Statement } from "#statements.ts"
 
 /**
  * The ordinary (writable, scannable) relations of a schema's record — the
@@ -132,16 +136,35 @@ interface Violation<Rels extends SchemaRelations> {
 }
 
 /**
- * A commit's domain outcome: the committed generation, or the COMPLETE
- * violation set (every violated statement cited once, per direction for a
- * containment, in materialized statement order). Narrows on `.ok`.
+ * The abandoned arm of a write result (ruled 2026-07-23, R10): present in
+ * the type EXACTLY when the callback can abandon — the conditional
+ * distributes over `R`, so a callback with no `Abandon` arm contributes
+ * `never` and the arm vanishes from the sum. The outcome is in the type;
+ * a dead arm is never handled.
  */
-type WriteResult<Rels extends SchemaRelations> =
+type AbandonedArm<R> = R extends Abandon<infer P> ? { readonly ok: false; readonly abandoned: P } : never
+
+/**
+ * A write's domain outcome, one sum for BOTH verbs (ruled 2026-07-23,
+ * R10): the committed generation; the COMPLETE violation set (every
+ * violated statement cited once, per direction for a containment, in
+ * materialized statement order); or the callback's own abandon payload —
+ * commit-vs-abandon is in the type, so a caller's explicit decline to
+ * commit can never be silently discarded. Narrows on `.ok`, then (when the
+ * callback can abandon) on `"violations" in result`.
+ */
+type WriteResult<Rels extends SchemaRelations, R = void> =
 	| { readonly ok: true; readonly generation: bigint }
 	| { readonly ok: false; readonly violations: readonly Violation<Rels>[] }
+	| AbandonedArm<R>
 
-/** The delta-building callback of a write: runs synchronously against the live transaction. */
-type DeltaBuild<Rels extends SchemaRelations> = (tx: Tx<Rels>) => void
+/**
+ * The delta-building callback of a write: runs synchronously against the
+ * live transaction. Returning {@link abandon}`(payload)` rolls the
+ * transaction back (R10) — the result type carries the payload arm exactly
+ * then.
+ */
+type DeltaBuild<Rels extends SchemaRelations, R = void> = (tx: Tx<Rels>) => R
 
 /**
  * The runtime discriminant of {@link Abandon} values — a property probe is
@@ -151,10 +174,11 @@ type DeltaBuild<Rels extends SchemaRelations> = (tx: Tx<Rels>) => void
 const abandonMark: unique symbol = Symbol("bumbledb.abandon")
 
 /**
- * The abandon sentinel {@link abandon} builds: returning one from a
- * `writeWitnessed` callback aborts the attempt WITHOUT committing (no empty
- * commit is ever issued) and surfaces the payload as
- * `{ ok: false, abandoned: payload }`.
+ * The abandon sentinel {@link abandon} builds: returning one from a `write`
+ * or `writeWitnessed` callback rolls the transaction back WITHOUT
+ * committing (no empty commit is ever issued) and surfaces the payload as
+ * `{ ok: false, abandoned: payload }` (ruled 2026-07-23, R10 — the
+ * sentinel's contract is unconditional, whichever write verb received it).
  */
 interface Abandon<P> {
 	readonly [abandonMark]: true
@@ -162,26 +186,28 @@ interface Abandon<P> {
 }
 
 /**
- * Wraps a payload in the {@link Abandon} sentinel — the one way a
- * `writeWitnessed` callback declines to commit: `return abandon(payload)`
- * aborts the delta (nothing is committed, not even an empty commit) and the
- * write resolves to `{ ok: false, abandoned: payload }`.
+ * Wraps a payload in the {@link Abandon} sentinel — the one way a write
+ * callback declines to commit: `return abandon(payload)` aborts the delta
+ * (nothing is committed, not even an empty commit) and the write resolves
+ * to `{ ok: false, abandoned: payload }`, from `write` and `writeWitnessed`
+ * alike (R10).
  */
 function abandon<P>(payload: P): Abandon<P> {
 	return Object.freeze({ [abandonMark]: true as const, payload })
 }
 
 /**
- * The abandon payload type a `writeWitnessed` callback's return type
- * implies: the payload of its `Abandon` arm, `never` when the callback can
- * never abandon (the `abandoned` outcome is then statically unreachable).
+ * The abandon payload type a write callback's return type implies: the
+ * payload of its `Abandon` arm, `never` when the callback can never
+ * abandon (the `abandoned` outcome is then statically unreachable and
+ * {@link AbandonedArm} erases it from the sum).
  */
 type AbandonedPayload<R> = R extends Abandon<infer P> ? P : never
 
 /**
- * Narrows a `writeWitnessed` callback result to the abandon sentinel. The
- * probe is the private {@link abandonMark} symbol only {@link abandon} sets,
- * and `R`'s `Abandon` arm is the only way a sentinel can flow out of the
+ * Narrows a write callback result to the abandon sentinel. The probe is
+ * the private {@link abandonMark} symbol only {@link abandon} sets, and
+ * `R`'s `Abandon` arm is the only way a sentinel can flow out of the
  * callback — so the narrowed payload type is sound by construction.
  */
 function isAbandon<R>(value: R): value is R & Abandon<AbandonedPayload<R>> {
@@ -189,15 +215,30 @@ function isAbandon<R>(value: R): value is R & Abandon<AbandonedPayload<R>> {
 }
 
 /**
- * `writeWitnessed`'s domain outcome: the committed generation, the COMPLETE
- * engine violation set (rejection-as-data, exactly {@link WriteResult}'s
- * false arm), or the callback's own abandon payload. Narrows on `.ok`, then
- * on `"violations" in result`.
+ * 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`.
  */
-type WitnessedWriteResult<Rels extends SchemaRelations, R> =
-	| { readonly ok: true; readonly generation: bigint }
-	| { readonly ok: false; readonly violations: readonly Violation<Rels>[] }
-	| { readonly ok: false; readonly abandoned: AbandonedPayload<R> }
+function isAbandonedOutcome<Rels extends SchemaRelations, R>(
+	outcome: { readonly ok: false; readonly abandoned: AbandonedPayload<R> },
+	sentinel: Abandon<AbandonedPayload<R>>
+): outcome is { readonly ok: false; readonly abandoned: AbandonedPayload<R> } & WriteResult<Rels, R> {
+	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<Rels extends SchemaRelations, R>(
+	sentinel: Abandon<AbandonedPayload<R>>
+): WriteResult<Rels, R> {
+	const outcome = Object.freeze({ ok: false as const, abandoned: sentinel.payload })
+	if (!isAbandonedOutcome<Rels, R>(outcome, sentinel)) {
+		throw errors.new("bumbledb abandon outcome construction incomplete")
+	}
+	return outcome
+}
 
 /**
  * One live write transaction: the submitted delta with the engine's
@@ -210,10 +251,17 @@ interface Tx<Rels extends SchemaRelations> {
 	/**
 	 * Records one insert. Omitted fresh fields are MINTED through the
 	 * engine's alloc lane and returned as bare bigints; supplying them instead
-	 * preserves identity (the resupply idiom). Returns the relation's
-	 * fresh cells, minted or resupplied.
+	 * preserves identity (the resupply idiom). Returns `{ changed, ...fresh }`
+	 * (ruled 2026-07-23, R11): the engine's changed-state report — the Rust
+	 * surface's `insert(&fact) -> bool` bijection `delete` always honored —
+	 * beside the relation's fresh cells, minted or resupplied. The
+	 * idempotent-replay lane reads the bit from the insert itself; no extra
+	 * `contains` round trip exists. The flattened shape cannot carry a FRESH
+	 * cell literally named `changed` beside the report, so admission refuses
+	 * that one spelling ({@link refuseShadowedChanged}) — never a silent
+	 * shadow here.
 	 */
-	insert<R extends MemberRelation<Rels>>(relation: R, fact: InsertFact<R>): Minted<R>
+	insert<R extends MemberRelation<Rels>>(relation: R, fact: InsertFact<R>): { readonly changed: boolean } & Minted<R>
 	/** Records one delete; `true` iff the final state changed. */
 	delete<R extends MemberRelation<Rels>>(relation: R, fact: Fact<R>): boolean
 	/** Final-state membership of one complete fact. */
@@ -236,19 +284,20 @@ interface Tx<Rels extends SchemaRelations> {
 }
 
 /**
- * The read view one `db.read(fn)` call scopes: an MVCC snapshot pinned at
- * its generation, valid EXACTLY for the synchronous extent of `fn`. The
- * value is invalidated when `fn` returns — every later verb call throws a
- * typed used-after-scope error; the underlying snapshot (and its LMDB
- * reader slot) is already closed. No close spelling exists here because
- * there is nothing the host could ever need to close.
+ * The read view one `db.read(fn)` call scopes — or one `using snap =
+ * db.read()` acquisition owns (ruled 2026-07-23, R12: lifetimes are
+ * disposables, never `close()`). The callback form invalidates the value
+ * when `fn` returns; the `using` form releases it at scope exit through
+ * `Symbol.dispose` — either way the release is deterministic and
+ * scope-shaped, every later verb call throws a typed used-after-scope
+ * error, and the underlying snapshot (with its LMDB reader slot) is
+ * already closed.
  */
-interface ReadScope<Rels extends SchemaRelations> {
+interface ReadScope<Rels extends SchemaRelations> extends Disposable {
 	/**
-	 * The committed generation this scope witnessed — captured atomically
-	 * with the snapshot: writes are synchronous and this process holds the
-	 * store's only write handle, so nothing can commit between the snapshot
-	 * open and the generation read.
+	 * The committed generation this scope witnessed — carried by the
+	 * snapshot open itself (one crossing, inside the snapshot's own
+	 * transaction), so it is atomic with the snapshot by construction.
 	 */
 	readonly generation: bigint
 	/** Full-relation export in row-id order, decoded to bare structural facts. */
@@ -277,6 +326,16 @@ interface ReadScope<Rels extends SchemaRelations> {
 	 * execution spelling ({@link Prepared} carries no `execute`).
 	 */
 	execute<Row, Params extends ParamsRecord>(prepared: Prepared<Rels, Row, Params>, params: Params): Row[]
+	/**
+	 * Plan introspection as data (ruled 2026-07-23, R13): runs the prepared
+	 * query against this scope's snapshot with counting instrumentation
+	 * (the engine's ANALYZE semantics) and returns the structured
+	 * {@link Explain} report — plan sections and counters as plain values,
+	 * so the host reads what the engine did with its query without a
+	 * second toolchain. A diagnostic surface, EXPLICITLY UNFROZEN: the
+	 * shape follows the plan representation wherever it goes.
+	 */
+	explain<Row, Params extends ParamsRecord>(prepared: Prepared<Rels, Row, Params>, params: Params): Explain
 }
 
 /**
@@ -326,6 +385,14 @@ interface Db<Rels extends SchemaRelations> {
 	 * when `fn` returns — a used-after-scope call throws a typed error.
 	 */
 	read<T>(fn: (snap: ReadScope<Rels>) => T): T
+	/**
+	 * The `using` acquisition (ruled 2026-07-23, R12): `using snap =
+	 * db.read()` — the caller owns the scope's lifetime, and the scope's
+	 * `Symbol.dispose` releases the snapshot deterministically at scope
+	 * exit, in the language's own syntax. Lifetimes are disposables, never
+	 * `close()`.
+	 */
+	read(): ReadScope<Rels>
 	/** `db.scan(r)` === `db.read(snap => snap.scan(r))` — the symmetry rule. */
 	scan<R extends MemberRelation<Rels>>(relation: R): Fact<R>[]
 	/** `db.get(r, k)` === `db.read(snap => snap.get(r, k))` — the symmetry rule. */
@@ -340,12 +407,18 @@ interface Db<Rels extends SchemaRelations> {
 	contains<R extends MemberRelation<Rels>>(relation: R, fact: Fact<R>): boolean
 	/** `db.execute(p, params)` === `db.read(snap => snap.execute(p, params))` — the symmetry rule. */
 	execute<Row, Params extends ParamsRecord>(prepared: Prepared<Rels, Row, Params>, params: Params): Row[]
+	/** `db.explain(p, params)` === `db.read(snap => snap.explain(p, params))` — the symmetry rule (R13). */
+	explain<Row, Params extends ParamsRecord>(prepared: Prepared<Rels, Row, Params>, params: Params): Explain
 	/**
 	 * One delta transaction: builds the delta synchronously through `fn`,
 	 * commits, and returns the domain outcome. A throw from `fn` aborts
-	 * the delta (LMDB untouched) and rethrows wrapped.
+	 * the delta (LMDB untouched) and rethrows wrapped. `fn` may decline to
+	 * commit by returning {@link abandon}`(payload)` (ruled 2026-07-23,
+	 * R10): the transaction rolls back — nothing is committed, not even an
+	 * empty commit — and the outcome is `{ ok: false, abandoned: payload }`,
+	 * an arm the result type carries exactly when the callback can abandon.
 	 */
-	write(fn: DeltaBuild<Rels>): WriteResult<Rels>
+	write<R = void>(fn: DeltaBuild<Rels, R>): WriteResult<Rels, R>
 	/**
 	 * The ONE witnessed-write form: snapshot → `fn` (premise reads via
 	 * `snap`, delta via `tx`) → witnessed commit, which lands only if no
@@ -364,7 +437,7 @@ interface Db<Rels extends SchemaRelations> {
 	 * `{ ok: false, abandoned: payload }` and NO commit (not even an empty
 	 * one) is issued.
 	 */
-	writeWitnessed<R>(fn: (snap: ReadScope<Rels>, tx: Tx<Rels>) => R): WitnessedWriteResult<Rels, R>
+	writeWitnessed<R>(fn: (snap: ReadScope<Rels>, tx: Tx<Rels>) => R): WriteResult<Rels, R>
 	/**
 	 * Prepares a query value built against THIS schema (identity is the
 	 * membership rule): lowers it to the engine IR, pins the plan, and
@@ -507,18 +580,16 @@ function isThenable(value: unknown): boolean {
 
 /**
  * Narrows a keyed-get middle argument to a statement value (vs a key
- * object): only statement values carry `data.kind` — no fact cell shape
- * (bool, bigint, string, bytes, `{ start, end }`) ever does, so the probe
- * never misreads a key object whose relation declares a field named `data`.
+ * object) through the statement module's admission brand — a
+ * REPRESENTATION, never a shape probe: fact cell shapes are structurally
+ * OPEN (an interval value carrying an excess `kind` property is a legal
+ * cell), so no property probe could ever be sound here, but no host-built
+ * key object can spell the module-private brand symbol.
  */
 function isStatementValue<R extends AnyRelation, P extends readonly string[]>(
 	value: KeyFact<R> | KeyStatement<R, P>
 ): value is KeyStatement<R, P> {
-	if (typeof value !== "object" || !("data" in value)) {
-		return false
-	}
-	const data: unknown = value.data
-	return typeof data === "object" && data !== null && "kind" in data
+	return isStatement(value)
 }
 
 /**
@@ -569,7 +640,11 @@ interface Tables {
  * Builds the id-resolution tables from the manifest, verifying the SDK's
  * positional mirror against the engine's reported order — any drift
  * (count, kind, id, or membership) is a construction-time failure, never a
- * silent misattribution of a violation to the wrong statement value.
+ * silent misattribution of a violation to the wrong statement value. The
+ * declaration-ordinal law the query lowering leans on is verified in the
+ * same walks: relation ids and sealed field ids both equal declaration
+ * order, so a constructed `Tables` IS the proof and `prepare` inherits it
+ * structurally — never a silently misaddressed query.
  */
 function tablesOf(theory: AnySchema, manifest: Manifest): Tables {
 	const entries = materializedEntries(theory)
@@ -596,6 +671,13 @@ function tablesOf(theory: AnySchema, manifest: Manifest): Tables {
 		for (const field of relation.fields) {
 			fieldIds.set(field.name, field.id)
 		}
+		sealedFieldsOf(member).forEach(function verifyField(declared, fieldOrdinal) {
+			if (fieldIds.get(declared.name) !== fieldOrdinal) {
+				throw errors.new(
+					`bumbledb manifest drift: ${relation.name}.${declared.name} has engine field id ${fieldIds.get(declared.name)}, its sealed ordinal is ${fieldOrdinal}`
+				)
+			}
+		})
 		let primaryKey: PrimaryKey | undefined
 		entries.forEach(function firstOwnedKey(entry, index) {
 			if (primaryKey === undefined && entry.key !== undefined && entry.key.owner === relation.name) {
@@ -604,11 +686,17 @@ function tablesOf(theory: AnySchema, manifest: Manifest): Tables {
 		})
 		relations.set(relation.name, Object.freeze({ id: relation.id, member, fieldIds, primaryKey }))
 	}
-	for (const name of Object.keys(theory.relations)) {
-		if (!relations.has(name)) {
+	Object.keys(theory.relations).forEach(function verifyRelation(name, ordinal) {
+		const entry = relations.get(name)
+		if (entry === undefined) {
 			throw errors.new(`bumbledb manifest drift: schema relation ${name} is not in the manifest`)
 		}
-	}
+		if (entry.id !== ordinal) {
+			throw errors.new(
+				`bumbledb manifest drift: relation ${name} has engine id ${entry.id}, its declaration ordinal is ${ordinal} — query lowering depends on declaration order = ids`
+			)
+		}
+	})
 	return Object.freeze({ relations, statements: Object.freeze(entries) })
 }
 
@@ -619,14 +707,20 @@ interface PointReads {
 }
 
 /**
- * One read scope's PRIVATE lifetime record: its live snapshot handle, its
- * liveness flag (flipped exactly when the owning `read`/`writeWitnessed`
- * callback returns), and its owning store's identity token. Held in
- * {@link scopeStates} — the snapshot handle is never a public value.
+ * One read scope's PRIVATE lifetime record: its live snapshot handle, the
+ * generation it witnessed (carried by the snapshot open itself — one
+ * crossing, finding 016), its liveness flag (flipped when the owning
+ * `read`/`writeWitnessed` callback returns, or by the scope's own
+ * `Symbol.dispose`), its close latch (`closed` — the snapshot closes
+ * exactly once, whichever of the owner and the dispose gets there first),
+ * and its owning store's identity token. Held in {@link scopeStates} —
+ * the snapshot handle is never a public value.
  */
 interface ScopeState {
 	readonly handle: SnapshotHandle
+	readonly generation: bigint
 	live: boolean
+	closed: boolean
 	readonly owner: object
 }
 
@@ -900,10 +994,11 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 	/**
 	 * Builds one {@link ReadScope} over a live scope state. Every verb
 	 * asserts liveness first: the owning call flips `state.live` the moment
-	 * its callback returns, so a leaked scope is a typed refusal forever
+	 * its callback returns (or the scope's own `Symbol.dispose` does, for a
+	 * `using`-acquired scope), so a leaked scope is a typed refusal forever
 	 * after.
 	 */
-	function makeScope(state: ScopeState, generation: bigint): ReadScope<Rels> {
+	function makeScope(state: ScopeState): ReadScope<Rels> {
 		function assertLive(): void {
 			if (!state.live) {
 				throw errors.new("bumbledb read scope is invalidated — its owning read callback already returned")
@@ -940,12 +1035,27 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 			})
 			return decodeAnswers<Row>(plan.finds, rows)
 		}
+		function explain<Row, Params extends ParamsRecord>(prepared: Prepared<Rels, Row, Params>, params: Params): Explain {
+			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(): void {
+			state.live = false
+			closeScopeState(state)
+		}
 		const scope: ReadScope<Rels> = Object.freeze({
-			generation,
+			generation: state.generation,
 			scan,
 			get: reads.get,
 			contains: reads.contains,
-			execute
+			execute,
+			explain,
+			[Symbol.dispose]: dispose
 		})
 		scopeStates.set(scope, state)
 		return scope
@@ -959,50 +1069,52 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 	 */
 	let liveSnapshots = 0
 
-	/** Opens one snapshot and its scope state (live until the owner flips it). */
+	/**
+	 * Opens one snapshot and its scope state (live until the owner flips
+	 * it). The witnessed generation rides the snapshot open itself — one
+	 * crossing carries both (finding 016), so the fault-pairing close
+	 * branch a second `dbGeneration` call needed is structurally gone.
+	 */
 	function openScopeState(): ScopeState {
-		const snapHandle = bridged("open bumbledb snapshot", function openSnapshot() {
+		const opened = bridged("open bumbledb snapshot", function openSnapshot() {
 			return native.dbSnapshot(handle)
 		})
 		liveSnapshots += 1
-		return { handle: snapHandle, live: true, owner }
+		return { handle: opened.snapshot, generation: opened.generation, live: true, closed: false, owner }
 	}
 
-	/** Closes a scope's snapshot after the owner invalidated it. */
+	/**
+	 * Closes a scope's snapshot after the owner invalidated it — a LATCH:
+	 * the snapshot closes exactly once, whichever of the owning call and
+	 * the scope's own `Symbol.dispose` gets there first, so an early
+	 * in-callback disposal never double-closes (and never double-counts
+	 * the census).
+	 */
 	function closeScopeState(state: ScopeState): void {
+		if (state.closed) {
+			return
+		}
+		state.closed = true
 		bridged("close bumbledb snapshot", function closeSnapshot() {
 			native.snapshotClose(state.handle)
 		})
 		liveSnapshots -= 1
 	}
 
-	/**
-	 * Reads the committed generation for a just-opened scope, closing the
-	 * scope's snapshot when the read faults: `dbGeneration` opens a transient
-	 * engine read txn, so reader-table exhaustion is precisely the state in
-	 * which it throws — with one snapshot already open. An unpaired fault
-	 * here would park a snapshot worker and consume one of the engine's
-	 * reader slots FOREVER (and undercount the liveSnapshots census), each
-	 * fault ratcheting toward ReadersFull-for-the-process's-lifetime.
-	 */
-	function generationForScope(state: ScopeState): bigint {
-		const generation = errors.trySync(function readGeneration() {
-			return bridged("read bumbledb generation", function callGeneration() {
-				return native.dbGeneration(handle)
-			})
-		})
-		if (generation.error) {
-			state.live = false
-			closeScopeState(state)
-			throw generation.error
-		}
-		return generation.data
-	}
-
-	function read<T>(fn: (snap: ReadScope<Rels>) => T): T {
+	function read<T>(fn: (snap: ReadScope<Rels>) => T): T
+	function read(): ReadScope<Rels>
+	function read<T>(fn?: (snap: ReadScope<Rels>) => T): T | ReadScope<Rels> {
 		const state = openScopeState()
-		const generation = generationForScope(state)
-		const scope = makeScope(state, generation)
+		const scope = makeScope(state)
+		if (fn === undefined) {
+			/**
+			 * The `using` acquisition (R12): the caller owns the lifetime —
+			 * `using snap = db.read()` — and the scope's `Symbol.dispose`
+			 * is the deterministic release, scope-shaped in the language's
+			 * own syntax.
+			 */
+			return scope
+		}
 		const result = errors.trySync(function runRead() {
 			return fn(scope)
 		})
@@ -1057,6 +1169,12 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		})
 	}
 
+	function explain<Row, Params extends ParamsRecord>(prepared: Prepared<Rels, Row, Params>, params: Params): Explain {
+		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
@@ -1085,21 +1203,25 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 				})
 			}
 		})
-		function insert<R extends MemberRelation<Rels>>(relation: R, fact: InsertFact<R>): Minted<R> {
+		function insert<R extends MemberRelation<Rels>>(
+			relation: R,
+			fact: InsertFact<R>
+		): { readonly changed: boolean } & Minted<R> {
 			assertLive()
 			const entry = resolveOrdinary(relation)
 			const txHandle = resolveTx()
-			const values = recordOf(fact)
+			/** The one spread copy of the write path: `mintFreshCells` writes minted cells in place, and they must never land in the caller's own fact object. */
+			const values: Record<string, unknown> = { ...recordOf(fact) }
 			const fresh = mintFreshCells(txHandle, entry, relation, values)
 			const row = rowOf(relation.data, values)
-			bridged("bumbledb tx insert", function record() {
-				native.txInsert(txHandle, entry.id, row)
+			const changed = bridged("bumbledb tx insert", function record() {
+				return native.txInsert(txHandle, entry.id, row)
 			})
-			Object.freeze(fresh)
-			if (!isMintedFresh(relation, fresh)) {
-				throw errors.new(`relation ${relation.name}: minted fresh record is incomplete`)
+			const inserted: Readonly<Record<string, FactValue | boolean>> = Object.freeze({ changed, ...fresh })
+			if (!isInserted(relation, inserted)) {
+				throw errors.new(`relation ${relation.name}: insert return record is incomplete`)
 			}
-			return fresh
+			return inserted
 		}
 		function remove<R extends MemberRelation<Rels>>(relation: R, fact: Fact<R>): boolean {
 			assertLive()
@@ -1122,7 +1244,7 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		return { tx, spend }
 	}
 
-	function runDelta(txHandle: TxHandle, fn: DeltaBuild<Rels>): WriteResult<Rels> {
+	function runDelta<R>(txHandle: TxHandle, fn: DeltaBuild<Rels, R>): WriteResult<Rels, R> {
 		const made = makeTx(function resolveTx() {
 			return txHandle
 		})
@@ -1152,6 +1274,18 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 				"bumbledb write callback returned a thenable — the delta build is synchronous; an async callback is refused, nothing was committed"
 			)
 		}
+		if (isAbandon(built.data)) {
+			/**
+			 * The caller's explicit decline to commit (R10): the sentinel's
+			 * contract is unconditional — roll back, nothing committed, not
+			 * even an empty commit; commit is unreachable for a sentinel
+			 * result.
+			 */
+			bridged("abort bumbledb write transaction", function abort() {
+				native.txAbort(txHandle)
+			})
+			return abandonedOutcome<Rels, R>(built.data)
+		}
 		const committed = errors.trySync(function commitDelta() {
 			return bridged("commit bumbledb write transaction", function commit() {
 				return native.txCommit(txHandle)
@@ -1182,16 +1316,11 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		})
 	}
 
-	function write(fn: DeltaBuild<Rels>): WriteResult<Rels> {
-		const begun = errors.trySync(function beginDelta() {
-			return bridged("begin bumbledb write transaction", function begin() {
-				return native.dbWriteBegin(handle)
-			})
+	function write<R = void>(fn: DeltaBuild<Rels, R>): WriteResult<Rels, R> {
+		const txHandle = bridged(`begin bumbledb write transaction (live snapshots: ${liveSnapshots})`, function begin() {
+			return native.dbWriteBegin(handle)
 		})
-		if (begun.error) {
-			throw errors.wrap(begun.error, `begin bumbledb write transaction (live snapshots at fault: ${liveSnapshots})`)
-		}
-		return runDelta(begun.data, fn)
+		return runDelta(txHandle, fn)
 	}
 
 	/**
@@ -1199,7 +1328,7 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 	 * attempt's snapshot: the committed generation, or the engine's
 	 * complete violation set as data.
 	 */
-	function commitWitnessed<R>(state: ScopeState, txHandle: TxHandle): WitnessedWriteResult<Rels, R> {
+	function commitWitnessed<R>(state: ScopeState, txHandle: TxHandle): WriteResult<Rels, R> {
 		const committed = errors.trySync(function commitWitnessedDelta() {
 			return bridged("commit bumbledb witnessed write transaction", function commit() {
 				return native.txCommit(txHandle)
@@ -1235,12 +1364,9 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 	 * `undefined` exactly when the generation moved and the whole callback
 	 * must rerun on a fresh snapshot.
 	 */
-	function witnessedAttempt<R>(
-		fn: (snap: ReadScope<Rels>, tx: Tx<Rels>) => R
-	): WitnessedWriteResult<Rels, R> | undefined {
+	function witnessedAttempt<R>(fn: (snap: ReadScope<Rels>, tx: Tx<Rels>) => R): WriteResult<Rels, R> | undefined {
 		const state = openScopeState()
-		const generation = generationForScope(state)
-		const scope = makeScope(state, generation)
+		const scope = makeScope(state)
 		const pending: { tx: TxHandle | undefined } = { tx: undefined }
 		function beginWitnessed(): TxHandle | undefined {
 			const witnessed = bridged("begin witnessed bumbledb write transaction", function begin() {
@@ -1304,7 +1430,7 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		if (isAbandon(built.data)) {
 			abortPending()
 			closeScopeState(state)
-			return Object.freeze({ ok: false, abandoned: built.data.payload })
+			return abandonedOutcome<Rels, R>(built.data)
 		}
 		const late = errors.trySync(function resolveCommitTx() {
 			if (pending.tx === undefined) {
@@ -1340,7 +1466,7 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 	 * error, never a loop — retry is host policy, and this is the host
 	 * policy's own honesty bound).
 	 */
-	function writeWitnessed<R>(fn: (snap: ReadScope<Rels>, tx: Tx<Rels>) => R): WitnessedWriteResult<Rels, R> {
+	function writeWitnessed<R>(fn: (snap: ReadScope<Rels>, tx: Tx<Rels>) => R): WriteResult<Rels, R> {
 		for (let attempts = 0; attempts < WITNESSED_ATTEMPT_CAP; attempts += 1) {
 			const attempt = witnessedAttempt(fn)
 			if (attempt !== undefined) {
@@ -1353,45 +1479,12 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		)
 	}
 
-	/**
-	 * Verifies the declaration-ordinal law the query lowering leans on
-	 * against the live manifest tables: relation ids and sealed field ids
-	 * both equal declaration order (`dbManifest` is the engine's own
-	 * pinning of it). Any drift is a construction-time failure here, never
-	 * a silently misaddressed query.
-	 */
-	function assertOrdinalAlignment(): void {
-		Object.keys(theory.relations).forEach(function verifyRelation(name, ordinal) {
-			const entry = tables.relations.get(name)
-			if (entry === undefined || entry.id !== ordinal) {
-				throw errors.new(
-					`bumbledb manifest drift: relation ${name} has engine id ${entry?.id}, its declaration ordinal is ${ordinal} — query lowering depends on declaration order = ids`
-				)
-			}
-			const member = theory.relations[name]
-			if (member === undefined) {
-				throw errors.new(`bumbledb manifest drift: schema ${theory.name} lost relation ${name}`)
-			}
-			const sealed = sealedFieldsOf(member).map(function fieldName(declared) {
-				return declared.name
-			})
-			sealed.forEach(function verifyField(fieldName, fieldOrdinal) {
-				if (entry.fieldIds.get(fieldName) !== fieldOrdinal) {
-					throw errors.new(
-						`bumbledb manifest drift: ${name}.${fieldName} has engine field id ${entry.fieldIds.get(fieldName)}, its sealed ordinal is ${fieldOrdinal}`
-					)
-				}
-			})
-		})
-	}
-
 	function prepare<Row, Params extends ParamsRecord>(q: Query<Rels, Row, Params>): Prepared<Rels, Row, Params> {
 		if (q.schema !== theory) {
 			throw errors.new(
 				`query was built against schema ${q.schema.name}, not the identical schema value this store opened with — schema identity is the membership rule`
 			)
 		}
-		assertOrdinalAlignment()
 		const program = lowerQuery(q)
 		const outcome = bridged("prepare bumbledb program", function callPrepare() {
 			return native.dbPrepare(handle, program)
@@ -1438,6 +1531,7 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		get,
 		contains,
 		execute,
+		explain,
 		write,
 		writeWitnessed,
 		prepare
@@ -1508,6 +1602,27 @@ const ErrNewtypeMismatch = errors.new(
 	"bumbledb newtypeMismatch: a statement pairs faces whose newtypes disagree — the faces of a dependency agree on their newtype, or neither carries one"
 )
 
+/**
+ * `Tx.insert` returns the flattened `{ changed, ...fresh }` record (R11),
+ * where the spread wins: a FRESH field literally named `changed` would
+ * shadow the engine's changed-state report on every insert of its
+ * relation. No field name is reserved SILENTLY — the one unspeakable
+ * spelling is refused here at admission, before any store is touched.
+ * Supplied (non-fresh) fields named `changed` never enter the return
+ * record and stay legal.
+ */
+function refuseShadowedChanged(theory: AnySchema): void {
+	for (const [name, member] of Object.entries(theory.relations)) {
+		for (const declared of sealedFieldsOf(member)) {
+			if (declared.name === "changed" && isFreshField(declared.field)) {
+				throw errors.new(
+					`relation ${name}: a fresh field named "changed" would shadow tx.insert's changed-state report in its { changed, ...fresh } return (R11) — rename the fresh field; a supplied field named "changed" stays legal (only fresh cells ride the return)`
+				)
+			}
+		}
+	}
+}
+
 /**
  * The one admission path both verbs share: canonical-path cache lookup
  * first (a hit returns the SAME `Db` value for the identical theory, a
@@ -1525,6 +1640,7 @@ function admit<Rels extends SchemaRelations>(
 	storePath: string,
 	theory: Schema<Rels>
 ): Db<Rels> {
+	refuseShadowedChanged(theory)
 	const canonical = path.resolve(storePath)
 	const cached = openStores.get(canonical)
 	if (cached !== undefined) {
@@ -1594,12 +1710,12 @@ const Db = Object.freeze({
 	 * one schema-independent read path (no theory, no fingerprint check; the
 	 * store rebirth tool's entry). Lives beside `open`/`create` so the path
 	 * law stays in one place: the same `node:path.resolve` canonicalization,
-	 * applied here. The value is NOT cached and carries no close: the
-	 * engine-side handle (and the store's exclusive lock) is reclaimed by GC
-	 * — reclamation only, never correctness. A store not yet adopted rejects
-	 * with the typed `ErrExhumeNoDescriptor` (the remedy: one
-	 * fingerprint-matching `Db.open` under the creating schema back-fills
-	 * the descriptor).
+	 * applied here. The value is NOT cached and is a DISPOSABLE lifetime
+	 * (R12) — `using exhumed = await Db.exhume(path)` releases the engine
+	 * handle and the store's exclusive lock at scope exit, so a same-path
+	 * reopen never waits on GC. A store not yet adopted rejects with the
+	 * typed `ErrExhumeNoDescriptor` (the remedy: one fingerprint-matching
+	 * `Db.open` under the creating schema back-fills the descriptor).
 	 */
 	async exhume(storePath: string): Promise<Exhumed> {
 		return exhumeStore(path.resolve(storePath))
@@ -1608,6 +1724,7 @@ const Db = Object.freeze({
 
 export type {
 	Abandon,
+	AbandonedArm,
 	DeclaredKeyFact,
 	DeltaBuild,
 	MemberRelation,
@@ -1616,7 +1733,6 @@ export type {
 	ReadScope,
 	Tx,
 	Violation,
-	WitnessedWriteResult,
 	WriteResult
 }
 export { abandon, Db, ErrNewtypeMismatch, ErrWitnessedLivelock, WITNESSED_ATTEMPT_CAP }