@bjornpagen/bumbledb 0.6.0 → 0.7.0

package/src/exhume.ts

@@ -17,11 +17,20 @@
  * reconstructs a `Schema` value from the descriptor — that inverse mapping
  * is deliberately out of scope; the rebirth tool keys by name.
  *
- * ZERO CLOSABLES: no value here carries a close, dispose, or release
- * spelling. The engine-side handle (and the store's exclusive advisory
- * lock) is reclaimed when the `Exhumed` value is garbage-collected —
- * reclamation only, never correctness: the store is never written through
- * this surface, so there is nothing to flush.
+ * LIFETIMES ARE DISPOSABLES, never `close()` (ruled 2026-07-23, R12): the
+ * `Exhumed` value implements `Symbol.dispose` — teardown is synchronous
+ * (one environment close) — and `using` is the documented idiom:
+ *
+ *   using exhumed = await Db.exhume(path)
+ *
+ * Disposal releases the engine handle AND the store's exclusive advisory
+ * lock deterministically, scope-shaped in the language's own syntax, so a
+ * same-path reopen (retry after a half-failed migration, a second forensic
+ * read) never waits on an unforceable GC finalizer. Every verb after
+ * disposal is a typed used-after-dispose refusal. The engine-side drop
+ * remains the reclamation-only backstop for a collected-but-undisposed
+ * value; the store is never written through this surface, so there is
+ * nothing to flush.
  */
 
 import * as errors from "@superbuilders/errors"
