@bjornpagen/bumbledb 0.15.0 → 0.17.1

package/src/law.ts

@@ -1,6 +1,6 @@
 /**
  * The law-typing engine (owner ruling 2026-07-18, "option 2, zero debate"):
- * THE LAWS TYPE THE COLUMNS. Domains are declared nowhere — `schema()`
+ * THE LAWS TYPE THE COLUMNS. Domains are declared nowhere — `schema`
  * computes every field's domain FROM the statement list, at BOTH the type
  * level (this module's type machinery, reading the statements tuple type)
  * and at runtime (a plain union-find over the same pairs), and the two
@@ -8,37 +8,41 @@
  *
  * The three class laws (ratified; implemented exactly):
  *
- *   1. GENERATORS — a `fresh` field is a generator and names its class by
- *      its declaration coordinate (`"Account.id"`); a closed relation's
- *      synthetic id is a generator named `"Kind.id"`.
- *   2. GENERATOR-LESS classes are named by their least member coordinate
- *      in relation-declaration × field-declaration order (readable off the
- *      relation record and each member's frozen field list at the VALUE
- *      tier — deterministic, pinned forever; the wire reads only this
- *      tier). At the TYPE tier the same class is carried as its
- *      member-coordinate SET (see {@link ClassOfCoord}): TypeScript's
- *      union member order is not observably deterministic, so a type-level
- *      least-member pick would drift between compilations — the set is the
- *      canonical deterministic spelling, the runtime name is always a
- *      member of it, and the join judgment is identical at both tiers.
- *   3. BARE — a field in no law has NO class and pairs only with bare in
- *      queries (the deliberate sum-domain pointer stays legal).
+ * 1. GENERATORS — a `fresh` field is a generator and names its class by
+ * its declaration coordinate (`"Account.id"`); a closed relation's
+ * synthetic id is a generator named `"Kind.id"`.
+ * 2. GENERATOR-LESS classes are named by their least member coordinate
+ * in relation-declaration × field-declaration order (readable off the
+ * relation record and each member's frozen field list at the VALUE
+ * tier — deterministic, pinned forever; the wire reads only this
+ * tier). At the TYPE tier the same class is carried as its
+ * member-coordinate SET (see {@link ClassOfCoord}): TypeScript's
+ * union member order is not observably deterministic, so a type-level
+ * least-member pick would drift between compilations — the set is the
+ * canonical deterministic spelling, the runtime name is always a
+ * member of it, and the join judgment is identical at both tiers.
+ * 3. BARE — a field in no law has NO class and pairs only with bare in
+ * queries (the deliberate sum-domain pointer stays legal).
  *
  * THE WALL: a class containing more than one generator is a contradiction
  * (two mints cannot share a carrier) — a schema-level COMPILE error (the
  * named, self-locating {@link ClassWall}: which generator coordinates
  * collided, through which paired slots) with a construction-time runtime
  * twin (`computeClasses` throws with the same content, naming the exact
- * statement).
+ * statement). The TARGET-KEY WALL ({@link TargetKeyWall},
+ * 60-containment-parity) rides the same constraint seam: a containment/
+ * mirrors/capacity target projection that resolves no key of its relation
+ * is the same kind of schema-level compile error, with `schema`'s
+ * `verifyTargetKeys` as its authoritative runtime twin.
  *
  * Every paired face of the statement tuple unions its positionwise field
  * slots: containment (ψ-selected targets included — a selection changes
  * pairing not at all), the `==` bijection, and capacity source/target pairs.
- * `key()` statements pair nothing (an FD constrains one relation's own
+ * `key` statements pair nothing (an FD constrains one relation's own
  * rows; it identifies no carriers).
  *
  * The type tier reads pairs off the statement types' exact face data, so
- * spell the statement list INLINE in `schema()` (the `const` type
+ * spell the statement list INLINE in `schema` (the `const` type
  * parameter keeps the tuple precise). A widened `Statement[]` list
  * degrades the TYPE tier to generators-only (no pair is readable off a
  * widened type) — the runtime map stays complete and authoritative, and
@@ -58,75 +62,42 @@ import type { AnyRelation, RelationFields } from "#relation.ts"
 import type { SchemaRelation, SchemaRelations } from "#schema.ts"
 import { renderStatement, type Statement } from "#statements.ts"
 
-// ————————————————————————————————————————————————————————————————————————
-// The class-map shapes.
-// ————————————————————————————————————————————————————————————————————————
-
-/** One relation's computed classes: field name → class name, `undefined` = bare. */
 type RelationClasses = { readonly [field: string]: string | undefined }
 
