@bjornpagen/bumbledb 0.15.0 → 0.17.1

package/src/schema.ts

@@ -1,12 +1,18 @@
 /**
- * `schema()` — assembles relations and statements into a theory value (the
+ * `schema` — assembles relations and statements into a theory value (the
  * `Theory` analog; what `Db.create`/`Db.open` take). Construction-time
- * validation is the macro-EXPANSION-boundary analog and nothing more:
- * membership, implied-key duplicates, duplicate statements, and a
- * belt-and-braces handle re-verification. Everything semantically deeper
- * (containment targets resolving declared keys, fresh-on-u64, …) is
- * DELIBERATELY left to the engine's `SchemaError` at `Db.create` — the
- * same judge, the same two-boundary split as Rust.
+ * validation is the macro-EXPANSION-boundary analog: membership,
+ * implied-key duplicates, duplicate statements, a belt-and-braces handle
+ * re-verification — and the TARGET-KEY WALL ({@link verifyTargetKeys}),
+ * the value tier of the two-tier containment law
+ * (60-containment-parity): every containment/mirrors/capacity target
+ * projection must set-match a key of its relation, judged HERE with the
+ * engine's exact rule so `lower` never emits an engine-refused
+ * containment. The type tier is `law.ts`'s `TargetKeyWall` (best effort,
+ * statically known tuples); every OTHER semantic judgment (key-internal
+ * legality, fresh-on-u64, …) stays the engine's `SchemaError` at
+ * `Db.create` — the engine is the final authority for every boundary,
+ * this wall just makes the SDK agree with it first.
  */
 
 import * as errors from "@superbuilders/errors"
@@ -19,16 +25,15 @@ import type { AnyRelation } from "#relation.ts"
 import type { LiteralSetSpec, LiteralSpec } from "#spec.ts"
 import { isStatement, renderStatement, type Statement } from "#statements.ts"
 
