@bjornpagen/bumbledb 0.2.0 → 0.4.0

package/src/closed.ts

@@ -1,20 +1,33 @@
 /**
  * Closed relations (`docs/architecture/10-data-model.md` § closed
  * relations): a vocabulary whose extension is declared in the schema — two
- * tiers, one function. The emission per closed relation mirrors the
- * macro's (host-enum analog): handle CONSTANTS on the value
- * (`Kind.Checking`, ids = declaration order, each a BARE `bigint` — no
- * brand), the `fromId` weld, an `id` field descriptor carrying the handle
- * DOMAIN (`"KindId"`, mirroring Rust's `closed relation Kind as KindId`)
- * for other relations' field blocks (`kind: Kind.id`), payload readback
- * (`Kind.axioms`), and the declared payload column descriptors
- * (`Kind.columns` — the runtime twin of the `Cols` type parameter, which
- * the face layer's domain wall reads). Bare tier: `closed("Kind", ["Checking",
- * "Savings"])`. Payload tier: `closed("Sev", { pages: bool })({ Critical:
- * { pages: true }, ... })` — the axioms record IS the handle declaration,
- * every handle carrying every column exactly once (type-enforced). No fact
- * type and no insert surface exist — closed relations are unwritable by
- * construction: the value simply lacks the writable relation shape.
+ * tiers, one function. Bare tier: `closed("Kind", ["Checking",
+ * "Savings"])`. Payload tier: `closed("Sev", { pages: bool }, { Critical:
+ * { pages: true }, ... })` — one call, three arguments (the curried tier-2
+ * spelling is DELETED — canonical utterance): the axioms record IS the
+ * handle declaration, every handle carrying every column exactly once
+ * (type-enforced). At the host surface a handle is its NAME — a string
+ * literal of the roster's union (the drizzle law: translation, not
+ * abstraction; dispatch over a vocabulary is native `switch` narrowing, so
+ * no match operator is minted and no handle constants exist — the literal
+ * `"Checking"` is the ONE spelling). Handles are pure DATA, not properties
+ * of the value, so NO handle name is reserved: a vocabulary may legally
+ * contain handles named `match`, `where`, or `id` — the axioms record and
+ * the roster are their own namespaces. The value's whole surface: `name`;
+ * `id` — the field descriptor carrying the CLOSED LINKAGE (the roster —
+ * pure structure, no declared domain: the laws type the columns, and
+ * `schema()` names the id's generator class `"Kind.id"`) for other
+ * relations' field blocks (`kind: Kind.id`); `data` (the lowering
+ * carrier); `axioms` (payload readback, `Kind.axioms`); `columns` (the
+ * runtime twin of the `Cols` type parameter, which the face layer's
+ * structural wall reads); and — exactly when payload columns exist —
+ * `where()`, the ψ-selection surface (`Kind.where({ mastered: true })` as a
+ * face source), resolved through the ONE selection machine
+ * (`relation.ts::resolveSelection`); the bare tier has no payload columns
+ * to select on, so `.where` is absent there, at the type AND on the value.
+ * No fact type and no insert surface exist — closed relations are
+ * unwritable by construction: the value simply lacks the writable relation
+ * shape.
  */
 
 import * as errors from "@superbuilders/errors"
@@ -26,31 +39,27 @@ import {
 	type Infer,
 	literalOf
 } from "#fields.ts"
+import { resolveSelection, type SelectionBinding, type SelectionInput } from "#relation.ts"
 import type { LiteralSpec } from "#spec.ts"
 
-/**
- * The value-surface property names a handle may not shadow — the macro's
- * name-collision diagnostic, here over the closed value's own properties
- * (`relation`/`selection` are reserved so a closed value can never be
- * mistaken for a selected relation by `on()`'s discriminant).
- */
-const reservedHandleNames: readonly string[] = Object.freeze([
-	"name",
-	"id",
-	"data",
-	"axioms",
-	"columns",
-	"fromId",
-	"relation",
-	"selection"
-])
-
 /**
  * A payload column of a closed relation: any field descriptor except a
  * fresh-marked one (a vocabulary's rows are ground axioms, never minted).
  */
 type PayloadField = Exclude<AnyField, { readonly fresh: true }>
 