-/**
- * The class map a schema carries — relation name → field name → the
- * computed class name (`undefined` = bare). THE domain authority: queries
- * and the wire lowering read domains from here and nowhere else. The wide
- * shape is the default every `Schema`-generic surface accepts; a concrete
- * schema's `classes` property carries the EXACT computed map
- * ({@link ClassesOf}) at the type level and the frozen runtime twin
- * (`computeClasses`) at the value level — one property, two tiers, one
- * computation.
- */
 type SchemaClasses = { readonly [relation: string]: RelationClasses }
 
-/** Looks one relation's class record up in a schema's class map (absent relation = no classes). */
 type ClassRecordOf<Classes extends SchemaClasses, N extends string> = N extends keyof Classes
 	? Classes[N]
 	: Record<never, never>
 
-/** Looks one field's class up in a relation's class record (absent field = bare). */
 type ClassLookup<CR, K> = K extends keyof CR ? CR[K] & (string | undefined) : undefined
 
-// ————————————————————————————————————————————————————————————————————————
-// Coordinates.
-// ————————————————————————————————————————————————————————————————————————
-
-/** A closed member's declared payload-column record (`never` on ordinary relations). */
 type MemberColumns<M> = M extends AnyClosed ? M["columns"] : never
 
-/** The field names of one schema member: a relation's declared fields; a closed relation's sealed `id` + columns. */
 type MemberFieldNames<M extends SchemaRelation> = M extends AnyClosed
 	? "id" | (keyof MemberColumns<M> & string)
 	: M extends AnyRelation
 		? keyof RelationFields<M> & string
 		: never
 
-/** The fresh-marked field names of one field block. */
 type FreshFieldNames<Fields> = {
 	[F in keyof Fields & string]: Fields[F] extends { readonly fresh: true } ? F : never
 }[keyof Fields & string]
 
-/** One member's generator coordinates: fresh fields; a closed relation's synthetic id. */
 type MemberGenerators<N extends string, M extends SchemaRelation> = M extends AnyClosed
 	? `${N}.id`
 	: M extends AnyRelation
 		? `${N}.${FreshFieldNames<RelationFields<M>>}`
 		: never
 
-/** Every generator coordinate of a relation record (a union). */
 type GeneratorsOf<Rels extends SchemaRelations> = {
 	[N in keyof Rels & string]: MemberGenerators<N, Rels[N]>
 }[keyof Rels & string]
 
-// ————————————————————————————————————————————————————————————————————————
-// Pairs: the positionwise slot pairs of every paired face.
-// ————————————————————————————————————————————————————————————————————————
-
-/** One paired-slot pair of coordinates. */
 type Pair = readonly [string, string]
 
-/** A list of slot pairs. */
 type PairList = readonly Pair[]
 
-/** Zips two faces' projections into coordinate pairs, positionwise. */
 type ZipCoords<
 	SN extends string,
 	SP extends readonly string[],
@@ -139,13 +110,6 @@ type ZipCoords<
 		: Acc
 	: Acc
 
