@bjornpagen/bumbledb 0.14.0 → 0.17.0

package/src/face.ts

@@ -1,50 +1,13 @@
-/**
- * Faces — the projection-with-selection value both containments and
- * windows consume: `on(Account, "holder")` the common single-field
- * position, `on(Booking, ["room", "during"])` the composite/pointwise
- * position (one spelling, arity-generic), `on(Account.where({ kind:
- * Kind.Savings }), "id")` the σ-carrying source, `on(Kind, "id")` a closed
- * relation's sealed shape opened through its synthetic `id`,
- * `on(Kind.where({ mastered: true }), "id")` the ψ-selected closed source
- * (the selection lowered as-is — the ENGINE folds it against the sealed
- * extension at validate, never the SDK). Projection is
- * positional: tuple order is preserved in the type, and the statement
- * constructors pair the two sides' tuples by arity ({@link SameArity}) AND
- * by structural shape ({@link SameShapes}) — every projected field's
- * kind/width/element/roster quadruple is read off the schema type (the
- * minimal kernel: descriptors are pure structure, and a closed reference's
- * roster IS part of that structure) and compared positionwise. There is no
- * domain to compare at construction — domains are LAW-BORN: the statements
- * themselves define the equivalence classes, and `schema()` is where they
- * aggregate and get judged (the one-generator-per-class wall).
- */
-
 import * as errors from "@superbuilders/errors"
 import type { AnyClosed, AnySelectedClosed, PayloadField } from "#closed.ts"
 import type { AnyField } from "#fields.ts"
 import type { AnyRelation, AnySelected, FieldsShape, RelationFields, SelectionBinding } from "#relation.ts"
 import { renderLiteralSet } from "#spec.ts"
 
-/** The empty σ of a selection-free face, shared by every bare projection. */
 const emptySelection: readonly SelectionBinding[] = Object.freeze([])
 
-/**
- * The OWNER a face source resolves to: a selected relation — ordinary σ or
- * closed ψ, one shape — projects from its underlying relation; a bare
- * relation or closed relation is its own owner. The type-level twin of
- * {@link faceParts}'s split, and what a statement's face `data` carries at
- * its EXACT type — `schema()`'s law-typing reads the owner's literal name
- * (and the projection tuple) straight off the statement type.
- */
 type OwnerOf<S extends FaceSource> = S extends AnySelected | AnySelectedClosed ? S["relation"] : S
 