+/**
+ * A declared payload column BLOCK: name → descriptor, with `id`
+ * 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
+ * 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`.
+ */
+type PayloadColumns = Record<string, PayloadField> & { readonly id?: never }
+
 /** One declared payload column: name plus its field descriptor. */
 interface ClosedColumn {
 	readonly name: string
@@ -96,39 +105,84 @@ type Axioms<Handles extends string, Cols extends Record<string, PayloadField>> =
 interface ClosedCore<Name extends string, Handles extends string, Cols extends Record<string, PayloadField>> {
 	readonly name: Name
 	/**
-	 * The handle-domain reference descriptor: `kind: Kind.id` in another
-	 * relation's field block is the reference through which bare handle ids
-	 * become legal in that relation's selections. Its domain is the closed
-	 * relation's handle domain (`"KindId"` — Rust's `as KindId`).
+	 * The closed reference descriptor: `kind: Kind.id` in another relation's
+	 * field block is the reference through which handle literals become
+	 * legal in that relation's selections. Pure structure plus the PRECISE
+	 * roster (`ClosedIdField<Handles>` — the handle union is the field's
+	 * value type under `Infer`); the referencing field's domain is law-born:
+	 * `schema()` computes it from the declared containment (`"Kind.id"`, the
+	 * generator class).
 	 */
-	readonly id: ClosedIdField<`${Name}Id`>
+	readonly id: ClosedIdField<Handles>
 	readonly data: ClosedData
 	/** Payload readback: handle to its declared column values, bare and structural. */
 	readonly axioms: Axioms<Handles, Cols>
 	/**
-	 * The declared payload columns, name → S1 field descriptor — an HONEST
+	 * The declared payload columns, name → field descriptor — an HONEST
 	 * frozen runtime record (the descriptors themselves, by identity), and
-	 * the typed carrier a projected payload column's domain label is
+	 * the typed carrier a projected payload column's structural shape is
 	 * recovered through off the schema type (the face layer's
-	 * `ProjectedDomain` reads it; `data.columns` carries the same
+	 * `ProjectedShape` reads it; `data.columns` carries the same
 	 * descriptors in declaration order for the lowering).
 	 */
 	readonly columns: Cols
-	/** The weld: declaration-order id back to its handle, or undefined beyond the roster. */
-	fromId(id: bigint): Handles | undefined
 }
 
 /**
- * A closed relation value: the core surface plus one BARE constant per
- * handle (`Kind.Checking: bigint`, ids = declaration order — the value is
- * structural; the roster judges out-of-vocabulary ids at construction and
- * the engine at commit).
+ * The `where()` argument of a closed relation: EXACTLY the relation
+ * surface's {@link SelectionInput}, over the declared payload columns — the
+ * ONE selection vocabulary, so a spelling change there (H3's membership
+ * arrays) flows through with no local change here. The synthetic `id` is
+ * deliberately unspellable ({@link PayloadColumns} refuses an `id` column):
+ * an id selection is spelled only as handle literals on the REFERENCING
+ * side (the canonical-utterance law).
+ */
+type ClosedSelectionInput<Cols extends Record<string, PayloadField>> = SelectionInput<Cols>
+
+/**
+ * A closed relation with a ψ selection applied — what `on()` consumes as a
+ * σ-carrying closed source (`on(Kind.where({ mastered: true }), "id")`).
+ * Deliberately the SAME discriminant shape as the ordinary `Selected`
+ * (`relation`/`selection` — `face.ts::faceParts` splits both by `"relation"
+ * in source`), and structurally UNMISTAKABLE for one: an `AnyClosed` lacks
+ * the relation shape (no `fields` record, no `RelationData`).
+ */
+interface SelectedClosed<Name extends string, Handles extends string, Cols extends Record<string, PayloadField>> {
+	readonly relation: Closed<Name, Handles, Cols>
+	readonly selection: readonly SelectionBinding[]
+}
+
+/** Any ψ-selected closed relation value. */
+interface AnySelectedClosed {
+	readonly relation: AnyClosed
+	readonly selection: readonly SelectionBinding[]
+}
+
+/**
+ * The ψ-selection surface of a payload-tier closed value. The selection is
+ * resolved EAGERLY against the declared columns and lowered as-is — the SDK
+ * never pre-folds ψ into an id set: pass-through lowering is what the macro
+ * does, and the ENGINE folds against the sealed extension at validate
+ * (`compile_member_set`).
+ */
+interface ClosedSelectable<Name extends string, Handles extends string, Cols extends Record<string, PayloadField>> {
+	where(selection: ClosedSelectionInput<Cols>): SelectedClosed<Name, Handles, Cols>
+}
+
+/**
+ * A closed relation value: the core surface plus — exactly when payload
+ * columns exist — `where()` (the bare tier has nothing to select on, so
+ * the method is ABSENT there, not merely uncallable). NOTHING else:
+ * handles are data on the roster, never properties of the value (the
+ * handle constants, the match operator, and the id-to-handle weld died
+ * with the bigint era — dispatch is native `switch` narrowing over the
+ * handle union).
  */
-type Closed<Name extends string, Handles extends string, Cols extends Record<string, PayloadField>> = ClosedCore<
-	Name,
-	Handles,
-	Cols
-> & { readonly [H in Handles]: bigint }
+type Closed<Name extends string, Handles extends string, Cols extends Record<string, PayloadField>> = [
+	keyof Cols
+] extends [never]
+	? ClosedCore<Name, Handles, Cols>
+	: ClosedCore<Name, Handles, Cols> & ClosedSelectable<Name, Handles, Cols>
 
 /** Any closed relation value, whatever its roster and columns. */
 interface AnyClosed {
@@ -183,21 +237,6 @@ function axiomsMinted<Handles extends string, Cols extends Record<string, Payloa
 	})
 }
 
