@bjornpagen/bumbledb 1.1.0 → 1.2.0

package/src/query/parse-ir.ts

@@ -1,75 +1,268 @@
 import { AuthoringError } from "#errors.ts"
-import type { FindTermIr, HeadTermIr, ParsedQuery, QueryIr, RuleIr } from "#native.ts"
+import type {
+	AtomIr,
+	CmpOpIr,
+	ConditionTreeIr,
+	FindTermIr,
+	HeadTermIr,
+	ParsedQuery,
+	QueryIr,
+	RuleIr,
+	ScalarExprIr,
+	TermIr
+} from "#native.ts"
+import { arrayValue as array, recordValue, valueDescriptor } from "#values.ts"
 
-function parseQueryIr(ir: QueryIr): ParsedQuery {
-	if (ir.rules.length === 0) {
-		throw new AuthoringError({ message: "parseQueryIr: main rules are empty" })
-	}
-	align("query", ir.head, ir.rules)
-	ir.interiors.forEach(function checkInterior(interior, index) {
-		align(`interior ${index}`, interior.head, interior.rules)
+function fail(context: string, expected: string): never {
+	throw new AuthoringError({
+		message: `${context}: ${expected}`,
+		diagnostic: { code: "InvalidQuery", context, expected }
 	})
-	if (ir.kind === "reach") {
-		if (ir.rec.base.length === 0) {
-			throw new AuthoringError({ message: "parseQueryIr: rec base is empty" })
-		}
-		if (ir.rec.rec.length === 0) {
-			throw new AuthoringError({ message: "parseQueryIr: rec step is empty" })
-		}
-		align("rec base", ir.rec.head, ir.rec.base)
-		align("rec step", ir.rec.head, ir.rec.rec)
+}
+
+function tagged(context: string, input: unknown): Readonly<Record<string, unknown>> {
+	if (typeof input !== "object" || input === null) return fail(context, "expected a descriptor record")
+	return recordValue(context, input, Object.keys(input))
+}
+
+function ordinal(context: string, input: unknown, maximum = 0xffff): number {
+	if (typeof input !== "number" || !Number.isInteger(input) || input < 0 || input > maximum)
+		return fail(context, `expected an ordinal from 0 through ${maximum}`)
+	return input
+}
+
+function term(context: string, input: unknown): TermIr {
+	const raw = tagged(context, input)
+	switch (raw.kind) {
+		case "var":
+			recordValue(context, raw, ["kind", "var"])
+			return Object.freeze({ kind: raw.kind, var: ordinal(context, raw.var) })
+		case "param":
+		case "paramSet":
+			recordValue(context, raw, ["kind", "param"])
+			return Object.freeze({ kind: raw.kind, param: ordinal(context, raw.param) })
+		case "literal":
+			recordValue(context, raw, ["kind", "value"])
+			return Object.freeze({ kind: raw.kind, value: valueDescriptor(`${context}.value`, raw.value) })
+		default:
+			return fail(context, "unknown term kind")
 	}
-	return ir as ParsedQuery
 }
 
-function align(context: string, head: readonly HeadTermIr[], rules: readonly RuleIr[]): void {
-	for (const [ruleIndex, rule] of rules.entries()) {
-		if (rule.finds.length !== head.length) {
-			throw new AuthoringError({
-				message: `${context}: rule ${ruleIndex} finds width ${rule.finds.length} does not match head width ${head.length}`
+function scalar(context: string, input: unknown, depth = 1): ScalarExprIr {
+	if (depth > 128) return fail(context, "scalar expression deeper than 128")
+	const raw = tagged(context, input)
+	switch (raw.kind) {
+		case "var":
+			recordValue(context, raw, ["kind", "var"])
+			return Object.freeze({ kind: raw.kind, var: ordinal(context, raw.var) })
+		case "literal":
+			recordValue(context, raw, ["kind", "value"])
+			return Object.freeze({ kind: raw.kind, value: valueDescriptor(`${context}.value`, raw.value) })
+		case "negate":
+		case "isNaN":
+		case "isFinite":
+			recordValue(context, raw, ["kind", "expr"])
+			return Object.freeze({ kind: raw.kind, expr: scalar(`${context}.expr`, raw.expr, depth + 1) })
+		case "add":
+		case "subtract":
+		case "multiply":
+		case "divide":
+			recordValue(context, raw, ["kind", "left", "right"])
+			return Object.freeze({
+				kind: raw.kind,
+				left: scalar(`${context}.left`, raw.left, depth + 1),
+				right: scalar(`${context}.right`, raw.right, depth + 1)
 			})
+		case "cast": {
+			recordValue(context, raw, ["kind", "cast", "expr"])
+			const cast = raw.cast
+			if (cast !== "toF64" && cast !== "toF64Exact" && cast !== "toI64Exact" && cast !== "toU64Exact")
+				return fail(context, "unknown numeric cast")
+			return Object.freeze({ kind: raw.kind, cast, expr: scalar(`${context}.expr`, raw.expr, depth + 1) })
 		}
-		rule.finds.forEach(function checkFind(find, position) {
-			parseFind(`${context} rule ${ruleIndex} find ${position}`, find)
-			const family = findFamily(find)
-			if (family !== head[position]?.kind) {
-				throw new AuthoringError({
-					message: `${context}: rule ${ruleIndex} find ${position} is ${family}, not head ${head[position]?.kind}`
-				})
-			}
-		})
+		default:
+			return fail(context, "unknown scalar expression kind")
 	}
 }
 
-function parseFind(context: string, find: FindTermIr): void {
-	const raw = find as Record<string, unknown>
-	if (find.kind === "count") {
-		if ("over" in raw) {
-			throw new AuthoringError({ message: `${context}: Count carries no over` })
-		}
-		return
-	}
-	if (find.kind === "pack" || find.kind === "aggregate") {
-		if (!("over" in raw)) {
-			throw new AuthoringError({ message: `${context}: ${find.kind} requires over` })
-		}
-	}
-	if (find.kind === "compute" && !("expr" in raw)) {
-		throw new AuthoringError({ message: `${context}: compute requires expr` })
+function headTerm(context: string, input: unknown): HeadTermIr {
+	const raw = tagged(context, input)
+	if (raw.kind === "var" || raw.kind === "compute") {
+		recordValue(context, raw, ["kind"])
+		return Object.freeze({ kind: raw.kind })
 	}
+	recordValue(context, raw, ["kind", "op"])
+	if (raw.kind !== "aggregate") return fail(context, "unknown head kind")
+	const op = raw.op
+	if (op !== "sum" && op !== "mean" && op !== "min" && op !== "max" && op !== "count" && op !== "pack")
+		return fail(context, "unknown head aggregate")
+	return Object.freeze({ kind: raw.kind, op })
 }
 
-function findFamily(find: FindTermIr): "var" | "aggregate" | "compute" {
-	switch (find.kind) {
+function find(context: string, input: unknown): FindTermIr {
+	const raw = tagged(context, input)
+	switch (raw.kind) {
 		case "var":
-			return "var"
-		case "compute":
-			return "compute"
+			recordValue(context, raw, ["kind", "var"])
+			return Object.freeze({ kind: raw.kind, var: ordinal(context, raw.var) })
 		case "count":
+			if (Object.hasOwn(raw, "over")) return fail(context, "Count carries no over")
+			recordValue(context, raw, ["kind"])
+			return Object.freeze({ kind: raw.kind })
+		case "compute":
+			if (!Object.hasOwn(raw, "expr")) return fail(context, "compute requires expr")
+			recordValue(context, raw, ["kind", "expr"])
+			return Object.freeze({ kind: raw.kind, expr: scalar(`${context}.expr`, raw.expr) })
 		case "pack":
-		case "aggregate":
-			return "aggregate"
+			recordValue(context, raw, ["kind", "over"])
+			return Object.freeze({ kind: raw.kind, over: ordinal(context, raw.over) })
+		case "aggregate": {
+			recordValue(context, raw, ["kind", "op", "over"])
+			const op = recordValue(`${context}.op`, raw.op, ["kind"]).kind
+			if (op !== "sum" && op !== "mean" && op !== "min" && op !== "max") return fail(context, "unknown fold operator")
+			return Object.freeze({ kind: raw.kind, op: Object.freeze({ kind: op }), over: ordinal(context, raw.over) })
+		}
+		default:
+			return fail(context, "unknown find kind")
+	}
+}
+
+function atom(context: string, input: unknown): AtomIr {
+	const raw = recordValue(context, input, ["source", "bindings"])
+	const source = tagged(`${context}.source`, raw.source)
+	let owned: AtomIr["source"]
+	if (source.kind === "edb") {
+		recordValue(context, source, ["kind", "relation"])
+		owned = { kind: source.kind, relation: ordinal(`${context}.source.relation`, source.relation, 0xffffffff) }
+	} else if (source.kind === "interior") {
+		recordValue(context, source, ["kind", "interior"])
+		owned = { kind: source.kind, interior: ordinal(`${context}.source.interior`, source.interior, 0xffffffff) }
+	} else return fail(context, "unknown atom source")
+	const seen = new Set<number>()
+	const bindings = array(`${context}.bindings`, raw.bindings, (path, pair): readonly [number, TermIr] => {
+		const cells = array(path, pair, (_, value) => value)
+		if (cells.length !== 2) return fail(path, "a binding has exactly two elements")
+		const field = ordinal(`${path}[0]`, cells[0])
+		if (seen.has(field)) return fail(path, "duplicate field binding")
+		seen.add(field)
+		return Object.freeze([field, term(`${path}[1]`, cells[1])])
+	})
+	return Object.freeze({ source: Object.freeze(owned), bindings })
+}
+
+function comparisonOp(context: string, input: unknown): CmpOpIr {
+	const raw = tagged(context, input)
+	if (raw.kind === "allen") {
+		recordValue(context, raw, ["kind", "mask"])
+		return Object.freeze({ kind: raw.kind, mask: ordinal(`${context}.mask`, raw.mask, 0x1fff) })
+	}
+	recordValue(context, raw, ["kind"])
+	const kind = raw.kind
+	if (
+		kind !== "eq" &&
+		kind !== "ne" &&
+		kind !== "lt" &&
+		kind !== "le" &&
+		kind !== "gt" &&
+		kind !== "ge" &&
+		kind !== "pointIn"
+	)
+		return fail(context, "unknown comparison operator")
+	return Object.freeze({ kind })
+}
+
+function condition(context: string, input: unknown, depth = 1): ConditionTreeIr {
+	if (depth > 64) return fail(context, "condition tree deeper than 64")
+	const raw = tagged(context, input)
+	if (raw.kind === "leaf") {
+		recordValue(context, raw, ["kind", "cmp"])
+		const cmp = recordValue(`${context}.cmp`, raw.cmp, ["op", "lhs", "rhs"])
+		return Object.freeze({
+			kind: raw.kind,
+			cmp: Object.freeze({
+				op: comparisonOp(`${context}.cmp.op`, cmp.op),
+				lhs: term(`${context}.cmp.lhs`, cmp.lhs),
+				rhs: term(`${context}.cmp.rhs`, cmp.rhs)
+			})
+		})
+	}
+	if (raw.kind !== "and" && raw.kind !== "or") return fail(context, "unknown condition kind")
+	recordValue(context, raw, ["kind", "children"])
+	return Object.freeze({
+		kind: raw.kind,
+		children: array(`${context}.children`, raw.children, (path, value) => condition(path, value, depth + 1))
+	})
+}
+
+function rule(context: string, input: unknown): RuleIr {
+	const raw = recordValue(context, input, ["finds", "atoms", "negated", "conditions"])
+	return Object.freeze({
+		finds: array(`${context}.finds`, raw.finds, find),
+		atoms: array(`${context}.atoms`, raw.atoms, atom),
+		negated: array(`${context}.negated`, raw.negated, atom),
+		conditions: array(`${context}.conditions`, raw.conditions, condition)
+	})
+}
+
+function align(context: string, head: readonly HeadTermIr[], rules: readonly RuleIr[]): void {
+	for (const [index, rule] of rules.entries()) {
+		if (rule.finds.length !== head.length) fail(`${context}.rules[${index}]`, "finds width does not match head width")
+		for (const [position, find] of rule.finds.entries()) {
+			const term = head[position]
+			const family = find.kind === "var" || find.kind === "compute" ? find.kind : "aggregate"
+			if (term?.kind !== family)
+				fail(`${context}.rules[${index}].finds[${position}]`, "find family does not match head")
+			if (term.kind === "aggregate") {
+				const op = find.kind === "aggregate" ? find.op.kind : find.kind
+				if (op !== term.op)
+					fail(`${context}.rules[${index}].finds[${position}]`, "aggregate operator does not match head")
+			}
+		}
+	}
+}
+
+/**
+ * Own and validate the complete wire grammar. The native compiler then
+ * checks schema membership, binding types, safety and recursion semantics;
+ * parsing alone does not assert that a query is admitted by a schema.
+ */
+function parseQueryIr(input: unknown): ParsedQuery {
+	const raw = tagged("query", input)
+	if (raw.kind !== "cq" && raw.kind !== "reach") return fail("query", "unknown query kind")
+	recordValue(
+		"query",
+		raw,
+		raw.kind === "cq" ? ["kind", "interiors", "head", "rules"] : ["kind", "interiors", "rec", "head", "rules"]
+	)
+	const rules = array("query.rules", raw.rules, rule)
+	if (rules.length === 0) return fail("parseQueryIr", "main rules are empty")
+	const head = array("query.head", raw.head, headTerm)
+	align("query", head, rules)
+	const interiors = array("query.interiors", raw.interiors, (path, input) => {
+		const raw = recordValue(path, input, ["head", "rules"])
+		const head = array(`${path}.head`, raw.head, headTerm)
+		const rules = array(`${path}.rules`, raw.rules, rule)
+		if (rules.length === 0) return fail(path, "interior rules are empty")
+		align(path, head, rules)
+		return Object.freeze({ head, rules })
+	})
+	let owned: QueryIr
+	if (raw.kind === "cq") owned = { kind: raw.kind, interiors, head, rules }
+	else {
+		const rawRec = recordValue("query.rec", raw.rec, ["head", "base", "rec"])
+		const headRec = array("query.rec.head", rawRec.head, headTerm)
+		const base = array("query.rec.base", rawRec.base, rule)
+		if (base.length === 0) return fail("parseQueryIr", "rec base is empty")
+		const rec = array("query.rec.rec", rawRec.rec, rule)
+		if (rec.length === 0) return fail("parseQueryIr", "rec step is empty")
+		align("rec base", headRec, base)
+		align("rec step", headRec, rec)
+		if (headRec.some((term) => term.kind !== "var") || [...base, ...rec].some((rule) => rule.negated.length !== 0))
+			return fail("query.rec", "recursion requires projection-only heads and no negation")
+		owned = { kind: raw.kind, interiors, head, rules, rec: Object.freeze({ head: headRec, base, rec }) }
 	}
+	return Object.freeze(owned) as ParsedQuery
 }
 
 export type { ParsedQuery }

package/src/query/run.ts

@@ -4,7 +4,8 @@ import type { FindColumn } from "#query/atom.ts"
 import { taggedCmpLiteral } from "#query/lower.ts"
 import type { ParamEntry } from "#query/scope.ts"
 import type { CellValue } from "#rows.ts"
-import { decodeCell, handleOf } from "#rows.ts"
+import { decodeCell, handleOf, setOwnField } from "#rows.ts"
+import { arrayValue, recordValue } from "#values.ts"
 
 function wireValue(entry: ParamEntry, context: string, value: unknown): TaggedValue {
 	if (entry.anchor === undefined) {
@@ -16,22 +17,24 @@ function wireValue(entry: ParamEntry, context: string, value: unknown): TaggedVa
 }
 
 function wireParams(entries: readonly ParamEntry[], supplied: Readonly<Record<string, unknown>>): QueryParam[] {
+	const input = recordValue(
+		"query parameters",
+		supplied,
+		entries.filter((entry) => entry.membership === undefined).map((entry) => entry.name)
+	)
 	return entries.map(function wireOne(entry): QueryParam {
 		if (entry.membership !== undefined) {
 			return entry.membership
 		}
-		const value = supplied[entry.name]
+		const value = input[entry.name]
 		if (value === undefined) {
 			throw new AuthoringError({ message: `execute params object is missing param ${entry.name}` })
 		}
 		if (entry.shape === "set") {
-			if (!Array.isArray(value)) {
-				throw new AuthoringError({ message: `param ${entry.name}: a set param binds a readonly array of values` })
-			}
 			return {
 				kind: "set",
-				values: value.map(function wireElement(element, index) {
-					return wireValue(entry, `param ${entry.name}[${index}]`, element)
+				values: arrayValue(`param ${entry.name}`, value, function wireElement(context, element) {
+					return wireValue(entry, context, element)
 				})
 			}
 		}
@@ -71,11 +74,14 @@ function decodeAnswers<Row>(finds: readonly FindColumn[], rows: readonly (readon
 				throw new SdkInvariantError({ message: `query answer cell ${ordinal} (${column.name}) is absent` })
 			}
 			if (column.slot !== undefined) {
-				decoded[column.name] = decodeCell(`query answer column ${column.name}`, column.slot.field, cell)
+				setOwnField(decoded, column.name, decodeCell(`query answer column ${column.name}`, column.slot.field, cell))
 				return
 			}
-			decoded[column.name] =
+			setOwnField(
+				decoded,
+				column.name,
 				column.closed === undefined ? cell : handleOf(`query answer column ${column.name}`, column.closed, cell)
+			)
 		})
 		Object.freeze(decoded)
 		if (!isAnswerRow<Row>(finds, decoded)) {

package/src/query/scope.ts

@@ -1,5 +1,5 @@
 import type { AnyClosed } from "#closed.ts"
-import { sealedFieldsOf } from "#closed.ts"
+import { memberDescriptor, sealedFieldsOf } from "#closed.ts"
 import { AuthoringError, SdkInvariantError } from "#errors.ts"
 import type { AnyField, Infer, SignatureOf } from "#fields.ts"
 import { rosterOf, signaturesAgree } from "#fields.ts"
@@ -7,7 +7,8 @@ import type { Same, SameLen } from "#judgment.ts"
 import type { ClassLookup, ClassRecordOf, SchemaClasses } from "#law.ts"
 import type { QueryParam } from "#native.ts"
 import type { FindColumn } from "#query/atom.ts"
-import type { AnyRelation, RelationFields } from "#relation.ts"
+import type { AnyRelation } from "#relation.ts"
+import type { FieldsOf } from "#selection.ts"
 
 const term: unique symbol = Symbol("bumbledb.query.term")
 
@@ -15,11 +16,7 @@ const inferred: unique symbol = Symbol("bumbledb.query.inferred")
 
 type MatchOwner = AnyRelation | AnyClosed
 
-type MatchFields<R extends MatchOwner> = R extends AnyClosed
-	? { readonly id: R["id"] } & R["columns"]
-	: R extends AnyRelation
-		? RelationFields<R>
-		: never
+type MatchFields<R extends MatchOwner> = FieldsOf<R>
 
 interface Var<F extends AnyField, RN extends string, K extends string> {
 	readonly [term]: "var"
@@ -157,7 +154,7 @@ function importFacadeOf(source: ImportedSource): ImportFacade {
 	importOrdinal += 1
 	const name = importLabels.get(source) ?? `\u0000import:${importOrdinal}`
 	const columns = new Map<string, FindColumn>()
-	const fields: Array<{ readonly name: string; readonly field: AnyField }> = []
+	const fields: Array<readonly [string, AnyField]> = []
 	for (const column of source.data.finds) {
 		if (column.slot === undefined) {
 			throw new AuthoringError({
@@ -165,18 +162,13 @@ function importFacadeOf(source: ImportedSource): ImportFacade {
 			})
 		}
 		columns.set(column.name, column)
-		fields.push(Object.freeze({ name: column.name, field: column.slot.field }))
+		fields.push([column.name, column.slot.field])
 	}
-	const data = Object.freeze({ name, fields: Object.freeze(fields) })
 	const owner = Object.freeze({
+		kind: "relation" as const,
 		name,
-		data,
-		where(): never {
-			throw new AuthoringError({
-				message: `imported query ${name}: an imported relation expression takes no selection — filter through where() in the consuming rule`
-			})
-		}
-	}) as unknown as MatchOwner & { readonly name: string }
+		fields: Object.freeze(Object.fromEntries(fields))
+	})
 	const facade: ImportFacade = Object.freeze({ owner, source, columns })
 	facadeBySource.set(source, facade)
 	facadeByOwner.set(owner, facade)
@@ -210,7 +202,7 @@ function v(owner: MatchOwner | ImportedSource): Readonly<Record<string, AnyVar>>
 		}
 		return Object.freeze(record)
 	}
-	const member = owner as MatchOwner
+	const member = memberDescriptor(owner as MatchOwner)
 	const record: Record<string, AnyVar> = {}
 	for (const declared of sealedFieldsOf(member)) {
 		const variable: AnyVar = Object.freeze({

package/src/relation.ts

@@ -1,160 +1,76 @@
 import { AuthoringError } from "#errors.ts"
-/**
- * `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`,
- * 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
- * records all spell the field's own name, checked by type
- * (`FaceFields`/`MatchShape`). `Fact<>` is the inferred row object type
- * at BARE structural value types: every field is present. Identities are
- * ordinary application-owned values (`Uuid`); the database mints none.
- */
-
-import { type AnyField, assertDeclarationOrderKey, assertDeclarationRecord, type Infer, literalOf } from "#fields.ts"
-import { type LiteralSetSpec, type LiteralSpec, renderLiteral } from "#spec.ts"
-
-function resolveEntry(context: string, field: AnyField, entry: unknown): LiteralSetSpec {
-	if (Array.isArray(entry)) {
-		if (entry.length < 2) {
-			throw new AuthoringError({
-				message:
-					entry.length === 0
-						? `${context}: an empty literal set selects nothing — write the selection you mean`
-						: `${context}: a one-element literal set is the bare literal respelled — write the literal (the canonical-utterance law: one meaning, one spelling)`
-			})
-		}
-		const seen = new Set<string>()
-		const literals: LiteralSpec[] = entry.map(function lowerSetLiteral(literal: unknown) {
-			const lowered = Object.freeze(literalOf(field, literal))
-			const rendered = renderLiteral(lowered)
-			if (seen.has(rendered)) {
-				throw new AuthoringError({
-					message: `${context}: the literal set spells ${rendered} twice — write it once (the canonical-utterance law: one meaning, one spelling)`
-				})
-			}
-			seen.add(rendered)
-			return lowered
-		})
-		return Object.freeze({ kind: "many", literals: Object.freeze(literals) })
-	}
-	return Object.freeze({ kind: "one", literal: Object.freeze(literalOf(field, entry)) })
-}
-
-function resolveSelection(
-	name: string,
-	ordered: readonly RelationField[],
-	entries: ReadonlyArray<readonly [string, unknown]>
-): readonly SelectionBinding[] {
-	const bindings: SelectionBinding[] = []
-	for (const [fieldName, entry] of entries) {
-		if (entry === undefined) {
-			continue
-		}
-		const declared = ordered.find(function byName(candidate) {
-			return candidate.name === fieldName
-		})
-		if (declared === undefined) {
-			throw new AuthoringError({ message: `relation ${name} has no field ${fieldName}` })
-		}
-		bindings.push(
-			Object.freeze({ field: fieldName, set: resolveEntry(`relation ${name}.${fieldName}`, declared.field, entry) })
-		)
-	}
-	if (bindings.length === 0) {
-		throw new AuthoringError({
-			message: `relation ${name}: an empty selection is the bare relation respelled — pass the relation itself (the canonical-utterance law: one meaning, one spelling)`
-		})
-	}
-	return Object.freeze(bindings)
+import {
+	type AnyField,
+	assertDeclarationOrderKey,
+	assertDeclarationRecord,
+	fieldDescriptor,
+	type Infer
+} from "#fields.ts"
+import { descriptorCache } from "#immutable.ts"
+import { recordValue } from "#values.ts"
+
+/** Ordinary relations are structural declarations. Field order defines native ordinals. */
+interface Relation<Name extends string = string, Fields extends FieldsShape = FieldsShape> {
+	readonly kind: "relation"
+	readonly name: Name
+	readonly fields: Fields
 }
-
-type FieldsShape = Record<string, AnyField>
+type FieldsShape = Readonly<Record<string, AnyField>>
+type AnyRelation = Relation
+type RelationFields<R extends AnyRelation> = R["fields"]
+type Fact<R extends AnyRelation> = { -readonly [K in keyof R["fields"]]: Infer<R["fields"][K]> }
 
 interface RelationField {
 	readonly name: string
 	readonly field: AnyField
 }
 
-interface RelationData {
-	readonly name: string
-	readonly fields: readonly RelationField[]
-}
-
-interface SelectionBinding {
-	readonly field: string
-	readonly set: LiteralSetSpec
-}
-
-type SelectionInput<Fields extends FieldsShape> = {
-	readonly [K in keyof Fields]?: Infer<Fields[K]> | readonly Infer<Fields[K]>[]
-}
-
-interface Selected<Name extends string, Fields extends FieldsShape> {
-	readonly relation: Relation<Name, Fields>
-	readonly selection: readonly SelectionBinding[]
-}
-
-interface Relation<Name extends string, Fields extends FieldsShape> {
-	readonly name: Name
-	readonly data: RelationData
-	where(selection: SelectionInput<Fields>): Selected<Name, Fields>
-}
-
-type AnyRelation = Relation<string, FieldsShape>
-
-interface AnySelected {
-	readonly relation: AnyRelation
-	readonly selection: readonly SelectionBinding[]
+/** Validate and own every field, without freezing or retaining caller records. */
+function ownFields<F extends FieldsShape>(context: string, input: F): F
+function ownFields(context: string, input: unknown): FieldsShape
+function ownFields(context: string, input: unknown): FieldsShape {
+	if (typeof input !== "object" || input === null)
+		throw new AuthoringError({ message: `${context}: expected a field record` })
+	assertDeclarationRecord(context, input)
+	return Object.freeze(
+		Object.fromEntries(
+			Object.entries(input).map(([name, field]) => {
+				assertDeclarationOrderKey(context, name)
+				return [name, fieldDescriptor(`${context}.${name}`, field)]
+			})
+		)
+	)
 }
 
-type RelationFields<R extends AnyRelation> = R extends Relation<string, infer F extends FieldsShape> ? F : never
-
-type Fact<R extends AnyRelation> = {
-	[K in keyof RelationFields<R>]: Infer<RelationFields<R>[K]>
+function relationDescriptor<R extends AnyRelation>(input: R): R
+function relationDescriptor(input: unknown): AnyRelation
+function relationDescriptor(input: unknown): AnyRelation {
+	return checkedRelation(input)
 }
 
-function relation<const Name extends string, Fields extends FieldsShape>(
+const checkedRelation = descriptorCache((input): AnyRelation => {
+	const raw = recordValue("relation", input, ["kind", "name", "fields"])
+	if (raw.kind !== "relation" || typeof raw.name !== "string")
+		throw new AuthoringError({ message: "relation: expected a relation declaration" })
+	assertDeclarationOrderKey("relation", raw.name)
+	return Object.freeze({
+		kind: "relation",
+		name: raw.name,
+		fields: ownFields(`relation ${raw.name} fields`, raw.fields)
+	})
+})
+
+function relation<const Name extends string, const Fields extends FieldsShape>(
 	name: Name,
 	fields: Fields
 ): Relation<Name, Fields> {
-	assertDeclarationOrderKey("relation", name)
-	assertDeclarationRecord(`relation ${name} fields`, fields)
-	const ordered: RelationField[] = []
-	for (const [fieldName, field] of Object.entries(fields)) {
-		assertDeclarationOrderKey(`relation ${name} field`, fieldName)
-		ordered.push(Object.freeze({ name: fieldName, field }))
-	}
-	const data: RelationData = Object.freeze({ name, fields: Object.freeze(ordered) })
-	const holder: { value: Relation<Name, Fields> | undefined } = { value: undefined }
-	function where(selection: SelectionInput<Fields>): Selected<Name, Fields> {
-		const owner = holder.value
-		if (owner === undefined) {
-			throw new AuthoringError({ message: `relation ${name}: self-reference read before construction completed` })
-		}
-		return Object.freeze({
-			relation: owner,
-			selection: resolveSelection(name, ordered, Object.entries(selection))
-		})
-	}
-	const value: Relation<Name, Fields> = Object.freeze({ name, data, where })
-	holder.value = value
-	return value
+	return relationDescriptor({ kind: "relation", name, fields })
 }
 
-export type {
-	AnyRelation,
-	AnySelected,
-	Fact,
-	FieldsShape,
-	Relation,
-	RelationData,
-	RelationField,
-	RelationFields,
-	Selected,
-	SelectionBinding,
-	SelectionInput
+/** Ordered field view derived from the one declaration record. */
+function relationFields(relation: AnyRelation): readonly RelationField[] {
+	return Object.entries(relation.fields).map(([name, field]) => ({ name, field }))
 }
-export { relation, resolveSelection }
+
+export type { AnyRelation, Fact, FieldsShape, Relation, RelationField, RelationFields }
+export { ownFields, relation, relationDescriptor, relationFields }