-/**
- * Validates the relation record and collects the implied keys: the
- * fresh-implied `R(field) -> R` per minted field and the closed auto-key
- * `R(id) -> R` per closed relation, each rendered canonically so an
- * explicit duplicate is caught by string identity with the renderer as the
- * single spelling authority.
- */
-function collectImplied(name: string, relations: SchemaRelations): Set<string> {
+interface ImpliedKeys {
+	readonly rendered: ReadonlySet<string>
+	readonly roster: ReadonlyMap<string, ReadonlyArray<readonly string[]>>
+}
+
+function collectImplied(name: string, relations: SchemaRelations): ImpliedKeys {
 	assertDeclarationRecord(`schema ${name} relations`, relations)
-	const implied = new Set<string>()
+	const rendered = new Set<string>()
+	const roster = new Map<string, ReadonlyArray<readonly string[]>>()
 	for (const [recordKey, member] of Object.entries(relations)) {
 		assertDeclarationOrderKey(`schema ${name} relation`, recordKey)
 		if (member.name !== recordKey) {
@@ -36,20 +41,24 @@ function collectImplied(name: string, relations: SchemaRelations): Set<string> {
 				`schema ${name}: record key ${recordKey} holds relation ${member.name} — the key must equal the relation's declared name`
 			)
 		}
+		const projections: Array<readonly string[]> = []
 		if (isClosedMember(member)) {
-			implied.add(`${member.name}(id) -> ${member.name}`)
-			continue
-		}
-		for (const declared of member.data.fields) {
-			if ("fresh" in declared.field && declared.field.fresh === true) {
-				implied.add(`${member.name}(${declared.name}) -> ${member.name}`)
+			projections.push(Object.freeze(["id"]))
+		} else {
+			for (const declared of member.data.fields) {
+				if ("fresh" in declared.field && declared.field.fresh === true) {
+					projections.push(Object.freeze([declared.name]))
+				}
 			}
 		}
+		for (const projection of projections) {
+			rendered.add(`${member.name}(${projection.join(", ")}) -> ${member.name}`)
+		}
+		roster.set(member.name, Object.freeze(projections))
 	}
-	return implied
+	return { rendered, roster }
 }
 
-/** The relation values a statement addresses, for membership checking. */
 function statementOwners(statement: Statement): readonly SchemaRelation[] {
 	const data = statement.data
 	if (data.kind === "key") {
@@ -58,11 +67,6 @@ function statementOwners(statement: Statement): readonly SchemaRelation[] {
 	return [data.source.owner, data.target.owner]
 }
 
-/**
- * Requires every relation a statement addresses to be the IDENTICAL value
- * the schema record declares — same-name-different-value is a forgery, not
- * a membership.
- */
 function verifyMembership(name: string, relations: SchemaRelations, statement: Statement, rendered: string): void {
 	for (const owner of statementOwners(statement)) {
 		const member = relations[owner.name]
@@ -77,7 +81,6 @@ function verifyMembership(name: string, relations: SchemaRelations, statement: S
 	}
 }
 
-/** Flattens one binding's literal set into its literals. */
 function bindingLiterals(set: LiteralSetSpec): readonly LiteralSpec[] {
 	if (set.kind === "one") {
 		return [set.literal]
@@ -85,12 +88,6 @@ function bindingLiterals(set: LiteralSetSpec): readonly LiteralSpec[] {
 	return set.literals
 }
 
-/**
- * Re-verifies one binding's handle literals against the field's roster —
- * belt-and-braces over what `where()` already resolved and the type level
- * already blocked, so a forged binding fails here rather than at the
- * engine boundary with a colder message.
- */
 function verifyBindingHandles(
 	name: string,
 	face: FaceData,
@@ -113,7 +110,6 @@ function verifyBindingHandles(
 	}
 }
 
-/** Walks every face of a statement through the handle re-verification. */
 function verifyHandles(name: string, statement: Statement, rendered: string): void {
 	const data = statement.data
 	if (data.kind === "key") {
@@ -126,15 +122,6 @@ function verifyHandles(name: string, statement: Statement, rendered: string): vo
 	}
 }
 
-/**
- * Resolves the closed relation a `(relation, field)` pair references
- * through the DECLARED containments — the identical walk the engine's
- * canonical renderer performs (`schema/render.rs` `closed_target_of`): one
- * hop, source projecting exactly `[field]`, target projecting exactly the
- * closed relation's `[id]`, first declared match wins; a `mirrors`
- * contributes both of its materialized orientations. `undefined` = the
- * engine would render the field's selection literals as raw row ids.
- */
 function closedTargetOf(statements: readonly Statement[], owner: string, field: string): string | undefined {
 	for (const statement of statements) {
 		const data = statement.data
@@ -161,18 +148,6 @@ function closedTargetOf(statements: readonly Statement[], owner: string, field:
 	return undefined
 }
 
-/**
- * Admits a handle spelling only when the schema also declares the
- * containment the ENGINE's canonical renderer resolves it through
- * (`docs/architecture/10-data-model.md` § closed relations: a closed
- * reference is the plain u64 column PLUS a declared containment). Without
- * it the two renderers drift — `renderStatement` prints the handle name,
- * the engine's violation `canonical` prints the raw row id — and the
- * paste-back law (`violation.canonical === renderStatement(statement)`)
- * breaks. Runs over the COMPLETE statement list, so declaration order
- * never matters. The closed relation's own `id` field resolves directly
- * (the walk's field-0 case).
- */
 function verifyClosedReferences(name: string, statements: readonly Statement[]): void {
 	for (const statement of statements) {
 		const data = statement.data
@@ -188,7 +163,6 @@ function verifyClosedReferences(name: string, statements: readonly Statement[]):
 	}
 }
 
-/** One binding's closed-reference resolution check (the {@link verifyClosedReferences} leaf). */
 function verifyClosedReferenceBinding(
 	name: string,
 	statements: readonly Statement[],
@@ -217,22 +191,118 @@ function verifyClosedReferenceBinding(
 	}
 }
 
-/** One member of a schema's relation record. */
-type SchemaRelation = AnyRelation | AnyClosed
+/**
+ * THE TARGET-KEY WALL, value tier (60-containment-parity — the runtime
+ * twin of `law.ts`'s `TargetKeyWall`, the engine's `resolve_target_key` /
+ * `resolve_capacity_target` mirrored exactly): every `contained`/
+ * `mirrors`/`capacity` statement's target projection must resolve a key
+ * of the target relation, judged over the SAME key population the engine
+ * materializes — the fresh-implied and closed auto-keys
+ * ({@link collectImplied}'s roster) first, then the declared `key`
+ * statements in written order (a key may be declared after its probe, so
+ * this wall runs over the COMPLETE list, never inside the statement
+ * loop). `mirrors` materializes as two containments source-first, so both
+ * orientations judge their own target. SOUNDNESS BAR: the set-match +
+ * closed-id rule below is the engine's COMPLETE rule for this law
+ * (`matching_functionality` compares field SETS — permutations resolve,
+ * subsets/supersets refuse), so this wall never rejects what the engine
+ * accepts; every other schema judgment stays engine-first.
+ */
+function verifyTargetKeys(
+	name: string,
+	statements: readonly Statement[],
+	implied: ReadonlyMap<string, ReadonlyArray<readonly string[]>>
+): void {
+	const declared = new Map<string, Array<readonly string[]>>()
+	for (const statement of statements) {
+		const data = statement.data
+		if (data.kind !== "key") {
+			continue
+		}
+		const keys = declared.get(data.owner.name)
+		if (keys === undefined) {
+			declared.set(data.owner.name, [data.projection])
+		} else {
+			keys.push(data.projection)
+		}
+	}
+	for (const statement of statements) {
+		const data = statement.data
+		if (data.kind === "key") {
+			continue
+		}
+		const rendered = renderStatement(statement)
 
-/** The relation record a schema is generic over — what `Db` and queries key on. */
-type SchemaRelations = Record<string, SchemaRelation>
+		const faces = data.kind === "mirrors" ? [data.target, data.source] : [data.target]
+		for (const face of faces) {
+			verifyTargetKeyFace(name, face, implied, declared, rendered)
+		}
+	}
+}
 
 /**
- * A theory value: named relations, the DECLARED dependency statements, and
- * the LAW-COMPUTED class map (`classes` — relation → field → class name,
- * `undefined` = bare). The class map is THE domain authority: `schema()`
- * computes it FROM the statement list at both tiers (the type through
- * {@link ClassesOf}, the value through the union-find twin), queries
- * compare class names off it, and the wire lowering emits it as the spec
- * `newtype` labels. Nothing is ever synthesized: `statements` is exactly
- * the declared list, in written order.
+ * One target face's key resolution (the {@link verifyTargetKeys} leaf).
+ * Closed target: the handle id is the ONE probe-able identity of a closed
+ * relation, so the projection must be exactly `["id"]` — its own refusal
+ * (the engine's `ClosedTargetNotHandle`): the rule is CLOSEDNESS, not key
+ * absence. Ordinary target: the projection's field-name SET must equal
+ * some roster member's set (the engine's `matching_functionality` —
+ * permutations resolve, subsets and supersets do not). The refusal speaks
+ * the engine's shape in NAMES, with the engine's pointwise hint verbatim
+ * when the projection carries an interval position.
  */
+function verifyTargetKeyFace(
+	name: string,
+	face: FaceData,
+	implied: ReadonlyMap<string, ReadonlyArray<readonly string[]>>,
+	declared: ReadonlyMap<string, ReadonlyArray<readonly string[]>>,
+	rendered: string
+): void {
+	if (isClosedMember(face.owner)) {
+		if (face.projection.length === 1 && face.projection[0] === "id") {
+			return
+		}
+		throw errors.new(
+			`schema ${name}: ${rendered}: closed target ${face.owner.name} is addressed by its synthetic id only — projection (${face.projection.join(", ")}) must be exactly (id) (rewrite the target side as on(${face.owner.name}, "id"))`
+		)
+	}
+	const roster = [...(implied.get(face.owner.name) ?? []), ...(declared.get(face.owner.name) ?? [])]
+	const want = new Set(face.projection)
+	const matched = roster.some(function sameFieldSet(key) {
+		// engine's FieldSet refuses (duplicates are refused at the key()
+
+		if (key.length !== face.projection.length || want.size !== face.projection.length) {
+			return false
+		}
+		const keySet = new Set(key)
+		if (keySet.size !== want.size) {
+			return false
+		}
+		for (const field of keySet) {
+			if (!want.has(field)) {
+				return false
+			}
+		}
+		return true
+	})
+	if (matched) {
+		return
+	}
+	const available = roster.length === 0 ? "none" : roster.map((key) => `(${key.join(", ")})`).join("; ")
+	const pointwise = face.projection.some(function carriesInterval(fieldName) {
+		const descriptor = sealedFieldOf(face.owner, fieldName)
+		return descriptor !== undefined && descriptor.kind === "interval"
+	})
+	const hint = pointwise ? "; hint: declare the exact pointwise key `R(prefix…, interval) -> R`" : ""
+	throw errors.new(
+		`schema ${name}: ${rendered}: target projection (${face.projection.join(", ")}) matches no declared key of ${face.owner.name} — available keys: ${available}${hint}`
+	)
+}
+
+type SchemaRelation = AnyRelation | AnyClosed
+
+type SchemaRelations = Record<string, SchemaRelation>
+
 interface Schema<Rels extends SchemaRelations, Classes extends SchemaClasses = SchemaClasses> {
 	readonly name: string
 	readonly relations: Rels
@@ -240,56 +310,12 @@ interface Schema<Rels extends SchemaRelations, Classes extends SchemaClasses = S
 	readonly classes: Classes
 }
 
-/** Any schema value, whatever its relation record. */
 type AnySchema = Schema<SchemaRelations>
 
-/**
- * Forces the class map to EVALUATE at the `schema()` boundary: a two-level
- * mapped copy, type-identical to `C` — but instantiation resolves it to
- * the finished relation → field → class record, so hovering a schema value
- * (or anything carrying its `Classes` parameter — queries, `Db`) shows the
- * computed record instead of the unevaluated `ClassesOf<...>` application
- * dragging the whole statement-tuple type along. The conditional wrapper
- * is the display mechanism, not a judgment: resolving it drops the alias
- * reference, so tsc renders the finished record (measured against tsc's
- * own type rendering; a bare mapped alias still displays by name).
- * Display-only by construction; `classesComplete` guards the same type at
- * the value tier.
- */
 type EvaluatedClasses<C extends SchemaClasses> = C extends SchemaClasses
 	? { readonly [N in keyof C]: { readonly [F in keyof C[N]]: C[N][F] } }
 	: never
 
-/**
- * Assembles a theory:
- * `schema("Ledger", { Kind, Account, Holder }, [ ...statements ])`.
- *
- * Rejected here, each with the offending statement rendered canonically:
- * a record key differing from its relation's declared name; a statement
- * whose relation is not (identically) a member of the record; an explicit
- * duplicate of a fresh-implied or closedness-implied key (macro parity:
- * "redundant here — and rejected as a duplicate"); a duplicate statement
- * (two statements rendering to one canonical utterance ARE one judgment);
- * a handle selection that its roster does not hold (belt-and-braces —
- * the type level already blocks it); and a handle selection whose closed
- * reference no declared containment resolves (the engine's canonical
- * renderer would print the raw row id where `renderStatement` prints the
- * handle — the paste-back law demands the two spellings agree).
- *
- * The fresh-implied and closed auto-keys are NOT added to the statement
- * list: the engine materializes them itself, in its own pinned order
- * (`SchemaDescriptor::materialized_statements`), and restating them would
- * double them.
- *
- * THE LAW-TYPING happens here too (rulings 2/3 — the laws type the
- * columns): the statement list induces the equivalence classes over field
- * slots, at the TYPE level ({@link ClassesOf} — spell the statement list
- * inline so the tuple type stays precise) and at runtime (the union-find
- * twin), and the one-generator-per-class wall holds at both tiers — the
- * {@link LawfulStatements} verdict lands the compile error on the
- * statements argument; `computeClasses` throws the same content naming the
- * exact statement.
- */
 function schema<const Rels extends SchemaRelations, const Stmts extends readonly Statement[]>(
 	name: string,
 	relations: Rels,
@@ -298,12 +324,6 @@ function schema<const Rels extends SchemaRelations, const Stmts extends readonly
 	const implied = collectImplied(name, relations)
 	const seen = new Set<string>()
 	for (const statement of statements) {
-		/**
-		 * The untyped caller's half of the admission brand: the type tier
-		 * already refuses an unbranded structural literal, and this probe
-		 * refuses the same forgery at runtime — a statement that skipped the
-		 * construction-time arity and roster walls never enters the theory.
-		 */
 		if (!isStatement(statement)) {
 			throw errors.new(
 				`schema ${name}: a statement is minted only by key/contained/mirrors/capacity — a structural literal skips the construction-time arity and roster walls`
@@ -311,7 +331,7 @@ function schema<const Rels extends SchemaRelations, const Stmts extends readonly
 		}
 		const rendered = renderStatement(statement)
 		verifyMembership(name, relations, statement, rendered)
-		if (implied.has(rendered)) {
+		if (implied.rendered.has(rendered)) {
 			throw errors.new(
 				`schema ${name}: ${rendered} is redundant here (the fresh mark or closedness already implies it) — and rejected as a duplicate`
 			)
@@ -323,6 +343,7 @@ function schema<const Rels extends SchemaRelations, const Stmts extends readonly
 		verifyHandles(name, statement, rendered)
 	}
 	verifyClosedReferences(name, statements)
+	verifyTargetKeys(name, statements, implied.roster)
 	const classes = computeClasses(name, relations, statements)
 	if (!classesComplete<EvaluatedClasses<ClassesOf<Rels, Stmts>>>(classes, relations)) {
 		throw errors.new(`schema ${name}: class-map construction incomplete`)

package/src/spec.ts

@@ -1,28 +1,3 @@
-/**
- * The lowered wire shapes — a 1:1 TypeScript mirror of bumbledb's
- * `SchemaSpec` bindings contract (PRD-01;
- * `bumbledb/crates/bumbledb/src/schema/spec.rs`): a schema as named plain
- * data, relations and dependency statements each in declaration order (the
- * declaration-order law that mints every id). The SDK's `lower()` emits
- * these values; the napi bridge (PRD-04) marshals them into the Rust
- * `SchemaSpec` verbatim, and the engine's own judge (`SchemaSpec::descriptor`
- * name resolution + `SchemaDescriptor::validate` at `Db.create`/`Db.open`)
- * stays the single semantic authority — the SDK lowers, it never re-judges.
- *
- * Every u64 crosses as `bigint`, never `number` (PRD-04's marshaling law: no
- * 53-bit hazards, no branch). Object keys are always written in one fixed
- * literal order per shape, so serialization of a lowered schema is
- * deterministic (byte-stable) by construction.
- */
-
-/**
- * A structural value type — the one type vocabulary of the `schema!` field
- * grammar (`ValueType` in Rust): `bool`, `u64`, `i64`, `str` (`string`
- * here), `bytes<N>` (`fixedBytes`), and the interval family (`width:
- * undefined` is the general 16-byte encoding with rays representable;
- * `width: w` is the fixed-width `interval<E, w>` whose encoding stores only
- * the start).
- */
 type ValueTypeSpec =
 	| { readonly kind: "bool" }
 	| { readonly kind: "u64" }
@@ -35,12 +10,6 @@ type ValueTypeSpec =
 			readonly width: bigint | undefined
 	  }
 
-/**
- * One plain engine value as carried by a lowered literal — the mirror of
- * `bumbledb::Value` restricted to the schema-literal vocabulary (Allen masks
- * are query-side values, never schema literals). Intervals are half-open
- * `[start, end)`.
- */
 type ValueSpec =
 	| { readonly kind: "bool"; readonly value: boolean }
 	| { readonly kind: "u64"; readonly value: bigint }
@@ -50,84 +19,35 @@ type ValueSpec =
 	| { readonly kind: "intervalU64"; readonly start: bigint; readonly end: bigint }
 	| { readonly kind: "intervalI64"; readonly start: bigint; readonly end: bigint }
 
-/**
- * One literal as spelled: a plain value, or a closed relation's handle by
- * name (the `| status == Frozen` spelling) — resolved by the engine through
- * the selected field's newtype to the handle's declaration-order row id,
- * exactly as the macro resolves it at expansion.
- */
 type LiteralSpec =
 	| { readonly kind: "value"; readonly value: ValueSpec }
 	| { readonly kind: "handle"; readonly handle: string }
 
-/**
- * One σ binding's right side: a single literal or a literal set (read
- * disjunctively). The SDK's selection resolver refuses the degenerate sets
- * (a membership array needs two members — the empty set selects nothing,
- * the one-element set is the bare literal respelled), so a lowered `many`
- * always carries ≥ 2 literals.
- */
 type LiteralSetSpec =
 	| { readonly kind: "one"; readonly literal: LiteralSpec }
 	| { readonly kind: "many"; readonly literals: readonly LiteralSpec[] }
 
-/**
- * One side of a containment or capacity statement:
- * `R(fields… | field == literal…)`, all names. `projection` is π in the
- * statement's written order (positional pairing with the other side);
- * `selection` is σ as (field, literal-or-set) pairs, read conjunctively.
- */
 interface SideSpec {
 	readonly relation: string
 	readonly projection: readonly string[]
 	readonly selection: ReadonlyArray<readonly [string, LiteralSetSpec]>
 }
 
-/**
- * One capacity bound: a non-negative literal, a u64 field of the TARGET
- * row (the dependent bound — per-group capacity read at judge time), or
- * the interval-measure of a TARGET-row field (`Duration(span)`). Names,
- * not ids — the spec is the name-level wire; the engine resolves bound
- * names against the target's FULL roster (C1), never the projection.
- */
 type CapacityBoundSpec =
 	| { readonly kind: "lit"; readonly value: bigint }
 	| { readonly kind: "field"; readonly field: string }
 	| { readonly kind: "durationField"; readonly field: string }
 
-/**
- * A capacity statement's weight — a TOTAL sum (C4: `unit` is a case, not
- * an absence): the count instance (`unit`), a u64 field of the SOURCE row
- * (`field`), or a SOURCE-row interval's measure (`durationField`). The
- * wire always carries it — a unit statement crosses as `{ kind: "unit" }`,
- * never by omission.
- */
 type WeightSpec =
 	| { readonly kind: "unit" }
 	| { readonly kind: "field"; readonly field: string }
 	| { readonly kind: "durationField"; readonly field: string }
 
-/**
- * A capacity statement's window — the canonical-utterance law's surviving
- * spellings, per-aggregate where weight-sensitive (design § 6), since the
- * SDK's `within()` mint makes every banned spelling unwritable or a
- * construction error: `exact` is `{n}` (`{0}` the exclusion on the unit
- * instance, "total is zero" on a weighted one), `range` is `{lo..hi}` with
- * lo < hi (`{0..hi}` the canonical ceiling; the hi slot admits a dependent
- * bound — C6: hi only), `floor` is `{lo..*}` (`{1..*}` legal on weighted
- * statements only).
- */
 type CapacityWindowSpec =
 	| { readonly kind: "exact"; readonly n: CapacityBoundSpec }
 	| { readonly kind: "range"; readonly lo: CapacityBoundSpec; readonly hi: CapacityBoundSpec }
 	| { readonly kind: "floor"; readonly lo: CapacityBoundSpec }
 
-/**
- * One field: name, structural type, host newtype name — the field's
- * DOMAIN (the macro's declared `as NewType`; the SDK's law-computed class
- * name), carried for handle resolution only, dropped by the engine at
- * descriptor lowering and never fingerprinted — and the `fresh` mint mark.
- */
 interface FieldSpec {
 	readonly name: string
 	readonly valueType: ValueTypeSpec
@@ -135,10 +55,6 @@ interface FieldSpec {
 	readonly fresh: boolean
 }
 
-/**
- * One ground axiom of a closed relation: the handle plus one literal per
- * declared intrinsic column, in field-declaration order (row id = index).
- */
 interface RowSpec {
 	readonly handle: string
 	readonly values: readonly LiteralSpec[]
@@ -159,27 +75,12 @@ interface ClosedSpec {
 	readonly rows: readonly RowSpec[]
 }
 
-/**
- * One relation. A present `closed` declares it closed (the option is the
- * kind, one sum — R7); a closed relation's `fields` are its declared
- * intrinsic columns only — the synthetic (`id`, u64) handle field is
- * materialized by the engine's schema validation.
- */
 interface RelationSpec {
 	readonly name: string
 	readonly fields: readonly FieldSpec[]
 	readonly closed: ClosedSpec | undefined
 }
 
-/**
- * One dependency statement, tagged by form. `==` is not a variant: a
- * bidirectional containment is `containment` with `bidirectional: true`,
- * lowered by the engine to the two adjacent containments (`source <=
- * target` first). `capacity` reads as the operator does (C2 — target,
- * weight, window, source): the target is the per-group parent, the source
- * is the weighed side, and the weight is ALWAYS present (`unit` the count
- * instance).
- */
 type StatementSpec =
 	| { readonly kind: "fd"; readonly relation: string; readonly projection: readonly string[] }
 	| {
@@ -196,38 +97,15 @@ type StatementSpec =
 			readonly source: SideSpec
 	  }
 
-/**
- * The whole theory as named plain data — what `lower()` produces and what
- * the bridge's `dbCreate`/`dbOpen` take. Both lists are in declaration
- * order. Only DECLARED statements appear: the engine materializes the
- * fresh-implied and closed auto-keys itself
- * (`SchemaDescriptor::materialized_statements` — fresh keys first, closed
- * auto-keys second, declared statements last), so re-stating them here
- * would double them and change the fingerprint.
- */
 interface SchemaSpec {
 	readonly relations: readonly RelationSpec[]
 	readonly statements: readonly StatementSpec[]
 }
 
-/**
- * The characters Rust's `char::escape_debug` (the engine renderer's string
- * formatter, `schema/render.rs` `literal`) escapes as `\u{…}`: everything
- * non-printable per rustc's generated tables — the C categories (Cc, Cf,
- * Cs, Co, Cn) and the Z separators (Zs, Zl, Zp) except U+0020 itself
- * (`library/core/src/unicode/printable.py`).
- */
 const NON_PRINTABLE = /[\p{C}\p{Z}]/u
 
-/** Grapheme-extending characters, which `char::escape_debug` always escapes even when printable. */
 const GRAPHEME_EXTEND = /\p{Grapheme_Extend}/u
 
-/**
- * One char exactly as Rust's `char::escape_debug` spells it (the engine
- * renders strings char by char through it): `\0`, `\t`, `\r`, `\n`,
- * backslash-escaped `\\`/`\'`/`\"`, `\u{hex}` (lowercase, unpadded) for
- * grapheme-extending and non-printable chars, the char itself otherwise.
- */
 function escapeDebugChar(ch: string): string {
 	if (ch === "\0") {
 		return "\\0"
@@ -254,12 +132,6 @@ function escapeDebugChar(ch: string): string {
 	return ch
 }
 
-/**
- * One byte exactly as Rust's `u8::escape_ascii` spells it (the engine
- * renders `bytes<N>` literals byte by byte through it): `\t`, `\r`, `\n`,
- * `\\`, `\'`, `\"` as two-char escapes, printable ASCII (0x20–0x7e)
- * verbatim, everything else `\xNN` lowercase.
- */
 function escapeAsciiByte(byte: number): string {
 	if (byte === 0x09) {
 		return "\\t"
@@ -285,16 +157,6 @@ function escapeAsciiByte(byte: number): string {
 	return `\\x${byte.toString(16).padStart(2, "0")}`
 }
 
-/**
- * Renders one lowered literal in the exact macro spelling the engine's own
- * renderer uses (`schema/render.rs` `literal`): handles bare by name,
- * integers as digits, `true`/`false`, intervals as `start..end`, strings
- * char-escaped through the `char::escape_debug` mirror, bytes as `b"…"`
- * byte-escaped through the `u8::escape_ascii` mirror — byte-for-byte the
- * engine's violation canonicals, so TS-side construction errors and
- * engine-side violations read identically and `renderStatement` equals the
- * violation's `canonical`.
- */
 function renderLiteral(literal: LiteralSpec): string {
 	if (literal.kind === "handle") {
 		return literal.handle
@@ -326,10 +188,6 @@ function renderLiteral(literal: LiteralSpec): string {
 	}
 }
 
-/**
- * Renders one σ binding's right side: a bare literal, or a disjunctive
- * literal set in braces (`{A, B}`).
- */
 function renderLiteralSet(set: LiteralSetSpec): string {
 	if (set.kind === "one") {
 		return renderLiteral(set.literal)
@@ -337,11 +195,6 @@ function renderLiteralSet(set: LiteralSetSpec): string {
 	return `{${set.literals.map(renderLiteral).join(", ")}}`
 }
 
-/**
- * Renders one capacity bound in its one canonical spelling: a literal as
- * digits, a dependent bound bare by field name, an interval-measure bound
- * as `Duration(field)` — the spellings the engine's renderer emits.
- */
 function renderCapacityBound(bound: CapacityBoundSpec): string {
 	switch (bound.kind) {
 		case "lit":
@@ -353,12 +206,6 @@ function renderCapacityBound(bound: CapacityBoundSpec): string {
 	}
 }
 
-/**
- * Renders a capacity window in its one canonical spelling: `{n}` exact
- * (`{0}` the exclusion), `{lo..hi}`, `{lo..*}` — the spelling set the
- * engine's renderer emits for sealed statements, bounds through
- * {@link renderCapacityBound}.
- */
 function renderCapacityWindow(window: CapacityWindowSpec): string {
 	switch (window.kind) {
 		case "exact":
@@ -370,12 +217,6 @@ function renderCapacityWindow(window: CapacityWindowSpec): string {
 	}
 }
 
-/**
- * Renders a capacity weight as the operator's bracket: the unit weight
- * renders NOTHING — the count utterance `<={lo..hi}` falls out of the one
- * printer, never a second "legacy" arm — a field weight as `[field]`, an
- * interval measure as `[Duration(field)]`.
- */
 function renderWeight(weight: WeightSpec): string {
 	switch (weight.kind) {
 		case "unit":
@@ -403,4 +244,4 @@ export type {
 	ValueTypeSpec,
 	WeightSpec
 }
-export { renderCapacityBound, renderCapacityWindow, renderLiteral, renderLiteralSet, renderWeight }
+export { renderCapacityWindow, renderLiteral, renderLiteralSet, renderWeight }