-/**
- * One statement's slot pairs: containments (bidirectional included — pair
- * unions are symmetric) and capacity statements pair their two faces
- * positionwise;
- * `key()` pairs nothing. A widened face (owner name or projection no
- * longer literal) contributes nothing — the runtime map stays complete.
- */
 type StatementPairs<St extends Statement> = St["data"] extends {
 	readonly source: infer S extends FaceData
 	readonly target: infer T extends FaceData
@@ -157,7 +121,6 @@ type StatementPairs<St extends Statement> = St["data"] extends {
 			: ZipCoords<S["owner"]["name"], S["projection"], T["owner"]["name"], T["projection"]>
 	: []
 
-/** Every slot pair of a statements tuple, in written order. */
 type PairsOf<Stmts extends readonly Statement[], Acc extends PairList = []> = Stmts extends readonly [
 	infer H extends Statement,
 	...infer T extends readonly Statement[]
@@ -165,11 +128,6 @@ type PairsOf<Stmts extends readonly Statement[], Acc extends PairList = []> = St
 	? PairsOf<T, readonly [...Acc, ...StatementPairs<H>]>
 	: Acc
 
-// ————————————————————————————————————————————————————————————————————————
-// Union-find over the pairs: connected components as coordinate unions.
-// ————————————————————————————————————————————————————————————————————————
-
-/** The component (a union of coordinates) containing `X`, or `never` when `X` is in none. */
 type CompOf<Comps extends readonly string[], X extends string> = Comps extends readonly [
 	infer H extends string,
 	...infer T extends readonly string[]
@@ -179,7 +137,6 @@ type CompOf<Comps extends readonly string[], X extends string> = Comps extends r
 		: CompOf<T, X>
 	: never
 
-/** Rebuilds the component list without the component `C` (components are disjoint; identity is mutual extension). */
 type WithoutComp<
 	Comps extends readonly string[],
 	C extends string,
@@ -190,7 +147,6 @@ type WithoutComp<
 		: WithoutComp<T, C, readonly [...Acc, H]>
 	: Acc
 
-/** Unions one pair into the component list: create, extend, keep, or merge. */
 type AddPair<Comps extends readonly string[], A extends string, B extends string> = [
 	CompOf<Comps, A>,
 	CompOf<Comps, B>
@@ -206,7 +162,6 @@ type AddPair<Comps extends readonly string[], A extends string, B extends string
 				: readonly [...WithoutComp<WithoutComp<Comps, CA>, CB>, CA | CB]
 	: Comps
 
-/** Folds every pair into connected components (tail-recursive — the whole walk is one loop). */
 type BuildComps<Pairs extends PairList, Comps extends readonly string[] = readonly []> = Pairs extends readonly [
 	infer P extends Pair,
 	...infer T extends PairList
@@ -214,21 +169,8 @@ type BuildComps<Pairs extends PairList, Comps extends readonly string[] = readon
 	? BuildComps<T, AddPair<Comps, P[0], P[1]>>
 	: Comps
 
-// ————————————————————————————————————————————————————————————————————————
-// The wall and the names.
-// ————————————————————————————————————————————————————————————————————————
-
-/** Whether a union holds two or more members (`All` captures the whole union across distribution). */
 type IsMulti<U, All = U> = [U] extends [never] ? false : U extends unknown ? ([All] extends [U] ? false : true) : never
 
-/**
- * The named, self-locating compile verdict of the one-generator wall: the
- * generator coordinates that collided and the paired slots (rendered
- * `A.x ~ B.y`, statement order) whose chain unified them. Intersected into
- * `schema()`'s statements parameter, so the error lands ON the statement
- * list with this key naming the law. The runtime twin throws from
- * `computeClasses` with the same content, naming the exact statement.
- */
 interface ClassWall<Generators extends string, Chain extends readonly string[]> {
 	readonly "schema class wall — the statements unify two generators into one class (two mints cannot share a carrier)": {
 		readonly generators: Generators
@@ -236,7 +178,6 @@ interface ClassWall<Generators extends string, Chain extends readonly string[]>
 	}
 }
 
-/** The paired slots lying inside component `C`, rendered — the wall's self-locating chain. */
 type ChainOf<Pairs extends PairList, C extends string, Acc extends readonly string[] = []> = Pairs extends readonly [
 	infer P extends Pair,
 	...infer T extends PairList
@@ -246,7 +187,6 @@ type ChainOf<Pairs extends PairList, C extends string, Acc extends readonly stri
 		: ChainOf<T, C, Acc>
 	: Acc
 
-/** Scans the components for a two-generator class: `unknown` (lawful) or the {@link ClassWall}. */
 type WallScan<Comps extends readonly string[], Gens extends string, Pairs extends PairList> = Comps extends readonly [
 	infer H extends string,
 	...infer T extends readonly string[]
@@ -256,35 +196,181 @@ type WallScan<Comps extends readonly string[], Gens extends string, Pairs extend
 		: WallScan<T, Gens, Pairs>
 	: unknown
 
+type SetEq<A extends string, B extends string> = [A] extends [B] ? ([B] extends [A] ? true : false) : false
+
+type KeyEntry = readonly [string, string]
+
+/**
+ * Every declared `key` of a statements tuple as {@link KeyEntry} rows —
+ * the declared half of the target-key roster (the implied half is read off
+ * each target face's own relation value: fresh marks, closed ids). A
+ * statement-tuple union or any undecidable key element degrades the WHOLE
+ * wall to silent before this roster is ever consulted
+ * ({@link DecidableRoster}) — the skip arm here is the same judgment
+ * stated locally, kept as belt, as is {@link DeclaredKeyMatch}'s
+ * unjudgeable-projection arm.
+ */
+type DeclaredKeysOf<Stmts extends readonly Statement[], Acc extends readonly KeyEntry[] = []> = Stmts extends readonly [
+	infer H extends Statement,
+	...infer T extends readonly Statement[]
+]
+	? H["data"] extends {
+			readonly kind: "key"
+			readonly owner: infer O extends AnyRelation
+			readonly projection: infer P extends readonly string[]
+		}
+		? string extends O["name"]
+			? DeclaredKeysOf<T, Acc>
+			: DeclaredKeysOf<T, readonly [...Acc, readonly [O["name"], P[number]]]>
+		: DeclaredKeysOf<T, Acc>
+	: Acc
+
+type LiteralProjection<P extends readonly string[]> = [true] extends [IsMulti<P>]
+	? false
+	: [number] extends [P["length"]]
+		? false
+		: [P] extends [readonly [infer H extends string, ...infer T extends readonly string[]]]
+			? [string] extends [H]
+				? false
+				: [true] extends [IsMulti<H>]
+					? false
+					: LiteralProjection<T>
+			: true
+
+type DecidableKeyData<D> = [D] extends [
+	{
+		readonly kind: "key"
+		readonly owner: infer O extends AnyRelation
+		readonly projection: infer P extends readonly string[]
+	}
+]
+	? [true] extends [IsMulti<D>]
+		? false
+		: [string] extends [O["name"]]
+			? false
+			: [true] extends [IsMulti<O["name"]>]
+				? false
+				: LiteralProjection<P>
+	: false
+
 /**
- * The one-generator-per-class law as a constraint: resolves to `unknown`
- * (a no-op intersection into the statements parameter) when the statement
- * list is lawful, and to the named {@link ClassWall} otherwise.
+ * THE total decidability detector of the type-tier target-key judgment —
+ * a strict WHITELIST of provably-judgeable shapes, never a blocklist of
+ * known-bad spellings (representation over control flow: the detector is
+ * total by construction, so a spelling nobody has met yet degrades
+ * instead of firing). It answers `true` ONLY when ALL hold, each check
+ * tuple-bracketed against distribution:
+ *
+ * - SINGULAR — `Stmts` itself is a single non-union type (a ternary
+ * between two individually-lawful `as const` statement lists infers a
+ * UNION of tuples; a naked `Stmts` would distribute the scan
+ * ({@link TargetKeyScan}) and the roster ({@link DeclaredKeysOf})
+ * INDEPENDENTLY, cross-judging one arm's faces against the other
+ * arm's keys). The union test is the house device ({@link IsMulti}).
+ * - FIXED-LENGTH — `Stmts` is a literal tuple with no rest tail:
+ * `[number] extends [Stmts["length"]]` detects a rest/array length. A
+ * rest-tail tuple (`readonly [typeof stmt,...Statement[]]`) peels its
+ * literal head and hides EVERY key in the tail from a head-peeling
+ * roster read — the scan would judge the head against a roster blind
+ * to keys the value tier can see.
+ * - CONCRETE ELEMENTS — every element is a single non-union statement
+ * (per-element {@link IsMulti}), and every element whose
+ * `data["kind"]` type INCLUDES `"key"` is a single concrete `KeyData`
+ * with a literal owner name and a projection that is itself a single
+ * non-union fixed-length tuple of string literals
+ * ({@link DecidableKeyData}, {@link LiteralProjection}). A bare
+ * `Statement` element, a `Statement` union, a `KeyStatement` union, a
+ * widened owner, a widened or union projection each make the roster
+ * UNKNOWABLE.
+ *
+ * Any failure is the tier's one forbidden verdict in waiting — a false
+ * wall — so anything outside the whitelist degrades the WHOLE
+ * {@link TargetKeyWall} to silent (the degradation law: best effort
+ * degrades to silent, never to a wrong judgment), exactly as a widened
+ * FACE already silences its own judgment; the value tier stays
+ * authoritative. ONE recorded limit, pre-existing and outside this
+ * detector's reach: a generic type parameter CONSTRAINED to a union of
+ * tuples hangs tsc in the deferred-scan machinery before any verdict is
+ * reached — a degenerate spelling no shipped surface writes, recorded
+ * here as the tier's known boundary, not fixed.
  */
+type DecidableRoster<Stmts extends readonly Statement[]> = [true] extends [IsMulti<Stmts>]
+	? false
+	: [number] extends [Stmts["length"]]
+		? false
+		: [Stmts] extends [readonly [infer H extends Statement, ...infer T extends readonly Statement[]]]
+			? [true] extends [IsMulti<H>]
+				? false
+				: "key" extends H["data"]["kind"]
+					? [DecidableKeyData<H["data"]>] extends [true]
+						? DecidableRoster<T>
+						: false
+					: DecidableRoster<T>
+			: true
+
+interface TargetKeyWall<Target extends string, Projection extends string> {
+	readonly "schema target-key wall — a containment/mirrors/capacity target projection matches no key of the target relation (declare the key() it resolves, or project an existing one)": {
+		readonly target: Target
+		readonly projection: Projection
+	}
+}
+
+type DeclaredKeyMatch<N extends string, PU extends string, Keys extends readonly KeyEntry[]> = Keys extends readonly [
+	infer H extends KeyEntry,
+	...infer T extends readonly KeyEntry[]
+]
+	? SetEq<H[0], N> extends true
+		? string extends H[1]
+			? true
+			: SetEq<PU, H[1]> extends true
+				? true
+				: DeclaredKeyMatch<N, PU, T>
+		: DeclaredKeyMatch<N, PU, T>
+	: TargetKeyWall<N, PU>
+
+type FreshKeyMatch<PU extends string, O extends AnyRelation> = [PU] extends [FreshFieldNames<RelationFields<O>>]
+	? true extends IsMulti<PU>
+		? false
+		: true
+	: false
+
+type JudgeTargetFace<F extends FaceData, Keys extends readonly KeyEntry[]> = string extends F["owner"]["name"]
+	? true
+	: string extends F["projection"][number]
+		? true
+		: F["owner"] extends AnyClosed
+			? SetEq<F["projection"][number], "id"> extends true
+				? true
+				: TargetKeyWall<F["owner"]["name"], F["projection"][number]>
+			: F["owner"] extends AnyRelation
+				? FreshKeyMatch<F["projection"][number], F["owner"]> extends true
+					? true
+					: DeclaredKeyMatch<F["owner"]["name"], F["projection"][number], Keys>
+				: true
+
+type JudgeStatement<St extends Statement, Keys extends readonly KeyEntry[]> = St["data"] extends {
+	readonly source: FaceData
+	readonly target: infer Tg extends FaceData
+}
+	? JudgeTargetFace<Tg, Keys>
+	: true
+
+type TargetKeyScan<Stmts extends readonly Statement[], Keys extends readonly KeyEntry[]> = Stmts extends readonly [
+	infer H extends Statement,
+	...infer T extends readonly Statement[]
+]
+	? [JudgeStatement<H, Keys>] extends [true]
+		? TargetKeyScan<T, Keys>
+		: JudgeStatement<H, Keys>
+	: unknown
+
 type LawfulStatements<Rels extends SchemaRelations, Stmts extends readonly Statement[]> = WallScan<
 	BuildComps<PairsOf<Stmts>>,
 	GeneratorsOf<Rels>,
 	PairsOf<Stmts>
->
+> &
+	([DecidableRoster<Stmts>] extends [true] ? TargetKeyScan<Stmts, DeclaredKeysOf<Stmts>> : unknown)
 
-/**
- * One coordinate's class per the three laws, at the TYPE tier: its
- * component's single generator (the exact literal — a generator names its
- * class); a component-less generator is its own class; a component-less
- * non-generator is bare (`undefined`); and a GENERATOR-LESS component is
- * carried as its member-coordinate SET (the union of the component's
- * coordinates — a canonical, deterministic type). The set REPRESENTS the
- * runtime's least-member class name faithfully: the runtime name is by
- * construction a member, two slots share a class exactly when their sets
- * are identical (so `JoinOk` judges identically at both tiers), and bare
- * never equals a set. The least-member PICK itself is deliberately not
- * made at the type tier: TypeScript's union member order is not observably
- * deterministic (the same key union tuples differently across checking
- * contexts — measured, not conjectured), so any type-level "least in
- * declaration order" would drift between compilations; the ratified
- * declaration-order name lives at the VALUE tier (`computeClasses`), which
- * is the only tier the wire reads.
- */
 type ClassOfCoord<Comps extends readonly string[], Gens extends string, C extends string> = [CompOf<Comps, C>] extends [
 	infer M extends string
 ]
@@ -299,43 +385,23 @@ type ClassOfCoord<Comps extends readonly string[], Gens extends string, C extend
 			: never
 	: never
 
-/** The computed class map over precomputed components/generators. */
 type ComputedClasses<Rels extends SchemaRelations, Comps extends readonly string[], Gens extends string> = {
 	readonly [N in keyof Rels & string]: {
 		readonly [F in MemberFieldNames<Rels[N]>]: ClassOfCoord<Comps, Gens, `${N}.${F}`>
 	}
 }
 
-/**
- * THE type-level class map of a schema: relation name → field name → the
- * law-computed class (`undefined` = bare) — what `schema()` returns as the
- * `classes` property's type, and what query joins compare. Generator
- * classes are exact name literals; generator-less classes are their
- * member-coordinate sets (see {@link ClassOfCoord} — the runtime map's
- * least-member name is always a member, so the property type is honest).
- */
 type ClassesOf<Rels extends SchemaRelations, Stmts extends readonly Statement[]> = ComputedClasses<
 	Rels,
 	BuildComps<PairsOf<Stmts>>,
 	GeneratorsOf<Rels>
 >
 
-// ————————————————————————————————————————————————————————————————————————
-// The runtime twin: the same computation as a plain union-find.
-// ————————————————————————————————————————————————————————————————————————
-
-/** One relation's declared coordinates and generator flags, in declaration order. */
 interface MemberCoords {
 	readonly relation: string
 	readonly fields: ReadonlyArray<{ readonly name: string; readonly generator: boolean }>
 }
 
-/**
- * Reads every member's coordinates off the relation record, declaration
- * order throughout — the sealed shape through THE one reader
- * (`sealedFieldsOf`): a closed member's generator is its synthetic `id`
- * (ordinal 0), an ordinary member's generators are its fresh-marked fields.
- */
 function memberCoords(relations: SchemaRelations): MemberCoords[] {
 	const out: MemberCoords[] = []
 	for (const [relationName, member] of Object.entries(relations)) {
@@ -351,7 +417,6 @@ function memberCoords(relations: SchemaRelations): MemberCoords[] {
 	return out
 }
 
-/** A plain union-find over coordinate strings, with per-root generator rosters. */
 interface UnionFind {
 	find(coord: string): string
 	union(a: string, b: string): string
@@ -359,7 +424,6 @@ interface UnionFind {
 	markGenerator(coord: string): void
 }
 
-/** Builds the union-find. */
 function makeUnionFind(): UnionFind {
 	const parent = new Map<string, string>()
 	const generators = new Map<string, string[]>()
@@ -402,7 +466,6 @@ function makeUnionFind(): UnionFind {
 	}
 }
 
-/** The paired faces of one statement, or undefined for a key (an FD pairs nothing). */
 function statementFaces(statement: Statement): readonly [FaceData, FaceData] | undefined {
 	const data = statement.data
 	if (data.kind === "key") {
@@ -517,5 +580,14 @@ function classesComplete<Classes extends SchemaClasses>(
 	})
 }
 
-export type { ClassesOf, ClassLookup, ClassRecordOf, ClassWall, LawfulStatements, RelationClasses, SchemaClasses }
+export type {
+	ClassesOf,
+	ClassLookup,
+	ClassRecordOf,
+	ClassWall,
+	LawfulStatements,
+	RelationClasses,
+	SchemaClasses,
+	TargetKeyWall
+}
 export { classesComplete, computeClasses }

package/src/lower.ts

@@ -3,9 +3,13 @@
  * data (`#spec.ts`), which the napi bridge marshals verbatim. Lowering is
  * TOTAL on well-typed inputs — no validation lives here beyond what the
  * types and the construction boundaries already guarantee — and it is the
- * only place statement internals are read for the wire. Ordering is
- * declaration order throughout, and every output object is built with one
- * fixed key order, so serialization is deterministic (byte-stable).
+ * only place statement internals are read for the wire. In particular,
+ * lowering never emits an engine-refused containment target: it accepts
+ * only `schema` outputs, and `schema`'s target-key wall already
+ * refused any non-key target projection (60-containment-parity —
+ * totality INHERITED, not re-checked). Ordering is declaration order
+ * throughout, and every output object is built with one fixed key order,
+ * so serialization is deterministic (byte-stable).
  */
 
 import * as errors from "@superbuilders/errors"
@@ -27,12 +31,6 @@ import type {
 } from "#spec.ts"
 import type { Statement } from "#statements.ts"
 
-/**
- * Lowers one field descriptor's structural type to the wire
- * {@link ValueTypeSpec}: the S1 kind tags map 1:1 onto the `ValueType`
- * vocabulary (`str` spells `string`, `bytes` spells `fixedBytes` with its
- * width label as `len`; intervals carry element and width labels through).
- */
 function valueTypeOf(field: AnyField): ValueTypeSpec {
 	switch (field.kind) {
 		case "bool":
@@ -50,16 +48,6 @@ function valueTypeOf(field: AnyField): ValueTypeSpec {
 	}
 }
 
-/**
- * Lowers one field descriptor to its {@link FieldSpec}: the structural
- * type, the structural fresh mark (`fresh` is the literal `true` exactly
- * on a fresh-marked u64 — on an unmarked one the property holds the marked
- * descriptor, never `true`), and the wire's `newtype` — the COMPUTED class
- * name `schema()` derived from the statement list (the laws type the
- * columns), `undefined` on a bare field. The engine reads newtypes for
- * handle resolution and the coherence check only and DROPS them at
- * descriptor lowering — class names are never fingerprinted.
- */
 function lowerField(name: string, field: AnyField, newtype: string | undefined): FieldSpec {
 	return {
 		name,
@@ -69,7 +57,6 @@ function lowerField(name: string, field: AnyField, newtype: string | undefined):
 	}
 }
 
-/** Lowers one face to a `SideSpec`: names only, σ as (field, set) pairs. */
 function lowerFace(face: FaceData): SideSpec {
 	return {
 		relation: face.owner.name,
@@ -80,12 +67,6 @@ function lowerFace(face: FaceData): SideSpec {
 	}
 }
 
-/**
- * Lowers one statement. `mirrors` stays ONE spec statement
- * (`bidirectional: true`) — the engine performs the `==` lowering to two
- * adjacent containments, `source <= target` first, exactly as the macro
- * does.
- */
 function lowerStatement(statement: Statement): StatementSpec {
 	const data = statement.data
 	switch (data.kind) {
@@ -116,13 +97,6 @@ function lowerStatement(statement: Statement): StatementSpec {
 	}
 }
 
-/**
- * Lowers one ordinary relation to its `RelationSpec` fragment: fields in
- * declaration order, each carrying its law-computed class name as the
- * `newtype` (`classes` — the schema's class record for this relation;
- * bare fields carry `undefined`), `closed: undefined` (the option is the
- * kind — one sum, R7).
- */
 function lowerRelation(relation: AnyRelation, classes: RelationClasses): RelationSpec {
 	const fields: FieldSpec[] = relation.data.fields.map(function lowerDeclared(declared) {
 		return lowerField(declared.name, declared.field, classes[declared.name])
@@ -130,16 +104,6 @@ function lowerRelation(relation: AnyRelation, classes: RelationClasses): Relatio
 	return { name: relation.name, fields, closed: undefined }
 }
 
-/**
- * Lowers one closed relation to its `RelationSpec` fragment: declared
- * intrinsic columns only (the engine materializes the synthetic `id`) and
- * the fused closedness sum (R7) — the handle newtype (the COMPUTED class
- * name of the id's generator class, `"Kind.id"`, always present: a closed
- * id is a generator; every referencing field shares it by law, which is
- * how the engine resolves a handle literal back to its roster) together
- * with the ground axioms in declaration order (row id = index); the
- * literals were already lowered at `closed()` construction.
- */
 function lowerClosed(member: AnyClosed, classes: RelationClasses): RelationSpec {
 	const fields: FieldSpec[] = member.data.columns.map(function lowerColumn(column) {
 		return lowerField(column.name, column.field, classes[column.name])
@@ -154,17 +118,8 @@ function lowerClosed(member: AnyClosed, classes: RelationClasses): RelationSpec
 	return { name: member.name, fields, closed: { newtype, rows } }
 }
 
-/** The frozen empty class record a relation outside the schema's map lowers under (nothing classed). */
 const noClasses: RelationClasses = Object.freeze({})
 
-/**
- * Lowers a whole theory to the `SchemaSpec` the bridge takes: relations in
- * record declaration order, DECLARED statements only in written order (the
- * engine materializes the fresh-implied and closed auto-keys itself), and
- * every field's `newtype` slot fed from the schema's law-computed class
- * map — the ONE domain authority (fingerprint-neutral: the engine drops
- * newtypes at descriptor lowering).
- */
 function lower(theory: AnySchema): SchemaSpec {
 	const relations: RelationSpec[] = Object.entries(theory.relations).map(function lowerMember([name, member]) {
 		const classes = theory.classes[name] ?? noClasses
@@ -176,4 +131,4 @@ function lower(theory: AnySchema): SchemaSpec {
 	return { relations, statements: theory.statements.map(lowerStatement) }
 }
 
-export { lower, lowerClosed, lowerRelation }
+export { lower }