-/**
- * The trusted seam of the handle-constant mint: every handle reads back as
- * an own bigint — verified before the record is admitted at the constants
- * type (a "__proto__"-named handle riding the object-protocol accessor
- * would fail exactly this check).
- */
-function constantsMinted<Handles extends string>(
-	record: Readonly<Record<string, bigint>>,
-	handles: readonly Handles[]
-): record is Readonly<Record<string, bigint>> & { readonly [H in Handles]: bigint } {
-	return handles.every(function constantMinted(handle) {
-		return typeof record[handle] === "bigint"
-	})
-}
-
 /**
  * Reads one handle's ground axiom row for lowering. The typed payload
  * surface makes absence unrepresentable ({@link Axioms} carries every
@@ -239,22 +278,6 @@ function mintAxioms<Handles extends string, Cols extends Record<string, PayloadF
 	return out
 }
 
-/** Mints the handle constants: one own bigint per handle, ids = declaration order. */
-function mintHandleConstants<Handles extends string>(
-	name: string,
-	handles: readonly Handles[]
-): { readonly [H in Handles]: bigint } {
-	const out: Record<string, bigint> = {}
-	handles.forEach(function mintHandleConstant(handle, index) {
-		Object.defineProperty(out, handle, { value: BigInt(index), enumerable: true })
-	})
-	Object.freeze(out)
-	if (!constantsMinted(out, handles)) {
-		throw errors.new(`closed relation ${name}: handle-constant minting incomplete`)
-	}
-	return out
-}
-
 /** Bare tier: `closed("Kind", ["Checking", "Savings"])` — handles only. */
 function closed<const Name extends string, const Handles extends readonly [string, ...string[]]>(
 	name: Name,
@@ -262,29 +285,40 @@ function closed<const Name extends string, const Handles extends readonly [strin
 ): Closed<Name, Handles[number], Record<never, never>>
 
 /**
- * Payload tier: declared columns, then ground axioms — `closed("Grade",
- * { mastered: bool })({ DirectPass: { mastered: true }, Failed: { mastered:
- * false } })`. The axioms record's keys ARE the handles (declaration order
- * = key order, integer-index names rejected); every row carries every
- * column exactly once (type-enforced by {@link Axioms}).
+ * Payload tier: declared columns AND ground axioms, one call — `closed(
+ * "Grade", { mastered: bool }, { DirectPass: { mastered: true }, Failed:
+ * { mastered: false } })`. The curried tier-2 spelling is DELETED
+ * (canonical utterance): `Cols` infers from the column block, the handle
+ * set from the axioms record's keys (reverse mapped-type inference), and
+ * every row is contextually checked against the declared columns — a
+ * wrong-typed value errors ON its property. The axioms record's keys ARE
+ * the handles (declaration order = key order, integer-index names
+ * rejected); every row carries every column exactly once (type-enforced by
+ * {@link Axioms}).
  */
-function closed<const Name extends string, const Cols extends Record<string, PayloadField>>(
+function closed<const Name extends string, const Cols extends PayloadColumns, Handles extends string>(
 	name: Name,
-	columns: Cols
-): <Handles extends string>(axioms: Axioms<Handles, Cols>) => Closed<Name, Handles, Cols>
+	columns: Cols,
+	axioms: Axioms<Handles, Cols>
+): Closed<Name, Handles, Cols>
 
-function closed<const Name extends string>(
+function closed<const Name extends string, const Cols extends PayloadColumns, Handles extends string>(
 	name: Name,
-	shape: readonly [string, ...string[]] | Record<string, PayloadField>
-):
-	| Closed<Name, string, Record<never, never>>
-	| (<Handles extends string>(
-			axioms: Axioms<Handles, Record<string, PayloadField>>
-	  ) => Closed<Name, Handles, Record<string, PayloadField>>) {
+	shape: readonly [string, ...string[]] | Cols,
+	axioms?: Axioms<Handles, Cols>
+): Closed<Name, string, Record<never, never>> | Closed<Name, Handles, Cols> {
 	if (isHandleTuple(shape)) {
+		if (axioms !== undefined) {
+			throw errors.new(`closed relation ${name}: the bare tier declares no columns, so ground axioms are inadmissible`)
+		}
 		return closedBare(name, shape)
 	}
-	return closedPayload(name, shape)
+	if (axioms === undefined) {
+		throw errors.new(
+			`closed relation ${name}: payload columns declared without ground axioms — the payload tier is spelled closed(name, columns, axioms) (the curried spelling is deleted)`
+		)
+	}
+	return closedPayload(name, shape, axioms)
 }
 
 /** The bare tier's precisely-typed builder: no columns, no axioms. */
@@ -297,35 +331,49 @@ function closedBare<Name extends string, Handles extends string>(
 
 /**
  * The payload tier's precisely-typed builder: column names are judged
- * EAGERLY (at `closed(name, columns)`, before any axioms arrive — the
- * macro-expansion analog), and the returned `withAxioms` reads its handle
- * set off the axioms record's own keys.
+ * first (the macro-expansion analog), then the handle set is read off the
+ * axioms record's own keys.
  */
-function closedPayload<Name extends string, Cols extends Record<string, PayloadField>>(
+function closedPayload<Name extends string, Handles extends string, Cols extends PayloadColumns>(
 	name: Name,
-	columns: Cols
-): <Handles extends string>(axioms: Axioms<Handles, Cols>) => Closed<Name, Handles, Cols> {
+	columns: Cols,
+	axioms: Axioms<Handles, Cols>
+): Closed<Name, Handles, Cols> {
 	for (const columnName of Object.keys(columns)) {
 		assertDeclarationOrderKey(`closed relation ${name} column`, columnName)
 	}
-	return function withAxioms<Handles extends string>(axioms: Axioms<Handles, Cols>): Closed<Name, Handles, Cols> {
-		const handles = Object.keys(axioms)
-		for (const handle of handles) {
-			assertDeclarationOrderKey(`closed relation ${name} handle`, handle)
-		}
-		if (!handleKeysOwn(axioms, handles)) {
-			throw errors.new(`closed relation ${name}: handle enumeration incomplete`)
-		}
-		return mintClosed<Name, Handles, Cols>(name, handles, columns, axioms)
+	const handles = Object.keys(axioms)
+	for (const handle of handles) {
+		assertDeclarationOrderKey(`closed relation ${name} handle`, handle)
 	}
+	if (!handleKeysOwn(axioms, handles)) {
+		throw errors.new(`closed relation ${name}: handle enumeration incomplete`)
+	}
+	return mintClosed<Name, Handles, Cols>(name, handles, columns, axioms)
+}
+
+/**
+ * The trusted seam of the ergonomic-surface mint: `where` reads back as an
+ * own function exactly when payload columns exist, and is ABSENT otherwise
+ * — the runtime twin of the {@link Closed} type's conditional arm
+ * (`ClosedCore` alone vs `ClosedCore & ClosedSelectable`), verified before
+ * the minted value is admitted at the conditional type.
+ */
+function surfaceMinted<Name extends string, Handles extends string, Cols extends Record<string, PayloadField>>(
+	value: ClosedCore<Name, Handles, Cols>,
+	cols: readonly ClosedColumn[]
+): value is ClosedCore<Name, Handles, Cols> & Closed<Name, Handles, Cols> {
+	const selectable = "where" in value && typeof value.where === "function"
+	return cols.length > 0 ? selectable : !selectable
 }
 
 /**
  * Mints one closed relation value — the shared seam of both tiers, HONESTLY
  * typed end to end (a wrong-shaped mint is a compile error here, not a
  * laundered `unknown`): roster checks, eager axiom lowering, the
- * domain-labeled `id` descriptor, the frozen `columns` carrier (the runtime
- * twin of the `Cols` type parameter), and the handle constants.
+ * roster-carrying `id` descriptor, the frozen `columns` carrier (the runtime
+ * twin of the `Cols` type parameter), and — on the payload tier only — the
+ * ψ-selection `where()`.
  */
 function mintClosed<Name extends string, Handles extends string, Cols extends Record<string, PayloadField>>(
 	name: Name,
@@ -342,17 +390,17 @@ function mintClosed<Name extends string, Handles extends string, Cols extends Re
 			throw errors.new(`closed relation ${name}: duplicate handle ${handle}`)
 		}
 		seen.add(handle)
-		if (reservedHandleNames.includes(handle)) {
-			throw errors.new(
-				`closed relation ${name}: handle ${handle} collides with the closed value's own surface (${reservedHandleNames.join(", ")})`
-			)
-		}
 	}
 	const handleList: readonly Handles[] = Object.freeze([...handles])
-	const roster: ClosedRoster = Object.freeze({ name, handles: handleList })
+	const roster: ClosedRoster<Handles> = Object.freeze({ name, handles: handleList })
 	const cols: ClosedColumn[] = []
 	for (const [columnName, field] of Object.entries(columns)) {
 		assertDeclarationOrderKey(`closed relation ${name} column`, columnName)
+		if (columnName === "id") {
+			throw errors.new(
+				`closed relation ${name}: the payload column id collides with the sealed shape's synthetic id (the relation mints its own id at ordinal 0; name the column something else)`
+			)
+		}
 		cols.push(Object.freeze({ name: columnName, field }))
 	}
 	Object.freeze(cols)
@@ -369,38 +417,58 @@ function mintClosed<Name extends string, Handles extends string, Cols extends Re
 		columns: cols,
 		rows: Object.freeze(rows)
 	})
-	const id: ClosedIdField<`${Name}Id`> = Object.freeze({
-		kind: "u64",
-		domain: `${name}Id`,
-		closed: roster
-	})
+	const id: ClosedIdField<Handles> = Object.freeze({ kind: "u64", closed: roster })
 	/**
-	 * Handle names are arbitrary identifiers, so rows and constants are
-	 * minted with OWN-property definition (inside {@link mintAxioms} and
-	 * {@link mintHandleConstants}), never assignment: a handle named
-	 * "__proto__" would otherwise ride the Object.prototype accessor —
-	 * silently swapping the record's prototype instead of creating the row,
-	 * and no-oping the constant (a primitive through the setter) — minting a
-	 * value whose type claims a bigint constant but reads back an object.
-	 * (Object SPREAD is CreateDataProperty by spec, so the copies below are
-	 * own-property safe for column names too.)
+	 * Handle names are arbitrary identifiers, so axiom rows are minted with
+	 * OWN-property definition (inside {@link mintAxioms}), never assignment:
+	 * a handle named "__proto__" would otherwise ride the Object.prototype
+	 * accessor — silently swapping the record's prototype instead of
+	 * creating the row. (Object SPREAD is CreateDataProperty by spec, so the
+	 * copies below are own-property safe for column names too.)
 	 */
 	const axiomsOut = mintAxioms<Handles, Cols>(name, handleList, cols, axioms)
-	const constants = mintHandleConstants(name, handleList)
 	const columnsOut: Cols = { ...columns }
 	Object.freeze(columnsOut)
-	return Object.freeze({
-		...constants,
-		name,
-		id,
-		data,
-		axioms: axiomsOut,
-		columns: columnsOut,
-		fromId(idValue: bigint): Handles | undefined {
-			return handleList[Number(idValue)]
+	const holder: { value: Closed<Name, Handles, Cols> | undefined } = { value: undefined }
+	/**
+	 * The ψ selection: resolved against the declared payload columns through
+	 * the ONE selection machine (`relation.ts::resolveSelection` — a
+	 * `ClosedColumn` is structurally a `RelationField`), never pre-folded
+	 * into an id set (the engine folds at validate).
+	 */
+	function where(selection: ClosedSelectionInput<Cols>): SelectedClosed<Name, Handles, Cols> {
+		const owner = holder.value
+		if (owner === undefined) {
+			throw errors.new(`closed relation ${name}: self-reference read before construction completed`)
 		}
-	})
+		return Object.freeze({
+			relation: owner,
+			selection: resolveSelection(name, cols, Object.entries(selection))
+		})
+	}
+	const core = { name, id, data, axioms: axiomsOut, columns: columnsOut }
+	const value: ClosedCore<Name, Handles, Cols> =
+		cols.length > 0 ? Object.freeze({ ...core, where }) : Object.freeze(core)
+	if (!surfaceMinted<Name, Handles, Cols>(value, cols)) {
+		throw errors.new(`closed relation ${name}: ergonomic-surface minting incomplete`)
+	}
+	holder.value = value
+	return value
 }
 
-export type { AnyClosed, AxiomRow, Axioms, Closed, ClosedColumn, ClosedCore, ClosedData, ClosedRow, PayloadField }
+export type {
+	AnyClosed,
+	AnySelectedClosed,
+	AxiomRow,
+	Axioms,
+	Closed,
+	ClosedColumn,
+	ClosedCore,
+	ClosedData,
+	ClosedRow,
+	ClosedSelectable,
+	ClosedSelectionInput,
+	PayloadField,
+	SelectedClosed
+}
 export { closed }

package/src/db.ts

@@ -35,7 +35,17 @@ import * as errors from "@superbuilders/errors"
 import type { Exhumed } from "#exhume.ts"
 import { exhumeStore } from "#exhume.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,
@@ -55,7 +65,7 @@ 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 } from "#relation.ts"
+import type { AnyRelation, Fact, InsertFact, RelationField } from "#relation.ts"
 import type { AnySchema, Schema, SchemaRelation, SchemaRelations } from "#schema.ts"
 import type { KeyStatement, Statement } from "#statements.ts"
 
@@ -79,7 +89,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
@@ -525,6 +538,22 @@ 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>
@@ -705,12 +734,20 @@ 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 = declaredFieldsOf(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
+			})
+			decoded[cell.name] =
+				cited !== undefined && "closed" in cited.field
+					? handleOf(`violation fact ${fact.relation} field ${cell.name}`, cited.field.closed, cell.value)
+					: cell.value
 		}
 		return Object.freeze({ relation: fact.relation, fact: Object.freeze(decoded) })
 	}