@@ -116,9 +125,11 @@ interface ExhumedDescriptor {
 /**
  * One exhumed store: the self-described relation shapes and the raw facts
  * by relation name. Read-only by construction — no write verb, no prepare
- * verb, no close (zero closables; the engine handle is GC-reclaimed).
+ * verb. A DISPOSABLE lifetime (R12): `Symbol.dispose` releases the engine
+ * handle and the store's exclusive lock deterministically; `using` is the
+ * idiom, and a disposed value's verbs are typed refusals.
  */
-interface Exhumed {
+interface Exhumed extends Disposable {
 	/** The store's own persisted schema, as its creator declared it. */
 	readonly descriptor: ExhumedDescriptor
 	/**
@@ -167,9 +178,10 @@ function descriptorOf(manifest: Manifest): ExhumedDescriptor {
  * The bridge's three domain refusals become the typed error constants
  * ({@link ErrExhumeNoDescriptor}, {@link ErrExhumeFormatMismatch},
  * {@link ErrExhumeCorruption}), each carrying the engine's message in its
- * wrap. The returned value is NOT cached: exhume is a forensic read, and
- * caching would pin the store's exclusive lock for the process's life —
- * GC reclamation is the whole lifecycle.
+ * wrap. The returned value is NOT cached: exhume is a forensic read whose
+ * lifetime is the caller's `using` scope — disposal releases the store's
+ * exclusive lock deterministically (R12), so the path is reusable the
+ * moment the scope exits.
  */
 function exhumeStore(canonical: string): Exhumed {
 	const outcome = bridged(`exhume bumbledb store at ${canonical}`, function callExhume() {
@@ -199,7 +211,27 @@ function exhumeStore(canonical: string): Exhumed {
 			})
 		)
 	}
+	/** The lifetime record: flipped once by {@link dispose}, judged by every verb. */
+	const lifetime = { live: true }
+	/**
+	 * The `Symbol.dispose` teardown (R12): idempotent — a manual call inside
+	 * a `using` scope must not double-close — and deterministic: the engine
+	 * handle and the store's exclusive lock release HERE, never on a GC
+	 * schedule.
+	 */
+	function dispose(): void {
+		if (!lifetime.live) {
+			return
+		}
+		lifetime.live = false
+		bridged(`close bumbledb exhumed store at ${canonical}`, function close() {
+			native.exhumeClose(handle)
+		})
+	}
 	function scan(relation: string): readonly ExhumedFact[] {
+		if (!lifetime.live) {
+			throw errors.new("bumbledb exhumed store is disposed — its using scope already exited")
+		}
 		const names = fieldNames.get(relation)
 		if (names === undefined) {
 			throw errors.new(`bumbledb exhume: the store's descriptor declares no relation ${relation}`)
@@ -209,6 +241,11 @@ function exhumeStore(canonical: string): Exhumed {
 		})
 		return Object.freeze(
 			rows.map(function factOf(row): ExhumedFact {
+				if (row.length !== names.length) {
+					throw errors.new(
+						`bumbledb exhume drift: relation ${relation} row arity ${row.length} does not match the ${names.length} descriptor fields`
+					)
+				}
 				const fact: Record<string, FactValue> = {}
 				names.forEach(function pair(name, index) {
 					const cell = row[index]
@@ -223,7 +260,7 @@ function exhumeStore(canonical: string): Exhumed {
 			})
 		)
 	}
-	return Object.freeze({ descriptor, scan })
+	return Object.freeze({ descriptor, scan, [Symbol.dispose]: dispose })
 }
 
 export type { Exhumed, ExhumedAxiom, ExhumedDescriptor, ExhumedFact, ExhumedField, ExhumedRelation }

package/src/face.ts

@@ -121,18 +121,25 @@ type FaceFields<S extends FaceSource> = S extends AnySelected
  * mirrors, recipe 29's mixed-width zones) and the width slot reads
  * `undefined` for every interval. Elements stay bound: u64-vs-i64 interval
  * pairs still mismatch. The ROSTER slot is SDK-only structure (the engine's
- * wire carries plain u64s): a closed reference contributes its handle
- * union, every other kind `undefined`, so a plain u64 face cannot pair with
- * a closed `[id]` face — the vocabulary's own descriptor (`Kind.id`) is the
- * ONE spelling of a closed reference at this surface, and a bare column
- * cannot alias a vocabulary through a declared law. The runtime twin is the
+ * wire carries plain u64s): a closed reference contributes its vocabulary
+ * NAME literal paired with its handle union — the faithful encoding of the
+ * runtime's roster VALUE-IDENTITY judgment, so two same-shaped vocabularies
+ * mismatch at compile time exactly as they throw at construction — every
+ * other kind `undefined`, so a plain u64 face cannot pair with a closed
+ * `[id]` face — the vocabulary's own descriptor (`Kind.id`) is the ONE
+ * spelling of a closed reference at this surface, and a bare column cannot
+ * alias a vocabulary through a declared law. The runtime twin is the
  * statement constructors' roster-identity walk (`statements.ts`).
  */
 type ShapeOf<F extends AnyField> = readonly [
 	F["kind"],
 	F extends { readonly element: unknown } ? undefined : F extends { readonly width: infer W } ? W : undefined,
 	F extends { readonly element: infer E } ? E : undefined,
-	F extends { readonly closed: { readonly handles: readonly (infer H extends string)[] } } ? H : undefined
+	F extends {
+		readonly closed: { readonly name: infer N extends string; readonly handles: readonly (infer H extends string)[] }
+	}
+		? readonly [N, H]
+		: undefined
 ]
 
 /** One field's structural shape within a declared field block (`undefined` when the name is foreign). */

package/src/fields.ts

@@ -50,14 +50,19 @@ function span(start: bigint, end: bigint): IntervalValue {
  * A closed relation's roster as seen from a referencing field: the handle
  * namespace `where()` selections and ground axioms resolve bare handle ids
  * through (the macro's own rule: a handle is legal exactly on a field that
- * references a closed relation). The handle union is PRECISE — `H` carries
- * the literal handle names in declaration order (the unbound `string`
- * default exists only as the fallback where no roster is in scope); the
- * runtime twin is the same frozen declaration-order array that was always
+ * references a closed relation). The roster is PRECISE in BOTH slots —
+ * `Name` carries the vocabulary's literal name and `H` the literal handle
+ * names in declaration order (the unbound `string` defaults exist only as
+ * the fallback where no roster is in scope). The name literal is
+ * load-bearing: the runtime twins judge roster VALUE IDENTITY, so two
+ * same-shaped vocabularies (`Yes/No` twice) are distinct — carrying the
+ * name makes the type the faithful encoding of that judgment, and a
+ * cross-vocabulary pairing fails at compile time, not construction. The
+ * runtime twin is the same frozen declaration-order value that was always
  * there.
  */
-interface ClosedRoster<H extends string = string> {
-	readonly name: string
+interface ClosedRoster<Name extends string = string, H extends string = string> {
+	readonly name: Name
 	readonly handles: readonly H[]
 }
 
@@ -136,9 +141,9 @@ interface IntervalField<
  * map and JoinOk, which compare kind/class/width/element. Terminal: no
  * `.fresh` — a vocabulary's rows are ground axioms, never minted.
  */
-interface ClosedIdField<H extends string = string> {
+interface ClosedIdField<Name extends string = string, H extends string = string> {
 	readonly kind: "u64"
-	readonly closed: ClosedRoster<H>
+	readonly closed: ClosedRoster<Name, H>
 }
 
 /** Any field descriptor, whatever its kind or marks. */
@@ -238,14 +243,18 @@ function intervalLiteral(element: "u64" | "i64", value: unknown): LiteralSpec {
 }
 
 /**
- * Rejects a declaration name that JavaScript would re-order. Declaration
- * order = ordinal ids is the law relations, columns, and schemas all lean
- * on, and it is carried by object-literal key order — which ECMA-262's
+ * Rejects a declaration name that JavaScript would re-order, and a name
+ * that would break the class map's coordinate encoding. Declaration order =
+ * ordinal ids is the law relations, columns, and schemas all lean on, and
+ * it is carried by object-literal key order — which ECMA-262's
  * OrdinaryOwnPropertyKeys breaks for integer-index keys (they enumerate
- * first, ascending, regardless of where they were written). An
- * integer-index name would silently reorder its declaration, so it is a
- * construction error, exactly as an unparseable name is a macro expansion
- * error.
+ * first, ascending, regardless of where they were written). A `.` in a name
+ * would make the law engine's `${relation}.${field}` coordinate template
+ * non-injective at BOTH tiers (relation `"A.B"` field `"x"` and relation
+ * `"A"` field `"B.x"` are one coordinate), silently merging unrelated law
+ * classes — banned here, which is exact macro parity: Rust identifiers
+ * cannot contain dots. Both are construction errors, exactly as an
+ * unparseable name is a macro expansion error.
  */
 function assertDeclarationOrderKey(where: string, name: string): void {
 	if (/^(?:0|[1-9][0-9]*)$/.test(name)) {
@@ -253,6 +262,32 @@ function assertDeclarationOrderKey(where: string, name: string): void {
 			`${where}: name ${name} is an integer index — JavaScript object keys re-order integer indices, breaking the declaration-order law; use a non-numeric name`
 		)
 	}
+	if (name.includes(".")) {
+		throw errors.new(
+			`${where}: name ${name} contains a dot — the law classes key on the \`relation.field\` coordinate, so a dotted name would alias unrelated slots (macro parity: Rust identifiers cannot contain dots); use a dot-free name`
+		)
+	}
+}
+
+/**
+ * Rejects a declaration record whose prototype was replaced. A plain
+ * `__proto__: {...}` property in an object literal is ECMA-262 Annex B's
+ * prototype SETTER, not a data property — the entry never becomes an own
+ * enumerable key, so the declared handle/field/relation would silently
+ * vanish from every `Object.keys`/`Object.entries` walk while the type
+ * tier still admits its name. A non-default prototype on a declaration
+ * literal proves exactly that spelling, so it is a construction error; the
+ * computed spelling `["__proto__"]: {...}` creates an own data property
+ * and is admitted (no name is reserved). `Object.create(null)` records
+ * stay admissible.
+ */
+function assertDeclarationRecord(where: string, record: object): void {
+	const proto = Object.getPrototypeOf(record)
+	if (proto !== Object.prototype && proto !== null) {
+		throw errors.new(
+			`${where}: the declaration record's prototype was replaced — a plain \`__proto__: {...}\` entry is the prototype setter, so its key silently vanishes from the declaration; spell it computed (["__proto__"]: {...}) to declare it as data`
+		)
+	}
 }
 
 /** The one fresh-marked u64 descriptor (the `.fresh` property of the unmarked one). */
@@ -390,6 +425,7 @@ export type {
 }
 export {
 	assertDeclarationOrderKey,
+	assertDeclarationRecord,
 	bool,
 	bytes,
 	i64,

package/src/index.ts

@@ -44,6 +44,7 @@ export type { Count } from "#count.ts"
 export { atLeast, atMost, between, exactly, none } from "#count.ts"
 export type {
 	Abandon,
+	AbandonedArm,
 	DeclaredKeyFact,
 	DeltaBuild,
 	MemberRelation,
@@ -52,7 +53,6 @@ export type {
 	ReadScope,
 	Tx,
 	Violation,
-	WitnessedWriteResult,
 	WriteResult
 } from "#db.ts"
 export { abandon, Db, ErrNewtypeMismatch, ErrWitnessedLivelock, WITNESSED_ATTEMPT_CAP } from "#db.ts"

package/src/lower.ts

@@ -8,6 +8,7 @@
  * fixed key order, so serialization is deterministic (byte-stable).
  */
 
+import * as errors from "@superbuilders/errors"
 import type { AnyClosed } from "#closed.ts"
 import { isClosedMember } from "#closed.ts"
 import type { FaceData } from "#face.ts"
@@ -111,34 +112,38 @@ function lowerStatement(statement: Statement): StatementSpec {
  * Lowers one ordinary relation to its `RelationSpec` fragment: fields in
  * declaration order, each carrying its law-computed class name as the
  * `newtype` (`classes` — the schema's class record for this relation;
- * bare fields carry `undefined`), `extension: undefined` (the option is
- * the kind).
+ * bare fields carry `undefined`), `closed: undefined` (the option is the
+ * kind — one sum, R7).
  */
 function lowerRelation(relation: AnyRelation, classes: RelationClasses): RelationSpec {
 	const fields: FieldSpec[] = relation.data.fields.map(function lowerDeclared(declared) {
 		return lowerField(declared.name, declared.field, classes[declared.name])
 	})
-	return { name: relation.name, newtype: undefined, fields, extension: undefined }
+	return { name: relation.name, fields, closed: undefined }
 }
 
 /**
  * Lowers one closed relation to its `RelationSpec` fragment: declared
- * intrinsic columns only (the engine materializes the synthetic `id`),
- * the handle newtype — the COMPUTED class name of the id's generator
- * class (`"Kind.id"`, always present: a closed id is a generator), which
- * every referencing field shares by law (how the engine resolves a handle
- * literal back to its roster) — and the ground axioms in declaration
- * order (row id = index); the literals were already lowered at `closed()`
- * construction.
+ * intrinsic columns only (the engine materializes the synthetic `id`) and
+ * the fused closedness sum (R7) — the handle newtype (the COMPUTED class
+ * name of the id's generator class, `"Kind.id"`, always present: a closed
+ * id is a generator; every referencing field shares it by law, which is
+ * how the engine resolves a handle literal back to its roster) together
+ * with the ground axioms in declaration order (row id = index); the
+ * literals were already lowered at `closed()` construction.
  */
 function lowerClosed(member: AnyClosed, classes: RelationClasses): RelationSpec {
 	const fields: FieldSpec[] = member.data.columns.map(function lowerColumn(column) {
 		return lowerField(column.name, column.field, classes[column.name])
 	})
-	const extension = member.data.rows.map(function lowerRow(row) {
+	const rows = member.data.rows.map(function lowerRow(row) {
 		return { handle: row.handle, values: row.values }
 	})
-	return { name: member.name, newtype: classes.id, fields, extension }
+	const newtype = classes.id
+	if (newtype === undefined) {
+		throw errors.new(`closed relation ${member.name}: the id's generator class is missing from the class map`)
+	}
+	return { name: member.name, fields, closed: { newtype, rows } }
 }
 
 /** The frozen empty class record a relation outside the schema's map lowers under (nothing classed). */

package/src/marshal.ts

@@ -70,10 +70,31 @@ type KeyFact<R extends AnyRelation> = [FreshKeys<R>] extends [never]
 /**
  * Reprojects any host object to a string-indexed record — the boundary
  * through which generic fact objects (whose type parameters carry no index
- * signature) enter the name-directed marshaling below, without a cast.
+ * signature) enter the name-directed marshaling below, without a cast. An
+ * ALLOCATION-FREE IDENTITY (the admission predicate is the type
+ * reprojection; the value passes through untouched): every consumer
+ * downstream — `rowOf`, `keyRowOf`, the query param marshal — only READS
+ * properties, so no copy is warranted. The one mutating consumer
+ * (`mintFreshCells` on the insert path) takes its own spread copy at the
+ * call site, so the caller's fact object is never written through this
+ * seam.
  */
-function recordOf(fact: object): Record<string, unknown> {
-	return Object.fromEntries(Object.entries(fact))
+function recordOf(fact: object): Readonly<Record<string, unknown>> {
+	if (!isStringIndexed(fact)) {
+		throw errors.new("fact object is not string-indexable")
+	}
+	return fact
+}
+
+/**
+ * The trusted admission seam of {@link recordOf}: every JS object IS
+ * string-indexable (property reads on absent names yield `undefined`,
+ * which every consumer already guards), so the predicate verifies the one
+ * checkable fact — objecthood — and admits the value at the indexed type
+ * without a copy or a cast.
+ */
+function isStringIndexed(value: object): value is Readonly<Record<string, unknown>> {
+	return typeof value === "object" || typeof value === "function"
 }
 
 /**
@@ -240,18 +261,22 @@ function isCompleteFact<R extends AnyRelation>(
 }
 
 /**
- * The insert-return trusted seam: the collected fresh cells of one insert
- * (minted by the engine or resupplied by the caller) are the relation's
- * fresh ids as bare bigints — same presence-only direction as
+ * The insert-return trusted seam (R11): one insert's return carries the
+ * engine's changed-state report beside the collected fresh cells (minted by
+ * the engine or resupplied by the caller) — the bit is verified boolean and
+ * the fresh ids present, same presence-only direction as
  * {@link isCompleteFact}.
  */
-function isMintedFresh<R extends AnyRelation>(
+function isInserted<R extends AnyRelation>(
 	relation: R,
-	minted: Readonly<Record<string, FactValue>>
-): minted is Readonly<Record<string, FactValue>> & Minted<R> {
-	return relation.data.fields.every(function presentWhenFresh(declared) {
-		return !isFreshField(declared.field) || minted[declared.name] !== undefined
-	})
+	value: Readonly<Record<string, FactValue | boolean>>
+): value is Readonly<Record<string, FactValue | boolean>> & { readonly changed: boolean } & Minted<R> {
+	return (
+		typeof value.changed === "boolean" &&
+		relation.data.fields.every(function presentWhenFresh(declared) {
+			return !isFreshField(declared.field) || value[declared.name] !== undefined
+		})
+	)
 }
 
 /**
@@ -286,4 +311,4 @@ function factOf<R extends AnyRelation>(relation: R, row: readonly FactValue[]):
 }
 
 export type { KeyFact, Minted }
-export { cellOf, factOf, handleOf, isFreshField, isMintedFresh, keyRowOf, recordOf, rowOf }
+export { cellOf, factOf, handleOf, isFreshField, isInserted, keyRowOf, recordOf, rowOf }

package/src/native.ts

@@ -27,9 +27,11 @@ type SnapshotHandle = { readonly __brand: "bumbledb.snapshot" }
 
 /**
  * One exhumed store — the read-only, theory-less open (engine 70-api.md
- * § exhume). No close function exists for this handle anywhere on the
- * bridge (the zero-closables law): the engine side is dropped when the
- * handle is garbage-collected — reclamation only, never correctness.
+ * § exhume). Lifetimes are disposables (ruled 2026-07-23, R12):
+ * `exhumeClose` is the deterministic teardown the SDK's `Symbol.dispose`
+ * rides — releasing the environment (and the store's exclusive lock)
+ * scope-shaped, never a GC race; the engine-side drop remains the
+ * reclamation-only backstop for a collected-but-undisposed handle.
  */
 type ExhumeHandle = { readonly __brand: "bumbledb.exhume" }
 
@@ -320,6 +322,33 @@ interface Staleness {
 	readonly maxRatio: number
 }
 
+/**
+ * `dbSnapshot`'s reply: the live handle WITH its witnessed generation —
+ * one crossing carries both (read inside the snapshot's own transaction,
+ * the race-closing rule of 50-storage.md), so no second `dbGeneration`
+ * call exists to pay or defend (finding 016's bridge shape).
+ */
+type SnapshotOpened = { readonly ok: true; readonly snapshot: SnapshotHandle; readonly generation: bigint }
+
+/**
+ * The plan-as-data report (ruled 2026-07-23, R13): the engine's
+ * `ExecutionStats` rendered to plain objects — camelCase keys, u64
+ * counters as `bigint`. A diagnostic surface, EXPLICITLY UNFROZEN: the
+ * shape follows the plan representation wherever it goes and no
+ * compatibility claim attaches, so this typing names the stable spine
+ * (version, emits, the plan sections) and leaves each section's leaves
+ * open for the host to introspect.
+ */
+interface Explain {
+	readonly introspectionVersion: number
+	readonly emits: bigint
+	readonly disjointRules?: Readonly<Record<string, unknown>>
+	readonly subsumed: ReadonlyArray<Readonly<Record<string, unknown>>>
+	readonly dead: ReadonlyArray<Readonly<Record<string, unknown>>>
+	readonly rules: ReadonlyArray<Readonly<Record<string, unknown>>>
+	readonly strata: ReadonlyArray<Readonly<Record<string, unknown>>>
+}
+
 interface Native {
 	/**
 	 * Proof-of-life export (PRD-03): a non-empty string naming the bridge
@@ -367,11 +396,17 @@ interface Native {
 	 * Opens a store FROM ITS OWN PERSISTED DESCRIPTOR (the read-only,
 	 * theory-less open; engine 70-api.md § exhume) — no schema crosses in.
 	 * The three adoption-era refusals return as data ({@link ExhumeResult});
-	 * genuine failures throw. The handle has no close anywhere on this
-	 * bridge (zero closables): GC reclaims the engine side and releases the
-	 * store's exclusive lock — reclamation only, never correctness.
+	 * genuine failures throw. The handle's deterministic teardown is
+	 * `exhumeClose` (R12); GC reclamation remains the backstop only.
 	 */
 	dbExhume(path: string): ExhumeResult
+	/**
+	 * Closes the exhume handle, releasing its environment (and the store's
+	 * exclusive lock) deterministically — the native teardown under the
+	 * SDK's `Symbol.dispose` (ruled 2026-07-23, R12: lifetimes are
+	 * disposables, never `close()` methods to remember).
+	 */
+	exhumeClose(exhume: ExhumeHandle): void
 	/**
 	 * The exhumed store's persisted schema as manifest-shaped data — the
 	 * engine's own manifest rendering of the STORED descriptor: relations
@@ -388,8 +423,13 @@ interface Native {
 	 */
 	exhumeScan(exhume: ExhumeHandle, relationName: string): FactValue[][]
 
-	/** Opens one MVCC read snapshot as a live handle. */
-	dbSnapshot(db: DbHandle): SnapshotHandle
+	/**
+	 * Opens one MVCC read snapshot as a live handle, returned WITH its
+	 * witnessed generation — one crossing carries both (finding 016), so
+	 * no separate `dbGeneration` call (with its own transient read
+	 * transaction and fault-pairing close branch) exists on this path.
+	 */
+	dbSnapshot(db: DbHandle): SnapshotOpened
 	/** Closes the snapshot, releasing its LMDB reader slot. */
 	snapshotClose(snap: SnapshotHandle): void
 	/** Full-relation export in row-id order (one row per fact). */
@@ -461,6 +501,15 @@ interface Native {
 	 * — the host sorts.
 	 */
 	preparedExecute(prepared: PreparedHandle, snap: SnapshotHandle, params: readonly QueryParam[]): FactValue[][]
+	/**
+	 * Plan introspection as data (ruled 2026-07-23, R13): runs the prepared
+	 * query against the snapshot with counting instrumentation (the
+	 * engine's `Snapshot::profile`, ANALYZE semantics) and returns the
+	 * structured stats — plan sections and counters as plain values.
+	 * Scalar params only (the engine's profile entry has no param-set
+	 * spelling).
+	 */
+	preparedExplain(prepared: PreparedHandle, snap: SnapshotHandle, params: readonly QueryParam[]): Explain
 	/** The pull-based plan-drift signal against a snapshot. */
 	preparedStaleness(prepared: PreparedHandle, snap: SnapshotHandle): Staleness
 	/** Releases the prepared query. */
@@ -566,6 +615,7 @@ export type {
 	DbOpenResult,
 	ExhumeHandle,
 	ExhumeResult,
+	Explain,
 	FactValue,
 	FindTermIr,
 	HeadOpIr,
@@ -586,6 +636,7 @@ export type {
 	QueryParam,
 	RuleIr,
 	SnapshotHandle,
+	SnapshotOpened,
 	Staleness,
 	StatementKindTag,
 	TaggedValue,