@bjornpagen/bumbledb 0.3.0 → 0.5.0

package/src/db.ts

@@ -32,10 +32,22 @@
 
 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, isFreshField, isMintedFresh, type KeyFact, keyRowOf, type Minted, recordOf, rowOf } from "#marshal.ts"
+import {
+	factOf,
+	handleOf,
+	isFreshField,
+	isMintedFresh,
+	type KeyFact,
+	keyRowOf,
+	type Minted,
+	recordOf,
+	rowOf
+} from "#marshal.ts"
 
 import type {
 	DbHandle,
@@ -49,7 +61,7 @@ import type {
 	Violation as WireViolation,
 	ViolationFact as WireViolationFact
 } from "#native.ts"
-import { native } from "#native.ts"
+import { bridged, native } from "#native.ts"
 import type { SelectColumn } from "#query/atom.ts"
 import type { Query } from "#query/lower.ts"
 import { lowerQuery } from "#query/lower.ts"
@@ -79,7 +91,10 @@ type DeclaredKeyFact<R extends AnyRelation, Projection extends readonly string[]
 /**
  * One offending fact of a violation: the cited relation's name (a member
  * of the schema's record) and the fact decoded to a named natural-value
- * object — partial exactly as the engine cites it.
+ * object — partial exactly as the engine cites it. Closed-referencing
+ * cells arrive as handle NAMES (the marshal bijection's read half), so the
+ * record and the violation's `canonical` string — which the engine already
+ * renders with handle names — agree on the one spelling.
  */
 interface OffendingFact<Rels extends SchemaRelations> {
 	readonly relation: keyof Rels & string
@@ -335,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.
@@ -355,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
@@ -430,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) {
@@ -444,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,
@@ -514,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) {
@@ -638,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
@@ -696,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`
 			)
@@ -705,12 +765,21 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 	}
 
 	function offendingFactOf(fact: WireViolationFact): OffendingFact<Rels> {
-		if (!isMemberName(fact.relation)) {
+		const entry = tables.relations.get(fact.relation)
+		if (entry === undefined || !isMemberName(fact.relation)) {
 			throw errors.new(`bumbledb violation cites unknown relation ${fact.relation}`)
 		}
+		const declared = sealedFieldsOf(entry.member)
 		const decoded: Record<string, FactValue> = {}
 		for (const cell of fact.fields) {
-			decoded[cell.name] = cell.value
+			const cited = declared.find(function byName(candidate) {
+				return candidate.name === cell.name
+			})
+			const roster = rosterOf(cited?.field)
+			decoded[cell.name] =
+				roster !== undefined
+					? handleOf(`violation fact ${fact.relation} field ${cell.name}`, roster, cell.value)
+					: cell.value
 		}
 		return Object.freeze({ relation: fact.relation, fact: Object.freeze(decoded) })
 	}
@@ -791,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 }
 	}
@@ -966,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)
+			)
 		})
 	}
 
@@ -1261,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}`
+		)
 	}
 
 	/**
@@ -1289,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(
@@ -1544,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

@@ -11,11 +11,12 @@
  * positional: tuple order is preserved in the type, and the statement
  * constructors pair the two sides' tuples by arity ({@link SameArity}) AND
  * by structural shape ({@link SameShapes}) — every projected field's
- * kind/width/element triple is read off the schema type (the minimal
- * kernel: descriptors are pure structure) and compared positionwise. There
- * is no domain to compare at construction — domains are LAW-BORN: the
- * statements themselves define the equivalence classes, and `schema()` is
- * where they aggregate and get judged (the one-generator-per-class wall).
+ * kind/width/element/roster quadruple is read off the schema type (the
+ * minimal kernel: descriptors are pure structure, and a closed reference's
+ * roster IS part of that structure) and compared positionwise. There is no
+ * domain to compare at construction — domains are LAW-BORN: the statements
+ * themselves define the equivalence classes, and `schema()` is where they
+ * aggregate and get judged (the one-generator-per-class wall).
  */
 
 import * as errors from "@superbuilders/errors"
@@ -54,27 +55,6 @@ function faceParts(source: FaceSource): {
 	return { owner: source, selection: emptySelection }
 }
 
