@bjornpagen/bumbledb 0.15.0 → 0.17.1

package/src/query/parse-ir.ts

@@ -1,14 +1,6 @@
-/**
- * Host shape parse for the wire `QueryIr`: CQ/Reach eliminator, rec/main
- * nonempty, aggregate finds split (Count has no `over`; folds require
- * it), head/find alignment. The engine validator remains the one roster
- * authority — this parse refuses only shape the host type can see.
- */
-
 import * as errors from "@superbuilders/errors"
 import type { FindTermIr, HeadTermIr, ParsedQuery, QueryIr, RuleIr } from "#native.ts"
 
-/** Brands a shape-checked wire query so {@link Native.dbPrepare} will accept it. */
 function parseQueryIr(ir: QueryIr): ParsedQuery {
 	if (ir.rules.length === 0) {
 		throw errors.new("parseQueryIr: main rules are empty")
@@ -30,7 +22,6 @@ function parseQueryIr(ir: QueryIr): ParsedQuery {
 	return ir as ParsedQuery
 }
 
-/** One rule list must share the head's width and var/aggregate family. */
 function align(context: string, head: readonly HeadTermIr[], rules: readonly RuleIr[]): void {
 	for (const [ruleIndex, rule] of rules.entries()) {
 		if (rule.finds.length !== head.length) {
@@ -50,7 +41,6 @@ function align(context: string, head: readonly HeadTermIr[], rules: readonly Rul
 	}
 }
 
-/** Count is nullary; pack and folds require `over`. */
 function parseFind(context: string, find: FindTermIr): void {
 	const raw = find as Record<string, unknown>
 	if (find.kind === "count") {
@@ -59,23 +49,20 @@ function parseFind(context: string, find: FindTermIr): void {
 		}
 		return
 	}
-	if (find.kind === "pack" || find.kind === "aggregate" || find.kind === "aggregateMeasure") {
+	if (find.kind === "pack" || find.kind === "aggregate") {
 		if (!("over" in raw)) {
 			throw errors.new(`${context}: ${find.kind} requires over`)
 		}
 	}
 }
 
-/** Head family of one find term: measure is a var slot; count/pack/folds are aggregates. */
 function findFamily(find: FindTermIr): "var" | "aggregate" {
 	switch (find.kind) {
 		case "var":
-		case "measure":
 			return "var"
 		case "count":
 		case "pack":
 		case "aggregate":
-		case "aggregateMeasure":
 			return "aggregate"
 	}
 }

package/src/query/run.ts

@@ -1,21 +1,3 @@
-/**
- * Prepared-query marshaling seams, the two rides every execution takes —
- * the typed params object down to the bridge's positional `QueryParam[]`
- * (registry order = dense `ParamId`s, values tagged by each param's
- * ANCHORING use: the field position or comparison sibling that typed it,
- * op-aware exactly as comparison literals tag), and answer rows
- * (positional, head order) back up to plain objects of BARE structural
- * values — the marshal boundary is pure both ways: the engine computed
- * the answer under the prepared head, so a decoded row that carries every
- * select column IS a row (the trusted read seam), and nothing is asserted
- * on any value. A CLOSED answer column decodes id → handle NAME through
- * the marshal's one bijection (`handleOf` — the same read half every fact
- * decode rides; the column's roster rides `FindColumn.closed`), so query
- * rows speak the vocabulary exactly as scans and gets do. Answers are
- * SETS — no order or limit exists anywhere; hosts sort. The `Prepared`
- * VALUE itself (no lifecycle, GC-reclaimed plan) lives in `#db.ts`.
- */
-
 import * as errors from "@superbuilders/errors"
 import { handleOf } from "#marshal.ts"
 import type { FactValue, QueryParam, TaggedValue } from "#native.ts"
@@ -23,7 +5,6 @@ import type { FindColumn } from "#query/atom.ts"
 import { taggedCmpLiteral } from "#query/lower.ts"
 import type { ParamEntry } from "#query/scope.ts"
 
-/** Tags one supplied value-param cell by its anchoring use. */
 function wireValue(entry: ParamEntry, context: string, value: unknown): TaggedValue {
 	if (entry.anchor === undefined) {
 		throw errors.new(
@@ -33,18 +14,6 @@ function wireValue(entry: ParamEntry, context: string, value: unknown): TaggedVa
 	return taggedCmpLiteral(context, entry.anchor, value, entry.op)
 }
 
-/**
- * Marshals the typed params object to the bridge's positional arguments,
- * in registry order (= the lowering's dense `ParamId`s). A missing entry
- * is a typed error naming the param; values tag by the anchoring use's
- * structural type; a set param takes a readonly array (the empty set is
- * legal and matches nothing — the engine's rule). A MEMBERSHIP-ARRAY
- * entry (`membership` present — a literal set folded into the query) is
- * a program constant the registry already resolved through the one
- * roster-verification point at BUILD time: it crosses as its prebuilt
- * frozen `{ kind: "set", values }` by reference — the host's params object
- * is never consulted for it, and no per-execute work exists.
- */
 function wireParams(entries: readonly ParamEntry[], supplied: Readonly<Record<string, unknown>>): QueryParam[] {
 	return entries.map(function wireOne(entry): QueryParam {
 		if (entry.membership !== undefined) {
@@ -69,13 +38,6 @@ function wireParams(entries: readonly ParamEntry[], supplied: Readonly<Record<st
 	})
 }
 
-/**
- * The read-side trusted seam of answers: a decoded row carrying every
- * select column IS a `Row` — the engine computed it under the prepared
- * head, and the values are BARE structural values, so nothing is asserted
- * beyond presence (the store is the proof carrier; no brand exists to
- * re-derive).
- */
 function isAnswerRow<Row>(
 	finds: readonly FindColumn[],
 	decoded: Readonly<Record<string, FactValue>>
@@ -85,13 +47,6 @@ function isAnswerRow<Row>(
 	})
 }
 
-/**
- * Decodes positional answer rows (column order = the query's head order
- * = the select's written order) to named, frozen row objects of bare
- * structural values. A closed column lifts its row id back to the handle
- * NAME through the marshal's bijection — an out-of-roster id is the same
- * pointed throw a fact decode gives, never a silent fallback.
- */
 function decodeAnswers<Row>(finds: readonly FindColumn[], rows: FactValue[][]): Row[] {
 	return rows.map(function decodeRow(row) {
 		if (row.length !== finds.length) {

package/src/query/scope.ts

@@ -1,35 +1,3 @@
-/**
- * Query scope terms, REFERENCE-IDENTITY edition: a query variable is an
- * OBJECT, minted fresh by {@link v} over a relation's statically-known
- * columns. `v(relation)` returns a record of fresh variables — one per
- * column, each typed at mint by its column's descriptor AND the mint
- * coordinate (the owner relation name and the column name), so
- * destructuring preserves every literal and every class
- * (`const { id, holder } = v(Account)`). Variable IDENTITY is the object
- * reference: reusing the same var value across binding positions IS the
- * join, and a name-collision join is unrepresentable (two `v()` calls mint
- * two distinct batches, so two same-named vars are two variables). Params
- * stay STRING-named — their names are the execute() params object's runtime
- * keys, an honest load-bearing channel, not a lie.
- *
- * THE DESIGN THEOREM. {@link JoinOk} is an EQUALITY (kind, class, width,
- * element, roster), so judging every binding position against the
- * variable's MINT slot ({@link MintSlotOf}) makes all cross-binding joins
- * mutually class-equal by transitivity — the env/sibling checks the
- * name-keyed edition needed are subsumed, deleted rather than ported. The
- * one check representation cannot carry is BOUNDNESS (is this var positively
- * bound in this rule): TypeScript types cannot see object identity, so
- * boundness moves from the type tier to construction-time walls only — an
- * explicit essential-vs-accidental concession; every runtime twin is
- * preserved.
- *
- * This module also owns the environment/typing utilities the whole surface
- * shares: the join descriptor {@link ClassedField}, the mint-slot machinery
- * ({@link MintSlotOf}/{@link MintClassOf}), the class-equality judgment
- * {@link JoinOk} with its runtime twin {@link fieldJoins}, and the
- * record-folding helpers `Params` and `Row` inference ride.
- */
-
 import * as errors from "@superbuilders/errors"
 import type { AnyClosed } from "#closed.ts"
 import { sealedFieldsOf } from "#closed.ts"
@@ -39,52 +7,18 @@ import type { ClassLookup, ClassRecordOf, SchemaClasses } from "#law.ts"
 import type { QueryParam } from "#native.ts"
 import type { AnyRelation, RelationFields } from "#relation.ts"
 
-/**
- * The runtime discriminant of query term values. Host literals (bigints,
- * strings, interval objects) never carry it, so "is this position a term
- * or a literal" is one property probe, never a guess.
- */
 const term: unique symbol = Symbol("bumbledb.query.term")
 
-/**
- * The carrier of a value's INFERRED types (a rule's row/params, a query's
- * row/params, a rec's params). The property is never present at runtime —
- * it exists so inference rides plain values without any brand on any
- * field value.
- */
 const inferred: unique symbol = Symbol("bumbledb.query.inferred")
 
-/**
- * What a query atom matches over: an ordinary relation or a CLOSED
- * vocabulary (ψ query atoms — the engine folds a resolvable closed atom
- * into a plan-constant member set at prepare, or joins the L1-resident
- * virtual image when the shape does not fold; the SDK never pre-folds and
- * never knows which — transparency is the contract).
- */
 type MatchOwner = AnyRelation | AnyClosed
 
-/**
- * The matchable field block of an atom owner: a relation's declared
- * fields; a closed relation's SEALED shape — the synthetic `id` (the
- * value's OWN roster-carrying descriptor, at its precise type) first, then
- * the declared payload columns read through the typed `columns` carrier.
- * The runtime twin is `sealedFieldsOf` in `#closed.ts`.
- */
 type MatchFields<R extends MatchOwner> = R extends AnyClosed
 	? { readonly id: R["id"] } & R["columns"]
 	: R extends AnyRelation
 		? RelationFields<R>
 		: never
 
-/**
- * A query variable — an OBJECT minted by {@link v}. Identity is the object
- * reference: reuse of the same value across binding positions is the join,
- * strictly rule-scoped (each rule numbers its own dense `VarId`s). The type
- * carries the mint COORDINATE — `RN` the owner relation name literal, `K`
- * the column name literal — and `F` the mint descriptor, so the mint slot
- * (descriptor + law-computed class) is recoverable at every binding
- * position for the join judgment.
- */
 interface Var<F extends AnyField = AnyField, RN extends string = string, K extends string = string> {
 	readonly [term]: "var"
 	readonly owner: MatchOwner & { readonly name: RN }
@@ -93,60 +27,48 @@ interface Var<F extends AnyField = AnyField, RN extends string = string, K exten
 	readonly label: string
 }
 
-/** Any query variable, whatever its descriptor and mint coordinate. */
 type AnyVar = Var
 
-/**
- * A scalar query parameter — `r.param("root")`. The name is the key of the
- * typed params object `execute` takes; the type is the element type of the
- * position that anchors it (a field binding, or the bound-variable side of
- * a comparison).
- */
 interface Param<Name extends string = string> {
 	readonly [term]: "param"
 	readonly name: Name
 }
 
-/**
- * A set-valued query parameter (the IR's `ParamSet` term) — `r.inSet("frontier")`:
- * bound at execution to a readonly ARRAY of values of the anchoring field's
- * type; a binding position matches iff the field value is in the set. Legal
- * in atom bindings (positive and negated) and as the right side of `eq` —
- * nowhere else, exactly as the IR rules it.
- */
 interface SetParam<Name extends string = string> {
 	readonly [term]: "setParam"
 	readonly name: Name
 }
 
-/**
- * The measure of an interval-typed variable (`ir::Term::Measure`):
- * `|[s, e)| = e − s`, u64 — legal as one side of an order comparison, as a
- * find entry, and as the input of `sum`/`min`/`max`; every other position
- * is unwritable, exactly as the IR rejects it typed. Carries the interval
- * variable it measures BY REFERENCE.
- */
-interface Duration<V extends AnyVar = AnyVar> {
-	readonly [term]: "duration"
-	readonly over: V
-}
-
-/** Any scope term value. */
-type AnyTerm = Var | Param | SetParam | Duration
+type AnyTerm = Var | Param | SetParam
 
-/** Narrows an unknown position value to a scope term (vs a host literal). */
 function isTerm(value: unknown): value is AnyTerm {
 	return typeof value === "object" && value !== null && term in value
 }
 
-/**
- * The record of fresh variables `v(owner)` mints — one per statically-known
- * column, each typed by its column's descriptor and mint coordinate.
- */
 type VarsOf<R extends MatchOwner> = {
 	readonly [K in keyof MatchFields<R> & string]: Var<MatchFields<R>[K], R["name"], K>
 }
 
+/**
+ * The exactness judgment of the six full-binding `match` forms (`#query/
+ * lower.ts` intersects it into the `bindings` parameter): a mapped type
+ * over the INFERRED record `B` requiring every entry to be a variable
+ * whose mint COLUMN is the entry's own key restricted to `R`'s matchable
+ * fields — for a column of `R` that is just the {@link VarsOf} entry's own
+ * shape, and for a FOREIGN key the column type is `never`, which no
+ * mintable variable inhabits. So an aliased or function-returned record
+ * carrying an extra key (`{...v(Account), extra: otherVar }` — shapes
+ * excess-property checking never sees, it covers inline literals only)
+ * fails the intersection and falls to the general form's judgment: the
+ * pre-0.16.0 compile refusal, restored. The identity record `v(rel)` still
+ * unifies for GENERIC `R` — the judgment is intersections and index
+ * constraints only, no deferred conditional anywhere, so the full-binding
+ * law (50-generic-binding.md, "The ruling") stands untouched.
+ */
+type ExactVars<R extends MatchOwner, B> = {
+	readonly [K in keyof B]: Var<AnyField, R["name"], K & keyof MatchFields<R> & string>
+}
+
 /**
  * The trusted admission seam of the variable-record mint (the pattern's
  * home is `isTypedScope` in `#query/lower.ts`): the checkable fact — one own
@@ -164,7 +86,7 @@ function varsMinted<R extends MatchOwner>(owner: R, record: Readonly<Record<stri
  * statically-known columns — one variable per sealed column
  * (`sealedFieldsOf`: a closed owner mints `id` first, then payload columns),
  * each frozen and each defined by OWN-property definition (object-protocol
- * column names must work, the `closed()` precedent). Every `v()` call mints
+ * column names must work, the `closed` precedent). Every `v` call mints
  * new objects, so two batches are two variables; property access within one
  * batch is stable by construction (the record is an eager frozen record,
  * never a Proxy). Variable identity is the object reference: destructure
@@ -190,102 +112,51 @@ function v<R extends MatchOwner>(owner: R): VarsOf<R> {
 	return record
 }
 
-/** Builds one scalar-parameter term. */
 function makeParam<const Name extends string>(name: Name): Param<Name> {
 	const value: Param<Name> = { [term]: "param", name }
 	return Object.freeze(value)
 }
 
-/** Builds one set-parameter term. */
 function makeSetParam<const Name extends string>(name: Name): SetParam<Name> {
 	const value: SetParam<Name> = { [term]: "setParam", name }
 	return Object.freeze(value)
 }
 
-/** Builds one measure term over an interval-typed variable reference. */
-function makeDuration<const V extends AnyVar>(over: V): Duration<V> {
-	const value: Duration<V> = { [term]: "duration", over }
-	return Object.freeze(value)
-}
-
-/**
- * One bound field slot: the field's descriptor plus the slot's
- * law-computed CLASS (`undefined` = bare — the slot is in no law). The one
- * shape every join judgment compares, at the TYPE level (a variable's mint
- * slot, a binding position's slot) and at RUNTIME alike.
- */
 interface ClassedField {
 	readonly field: AnyField
 	readonly class: string | undefined
 }
 
-/**
- * A variable's law-computed CLASS at the TYPE level: its column's class,
- * read off the schema type's class map through the mint coordinate the
- * variable carries (`RN.K`). `undefined` = bare.
- */
 type MintClassOf<Classes extends SchemaClasses, V> =
 	V extends Var<AnyField, infer RN extends string, infer K extends string>
 		? ClassLookup<ClassRecordOf<Classes, RN>, K>
 		: never
 
-/**
- * A variable's MINT slot: the descriptor it was minted at plus its
- * law-computed class. The one slot every binding position judges against —
- * because {@link JoinOk} is an equality, judging each position against the
- * mint slot makes every cross-binding join transitively class-equal.
- */
 type MintSlotOf<Classes extends SchemaClasses, V extends AnyVar> = {
 	readonly field: V["field"]
 	readonly class: MintClassOf<Classes, V>
 }
 
-/** A params object type — what `execute` takes and inference carries. */
 type ParamsRecord = Readonly<Record<string, unknown>>
 
-/** Flattens an intersection into one displayed object type (hover legibility). */
 type Flatten<T> = { [K in keyof T]: T[K] }
 
-/** The standard union-to-intersection fold (distributes over `U`). */
 type UnionToIntersection<U> = (U extends unknown ? (member: U) => void : never) extends (member: infer I) => void
 	? I
 	: never
 
-/**
- * Folds a union of per-position record fragments into one flattened record
- * (the machinery both `Params` and `Row` inference ride).
- */
 type ShapeOf<U> = [U] extends [never] ? Record<never, never> : Flatten<UnionToIntersection<U>>
 
-/** Reads a field descriptor's width label (`bytes<N>`, `interval<E, W>`); `undefined` when the kind carries none. */
 type WidthOf<F extends AnyField> = F extends { readonly width: infer W } ? W : undefined
 
-/** Reads an interval descriptor's element kind; `undefined` on scalar kinds. */
 type ElementOf<F extends AnyField> = F extends { readonly element: infer E } ? E : undefined
 
-/**
- * Reads a closed reference's vocabulary name literal paired with its handle
- * union; `undefined` on every non-closed kind (the roster IS descriptor
- * structure). The name literal is the type-tier encoding of the runtime's
- * roster VALUE-IDENTITY judgment ({@link fieldJoins}): two same-shaped
- * vocabularies are distinct rosters, so they mismatch here exactly as they
- * refuse at runtime.
- */
 type RosterOf<F extends AnyField> = F extends {
 	readonly closed: { readonly name: infer N extends string; readonly handles: readonly (infer H extends string)[] }
 }
 	? readonly [N, H]
 	: undefined
 
-/**
- * The join judgment: two bound slots join iff their descriptors' structure
- * agrees (kind, width label, interval element, and the closed ROSTER — a
- * closed reference pairs only with the same vocabulary, never with a bare
- * u64) AND their law-computed classes agree — same class name joins, and
- * bare (`undefined`) pairs only with bare (ruling 3). The class names come
- * off the SCHEMA type's class map; no descriptor label beyond the roster
- * exists to compare.
- */
 type JoinOk<A extends ClassedField, B extends ClassedField> = [
 	A["field"]["kind"],
 	A["class"],
@@ -304,14 +175,6 @@ type JoinOk<A extends ClassedField, B extends ClassedField> = [
 		: false
 	: false
 
-/**
- * The runtime twin of {@link JoinOk}: two bound slots join iff descriptor
- * structure and class agree — the same comparison the type tier makes,
- * judged on the honest runtime values (the descriptor, the roster by VALUE
- * IDENTITY, and the schema value's frozen class map). The rule builders
- * throw through this on a class-unequal reuse, so the wall holds for untyped
- * callers too.
- */
 function fieldJoins(a: ClassedField, b: ClassedField): boolean {
 	const widthA = "width" in a.field ? a.field.width : undefined
 	const widthB = "width" in b.field ? b.field.width : undefined
@@ -328,12 +191,6 @@ function fieldJoins(a: ClassedField, b: ClassedField): boolean {
 	)
 }
 
-/**
- * Renders one bound slot for join-mismatch diagnostics — the structural
- * kind in the schema grammar's spelling (a closed reference names its
- * vocabulary) plus the slot's law-computed class (`u64 in class Holder.id`;
- * a lawless slot renders `bare`).
- */
 function renderFieldKind(slot: ClassedField): string {
 	const field = slot.field
 	let base: string = field.kind
@@ -350,32 +207,14 @@ function renderFieldKind(slot: ClassedField): string {
 	return slot.class === undefined ? `${base} (bare)` : `${base} in class ${slot.class}`
 }
 
-/**
- * What a PARAM anchored at field `F` accepts at execution: the field's
- * bare value type, exactly — at a CLOSED-reference field that is the
- * handle-name union (`"DirectPass" | "Failed"`), translated name → row id
- * at execute through the one roster-verification point (`taggedHandleId`).
- */
 type ParamValueAt<F extends AnyField> = Infer<F>
 
-/** Reads a value's inferred-types carrier (rules, queries, recs). */
 type InferredOf<T> = T extends { readonly [inferred]?: infer S } ? Exclude<S, undefined> : never
 
-/**
- * One registered parameter of a query, as the wire marshal reads it: the
- * name, the wire shape, the field descriptor (or the measure) that anchored
- * it, and the comparison op the anchor came from (`"binding"` for atom
- * positions). `anchor` is `undefined` only on a query built but not yet
- * anchored by any rule. `membership` is present exactly on a
- * MEMBERSHIP-ARRAY entry: the FROZEN wire param, already resolved through
- * the one roster-verification point at BUILD time (the entry stores the
- * image, never the pre-image — no per-execute re-translation exists, and an
- * out-of-roster handle name fails where the mistake was made).
- */
 interface ParamEntry {
 	readonly name: string
 	readonly shape: "value" | "set"
-	readonly anchor: AnyField | "measure" | undefined
+	readonly anchor: AnyField | undefined
 	readonly op: "binding" | "eq" | "ne" | "lt" | "le" | "gt" | "ge" | "pointIn" | "allen"
 	readonly membership: QueryParam | undefined
 }
@@ -384,7 +223,7 @@ export type {
 	AnyTerm,
 	AnyVar,
 	ClassedField,
-	Duration,
+	ExactVars,
 	Flatten,
 	InferredOf,
 	JoinOk,
@@ -402,4 +241,4 @@ export type {
 	Var,
 	VarsOf
 }
-export { fieldJoins, inferred, isTerm, makeDuration, makeParam, makeSetParam, renderFieldKind, term, v }
+export { fieldJoins, inferred, isTerm, makeParam, makeSetParam, renderFieldKind, term, v }

package/src/relation.ts

@@ -1,8 +1,8 @@
 /**
- * `relation()` — the ordinary-relation half of the theory's signature. A
+ * `relation` — the ordinary-relation half of the theory's signature. A
  * relation value is a frozen plain object carrying its name, its ordered
  * field descriptors (declaration order = ordinal ids, the macro's law),
- * and — since selections are the relation's own vocabulary — `where()`,
+ * and — since selections are the relation's own vocabulary — `where`,
  * which resolves a selection into lowered bindings eagerly (handles
  * verified against their roster at construction). Fields are addressed by
  * NAME everywhere — statements (`on(R, "holder")`), selections, and match
@@ -16,22 +16,6 @@ import * as errors from "@superbuilders/errors"
 import { type AnyField, assertDeclarationOrderKey, assertDeclarationRecord, type Infer, literalOf } from "#fields.ts"
 import { type LiteralSetSpec, type LiteralSpec, renderLiteral } from "#spec.ts"
 
-/**
- * Resolves one selection entry to its lowered literal set: a plain ARRAY
- * (detected by `Array.isArray` — no field's value type is an array;
- * `Uint8Array` is not one) becomes a disjunctive set, anything else the
- * bare literal. The degenerate sets are construction errors, each
- * self-locating (`context` names the relation and field) — the empty set
- * selects nothing, the one-element set is the bare literal respelled, and
- * a DUPLICATE literal (judged on the canonical rendering — the engine's
- * own duplicate test, reached here first so its index-speak twin at
- * `Db.create` stays unreachable from this surface) is the same respelling
- * in disguise (the canonical-utterance law; the old set combinator's
- * signature made the length degenerates unwritable, and the refusals here
- * are that law's runtime seat). The lowered set — `{ kind: "many",
- * literals }` — is byte-identical to what the combinator produced, so no
- * fingerprint moves.
- */
 function resolveEntry(context: string, field: AnyField, entry: unknown): LiteralSetSpec {
 	if (Array.isArray(entry)) {
 		if (entry.length < 2) {
@@ -58,15 +42,6 @@ function resolveEntry(context: string, field: AnyField, entry: unknown): Literal
 	return Object.freeze({ kind: "one", literal: Object.freeze(literalOf(field, entry)) })
 }
 
-/**
- * Resolves a whole `where()` selection against the declared fields, in the
- * selection's written order (macro parity: σ is spelled, not sorted). An
- * empty selection is the bare relation respelled and rejected (the
- * canonical-utterance law). THE one selection resolver — `closed()`'s
- * `where()` resolves its payload columns through this same machine (a
- * `ClosedColumn` is structurally a {@link RelationField}), so both surfaces
- * share one vocabulary and one error voice.
- */
 function resolveSelection(
 	name: string,
 	ordered: readonly RelationField[],
@@ -95,94 +70,55 @@ function resolveSelection(
 	return Object.freeze(bindings)
 }
 
-/** The field block of a relation: field name to field descriptor. */
 type FieldsShape = Record<string, AnyField>
 
-/** One declared field: name plus its descriptor, in declaration order. */
 interface RelationField {
 	readonly name: string
 	readonly field: AnyField
 }
 
-/** A relation's runtime description. */
 interface RelationData {
 	readonly name: string
 	readonly fields: readonly RelationField[]
 }
 
-/**
- * One resolved σ binding: the field name and its lowered literal set —
- * handles already resolved to names, values already tagged by structural
- * type.
- */
 interface SelectionBinding {
 	readonly field: string
 	readonly set: LiteralSetSpec
 }
 
-/**
- * The `where()` argument: per field, a bare structural literal of that
- * field's value type (a closed reference's literal IS its handle name —
- * `"Savings"`, verified against the roster at construction), a plain
- * ARRAY of such literals read disjunctively — `kind: ["Checking",
- * "Savings"]` — or a `span(start, end)` interval literal. Membership is
- * an array, never an operator (the drizzle law); equality-only by
- * construction: no operator parameter exists anywhere.
- */
 type SelectionInput<Fields extends FieldsShape> = {
 	readonly [K in keyof Fields]?: Infer<Fields[K]> | readonly Infer<Fields[K]>[]
 }
 
-/** A relation with a selection applied — what `on()` consumes as a σ-carrying source. */
 interface Selected<Name extends string, Fields extends FieldsShape> {
 	readonly relation: Relation<Name, Fields>
 	readonly selection: readonly SelectionBinding[]
 }
 
-/** A relation value. */
 interface Relation<Name extends string, Fields extends FieldsShape> {
 	readonly name: Name
 	readonly data: RelationData
 	where(selection: SelectionInput<Fields>): Selected<Name, Fields>
 }
 
-/** Any relation value, whatever its name and field block. */
 type AnyRelation = Relation<string, FieldsShape>
 
-/** Any selected relation value. */
 interface AnySelected {
 	readonly relation: AnyRelation
 	readonly selection: readonly SelectionBinding[]
 }
 
-/** Extracts a relation's field block type. */
 type RelationFields<R extends AnyRelation> = R extends Relation<string, infer F extends FieldsShape> ? F : never
 
-/**
- * The inferred row object type of a relation as READ: every field present,
- * at its BARE structural value type ({@link Infer}). Closed relations have
- * no `Fact` — they are unwritable, and the type constraint refuses them
- * because a closed value lacks the relation shape.
- */
 type Fact<R extends AnyRelation> = {
 	[K in keyof RelationFields<R>]: Infer<RelationFields<R>[K]>
 }
 
-/** The field names of `R` whose descriptor type carries the fresh mint mark. */
 type FreshKeys<R extends AnyRelation> = {
 	[K in keyof RelationFields<R>]: RelationFields<R>[K] extends { readonly fresh: true } ? K : never
 }[keyof RelationFields<R>]
 
-/**
- * Declares one relation: `relation("Account", { id: u64.fresh,
- * holder: u64, kind: Kind.id, ... })` — every field is a pure-structure
- * descriptor (the constructor values themselves; domains are never
- * declared: `schema()` computes them from the statements). Field
- * declaration order is ordinal-id order (macro parity), carried at BOTH
- * levels: the type level by the fields object, the value level by the
- * frozen `data.fields` list — the law the schema-level class naming leans
- * on. The returned value is frozen and side-effect free.
- */
 function relation<const Name extends string, Fields extends FieldsShape>(
 	name: Name,
 	fields: Fields