@bjornpagen/bumbledb 0.3.0 → 0.4.0

package/dist/statements.js

@@ -8,10 +8,16 @@
  * Every field reference is checked against the relation it names in the
  * TYPE — existence through {@link FaceFields} (`on(R, "nope")` does not
  * compile) and STRUCTURAL compatibility through {@link SameShapes}: the two
- * faces' projected kind/width/element triples are read off the schema type
- * (the minimal kernel — descriptors are pure structure) and constrained
- * positionwise equal, so a u64 face against a str face, a bytes width
- * mismatch, or an interval element mismatch is a compile error. Domains are
+ * faces' projected kind/width/element/roster quadruples are read off the
+ * schema type (the minimal kernel — descriptors are pure structure) and
+ * constrained positionwise equal, so a u64 face against a str face, a
+ * bytes width mismatch, an interval element mismatch, or a bare column
+ * against a closed reference is a compile error. The ROSTER slot carries a
+ * construction-time runtime twin here ({@link assertRosterAgreement} —
+ * roster IDENTITY, positionwise: a closed vocabulary's referencing column
+ * is spelled with the vocabulary's own id descriptor, the ONE spelling, so
+ * a plain u64 column can never alias a vocabulary through a declared law
+ * and the SDK's descriptor-keyed closed judgments stay sound). Domains are
  * NOT compared here — there is no domain to compare at construction: the
  * statements themselves are what define the equivalence classes, and the
  * domain wall lives where they aggregate — `schema()` (the
@@ -27,6 +33,66 @@
 import * as errors from "@superbuilders/errors";
 import { renderFace } from "#face.ts";
 import { renderWindow } from "#spec.ts";
+/**
+ * The field descriptor one face position projects: an ordinary relation's
+ * declared field; a closed relation's SEALED shape — the synthetic `id`
+ * (the value's own roster-carrying descriptor, by identity) or a declared
+ * payload column. `undefined` when the name is foreign (the type tier makes
+ * that unwritable; the engine re-judges projections at `Db.create`).
+ */
+function projectedFieldOf(face, fieldName) {
+    const owner = face.owner;
+    if ("axioms" in owner) {
+        if (fieldName === "id") {
+            return owner.id;
+        }
+        const column = owner.data.columns.find(function byName(candidate) {
+            return candidate.name === fieldName;
+        });
+        return column?.field;
+    }
+    const declared = owner.data.fields.find(function byName(candidate) {
+        return candidate.name === fieldName;
+    });
+    return declared?.field;
+}
+/** The roster a descriptor carries: present exactly on a closed reference, absent on every other kind. */
+function rosterOfField(field) {
+    if (field !== undefined && "closed" in field) {
+        return field.closed;
+    }
+    return undefined;
+}
+/** Renders one face position's closedness for the roster-agreement diagnostics. */
+function renderRosterSide(roster) {
+    return roster === undefined ? "a bare column" : `a ${roster.name} reference`;
+}
+/**
+ * The runtime twin of {@link SameShapes}'s roster slot: the two faces'
+ * projected descriptors must agree POSITIONWISE on closedness — the same
+ * roster (value identity — vocabulary identity is value identity, the
+ * SDK's membership rule everywhere) or none. Without this wall a plain u64
+ * column could alias a closed vocabulary through a declared containment
+ * (`docs/architecture/10-data-model.md` spells the ENGINE encoding that
+ * way), and every descriptor-keyed closed judgment — the orderable ban,
+ * the name↔id marshal, answer decode — would silently miss it. The
+ * vocabulary's own descriptor (`Kind.id`) is the ONE spelling of a closed
+ * reference at this surface (the canonical-utterance law); the engine
+ * cannot backstop this one — the wire carries plain u64s, no rosters.
+ */
+function assertRosterAgreement(source, target, statement) {
+    source.projection.forEach(function agreeAt(fieldName, position) {
+        const targetField = target.projection[position];
+        if (targetField === undefined) {
+            return;
+        }
+        const sourceRoster = rosterOfField(projectedFieldOf(source, fieldName));
+        const targetRoster = rosterOfField(projectedFieldOf(target, targetField));
+        if (sourceRoster !== targetRoster) {
+            throw errors.new(`${source.owner.name}.${fieldName} is ${renderRosterSide(sourceRoster)} but ${target.owner.name}.${targetField} is ${renderRosterSide(targetRoster)} — closedness rides the descriptor: a closed reference is spelled with the vocabulary's own id descriptor (one meaning, one spelling), so faces pair closed-with-closed through one roster or bare-with-bare, never across — ${renderStatement(statement)}`);
+        }
+    });
+}
 /**
  * `R(X) -> R` — the FD key form, composite keys as tuples. No selection
  * parameter exists (the FD-with-selection shape is unrepresentable, as in
@@ -65,7 +131,9 @@ function contained(source, target) {
         target: target.data,
         bidirectional: false
     });
-    return Object.freeze({ data });
+    const statement = Object.freeze({ data });
+    assertRosterAgreement(data.source, data.target, statement);
+    return statement;
 }
 /**
  * `A(X|φ) == B(Y|ψ)` — the bidirectional abbreviation, one utterance: the
@@ -83,7 +151,9 @@ function mirrors(source, target) {
         target: target.data,
         bidirectional: true
     });
-    return Object.freeze({ data });
+    const statement = Object.freeze({ data });
+    assertRosterAgreement(data.source, data.target, statement);
+    return statement;
 }
 /**
  * `B(Y|ψ) <={window} A(X|φ)` — the cardinality window. READ CAREFULLY: the
@@ -102,7 +172,9 @@ function window(target, count, source) {
         window: count.window,
         source: source.data
     });
-    return Object.freeze({ data });
+    const statement = Object.freeze({ data });
+    assertRosterAgreement(data.source, data.target, statement);
+    return statement;
 }
 /**
  * Renders one statement in the CANONICAL macro spelling

package/dist/statements.js.map

@@ -1 +1 @@
-{"version":3,"file":"statements.js","sourceRoot":"","sources":["../src/statements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAA;AAE/C,OAAO,EAA+B,UAAU,EAAmC,MAAM,UAAU,CAAA;AAEnG,OAAO,EAAE,YAAY,EAAmB,MAAM,UAAU,CAAA;AAqExD;;;;;;;;;;GAUG;AACH,SAAS,GAAG,CAGV,QAAW,EAAE,MAAkB;IAChC,IAAI,CAAC,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAClC,MAAM,MAAM,CAAC,GAAG,CACf,OAAO,QAAQ,CAAC,IAAI,2CAA2C,QAAQ,CAAC,IAAI,WAAW,QAAQ,CAAC,IAAI,oEAAoE,CACxK,CAAA;IACF,CAAC;IACD,MAAM,IAAI,GAA2B,MAAM,CAAC,MAAM,CAAC;QAClD,IAAI,EAAE,KAAK;QACX,KAAK,EAAE,QAAQ;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;KACjC,CAAC,CAAA;IACF,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAA;AAC/B,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,SAAS,CACjB,MAAS,EACT,MAA8C;IAE9C,MAAM,IAAI,GAA0C,MAAM,CAAC,MAAM,CAAC;QACjE,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,MAAM,CAAC,IAAI;QACnB,MAAM,EAAE,MAAM,CAAC,IAAI;QACnB,aAAa,EAAE,KAAK;KACpB,CAAC,CAAA;IACF,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAA;AAC/B,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,OAAO,CACf,MAAS,EACT,MAA8C;IAE9C,MAAM,IAAI,GAA0C,MAAM,CAAC,MAAM,CAAC;QACjE,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,MAAM,CAAC,IAAI;QACnB,MAAM,EAAE,MAAM,CAAC,IAAI;QACnB,aAAa,EAAE,IAAI;KACnB,CAAC,CAAA;IACF,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAA;AAC/B,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,MAAM,CACd,MAAS,EACT,KAAY,EACZ,MAA8C;IAE9C,MAAM,IAAI,GAAqC,MAAM,CAAC,MAAM,CAAC;QAC5D,IAAI,EAAE,QAAQ;QACd,MAAM,EAAE,MAAM,CAAC,IAAI;QACnB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,MAAM,EAAE,MAAM,CAAC,IAAI;KACnB,CAAC,CAAA;IACF,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAA;AAC/B,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,eAAe,CAAC,SAAoB;IAC5C,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAA;IAC3B,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,KAAK;YACT,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAA;QACjF,KAAK,aAAa,EAAE,CAAC;YACpB,MAAM,QAAQ,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAA;YACjD,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAA;QAC3E,CAAC;QACD,KAAK,QAAQ;YACZ,OAAO,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAA;IAC/F,CAAC;AACF,CAAC;AAYD,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,CAAA"}
+{"version":3,"file":"statements.js","sourceRoot":"","sources":["../src/statements.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bjornpagen/bumbledb",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Type-theoretic TypeScript SDK for the bumbledb embedded relational engine",
   "module": "dist/index.js",
   "main": "dist/index.js",
@@ -44,7 +44,7 @@
     "@superbuilders/errors": "^4.0.2"
   },
   "optionalDependencies": {
-    "@bjornpagen/bumbledb-darwin-arm64": "0.3.0"
+    "@bjornpagen/bumbledb-darwin-arm64": "0.4.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.0.0-beta.5",

package/src/closed.ts

@@ -1,34 +1,36 @@
 /**
  * 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 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`), 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 structural wall reads). Bare tier: `closed("Kind", ["Checking",
+ * 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). No fact type and no insert surface exist — closed
- * relations are unwritable by construction: the value simply lacks the
- * writable relation shape. Both tiers mint `match()` — exhaustive dispatch
- * over the handle union (arms typed by the mapped type, so a missing or
- * extra arm is a compile error; the payload tier's arm receives the typed
- * axiom row). The payload tier additionally mints `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.
+ * (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"
-import type { OneOf } from "#face.ts"
 import {
 	type AnyField,
 	assertDeclarationOrderKey,
@@ -37,31 +39,9 @@ import {
 	type Infer,
 	literalOf
 } from "#fields.ts"
-import { resolveSelection, type SelectionBinding } from "#relation.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; `where` is
- * reserved because the payload tier mints the ψ-selection method under
- * exactly that name; `match` because BOTH tiers mint the exhaustive
- * dispatch under exactly that name).
- */
-const reservedHandleNames: readonly string[] = Object.freeze([
-	"name",
-	"id",
-	"data",
-	"axioms",
-	"columns",
-	"fromId",
-	"where",
-	"match",
-	"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).
@@ -126,12 +106,14 @@ interface ClosedCore<Name extends string, Handles extends string, Cols extends R
 	readonly name: Name
 	/**
 	 * The closed 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. Pure structure plus the roster —
-	 * the referencing field's domain is law-born: `schema()` computes it
-	 * from the declared containment (`"Kind.id"`, the generator class).
+	 * 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
+	readonly id: ClosedIdField<Handles>
 	readonly data: ClosedData
 	/** Payload readback: handle to its declared column values, bare and structural. */
 	readonly axioms: Axioms<Handles, Cols>
@@ -144,20 +126,18 @@ interface ClosedCore<Name extends string, Handles extends string, Cols extends R
 	 * 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
 }
 
 /**
- * The `where()` argument of a closed relation: per PAYLOAD column, a bare
- * structural literal of that column's value type or an `oneOf(a, b, ...)`
- * literal set — the ordinary `where()`'s vocabulary exactly. The synthetic
- * `id` is deliberately absent: an id selection is spelled only as handle
- * literals on the REFERENCING side (the canonical-utterance law).
+ * 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>> = {
-	readonly [C in keyof Cols]?: Infer<Cols[C]> | OneOf<Infer<Cols[C]>>
-}
+type ClosedSelectionInput<Cols extends Record<string, PayloadField>> = SelectionInput<Cols>
 
 /**
  * A closed relation with a ψ selection applied — what `on()` consumes as a
@@ -190,44 +170,19 @@ interface ClosedSelectable<Name extends string, Handles extends string, Cols ext
 }
 
 /**
- * Exhaustive dispatch over a BARE closed vocabulary: one arm per handle,
- * no literal types and no brands — the handle-name union on the value's
- * type IS the exhaustiveness proof (a missing arm is a missing-property
- * compile error; an extra arm an excess-property compile error). The bare
- * tier declares no payload, so an arm takes nothing. The arms record types
- * any `bigint` in — the runtime roster refuses an out-of-vocabulary id
- * with a throw, never a misdispatch.
+ * 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).
  */
-interface ClosedMatchBare<Handles extends string> {
-	match<T>(id: bigint, arms: { readonly [H in Handles]: () => T }): T
-}
-
-/**
- * Exhaustive dispatch over a PAYLOAD-tier closed vocabulary: the same
- * mapped-type exhaustiveness as the bare tier, and each arm receives its
- * handle's typed axiom row (the declared columns, bare and structural —
- * the frozen readback row from `axioms`).
- */
-interface ClosedMatchPayload<Handles extends string, Cols extends Record<string, PayloadField>> {
-	match<T>(id: bigint, arms: { readonly [H in Handles]: (row: AxiomRow<Cols>) => T }): T
-}
-
-/**
- * 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), plus `match()` on BOTH tiers (bare arms take
- * nothing; payload arms receive the typed axiom row), plus — exactly when
- * payload columns exist — `where()` (the bare tier has nothing to select
- * on, so the method is ABSENT there, not merely uncallable).
- */
-type Closed<Name extends string, Handles extends string, Cols extends Record<string, PayloadField>> = ClosedCore<
-	Name,
-	Handles,
-	Cols
-> & { readonly [H in Handles]: bigint } & ([keyof Cols] extends [never]
-		? ClosedMatchBare<Handles>
-		: ClosedSelectable<Name, Handles, Cols> & ClosedMatchPayload<Handles, Cols>)
+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 {
@@ -282,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
@@ -338,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,
@@ -429,19 +353,18 @@ function closedPayload<Name extends string, Handles extends string, Cols extends
 }
 
 /**
- * The trusted seam of the ergonomic-surface mint: `match` reads back as an
- * own function on BOTH tiers, and `where` exactly when payload columns
- * exist — the runtime twin of the {@link Closed} type's conditional arm
- * (`ClosedMatchBare` vs `ClosedSelectable & ClosedMatchPayload`), verified
- * before the minted value is admitted at the conditional type.
+ * 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> & { readonly [H in Handles]: bigint },
+	value: ClosedCore<Name, Handles, Cols>,
 	cols: readonly ClosedColumn[]
-): value is Closed<Name, Handles, Cols> {
-	const matchable = "match" in value && typeof value.match === "function"
+): value is ClosedCore<Name, Handles, Cols> & Closed<Name, Handles, Cols> {
 	const selectable = "where" in value && typeof value.where === "function"
-	return matchable && (cols.length > 0 ? selectable : !selectable)
+	return cols.length > 0 ? selectable : !selectable
 }
 
 /**
@@ -449,8 +372,7 @@ function surfaceMinted<Name extends string, Handles extends string, Cols extends
  * typed end to end (a wrong-shaped mint is a compile error here, not a
  * laundered `unknown`): roster checks, eager axiom lowering, the
  * roster-carrying `id` descriptor, the frozen `columns` carrier (the runtime
- * twin of the `Cols` type parameter), the handle constants, the exhaustive
- * `match()` on both tiers, and — on the payload tier only — the
+ * 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>>(
@@ -468,14 +390,9 @@ 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)
@@ -500,25 +417,18 @@ function mintClosed<Name extends string, Handles extends string, Cols extends Re
 		columns: cols,
 		rows: Object.freeze(rows)
 	})
-	const id: ClosedIdField = Object.freeze({ kind: "u64", 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)
-	function 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
@@ -536,27 +446,9 @@ function mintClosed<Name extends string, Handles extends string, Cols extends Re
 			selection: resolveSelection(name, cols, Object.entries(selection))
 		})
 	}
-	/**
-	 * The exhaustive dispatch: the ROSTER judges the id (the structural type
-	 * admits any bigint — a dishonest id is a THROW, never a misdispatch),
-	 * and the chosen arm receives the handle's frozen axiom row (the bare
-	 * tier's arms are typed to take nothing; the empty row rides along
-	 * unread). One implementation serves both tiers — the conditional
-	 * {@link Closed} arm claims the tier-exact arm signature and
-	 * {@link surfaceMinted} is the trusted seam that admits it.
-	 */
-	function match<T>(idValue: bigint, arms: { readonly [H in Handles]: (row: AxiomRow<Cols>) => T }): T {
-		const handle = fromId(idValue)
-		if (handle === undefined) {
-			throw errors.new(`closed relation ${name}: match on id ${idValue} misses the roster (${handleList.join(", ")})`)
-		}
-		return arms[handle](axiomsOut[handle])
-	}
-	const core = { name, id, data, axioms: axiomsOut, columns: columnsOut, fromId }
-	const value: ClosedCore<Name, Handles, Cols> & { readonly [H in Handles]: bigint } =
-		cols.length > 0
-			? Object.freeze({ ...constants, ...core, where, match })
-			: Object.freeze({ ...constants, ...core, match })
+	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`)
 	}
@@ -574,6 +466,7 @@ export type {
 	ClosedCore,
 	ClosedData,
 	ClosedRow,
+	ClosedSelectable,
 	ClosedSelectionInput,
 	PayloadField,
 	SelectedClosed

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) })
 	}