@bjornpagen/bumbledb 0.1.0 → 0.2.0

package/dist/statements.js

@@ -4,9 +4,23 @@
  * form, conditional containment, the bidirectional `==` abbreviation, and
  * the cardinality window. A statement value is opaque and inert — no
  * methods, no fluent continuation: a fact about the theory, not a builder.
+ *
+ * Every field reference is checked against the relation it names in the
+ * TYPE — existence through {@link FaceFields} (`on(R, "nope")` does not
+ * compile) and DOMAIN compatibility through {@link SameDomains}: the two
+ * faces' projected domain labels are read structurally off the schema type
+ * (S1's `F["domain"]`) and constrained positionwise equal, so a
+ * cross-domain pair is a compile error by string-literal comparison of
+ * descriptor shapes — never by a value brand (the structural design's
+ * ratified check). What is only a SEMANTIC property — the target side of a
+ * containment resolving a declared key of its relation — is DELIBERATELY
+ * not (and cannot be) stated here: whether `B(y)` is a key of `B` depends
+ * on which `key()` statements the surrounding `schema()` collects, a set no
+ * face type can see; it stays the engine's typed `SchemaError` judgment at
+ * `Db.create`/`Db.open` (the two-boundary split, engine as final
+ * authority).
  */
 import * as errors from "@superbuilders/errors";
-import { phantom } from "#brand.ts";
 import { renderFace } from "#face.ts";
 import { renderWindow } from "#spec.ts";
 /**
@@ -14,9 +28,11 @@ import { renderWindow } from "#spec.ts";
  * parameter exists (the FD-with-selection shape is unrepresentable, as in
  * the grammar), and only ordinary relations are accepted: a closed
  * relation's key `R(id) -> R` is materialized by the engine, so an
- * explicit one would only ever be a duplicate. The projection tuple is
- * carried in the returned value's type ({@link KeyStatement}), so keyed
- * point reads through THIS statement are typed field-for-field.
+ * explicit one would only ever be a duplicate. Every projected name is
+ * checked against `R`'s field block in the type, and the tuple is carried
+ * in the returned value's type ({@link KeyStatement}) — keyed point reads
+ * through THIS statement are typed field-for-field, domains resolvable
+ * through the owner's schema type.
  */
 function key(relation, fields) {
     if (!("fields" in relation.data)) {
@@ -25,15 +41,18 @@ function key(relation, fields) {
     const data = Object.freeze({
         kind: "key",
         owner: relation,
-        projection: Object.freeze([...fields])
+        projection: Object.freeze(fields)
     });
     return Object.freeze({ data });
 }
 /**
- * `A(X|φ) <= B(Y|ψ)` — conditional inclusion, source left. The target
- * side must resolve a declared key of B — DELIBERATELY judged by the
- * engine at `Db.create`/`Db.open` (`SchemaError`), never re-checked here.
- * Arity mismatch between the two faces is a type error ({@link SameArity}).
+ * `A(X|φ) <= B(Y|ψ)` — conditional inclusion, source left. Arity mismatch
+ * between the two faces is a type error ({@link SameArity}); a cross-domain
+ * pair is a type error ({@link SameDomains} — positionwise string-literal
+ * equality of the projected S1 domain labels). The target side must
+ * resolve a declared key of B — a SEMANTIC property of the whole statement
+ * set that no face type can state, DELIBERATELY judged by the engine at
+ * `Db.create`/`Db.open` (`SchemaError`), never re-checked here.
  */
 function contained(source, target) {
     const data = Object.freeze({
@@ -45,9 +64,13 @@ function contained(source, target) {
     return Object.freeze({ data });
 }
 /**
- * `A(X|φ) == B(Y|ψ)` — the bidirectional abbreviation, one utterance. It
- * lowers to the two adjacent containments in the `A <= B` first order
- * (macro parity) and renders as `==` once, in the written orientation.
+ * `A(X|φ) == B(Y|ψ)` — the bidirectional abbreviation, one utterance: the
+ * selected `==` bijection, a keyed one-to-one correspondence between the
+ * two faces (each side contains the other). It lowers to the two adjacent
+ * containments in the `A <= B` first order (macro parity — the engine
+ * performs the split, source-first) and renders as `==` once, in the
+ * written orientation. Faces pair by arity AND domain, exactly as
+ * {@link contained}.
  */
 function mirrors(source, target) {
     const data = Object.freeze({
@@ -63,7 +86,9 @@ function mirrors(source, target) {
  * LEFT face is the window's TARGET, the per-group parent (B-family,
  * target-left — macro parity), and the RIGHT face is the counted source.
  * `window(on(Holder, "id"), atMost(3n), on(Account, "holder"))` says: each
- * Holder id groups at most three Account rows by holder.
+ * Holder id groups at most three Account rows by holder. The two faces
+ * pair by arity AND domain ({@link SameDomains}), exactly as containment —
+ * the grouping join reads the same positionwise field pairing.
  */
 function window(target, count, source) {
     const data = Object.freeze({

package/dist/statements.js.map

@@ -1 +1 @@
-{"version":3,"file":"statements.js","sourceRoot":"","sources":["../src/statements.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,MAAM,MAAM,uBAAuB,CAAA;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAEnC,OAAO,EAA+B,UAAU,EAAkB,MAAM,UAAU,CAAA;AAElF,OAAO,EAAE,YAAY,EAAmB,MAAM,UAAU,CAAA;AAmCxD;;;;;;;;GAQG;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,GAAkB,MAAM,CAAC,MAAM,CAAC;QACzC,IAAI,EAAE,KAAK;QACX,KAAK,EAAE,QAAQ;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC;KACtC,CAAC,CAAA;IACF,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAA;AAC/B,CAAC;AAED;;;;;GAKG;AACH,SAAS,SAAS,CAAuC,MAAS,EAAE,MAA2B;IAC9F,MAAM,IAAI,GAAkB,MAAM,CAAC,MAAM,CAAC;QACzC,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;;;;GAIG;AACH,SAAS,OAAO,CAAuC,MAAS,EAAE,MAA2B;IAC5F,MAAM,IAAI,GAAkB,MAAM,CAAC,MAAM,CAAC;QACzC,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;;;;;;GAMG;AACH,SAAS,MAAM,CAAuC,MAAS,EAAE,KAAY,EAAE,MAA2B;IACzG,MAAM,IAAI,GAAkB,MAAM,CAAC,MAAM,CAAC;QACzC,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;AAGD,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.1.0",
+  "version": "0.2.0",
   "description": "Type-theoretic TypeScript SDK for the bumbledb embedded relational engine",
   "module": "dist/index.js",
   "main": "dist/index.js",
@@ -21,7 +21,8 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "COOKBOOK.md"
   ],
   "keywords": [
     "database",
@@ -43,7 +44,7 @@
     "@superbuilders/errors": "^4.0.2"
   },
   "optionalDependencies": {
-    "@bjornpagen/bumbledb-darwin-arm64": "0.1.0"
+    "@bjornpagen/bumbledb-darwin-arm64": "0.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.0.0-beta.5",

package/src/closed.ts

@@ -1,25 +1,29 @@
 /**
  * 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), the `fromId` weld, an `id` field constructor
- * pre-branded with the handle newtype for other relations' field blocks
- * (`kind: Kind.id`), and payload readback (`Kind.axioms`). No fact type and
- * no insert surface exist — closed relations are unwritable by
+ * 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.
  */
 
 import * as errors from "@superbuilders/errors"
-import type { Brand } from "#brand.ts"
 import {
 	type AnyField,
 	assertDeclarationOrderKey,
 	type ClosedIdField,
 	type ClosedRoster,
-	type FieldData,
-	type FieldValue,
-	fieldData,
+	type Infer,
 	literalOf
 } from "#fields.ts"
 import type { LiteralSpec } from "#spec.ts"
@@ -35,41 +39,22 @@ const reservedHandleNames: readonly string[] = Object.freeze([
 	"id",
 	"data",
 	"axioms",
+	"columns",
 	"fromId",
 	"relation",
 	"selection"
 ])
 
 /**
- * Reads one handle's axiom row, refusing absence loudly: the payload tier's
- * overload types the record exhaustively, so a missing row is ill-typed
- * input, and the bare tier never reaches here (it declares no columns).
- */
-function axiomRow(
-	name: string,
-	axioms: Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined,
-	handle: string
-): Readonly<Record<string, unknown>> {
-	if (axioms === undefined) {
-		throw errors.new(`closed relation ${name}: payload columns declared without ground axioms`)
-	}
-	const row = axioms[handle]
-	if (row === undefined) {
-		throw errors.new(`closed relation ${name}: no ground axiom for handle ${handle}`)
-	}
-	return row
-}
-
-/**
- * A payload column of a closed relation: any field constructor except a
+ * 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 = AnyField & { readonly data: FieldData<false> }
+type PayloadField = Exclude<AnyField, { readonly fresh: true }>
 
-/** One declared payload column: name plus its field description. */
+/** One declared payload column: name plus its field descriptor. */
 interface ClosedColumn {
 	readonly name: string
-	readonly field: FieldData
+	readonly field: PayloadField
 }
 
 /**
@@ -91,75 +76,266 @@ interface ClosedData {
 	readonly rows: readonly ClosedRow[]
 }
 
-/** One axiom row as the host writes and reads it: column name to host value. */
-type AxiomRow<Cols> = { readonly [C in keyof Cols]: FieldValue<Cols[C]> }
+/** One axiom row as the host writes and reads it: column name to bare structural value. */
+type AxiomRow<Cols extends Record<string, PayloadField>> = { readonly [C in keyof Cols]: Infer<Cols[C]> }
 
 /**
  * The whole axiom record: every handle exactly once, every column exactly
- * once per row — a missing or extra axiom, column, or handle is a TYPE
- * error (mapped over the handle tuple).
+ * once per row — a missing or extra column is a TYPE error (each row is
+ * contextually checked against the declared columns), and the handle set
+ * IS the record's key set.
  */
-type Axioms<Handles extends readonly string[], Cols> = {
-	readonly [H in Handles[number]]: AxiomRow<Cols>
+type Axioms<Handles extends string, Cols extends Record<string, PayloadField>> = {
+	readonly [H in Handles]: AxiomRow<Cols>
 }
 
 /**
  * The named surface of a closed relation value, minus the handle constants
  * (which {@link Closed} intersects in).
  */
-interface ClosedCore<Name extends string, Handles extends readonly string[], Cols> {
+interface ClosedCore<Name extends string, Handles extends string, Cols extends Record<string, PayloadField>> {
 	readonly name: Name
 	/**
-	 * The pre-branded u64 field constructor: `kind: Kind.id` in another
-	 * relation's field block is the reference through which bare handles
-	 * become legal in that relation's selections.
+	 * 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`).
 	 */
-	readonly id: ClosedIdField<Name>
+	readonly id: ClosedIdField<`${Name}Id`>
 	readonly data: ClosedData
-	/** Payload readback: handle to its declared column values. */
+	/** 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
+	 * frozen runtime record (the descriptors themselves, by identity), and
+	 * the typed carrier a projected payload column's domain label is
+	 * recovered through off the schema type (the face layer's
+	 * `ProjectedDomain` 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: Brand<bigint, Name>): Handles[number] | undefined
+	fromId(id: bigint): Handles | undefined
 }
 
 /**
- * A closed relation value: the core surface plus one branded constant per
- * handle (`Kind.Checking: Brand<bigint, "Kind">`, ids = declaration order).
+ * 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).
  */
-type Closed<Name extends string, Handles extends readonly string[], Cols> = ClosedCore<Name, Handles, Cols> & {
-	readonly [H in Handles[number]]: Brand<bigint, Name>
-}
+type Closed<Name extends string, Handles extends string, Cols extends Record<string, PayloadField>> = ClosedCore<
+	Name,
+	Handles,
+	Cols
+> & { readonly [H in Handles]: bigint }
 
 /** Any closed relation value, whatever its roster and columns. */
 interface AnyClosed {
 	readonly name: string
-	readonly id: ClosedIdField<string>
+	readonly id: ClosedIdField
 	readonly data: ClosedData
 	readonly axioms: Readonly<Record<string, object>>
+	readonly columns: Readonly<Record<string, PayloadField>>
+}
+
+/** 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>
+): shape is readonly [string, ...string[]] {
+	return Array.isArray(shape)
+}
+
+/**
+ * The trusted seam of the payload tier's handle enumeration: the axioms
+ * record's own enumerable keys ARE its handle set (the type says so —
+ * {@link Axioms} is keyed by the handles), and this guard verifies exactly
+ * that checkable fact before the key list is admitted at the handle type.
+ */
+function handleKeysOwn<Handles extends string>(
+	axioms: { readonly [H in Handles]: object },
+	names: readonly string[]
+): names is readonly Handles[] {
+	return names.every(function ownHandle(name) {
+		return Object.hasOwn(axioms, name)
+	})
+}
+
+/**
+ * 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()`).
+ */
+function axiomsMinted<Handles extends string, Cols extends Record<string, PayloadField>>(
+	record: Readonly<Record<string, object>>,
+	handles: readonly Handles[],
+	cols: readonly ClosedColumn[]
+): record is Axioms<Handles, Cols> & Readonly<Record<string, object>> {
+	return handles.every(function rowMinted(handle) {
+		const row = record[handle]
+		return (
+			row !== undefined &&
+			cols.every(function columnMinted(column) {
+				return Object.hasOwn(row, column.name)
+			})
+		)
+	})
+}
+
+/**
+ * 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
+ * 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.
+ */
+function mintAxioms<Handles extends string, Cols extends Record<string, PayloadField>>(
+	name: string,
+	handles: readonly Handles[],
+	cols: readonly ClosedColumn[],
+	axioms: Axioms<Handles, Cols> | undefined
+): 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) })
+		Object.defineProperty(out, handle, { value: row, enumerable: true })
+	}
+	Object.freeze(out)
+	if (!axiomsMinted<Handles, Cols>(out, handles, cols)) {
+		throw errors.new(`closed relation ${name}: axiom-row minting incomplete`)
+	}
+	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,
 	handles: Handles
-): Closed<Name, Handles, Record<never, never>>
+): Closed<Name, Handles[number], Record<never, never>>
 
 /**
- * Payload tier: declared columns plus ground axioms, every handle with
- * every column exactly once (type-enforced by {@link Axioms}).
+ * 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}).
  */
-function closed<
-	const Name extends string,
-	const Handles extends readonly [string, ...string[]],
-	const Cols extends Record<string, PayloadField>
->(name: Name, handles: Handles, columns: Cols, axioms: Axioms<Handles, Cols>): Closed<Name, Handles, Cols>
+function closed<const Name extends string, const Cols extends Record<string, PayloadField>>(
+	name: Name,
+	columns: Cols
+): <Handles extends string>(axioms: Axioms<Handles, Cols>) => Closed<Name, Handles, Cols>
 
-function closed(
-	name: string,
-	handles: readonly [string, ...string[]],
-	columns?: Record<string, PayloadField>,
-	axioms?: Readonly<Record<string, Readonly<Record<string, unknown>>>>
-): unknown {
+function closed<const Name 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>>) {
+	if (isHandleTuple(shape)) {
+		return closedBare(name, shape)
+	}
+	return closedPayload(name, shape)
+}
+
+/** The bare tier's precisely-typed builder: no columns, no axioms. */
+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)
+}
+
+/**
+ * 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.
+ */
+function closedPayload<Name extends string, Cols extends Record<string, PayloadField>>(
+	name: Name,
+	columns: Cols
+): <Handles extends string>(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)
+	}
+}
+
+/**
+ * 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.
+ */
+function mintClosed<Name extends string, Handles extends string, Cols extends Record<string, PayloadField>>(
+	name: Name,
+	handles: readonly Handles[],
+	columns: Cols,
+	axioms: Axioms<Handles, Cols> | undefined
+): 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)`)
+	}
 	const seen = new Set<string>()
 	for (const handle of handles) {
 		if (seen.has(handle)) {
@@ -172,17 +348,17 @@ function closed(
 			)
 		}
 	}
-	const roster: ClosedRoster = Object.freeze({ name, handles: Object.freeze([...handles]) })
+	const handleList: readonly Handles[] = Object.freeze([...handles])
+	const roster: ClosedRoster = Object.freeze({ name, handles: handleList })
 	const cols: ClosedColumn[] = []
-	if (columns !== undefined) {
-		for (const [columnName, field] of Object.entries(columns)) {
-			assertDeclarationOrderKey(`closed relation ${name} column`, columnName)
-			cols.push(Object.freeze({ name: columnName, field: field.data }))
-		}
+	for (const [columnName, field] of Object.entries(columns)) {
+		assertDeclarationOrderKey(`closed relation ${name} column`, columnName)
+		cols.push(Object.freeze({ name: columnName, field }))
 	}
-	const rows: ClosedRow[] = handles.map(function lowerRow(handle) {
+	Object.freeze(cols)
+	const rows: ClosedRow[] = handleList.map(function lowerRow(handle) {
 		const values = cols.map(function lowerAxiomLiteral(column) {
-			const row = axiomRow(name, axioms, handle)
+			const row = groundRow(name, axioms, handle)
 			return Object.freeze(literalOf(column.field, row[column.name]))
 		})
 		return Object.freeze({ handle, values: Object.freeze(values) })
@@ -190,38 +366,40 @@ function closed(
 	const data: ClosedData = Object.freeze({
 		name,
 		handles: roster.handles,
-		columns: Object.freeze(cols),
+		columns: cols,
 		rows: Object.freeze(rows)
 	})
-	const id: ClosedIdField<string> = Object.freeze({
-		data: fieldData({ kind: "u64" }, name, false, roster)
+	const id: ClosedIdField<`${Name}Id`> = Object.freeze({
+		kind: "u64",
+		domain: `${name}Id`,
+		closed: roster
 	})
 	/**
 	 * Handle names are arbitrary identifiers, so rows and constants are
-	 * minted with OWN-property definition, never assignment: a handle named
+	 * 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 Brand<bigint, Name> but reads back an object.
+	 * 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.)
 	 */
-	const axiomsOut: Record<string, object> = {}
-	for (const handle of handles) {
-		const row = axioms === undefined ? Object.freeze({}) : Object.freeze({ ...axiomRow(name, axioms, handle) })
-		Object.defineProperty(axiomsOut, handle, { value: row, enumerable: true })
-	}
-	const value: Record<string, unknown> = {
+	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: Object.freeze(axiomsOut),
-		fromId(idValue: bigint): string | undefined {
-			return roster.handles[Number(idValue)]
+		axioms: axiomsOut,
+		columns: columnsOut,
+		fromId(idValue: bigint): Handles | undefined {
+			return handleList[Number(idValue)]
 		}
-	}
-	handles.forEach(function mintHandleConstant(handle, index) {
-		Object.defineProperty(value, handle, { value: BigInt(index), enumerable: true })
 	})
-	return Object.freeze(value)
 }
 
 export type { AnyClosed, AxiomRow, Axioms, Closed, ClosedColumn, ClosedCore, ClosedData, ClosedRow, PayloadField }