-/**
- * Splits a face source into its owner and σ: a selected relation — ordinary
- * σ or closed ψ, one shape — carries its own bindings (`relation` is the
- * discriminant — the property exists on no relation or closed value, and
- * `closed()` reserves the name against handle collisions); a bare relation
- * or closed relation carries none.
- */
 function faceParts(source: FaceSource): {
 	readonly owner: FaceOwner
 	readonly selection: readonly SelectionBinding[]
@@ -55,51 +18,24 @@ function faceParts(source: FaceSource): {
 	return { owner: source, selection: emptySelection }
 }
 
-/** The relation a face projects from — ordinary or closed. */
 type FaceOwner = AnyRelation | AnyClosed
 
-/**
- * A face's runtime description: owner, π (written order), σ (resolved
- * bindings). Generic over the owner and projection so a STATEMENT value
- * carries its paired coordinates at their exact types — the honest runtime
- * properties (`owner.name`, `projection`) ARE the type-level carrier
- * `schema()`'s law-typing reads; the defaults are the wide shape every
- * renderer and lowering walk consumes.
- */
 interface FaceData<O extends FaceOwner = FaceOwner, P extends readonly string[] = readonly string[]> {
 	readonly owner: O
 	readonly projection: P
 	readonly selection: readonly SelectionBinding[]
 }
 
-/**
- * A face value. `S` is the source exactly as written (the relation,
- * selected relation, or closed relation `on()` was handed — the statement
- * constructors resolve each projected field's DOMAIN through it), and `P`
- * is the projection tuple as written (its length is the positional-pairing
- * arity). Both are honest runtime properties, not phantoms — and `data`
- * carries the resolved owner at its exact type, which is what a statement
- * value hands to `schema()`'s law-typing.
- */
 interface Face<S extends FaceSource, P extends readonly string[]> {
 	readonly source: S
 	readonly projection: P
 	readonly data: FaceData<OwnerOf<S>, P>
 }
 
-/** Any face value, whatever its source and projection. */
 type AnyFace = Face<FaceSource, readonly string[]>
 
-/** What `on()` accepts: a relation, a closed relation, or either with a selection applied. */
 type FaceSource = AnyRelation | AnyClosed | AnySelected | AnySelectedClosed
 
-/**
- * The field names a face over `S` may project: a relation's declared
- * fields; a selected relation's underlying fields; a closed relation's
- * SEALED shape — the synthetic `id` plus its declared payload columns,
- * bare or ψ-selected alike (`docs/architecture/70-api.md`: statement field
- * names address the sealed shape).
- */
 type FaceFields<S extends FaceSource> = S extends AnySelected
 	? keyof RelationFields<S["relation"]> & string
 	: S extends AnySelectedClosed
@@ -110,27 +46,6 @@ type FaceFields<S extends FaceSource> = S extends AnySelected
 				? "id" | (keyof Row & string)
 				: never
 
-/**
- * One descriptor's structural comparand: the kind/width/element/roster
- * quadruple — exactly the structure the minimal kernel carries. The first
- * three slots compare exactly as the engine's Q1 law pairs positions
- * (`schema/validate.rs`): a `bytes` width is bound (bytes<16> vs bytes<32>
- * mismatch), while an INTERVAL width is FREE — the pointwise judgments
- * quantify over points, which carry an element domain and not a width, so
- * `interval(u64)` pairs with `interval(u64, 1n)` (recipe 9's extent/slot
- * mirrors, recipe 29's mixed-width zones) and the width slot reads
- * `undefined` for every interval. Elements stay bound: u64-vs-i64 interval
- * pairs still mismatch. The ROSTER slot is SDK-only structure (the engine's
- * wire carries plain u64s): a closed reference contributes its vocabulary
- * NAME literal paired with its handle union — the faithful encoding of the
- * runtime's roster VALUE-IDENTITY judgment, so two same-shaped vocabularies
- * mismatch at compile time exactly as they throw at construction — every
- * other kind `undefined`, so a plain u64 face cannot pair with a closed
- * `[id]` face — the vocabulary's own descriptor (`Kind.id`) is the ONE
- * spelling of a closed reference at this surface, and a bare column cannot
- * alias a vocabulary through a declared law. The runtime twin is the
- * statement constructors' roster-identity walk (`statements.ts`).
- */
 type ShapeOf<F extends AnyField> = readonly [
 	F["kind"],
 	F extends { readonly element: unknown } ? undefined : F extends { readonly width: infer W } ? W : undefined,
@@ -142,18 +57,8 @@ type ShapeOf<F extends AnyField> = readonly [
 		: undefined
 ]
 
-/** One field's structural shape within a declared field block (`undefined` when the name is foreign). */
 type ShapeIn<Fields extends FieldsShape, K extends string> = K extends keyof Fields ? ShapeOf<Fields[K]> : undefined
 
-/**
- * The structural SHAPE of one projected field, read off the source's
- * schema type — an ordinary or selected relation's field contributes its
- * descriptor's triple; a closed relation (bare or ψ-selected) contributes
- * its synthetic `id` as a u64 and its payload columns' declared
- * descriptors' triples through the closed value's typed `columns` carrier
- * (whose runtime twin is the frozen `columns` record the mint carries).
- * The engine stays the final authority at `Db.create`/`Db.open`.
- */
 type ProjectedShape<S extends FaceSource, K extends string> = S extends AnySelected
 	? ShapeIn<RelationFields<S["relation"]>, K>
 	: S extends AnySelectedClosed
@@ -171,22 +76,14 @@ type ProjectedShape<S extends FaceSource, K extends string> = S extends AnySelec
 					: ShapeIn<Cols, K>
 				: undefined
 
-/** The positionwise structural-shape tuple of a projection over `S`. */
 type ShapesOf<S extends FaceSource, P extends readonly string[]> = {
 	readonly [I in keyof P]: ProjectedShape<S, P[I] & string>
 }
 
-/** The shape tuple a face projects, positionwise — the comparand of {@link SameShapes}. */
 type FaceShapes<F extends AnyFace> = F extends Face<infer S, infer P> ? ShapesOf<S, P> : never
 
-/** The projection arity of a face. */
 type Arity<F extends AnyFace> = F["projection"]["length"]
 
-/**
- * The legible arity-mismatch verdict: when the two faces of a containment,
- * bijection, or window project different numbers of fields, this type is
- * intersected into the second face's parameter and names both arities.
- */
 interface FaceArityMismatch<Left, Right> {
 	readonly "face arity mismatch — positional pairing requires both sides to project equally many fields": readonly [
 		Left,
@@ -194,11 +91,6 @@ interface FaceArityMismatch<Left, Right> {
 	]
 }
 
-/**
- * Resolves to `unknown` (a no-op intersection) when the two faces project
- * equally many fields, and to {@link FaceArityMismatch} otherwise — the
- * named helper the statement constructors constrain with.
- */
 type SameArity<A extends AnyFace, B extends AnyFace> =
 	Arity<A> extends Arity<B>
 		? Arity<B> extends Arity<A>
@@ -206,14 +98,6 @@ type SameArity<A extends AnyFace, B extends AnyFace> =
 			: FaceArityMismatch<Arity<A>, Arity<B>>
 		: FaceArityMismatch<Arity<A>, Arity<B>>
 
-/**
- * The legible shape-mismatch verdict: when the two faces of a containment,
- * bijection, or window project structurally incompatible fields at any
- * position, this type is intersected into the second face's parameter and
- * names both shape tuples — a u64 face against a str face, a bytes width
- * mismatch, an interval element mismatch, or a bare column against a
- * closed reference (the roster slot) is a COMPILE error.
- */
 interface FaceShapeMismatch<Left, Right> {
 	readonly "face shape mismatch — positionwise kind, width, element, and closed roster must be equal on both sides": readonly [
 		Left,
@@ -221,17 +105,6 @@ interface FaceShapeMismatch<Left, Right> {
 	]
 }
 
-/**
- * Resolves to `unknown` (a no-op intersection) when the two faces project
- * positionwise-equal structural shapes, and to {@link FaceShapeMismatch}
- * otherwise. Equality is mutual tuple assignability over the
- * kind/width/element/roster quadruples. This is the whole
- * construction-time wall — deliberately: there is no domain to compare
- * here (the roster is descriptor STRUCTURE, not a domain). The domain wall
- * lives where domains are BORN: `schema()` computes every field's class
- * from the statement list and holds the one-generator-per-class law, and
- * query joins compare class names off the schema type.
- */
 type SameShapes<A extends AnyFace, B extends AnyFace> =
 	FaceShapes<A> extends FaceShapes<B>
 		? FaceShapes<B> extends FaceShapes<A>
@@ -239,16 +112,6 @@ type SameShapes<A extends AnyFace, B extends AnyFace> =
 			: FaceShapeMismatch<FaceShapes<A>, FaceShapes<B>>
 		: FaceShapeMismatch<FaceShapes<A>, FaceShapes<B>>
 
-/**
- * Projects a face — one spelling, arity-generic: `on(Account, "holder")`
- * for the common single-field position, `on(Booking, ["room", "during"])`
- * for the composite/pointwise position (the interval-pointwise `==` and
- * coverage recipes), `on(Account.where({...}), "id")` for a σ-carrying
- * source. Field names are typechecked against the source (unknown field =
- * type error, names autocomplete); tuple order is preserved (positional
- * pairing with the other side, macro parity). The empty projection is
- * unwritable by signature — it has no meaning in the statement grammar.
- */
 function on<S extends FaceSource, const F extends FaceFields<S>>(source: S, field: F): Face<S, readonly [F]>
 function on<S extends FaceSource, const P extends readonly [FaceFields<S>, ...FaceFields<S>[]]>(
 	source: S,
@@ -292,11 +155,6 @@ function faceMinted<S extends FaceSource, P extends readonly string[]>(
 	)
 }
 
-/**
- * Renders one face in the exact macro notation — `Name(p1, p2 | f == lit,
- * g == {a, b})`, the selection block only when σ is nonempty (the engine
- * renderer's own shape, `schema/render.rs`).
- */
 function renderFace(face: FaceData): string {
 	const projection = face.projection.join(", ")
 	if (face.selection.length === 0) {

package/src/fields.ts

@@ -1,20 +1,3 @@
-/**
- * Field descriptors — the value half of the `schema!` field grammar
- * (`docs/architecture/70-api.md`), MINIMAL edition: `bool`, `u64`, `i64`,
- * `str`, `bytes(n)`, `interval(u64|i64[, width])`, each a plain frozen value
- * that IS its own descriptor type — `{ kind, width?, element?, fresh? }` —
- * honest at runtime and in the type alike. A field's VALUE type is its bare
- * structural type (`u64` → `bigint`, `str` → `string`, `bytes(n)` →
- * `Uint8Array`, intervals → `{ start, end }`): no brands, no phantoms, no
- * minting casts. A descriptor carries STRUCTURE ONLY — domains are never
- * declared anywhere (the owner ruling: THE LAWS TYPE THE COLUMNS): a
- * field's domain is COMPUTED by `schema()` from the statement list, where
- * the dependencies themselves induce the equivalence classes. The macro's
- * refusals are reproduced representationally: `.fresh` exists only on u64,
- * and no field-level constraint vocabulary of any kind exists —
- * `unique`/`fk` are unwritable, not rejected.
- */
-
 import * as errors from "@superbuilders/errors"
 import type { LiteralSpec } from "#spec.ts"
 
@@ -24,7 +7,7 @@ import type { LiteralSpec } from "#spec.ts"
  * The ray is representable (`end` = the element type's MAX_END); widths
  * and signedness are NOT modeled on the value — they are descriptor-type
  * labels the engine judges at the typed write boundary. Interval fields
- * derive no order (the Rust refusal, `docs/architecture/10-data-model.md`),
+ * derive no order (the Rust refusal,,
  * so no comparators exist on the value type.
  */
 interface IntervalValue {
@@ -46,83 +29,38 @@ function span(start: bigint, end: bigint): IntervalValue {
 	return Object.freeze({ start, end })
 }
 
-/**
- * A closed relation's roster as seen from a referencing field: the handle
- * namespace `where()` selections and ground axioms resolve bare handle ids
- * through (the macro's own rule: a handle is legal exactly on a field that
- * references a closed relation). The roster is PRECISE in BOTH slots —
- * `Name` carries the vocabulary's literal name and `H` the literal handle
- * names in declaration order (the unbound `string` defaults exist only as
- * the fallback where no roster is in scope). The name literal is
- * load-bearing: the runtime twins judge roster VALUE IDENTITY, so two
- * same-shaped vocabularies (`Yes/No` twice) are distinct — carrying the
- * name makes the type the faithful encoding of that judgment, and a
- * cross-vocabulary pairing fails at compile time, not construction. The
- * runtime twin is the same frozen declaration-order value that was always
- * there.
- */
 interface ClosedRoster<Name extends string = string, H extends string = string> {
 	readonly name: Name
 	readonly handles: readonly H[]
 }
 
-/** The `bool` field descriptor: value type `boolean`. No `.fresh` (macro parity). */
 interface BoolField {
 	readonly kind: "bool"
 }
 
-/** The `str` field descriptor: value type `string`. No `.fresh` (macro parity). */
 interface StrField {
 	readonly kind: "str"
 }
 
-/**
- * A `fresh`-marked u64 field descriptor — `id: u64.fresh`. The mark is a
- * structural label (`fresh: true`) in the descriptor type AND on the
- * runtime value; it implies the key `R(field) -> R`, which the ENGINE
- * materializes (`SchemaDescriptor::materialized_statements`), and it makes
- * the field a GENERATOR — `schema()` names its equivalence class by the
- * declaration coordinate (`"Account.id"`). Terminal: no builder property
- * survives the mark.
- */
 interface FreshU64Field {
 	readonly kind: "u64"
 	readonly fresh: true
 }
 
-/**
- * The `u64` field descriptor. `.fresh` marks the field as engine-minted —
- * the property doubles as the mark itself: on an unmarked descriptor it
- * holds the marked descriptor, on a marked one it IS the literal `true`
- * (one structural property, read either way).
- */
 interface U64Field {
 	readonly kind: "u64"
 	readonly fresh: FreshU64Field
 }
 
-/** The `i64` field descriptor. Terminal: `.fresh` is legal on u64 only. */
 interface I64Field {
 	readonly kind: "i64"
 }
 
-/**
- * A `bytes<N>` field descriptor. The width is a descriptor-type label
- * (load-bearing: the engine enforces it at the write boundary) and the
- * value type is bare `Uint8Array`. No order is derived — no comparators
- * exist on the value type (the engine refuses order on bytes).
- */
 interface BytesField<Width extends number = number> {
 	readonly kind: "bytes"
 	readonly width: Width
 }
 
-/**
- * An interval field descriptor — `interval(i64)` general (rays
- * representable), `interval(u64, w)` the fixed-width family. Element and
- * width are descriptor-type labels; the value type is always the bare
- * {@link IntervalValue}.
- */
 interface IntervalField<
 	Element extends "u64" | "i64" = "u64" | "i64",
 	Width extends bigint | undefined = bigint | undefined
@@ -132,34 +70,13 @@ interface IntervalField<
 	readonly width: Width
 }
 
-/**
- * A closed relation's reference field descriptor (`Kind.id`) — a u64
- * descriptor carrying the closed linkage: the roster resolves handle
- * literals in selections and ground axioms, and `schema()` names the id's
- * generator class `"Kind.id"`. The handle union `H` is the field's VALUE
- * TYPE (see {@link Infer}); `kind: "u64"` stays load-bearing for the class
- * map and JoinOk, which compare kind/class/width/element. Terminal: no
- * `.fresh` — a vocabulary's rows are ground axioms, never minted.
- */
 interface ClosedIdField<Name extends string = string, H extends string = string> {
 	readonly kind: "u64"
 	readonly closed: ClosedRoster<Name, H>
 }
 
-/** Any field descriptor, whatever its kind or marks. */
 type AnyField = BoolField | StrField | U64Field | FreshU64Field | I64Field | BytesField | IntervalField | ClosedIdField
 
-/**
- * The bare structural VALUE type of a field descriptor — the one total
- * definition every fact, result row, and query term reads: `bool` →
- * `boolean`, `str` → `string`, `u64`/`i64` → `bigint`, `bytes<N>` →
- * `Uint8Array`, intervals → {@link IntervalValue}, and a closed reference →
- * its PRECISE handle union (`"DirectPass" | "Failed"` — the string-literal
- * union IS the value type at the TS surface; the engine keeps u64 row ids
- * and the marshal owns the bijection). The closed arm precedes the `u64`
- * arm because a closed reference is structurally a u64 descriptor plus the
- * roster.
- */
 type Infer<F extends AnyField> = F extends { readonly kind: "bool" }
 	? boolean
 	: F extends { readonly kind: "str" }
@@ -186,13 +103,6 @@ function literalShapeError(context: string, expected: string, value: unknown): E
 	return errors.new(`${context}: expected ${expected}, got ${typeof value}`)
 }
 
-/**
- * The roster a field descriptor carries — THE one reader: present exactly
- * on a closed-reference descriptor (the structural `closed` property of
- * {@link ClosedIdField}), absent on every other field kind. Tolerates
- * `undefined` so name-lookup misses flow through without a re-spelled
- * probe at every call site.
- */
 function rosterOf(field: AnyField | undefined): ClosedRoster | undefined {
 	if (field !== undefined && "closed" in field) {
 		return field.closed
@@ -200,7 +110,6 @@ function rosterOf(field: AnyField | undefined): ClosedRoster | undefined {
 	return undefined
 }
 
-/** Narrows an interval-shaped value: a plain object with bigint start/end — THE one interval predicate. */
 function isIntervalValue(value: unknown): value is IntervalValue {
 	return (
 		typeof value === "object" &&
@@ -212,15 +121,6 @@ function isIntervalValue(value: unknown): value is IntervalValue {
 	)
 }
 
-/**
- * Resolves one closed-handle literal: the handle NAME, verified against the
- * roster — an unknown name is a construction error, the belt the wide
- * fallback type deliberately does not provide (structural values make any
- * string spellable here; the roster judges). The name IS the value at the
- * TS surface (the drizzle law); the wire literal already crossed as
- * `{ kind: "handle", handle }`, so the output — and every fingerprint
- * derived from it — is untouched.
- */
 function handleLiteral(closed: ClosedRoster, value: unknown): LiteralSpec {
 	if (typeof value !== "string") {
 		throw literalShapeError("selection literal", `a ${closed.name} handle name (string)`, value)
@@ -231,7 +131,6 @@ function handleLiteral(closed: ClosedRoster, value: unknown): LiteralSpec {
 	return { kind: "handle", handle: value }
 }
 
-/** Lowers one interval literal at its element type. */
 function intervalLiteral(element: "u64" | "i64", value: unknown): LiteralSpec {
 	if (!isIntervalValue(value)) {
 		throw literalShapeError("selection literal", "interval ({ start, end } bigints)", value)
@@ -242,20 +141,6 @@ function intervalLiteral(element: "u64" | "i64", value: unknown): LiteralSpec {
 	return { kind: "value", value: { kind: "intervalI64", start: value.start, end: value.end } }
 }
 
-/**
- * Rejects a declaration name that JavaScript would re-order, and a name
- * that would break the class map's coordinate encoding. Declaration order =
- * ordinal ids is the law relations, columns, and schemas all lean on, and
- * it is carried by object-literal key order — which ECMA-262's
- * OrdinaryOwnPropertyKeys breaks for integer-index keys (they enumerate
- * first, ascending, regardless of where they were written). A `.` in a name
- * would make the law engine's `${relation}.${field}` coordinate template
- * non-injective at BOTH tiers (relation `"A.B"` field `"x"` and relation
- * `"A"` field `"B.x"` are one coordinate), silently merging unrelated law
- * classes — banned here, which is exact macro parity: Rust identifiers
- * cannot contain dots. Both are construction errors, exactly as an
- * unparseable name is a macro expansion error.
- */
 function assertDeclarationOrderKey(where: string, name: string): void {
 	if (/^(?:0|[1-9][0-9]*)$/.test(name)) {
 		throw errors.new(
@@ -269,18 +154,6 @@ function assertDeclarationOrderKey(where: string, name: string): void {
 	}
 }
 
-/**
- * Rejects a declaration record whose prototype was replaced. A plain
- * `__proto__: {...}` property in an object literal is ECMA-262 Annex B's
- * prototype SETTER, not a data property — the entry never becomes an own
- * enumerable key, so the declared handle/field/relation would silently
- * vanish from every `Object.keys`/`Object.entries` walk while the type
- * tier still admits its name. A non-default prototype on a declaration
- * literal proves exactly that spelling, so it is a construction error; the
- * computed spelling `["__proto__"]: {...}` creates an own data property
- * and is admitted (no name is reserved). `Object.create(null)` records
- * stay admissible.
- */
 function assertDeclarationRecord(where: string, record: object): void {
 	const proto = Object.getPrototypeOf(record)
 	if (proto !== Object.prototype && proto !== null) {
@@ -290,46 +163,23 @@ function assertDeclarationRecord(where: string, record: object): void {
 	}
 }
 
-/** The one fresh-marked u64 descriptor (the `.fresh` property of the unmarked one). */
 const freshU64: FreshU64Field = Object.freeze({ kind: "u64", fresh: true })
 
-/** The one `u64` constructor value. */
 const u64: U64Field = Object.freeze({ kind: "u64", fresh: freshU64 })
 
-/** The one `i64` constructor value. */
 const i64: I64Field = Object.freeze({ kind: "i64" })
 
-/** The one `bool` constructor value. */
 const bool: BoolField = Object.freeze({ kind: "bool" })
 
-/** The one `str` constructor value. */
 const str: StrField = Object.freeze({ kind: "str" })
 
-/**
- * The `bytes<N>` field constructor. The width is mandatory and a
- * descriptor-type label; `width` is validated to 1..=64 here because the
- * grammar pins that range at declaration (`docs/architecture/70-api.md`
- * § the `schema!` grammar: N ∈ 1..=64 — bare `bytes` does not parse), the
- * macro-expansion boundary's analog being construction.
- */
 function bytes<const Width extends number>(width: Width): BytesField<Width> {
 	if (!Number.isInteger(width) || width < 1 || width > 64) {
-		throw errors.new(
-			`bytes width must be an integer in 1..=64 (got ${width}) — docs/architecture/70-api.md pins the range at declaration`
-		)
+		throw errors.new(`bytes width must be an integer in 1..=64 (got ${width}) — the range is pinned at declaration`)
 	}
 	return Object.freeze({ kind: "bytes", width })
 }
 
-/**
- * The interval field constructor — `interval(u64)` / `interval(i64)` for
- * the general type (rays representable), `interval(u64, w)` for the
- * fixed-width family whose width IS a descriptor-type label. The element is
- * spelled with the u64/i64 constructor values themselves, never a string.
- * `width >= 1` is validated here because the grammar pins it at declaration
- * (`docs/architecture/70-api.md`: w ≥ 1; `interval<u64, 0>` is an
- * expansion error naming the field).
- */
 function interval<Element extends U64Field | I64Field>(element: Element): IntervalField<Element["kind"], undefined>
 function interval<Element extends U64Field | I64Field, const Width extends bigint>(
 	element: Element,
@@ -341,21 +191,11 @@ function interval(element: U64Field | I64Field, width?: bigint): IntervalField<"
 		throw errors.new(`interval element must be the u64 or i64 field constructor (got ${elementKind})`)
 	}
 	if (width !== undefined && width < 1n) {
-		throw errors.new(
-			`interval width must be >= 1 (got ${width}) — docs/architecture/70-api.md pins w >= 1 at declaration`
-		)
+		throw errors.new(`interval width must be >= 1 (got ${width}) — w >= 1 is pinned at declaration`)
 	}
 	return Object.freeze({ kind: "interval", element: elementKind, width })
 }
 
-/**
- * Lowers one host literal at its field position to the wire
- * {@link LiteralSpec} — the selection-literal machine ground axioms and
- * `where()` bindings both ride (one machine, same errors — the macro's own
- * rule). A value on a closed-reference field IS its handle NAME (verified
- * against the roster: an unknown name is a construction error); everything
- * else lowers to a plain value tagged by the field's structural kind.
- */
 function literalOf(field: AnyField, value: unknown): LiteralSpec {
 	const roster = rosterOf(field)
 	if (roster !== undefined) {
@@ -384,15 +224,7 @@ function literalOf(field: AnyField, value: unknown): LiteralSpec {
 			if (typeof value !== "string") {
 				throw literalShapeError("selection literal", "string", value)
 			}
-			/**
-			 * The marshal's bijection law at the schema-literal seam
-			 * (`marshal.ts` cellOf): a lone surrogate would cross dbCreate
-			 * lossily (stored as U+FFFD engine-side), collapsing two
-			 * distinct TS schema values into one stored theory/fingerprint
-			 * and splitting the canonical statement rendering from the
-			 * SDK's. All three string-admission seams — fact row, query
-			 * literal/param, schema literal — enforce the one law.
-			 */
+
 			if (!value.isWellFormed()) {
 				throw literalShapeError("selection literal", "well-formed string", value)
 			}