@bjornpagen/bumbledb 0.4.0 → 0.6.0

package/src/closed.ts

@@ -39,6 +39,7 @@ import {
 	type Infer,
 	literalOf
 } from "#fields.ts"
+import type { AnyRelation, RelationField } from "#relation.ts"
 import { resolveSelection, type SelectionBinding, type SelectionInput } from "#relation.ts"
 import type { LiteralSpec } from "#spec.ts"
 
@@ -53,7 +54,7 @@ type PayloadField = Exclude<AnyField, { readonly fresh: true }>
  * unspellable — the sealed shape mints the synthetic `id` itself (ordinal
  * 0 of the matchable fields), so a declared column named `id` would be
  * shadowed by the synthetic slot everywhere the shape resolves by name
- * (`matchFieldsOf`, the projected face, `spec.rs`'s resolver). The wall is
+ * (`sealedFieldsOf`, the projected face, `spec.rs`'s resolver). The wall is
  * typed here and judged again at construction in {@link mintClosed} — the
  * runtime twin for untyped callers, warmer and earlier than the engine's
  * `DuplicateFieldName` at `Db.create`.
@@ -193,6 +194,48 @@ interface AnyClosed {
 	readonly columns: Readonly<Record<string, PayloadField>>
 }
 
+/**
+ * THE relation-kind discriminant — the ONE spelling of "is this schema
+ * member closed?" (the type tier's twin is the `AnyClosed` conditional
+ * arms). A closed relation's runtime description carries its handle
+ * roster; an ordinary relation's never does. Every runtime closed/ordinary
+ * fork in the SDK judges through this predicate — never a re-spelled
+ * structural probe.
+ */
+function isClosedMember(member: AnyRelation | AnyClosed): member is AnyClosed {
+	return "handles" in member.data
+}
+
+/**
+ * The SEALED field list of a schema member — THE one reader of "what
+ * fields does this owner expose": an ordinary relation's declared fields;
+ * a closed relation's sealed shape — the synthetic `id` (the value's own
+ * roster-carrying descriptor, by identity) at ordinal 0, then the declared
+ * payload columns at declared index + 1 (the sealed shift, mirroring the
+ * engine's `SchemaDescriptor::sealed_fields`). A `ClosedColumn` is
+ * structurally a `RelationField`, so both kinds read uniformly.
+ */
+function sealedFieldsOf(member: AnyRelation | AnyClosed): readonly RelationField[] {
+	if (isClosedMember(member)) {
+		return Object.freeze([Object.freeze({ name: "id", field: member.id }), ...member.data.columns])
+	}
+	return member.data.fields
+}
+
+/**
+ * One sealed field by name — derived from {@link sealedFieldsOf}, so the
+ * closed synthetic `id` resolves everywhere a name is looked up (no reader
+ * can silently lack the `id` arm). `undefined` when the name is foreign
+ * (the type tiers make that unwritable; the engine re-judges at
+ * `Db.create`).
+ */
+function sealedFieldOf(member: AnyRelation | AnyClosed, fieldName: string): AnyField | undefined {
+	const declared = sealedFieldsOf(member).find(function byName(candidate) {
+		return candidate.name === fieldName
+	})
+	return declared?.field
+}
+
 /** Narrows the two-tier second argument: a handle tuple (bare tier) or a column block (payload tier). */
 function isHandleTuple(
 	shape: readonly [string, ...string[]] | Record<string, PayloadField>
@@ -219,7 +262,8 @@ function handleKeysOwn<Handles extends string>(
  * The trusted seam of the axiom-readback mint: every handle carries an own
  * frozen row and every row carries every declared column as an own
  * property — verified before the record is admitted as the typed
- * {@link Axioms} (the `refsComplete` analog of `relation()`).
+ * {@link Axioms} (the trusted-admission-seam pattern — its home is
+ * `isTypedScope` in query/lower.ts).
  */
 function axiomsMinted<Handles extends string, Cols extends Record<string, PayloadField>>(
 	record: Readonly<Record<string, object>>,
@@ -237,38 +281,22 @@ function axiomsMinted<Handles extends string, Cols extends Record<string, Payloa
 	})
 }
 
-/**
- * Reads one handle's ground axiom row for lowering. The typed payload
- * surface makes absence unrepresentable ({@link Axioms} carries every
- * handle's row); the refusal below guards the one ill-typed path — payload
- * columns with the bare tier's absent axioms — which no public spelling
- * reaches.
- */
-function groundRow<Handles extends string, Cols extends Record<string, PayloadField>>(
-	name: string,
-	axioms: Axioms<Handles, Cols> | undefined,
-	handle: Handles
-): Readonly<Record<string, unknown>> {
-	if (axioms === undefined) {
-		throw errors.new(`closed relation ${name}: payload columns declared without ground axioms`)
-	}
-	return axioms[handle]
-}
-
 /**
  * Mints the axiom-readback record: one own frozen row per handle (the bare
  * tier's rows are empty — it declares no columns), each row a fresh copy of
- * its ground axiom.
+ * its ground axiom. Both tiers supply a REAL axioms record ({@link
+ * closedBare} mints its empty rows), so the columns-without-axioms state is
+ * unrepresentable here — no undefined arm exists to guard.
  */
 function mintAxioms<Handles extends string, Cols extends Record<string, PayloadField>>(
 	name: string,
 	handles: readonly Handles[],
 	cols: readonly ClosedColumn[],
-	axioms: Axioms<Handles, Cols> | undefined
+	axioms: Axioms<Handles, Cols>
 ): Axioms<Handles, Cols> {
 	const out: Record<string, object> = {}
 	for (const handle of handles) {
-		const row = axioms === undefined ? Object.freeze({}) : Object.freeze({ ...groundRow(name, axioms, handle) })
+		const row = Object.freeze({ ...axioms[handle] })
 		Object.defineProperty(out, handle, { value: row, enumerable: true })
 	}
 	Object.freeze(out)
@@ -321,12 +349,29 @@ function closed<const Name extends string, const Cols extends PayloadColumns, Ha
 	return closedPayload(name, shape, axioms)
 }
 
-/** The bare tier's precisely-typed builder: no columns, no axioms. */
+/**
+ * The bare tier's precisely-typed builder: no columns, and the axioms
+ * record is the EMPTY-ROW record over the handle roster (one own frozen
+ * `{}` per handle, `__proto__`-safe own-property definition) — the same
+ * representation the payload tier carries, so `mintClosed` never sees a
+ * tier fork and the columns-without-axioms state stops being spellable.
+ */
 function closedBare<Name extends string, Handles extends string>(
 	name: Name,
 	handles: readonly [Handles, ...Handles[]]
 ): Closed<Name, Handles, Record<never, never>> {
-	return mintClosed<Name, Handles, Record<never, never>>(name, handles, {}, undefined)
+	const empty: Record<string, object> = {}
+	for (const handle of handles) {
+		/** A duplicated name mints one row; the roster's own duplicate refusal in {@link mintClosed} stays the judge. */
+		if (!Object.hasOwn(empty, handle)) {
+			Object.defineProperty(empty, handle, { value: Object.freeze({}), enumerable: true })
+		}
+	}
+	Object.freeze(empty)
+	if (!axiomsMinted<Handles, Record<never, never>>(empty, handles, [])) {
+		throw errors.new(`closed relation ${name}: bare-tier axiom-row minting incomplete`)
+	}
+	return mintClosed<Name, Handles, Record<never, never>>(name, handles, {}, empty)
 }
 
 /**
@@ -379,7 +424,7 @@ function mintClosed<Name extends string, Handles extends string, Cols extends Re
 	name: Name,
 	handles: readonly Handles[],
 	columns: Cols,
-	axioms: Axioms<Handles, Cols> | undefined
+	axioms: Axioms<Handles, Cols>
 ): Closed<Name, Handles, Cols> {
 	if (handles.length === 0) {
 		throw errors.new(`closed relation ${name}: at least one handle is required (an empty vocabulary declares nothing)`)
@@ -405,8 +450,8 @@ function mintClosed<Name extends string, Handles extends string, Cols extends Re
 	}
 	Object.freeze(cols)
 	const rows: ClosedRow[] = handleList.map(function lowerRow(handle) {
+		const row: Readonly<Record<string, unknown>> = axioms[handle]
 		const values = cols.map(function lowerAxiomLiteral(column) {
-			const row = groundRow(name, axioms, handle)
 			return Object.freeze(literalOf(column.field, row[column.name]))
 		})
 		return Object.freeze({ handle, values: Object.freeze(values) })
@@ -471,4 +516,4 @@ export type {
 	PayloadField,
 	SelectedClosed
 }
-export { closed }
+export { closed, isClosedMember, sealedFieldOf, sealedFieldsOf }

package/src/db.ts

@@ -32,8 +32,10 @@
 
 import * as path from "node:path"
 import * as errors from "@superbuilders/errors"
+import { isClosedMember, sealedFieldsOf } from "#closed.ts"
 import type { Exhumed } from "#exhume.ts"
 import { exhumeStore } from "#exhume.ts"
+import { rosterOf } from "#fields.ts"
 import { lower } from "#lower.ts"
 import {
 	factOf,
@@ -59,13 +61,13 @@ import type {
 	Violation as WireViolation,
 	ViolationFact as WireViolationFact
 } from "#native.ts"
-import { native } from "#native.ts"
-import type { SelectColumn } from "#query/atom.ts"
+import { bridged, native } from "#native.ts"
+import type { FindColumn } from "#query/atom.ts"
 import type { Query } from "#query/lower.ts"
 import { lowerQuery } from "#query/lower.ts"
 import { decodeAnswers, wireParams } from "#query/run.ts"
 import type { ParamEntry, ParamsRecord } from "#query/scope.ts"
-import type { AnyRelation, Fact, InsertFact, RelationField } from "#relation.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"
 
@@ -348,11 +350,16 @@ interface Db<Rels extends SchemaRelations> {
 	 * The ONE witnessed-write form: snapshot → `fn` (premise reads via
 	 * `snap`, delta via `tx`) → witnessed commit, which lands only if no
 	 * state-changing commit intervened since the snapshot. On a moved
-	 * generation the WHOLE `fn` reruns on a fresh snapshot, unbounded: this
-	 * process holds the store's only write handle, so every generation move
-	 * is self-inflicted by the host's own interleaved writes — contention
-	 * is bounded by the host's own progress, and any retry cap would be an
-	 * invented limit (the house no-limits law). `fn` may decline to commit
+	 * generation the WHOLE `fn` reruns on a fresh snapshot: this process
+	 * holds the store's only write handle, so every generation move is
+	 * self-inflicted by the host's own interleaved writes, and each rerun
+	 * witnesses a strictly newer generation — the benign race converges.
+	 * The loop's honesty bound is {@link WITNESSED_ATTEMPT_CAP}: a callback
+	 * that moves the generation on EVERY attempt (a plain `db.write` before
+	 * its first tx verb) would spin forever, so past the cap the typed
+	 * {@link ErrWitnessedLivelock} is thrown instead of a silent loop (the
+	 * engine's ruling: the error, never a loop — retry is host policy, and
+	 * the cap is that policy's own diagnostic). `fn` may decline to commit
 	 * by returning {@link abandon}`(payload)` — the outcome is then
 	 * `{ ok: false, abandoned: payload }` and NO commit (not even an empty
 	 * one) is issued.
@@ -368,19 +375,6 @@ interface Db<Rels extends SchemaRelations> {
 	prepare<Row, Params extends ParamsRecord>(q: Query<Rels, Row, Params>): Prepared<Rels, Row, Params>
 }
 
-/**
- * The bridge guard: runs one native call and wraps anything it throws —
- * marshal-shape refusals and handle-lifecycle refusals cross as genuine
- * typed failures, never bare foreign errors.
- */
-function bridged<T>(context: string, run: () => T): T {
-	const result = errors.trySync(run)
-	if (result.error) {
-		throw errors.wrap(result.error, context)
-	}
-	return result.data
-}
-
 /** One relation's runtime tables: engine id, the identical schema member, field ids, primary key. */
 interface RelationEntry {
 	readonly id: number
@@ -443,7 +437,7 @@ function materializedEntries(theory: AnySchema): StatementEntry[] {
 function impliedKeyEntries(theory: AnySchema): StatementEntry[] {
 	const entries: StatementEntry[] = []
 	for (const member of Object.values(theory.relations)) {
-		if ("handles" in member.data) {
+		if (isClosedMember(member)) {
 			continue
 		}
 		for (const declared of member.data.fields) {
@@ -457,7 +451,7 @@ function impliedKeyEntries(theory: AnySchema): StatementEntry[] {
 		}
 	}
 	for (const member of Object.values(theory.relations)) {
-		if ("handles" in member.data) {
+		if (isClosedMember(member)) {
 			entries.push({
 				kind: "functionality",
 				statement: undefined,
@@ -527,6 +521,33 @@ function isStatementValue<R extends AnyRelation, P extends readonly string[]>(
 	return typeof data === "object" && data !== null && "kind" in data
 }
 
+/**
+ * THE one selector dispatch of the `get` overload pair (primary-key vs
+ * key-statement, `docs/architecture/70-api.md` § the freeze): judges the
+ * middle argument once and hands the narrowed pieces to the chosen
+ * continuation. `Db.get` and the read scope's `get` both dispatch through
+ * here, so the two mismatch refusals speak with one voice and the symmetry
+ * rule (`db.get(...) === db.read(snap => snap.get(...))`) holds by
+ * construction.
+ */
+function selectKeyRead<R extends AnyRelation, P extends readonly string[], T>(
+	keyOrStatement: KeyFact<R> | KeyStatement<R, P>,
+	declaredKey: DeclaredKeyFact<R, P> | undefined,
+	byStatement: (statement: KeyStatement<R, P>, key: DeclaredKeyFact<R, P>) => T,
+	byPrimary: (key: KeyFact<R>) => T
+): T {
+	if (declaredKey !== undefined) {
+		if (!isStatementValue(keyOrStatement)) {
+			throw errors.new("keyed get takes a key() statement value as its second argument")
+		}
+		return byStatement(keyOrStatement, declaredKey)
+	}
+	if (isStatementValue(keyOrStatement)) {
+		throw errors.new("keyed get with a statement selector also takes the key object — get(relation, keyStatement, key)")
+	}
+	return byPrimary(keyOrStatement)
+}
+
 /** Maps a slot's reversal flag to the violation's `orientation` payload. */
 function orientationOf(reversed: boolean | undefined): "written" | "mirrored" | undefined {
 	if (reversed === undefined) {
@@ -538,22 +559,6 @@ function orientationOf(reversed: boolean | undefined): "written" | "mirrored" |
 	return "written"
 }
 
-/**
- * The declared field descriptors a violation's offending cells decode
- * through: an ordinary relation's declared fields; a closed relation's
- * SEALED shape — the roster-carrying synthetic `id` (the member's own
- * reference descriptor) plus its payload columns (a `ClosedColumn` is
- * structurally a `RelationField`). This is how {@link openDb}'s
- * `offendingFactOf` reaches the open-time descriptors: the cited relation
- * name resolves to the schema member, and the member carries them.
- */
-function declaredFieldsOf(member: SchemaRelation): readonly RelationField[] {
-	if ("axioms" in member) {
-		return [{ name: "id", field: member.id }, ...member.data.columns]
-	}
-	return member.data.fields
-}
-
 /** The id-resolution tables one open builds: relation entries by name, statement slots by id. */
 interface Tables {
 	readonly relations: ReadonlyMap<string, RelationEntry>
@@ -638,7 +643,7 @@ interface PreparedPlan {
 	readonly handle: PreparedHandle
 	readonly owner: object
 	readonly params: readonly ParamEntry[]
-	readonly select: readonly SelectColumn[]
+	readonly finds: readonly FindColumn[]
 }
 
 /** The private engine halves of this module's prepared values. */
@@ -667,6 +672,32 @@ const planReclaimer = new FinalizationRegistry<PreparedHandle>(function reclaimP
  */
 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}).
+ */
+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"
+)
+
 /**
  * Fills one insert's omitted fresh cells through the engine's
  * alloc-then-insert dyn lane (there is no insert-with-omitted-fields wire
@@ -725,7 +756,7 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		if (entry === undefined || entry.member !== relation) {
 			throw errors.new(`relation ${relation.name} is not a member of schema ${theory.name}`)
 		}
-		if ("handles" in relation.data) {
+		if (isClosedMember(relation)) {
 			throw errors.new(
 				`relation ${relation.name} is closed — its extension is schema data (axioms), never scanned or written`
 			)
@@ -738,15 +769,16 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		if (entry === undefined || !isMemberName(fact.relation)) {
 			throw errors.new(`bumbledb violation cites unknown relation ${fact.relation}`)
 		}
-		const declared = declaredFieldsOf(entry.member)
+		const declared = sealedFieldsOf(entry.member)
 		const decoded: Record<string, FactValue> = {}
 		for (const cell of fact.fields) {
 			const cited = declared.find(function byName(candidate) {
 				return candidate.name === cell.name
 			})
+			const roster = rosterOf(cited?.field)
 			decoded[cell.name] =
-				cited !== undefined && "closed" in cited.field
-					? handleOf(`violation fact ${fact.relation} field ${cell.name}`, cited.field.closed, cell.value)
+				roster !== undefined
+					? handleOf(`violation fact ${fact.relation} field ${cell.name}`, roster, cell.value)
 					: cell.value
 		}
 		return Object.freeze({ relation: fact.relation, fact: Object.freeze(decoded) })
@@ -828,25 +860,22 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		): Fact<R> | undefined {
 			assertLive()
 			const entry = resolveOrdinary(relation)
-			if (declaredKey !== undefined) {
-				if (!isStatementValue(keyOrStatement)) {
-					throw errors.new("keyed get takes a key() statement value as its second argument")
+			return selectKeyRead(
+				keyOrStatement,
+				declaredKey,
+				function byStatement(statement, key) {
+					return readThroughKey(relation, entry, declaredKeyOf(relation, statement), recordOf(key))
+				},
+				function byPrimary(key) {
+					const primaryKey = entry.primaryKey
+					if (primaryKey === undefined) {
+						throw errors.new(
+							`relation ${relation.name} has no candidate key — keyed get requires a fresh field or a declared key statement`
+						)
+					}
+					return readThroughKey(relation, entry, primaryKey, recordOf(key))
 				}
-				const selected = declaredKeyOf(relation, keyOrStatement)
-				return readThroughKey(relation, entry, selected, recordOf(declaredKey))
-			}
-			if (isStatementValue(keyOrStatement)) {
-				throw errors.new(
-					"keyed get with a statement selector also takes the key object — get(relation, keyStatement, key)"
-				)
-			}
-			const primaryKey = entry.primaryKey
-			if (primaryKey === undefined) {
-				throw errors.new(
-					`relation ${relation.name} has no candidate key — keyed get requires a fresh field or a declared key statement`
-				)
-			}
-			return readThroughKey(relation, entry, primaryKey, recordOf(keyOrStatement))
+			)
 		}
 		return { contains, get }
 	}
@@ -909,7 +938,7 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 			const rows = bridged("execute bumbledb prepared query", function callExecute() {
 				return native.preparedExecute(plan.handle, state.handle, wire)
 			})
-			return decodeAnswers<Row>(plan.select, rows)
+			return decodeAnswers<Row>(plan.finds, rows)
 		}
 		const scope: ReadScope<Rels> = Object.freeze({
 			generation,
@@ -1003,18 +1032,16 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		declaredKey?: DeclaredKeyFact<R, P>
 	): Fact<R> | undefined {
 		return read(function getInScope(snap) {
-			if (declaredKey !== undefined) {
-				if (!isStatementValue(keyOrStatement)) {
-					throw errors.new("keyed get takes a key() statement value as its second argument")
+			return selectKeyRead(
+				keyOrStatement,
+				declaredKey,
+				function byStatement(statement, key) {
+					return snap.get(relation, statement, key)
+				},
+				function byPrimary(key) {
+					return snap.get(relation, key)
 				}
-				return snap.get(relation, keyOrStatement, declaredKey)
-			}
-			if (isStatementValue(keyOrStatement)) {
-				throw errors.new(
-					"keyed get with a statement selector also takes the key object — get(relation, keyStatement, key)"
-				)
-			}
-			return snap.get(relation, keyOrStatement)
+			)
 		})
 	}
 
@@ -1298,13 +1325,32 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		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<R>(fn: (snap: ReadScope<Rels>, tx: Tx<Rels>) => R): WitnessedWriteResult<Rels, R> {
-		for (;;) {
+		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}`
+		)
 	}
 
 	/**
@@ -1326,17 +1372,9 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 			if (member === undefined) {
 				throw errors.new(`bumbledb manifest drift: schema ${theory.name} lost relation ${name}`)
 			}
-			const sealed =
-				"handles" in member.data
-					? [
-							"id",
-							...member.data.columns.map(function columnName(column) {
-								return column.name
-							})
-						]
-					: member.data.fields.map(function fieldName(declared) {
-							return declared.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(
@@ -1386,7 +1424,7 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 				handle: preparedHandle,
 				owner,
 				params: q.data.params,
-				select: q.data.select
+				finds: q.data.finds
 			})
 		)
 		planReclaimer.register(prepared, preparedHandle)
@@ -1581,4 +1619,4 @@ export type {
 	WitnessedWriteResult,
 	WriteResult
 }
-export { abandon, Db, ErrNewtypeMismatch }
+export { abandon, Db, ErrNewtypeMismatch, ErrWitnessedLivelock, WITNESSED_ATTEMPT_CAP }

package/src/exhume.ts

@@ -26,7 +26,7 @@
 
 import * as errors from "@superbuilders/errors"
 import type { FactValue, Manifest } from "#native.ts"
-import { native } from "#native.ts"
+import { bridged, native } from "#native.ts"
 import type { ValueTypeSpec } from "#spec.ts"
 
 /**
@@ -132,20 +132,6 @@ interface Exhumed {
 	scan(relation: string): readonly ExhumedFact[]
 }
 
-/**
- * The bridge guard (db.ts's twin over this module's calls): runs one
- * native call and wraps anything it throws, so marshal-shape and
- * handle-lifecycle refusals cross as genuine typed failures, never bare
- * foreign errors.
- */
-function bridged<T>(context: string, run: () => T): T {
-	const result = errors.trySync(run)
-	if (result.error) {
-		throw errors.wrap(result.error, context)
-	}
-	return result.data
-}
-
 /**
  * Shapes the bridge's manifest rendering of the stored descriptor into the
  * SDK's {@link ExhumedDescriptor}: same relations in the same engine-id

package/src/face.ts

@@ -101,11 +101,11 @@ type FaceSource = AnyRelation | AnyClosed | AnySelected | AnySelectedClosed
  * names address the sealed shape).
  */
 type FaceFields<S extends FaceSource> = S extends AnySelected
-	? keyof S["relation"]["fields"] & string
+	? keyof RelationFields<S["relation"]> & string
 	: S extends AnySelectedClosed
 		? "id" | (keyof S["relation"]["columns"] & string)
 		: S extends AnyRelation
-			? keyof S["fields"] & string
+			? keyof RelationFields<S> & string
 			: S extends { readonly axioms: Readonly<Record<string, infer Row>> }
 				? "id" | (keyof Row & string)
 				: never
@@ -263,7 +263,8 @@ function on<S extends FaceSource>(source: S, fields: string | readonly string[])
 }
 
 /**
- * The trusted seam of the face mint (the `refsComplete` pattern): the
+ * The trusted admission seam of the face mint (the pattern's home is
+ * `isTypedScope` in query/lower.ts): the
  * checkable facts — the value carries exactly the source and projection it
  * was built from, and `data.owner` is exactly the owner {@link faceParts}
  * resolves for that source — are verified before the wide construction is