@@ -1419,16 +1456,31 @@ process.once("exit", function closeCachedStores() {
 	}
 })
 
+/**
+ * The engine twin of the schema-level class wall, as a matchable value
+ * (`errors.is`): the shared lowering rejected a spec whose statement pairs
+ * faces with disagreeing newtype labels — the faces of a dependency agree
+ * on their newtype, or neither carries one. UNREACHABLE through the typed
+ * builder (the SDK computes every label from the laws, so its lowered
+ * specs cohere by construction); a raw spec handed to the bridge is the
+ * one road here, and the runtime referee that proves the engine judges
+ * what the types claim.
+ */
+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"
+)
+
 /**
  * The one admission path both verbs share: canonical-path cache lookup
  * first (a hit returns the SAME `Db` value for the identical theory, a
  * typed fingerprint error for a different one, and a typed refusal for
  * `create` — the store a cache entry proves initialized is exactly what
  * create refuses). On a miss: lower the theory, run one bridge call, and
- * wrap the two domain refusals — `schemaError` (spec resolution + schema
- * validation, every issue in one message) and `fingerprintMismatch` (a
- * different theory cannot open the store) — into typed errors carrying the
- * engine's message intact.
+ * wrap the domain refusals — `schemaError` (spec resolution + schema
+ * validation, every issue in one message), `newtypeMismatch` (the
+ * coherence wall, {@link ErrNewtypeMismatch}), and `fingerprintMismatch`
+ * (a different theory cannot open the store) — into typed errors carrying
+ * the engine's message intact.
  */
 function admit<Rels extends SchemaRelations>(
 	verb: "create" | "open",
@@ -1458,6 +1510,9 @@ function admit<Rels extends SchemaRelations>(
 		return native.dbOpen(canonical, spec)
 	})
 	if (!opened.ok) {
+		if (opened.kind === "newtypeMismatch") {
+			throw errors.wrap(ErrNewtypeMismatch, `${verb} ${canonical}: ${opened.message}`)
+		}
 		throw errors.new(`bumbledb ${opened.kind} (${verb} ${canonical}): ${opened.message}`)
 	}
 	const manifest = bridged("fetch bumbledb manifest", function fetchManifest() {
@@ -1526,4 +1581,4 @@ export type {
 	WitnessedWriteResult,
 	WriteResult
 }
-export { abandon, Db }
+export { abandon, Db, ErrNewtypeMismatch }