-/**
- * A disjunctive literal set for a selection binding — `field == {A, B}`.
- * The signature of {@link oneOf} demands two leading literals, so the
- * one-element set (banned: it is the bare literal) and the empty set
- * (banned: it selects nothing) are unwritable.
- */
-interface OneOf<V> {
-	readonly literals: readonly [V, V, ...V[]]
-}
-
-/**
- * Constructs a literal set (read disjunctively) for a `where()` binding.
- * Two leading arguments by signature: the degenerate sets have no spelling
- * (the canonical-utterance law, `docs/architecture/70-api.md`).
- */
-function oneOf<V>(first: V, second: V, ...rest: V[]): OneOf<V> {
-	const literals: readonly [V, V, ...V[]] = [first, second, ...rest]
-	Object.freeze(literals)
-	return Object.freeze({ literals })
-}
-
 /** The relation a face projects from — ordinary or closed. */
 type FaceOwner = AnyRelation | AnyClosed
 
@@ -121,30 +101,38 @@ 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
 
 /**
- * One descriptor's structural comparand: the kind/width/element triple —
- * exactly the structure the minimal kernel carries, compared exactly as the
- * engine's Q1 law pairs positions (`schema/validate.rs`): a `bytes` width is
- * bound (bytes<16> vs bytes<32> mismatch), while an INTERVAL width is FREE —
- * the pointwise judgments quantify over points, which carry an element
- * domain and not a width, so `interval(u64)` pairs with `interval(u64, 1n)`
- * (recipe 9's extent/slot 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.
+ * One descriptor's structural comparand: the kind/width/element/roster
+ * quadruple — exactly the structure the minimal kernel carries. The first
+ * three slots compare exactly as the engine's Q1 law pairs positions
+ * (`schema/validate.rs`): a `bytes` width is bound (bytes<16> vs bytes<32>
+ * mismatch), while an INTERVAL width is FREE — the pointwise judgments
+ * quantify over points, which carry an element domain and not a width, so
+ * `interval(u64)` pairs with `interval(u64, 1n)` (recipe 9's extent/slot
+ * 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
+ * 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 element: infer E } ? E : undefined,
+	F extends { readonly closed: { readonly handles: readonly (infer H extends string)[] } } ? H : undefined
 ]
 
 /** One field's structural shape within a declared field block (`undefined` when the name is foreign). */
@@ -216,10 +204,11 @@ type SameArity<A extends AnyFace, B extends AnyFace> =
  * bijection, or window project structurally incompatible fields at any
  * position, this type is intersected into the second face's parameter and
  * names both shape tuples — a u64 face against a str face, a bytes width
- * mismatch, or an interval element mismatch is a COMPILE error.
+ * mismatch, an interval element mismatch, or a bare column against a
+ * closed reference (the roster slot) is a COMPILE error.
  */
 interface FaceShapeMismatch<Left, Right> {
-	readonly "face shape mismatch — positionwise kind, width, and element must be equal on both sides": readonly [
+	readonly "face shape mismatch — positionwise kind, width, element, and closed roster must be equal on both sides": readonly [
 		Left,
 		Right
 	]
@@ -229,11 +218,12 @@ interface FaceShapeMismatch<Left, Right> {
  * Resolves to `unknown` (a no-op intersection) when the two faces project
  * positionwise-equal structural shapes, and to {@link FaceShapeMismatch}
  * otherwise. Equality is mutual tuple assignability over the
- * kind/width/element triples. This is the whole construction-time wall —
- * deliberately: there is no domain to compare here. The domain wall lives
- * where domains are BORN: `schema()` computes every field's class from the
- * statement list and holds the one-generator-per-class law, and query
- * joins compare class names off the schema type.
+ * kind/width/element/roster quadruples. This is the whole
+ * construction-time wall — deliberately: there is no domain to compare
+ * here (the roster is descriptor STRUCTURE, not a domain). The domain wall
+ * lives where domains are BORN: `schema()` computes every field's class
+ * from the statement list and holds the one-generator-per-class law, and
+ * query joins compare class names off the schema type.
  */
 type SameShapes<A extends AnyFace, B extends AnyFace> =
 	FaceShapes<A> extends FaceShapes<B>
@@ -273,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
@@ -323,9 +314,8 @@ export type {
 	FaceShapeMismatch,
 	FaceShapes,
 	FaceSource,
-	OneOf,
 	OwnerOf,
 	SameArity,
 	SameShapes
 }
-export { on, oneOf, renderFace }
+export { on, renderFace }