@bjornpagen/bumbledb 0.1.0

package/src/query/select.ts

@@ -0,0 +1,140 @@
+/**
+ * Select entries and aggregates (PRD-08) — the head vocabulary, mirroring
+ * the IR's aggregate roster exactly (`bumbledb/crates/bumbledb/src/ir.rs`
+ * `AggOp`/`FindTerm`; `docs/architecture/20-query-ir.md` § aggregation):
+ * `count` (nullary), `countDistinct`, `sum`/`min`/`max` (over a u64/i64
+ * variable or the measure), `argmax`/`argmin` (arg-restriction: carried
+ * value + orderable key; a tie yields every attaining row), and `pack`
+ * (the coalescing fold — RELATION-SHAPED: one answer row per (group,
+ * maximal segment), the result position interval-typed). Grouping is
+ * implicit: the non-aggregate select entries are the group key; over empty
+ * input an all-aggregate select yields the EMPTY SET, never a zero row.
+ */
+
+import type { IntervalValue } from "#brand.ts"
+import { phantom } from "#brand.ts"
+import type { Duration } from "#query/atom.ts"
+import type { AnyVar, Flatten, Var } from "#query/scope.ts"
+import { term } from "#query/scope.ts"
+
+/** The three folds the measure admits (and the plain-variable folds). */
+type FoldOp = "sum" | "min" | "max"
+
+/** One aggregate's runtime description. */
+type AggregateData =
+	| { readonly op: "count" }
+	| { readonly op: "countDistinct"; readonly over: AnyVar }
+	| { readonly op: "fold"; readonly fold: FoldOp; readonly over: AnyVar | Duration }
+	| {
+			readonly op: "arg"
+			readonly direction: "argMax" | "argMin"
+			readonly key: AnyVar
+			readonly over: AnyVar
+	  }
+	| { readonly op: "pack"; readonly over: AnyVar }
+
+/**
+ * One aggregate select value; the phantom carries the answer column's
+ * host type (`count`/`countDistinct` → `bigint` whatever they counted;
+ * folds carry their input's type; the Arg forms the carried payload's
+ * type; `pack` its interval type).
+ */
+interface Aggregate<R> {
+	readonly aggregate: AggregateData
+	readonly [phantom]?: R
+}
+
+/** What a select record's values may be: a projection, a measure, or an aggregate. */
+type SelectEntryInput = AnyVar | Duration | Aggregate<unknown>
+
+/** The select record: answer column name to entry, written order = column order. */
+type SelectShape = Readonly<Record<string, SelectEntryInput>>
+
+/** One select entry's answer type. */
+type SelectValue<T> = T extends { readonly aggregate: AggregateData; readonly [phantom]?: infer R }
+	? Exclude<R, undefined>
+	: T extends { readonly measure: AnyVar }
+		? bigint
+		: T extends { readonly [term]: "var"; readonly [phantom]?: infer V }
+			? Exclude<V, undefined>
+			: never
+
+/** The inferred answer-row object type of a select record. */
+type RowOf<Sel extends SelectShape> = Flatten<{ [K in keyof Sel]: SelectValue<Sel[K]> }>
+
+/** Nullary count: |the group's set of distinct full bindings|, `bigint`. */
+function count(): Aggregate<bigint> {
+	return Object.freeze({ aggregate: Object.freeze({ op: "count" as const }) })
+}
+
+/** |the distinct values of `over` across the group|, `bigint`; legal over every type. */
+function countDistinct<V>(over: Var<V>): Aggregate<bigint> {
+	return Object.freeze({ aggregate: Object.freeze({ op: "countDistinct" as const, over }) })
+}
+
+/**
+ * Exact checked sum over a u64/i64 variable (wide accumulator, one
+ * finalize range check — overflow is the engine's typed runtime error,
+ * never a wrap), or over the measure (`sum(duration(v))`).
+ */
+function sum<V extends bigint>(over: Var<V>): Aggregate<V>
+function sum(over: Duration): Aggregate<bigint>
+function sum(over: Var<bigint> | Duration): Aggregate<bigint> {
+	return Object.freeze({
+		aggregate: Object.freeze({ op: "fold" as const, fold: "sum" as const, over })
+	})
+}
+
+/** Minimum over a u64/i64 variable or the measure (orderable types only). */
+function min<V extends bigint>(over: Var<V>): Aggregate<V>
+function min(over: Duration): Aggregate<bigint>
+function min(over: Var<bigint> | Duration): Aggregate<bigint> {
+	return Object.freeze({
+		aggregate: Object.freeze({ op: "fold" as const, fold: "min" as const, over })
+	})
+}
+
+/** Maximum over a u64/i64 variable or the measure (orderable types only). */
+function max<V extends bigint>(over: Var<V>): Aggregate<V>
+function max(over: Duration): Aggregate<bigint>
+function max(over: Var<bigint> | Duration): Aggregate<bigint> {
+	return Object.freeze({
+		aggregate: Object.freeze({ op: "fold" as const, fold: "max" as const, over })
+	})
+}
+
+/**
+ * Arg-restriction toward the maximum of `key` (`ir::AggOp::ArgMax`): the
+ * group's binding set is restricted to the bindings attaining the extreme
+ * of the orderable key, and `value` is the carried payload — a tie yields
+ * every attaining row. All Arg entries of one query share one key and one
+ * direction; Arg and fold aggregates never mix (both the engine's typed
+ * rules).
+ */
+function argmax<K extends bigint, V>(key: Var<K>, value: Var<V>): Aggregate<V> {
+	return Object.freeze({
+		aggregate: Object.freeze({ op: "arg" as const, direction: "argMax" as const, key, over: value })
+	})
+}
+
+/** Arg-restriction toward the minimum of `key`; rules as {@link argmax}. */
+function argmin<K extends bigint, V>(key: Var<K>, value: Var<V>): Aggregate<V> {
+	return Object.freeze({
+		aggregate: Object.freeze({ op: "arg" as const, direction: "argMin" as const, key, over: value })
+	})
+}
+
+/**
+ * The coalescing fold (Snodgrass coalesce, `ir::AggOp::Pack`): per group,
+ * the maximal disjoint half-open segments of the union of the group's
+ * interval point sets — RELATION-SHAPED, one answer row per (group,
+ * maximal segment), the result position carrying one interval of the
+ * input's element type. At most one `pack` per select, never beside a
+ * fold or an Arg entry (the engine's typed rules).
+ */
+function pack<IV extends IntervalValue>(over: Var<IV>): Aggregate<IV> {
+	return Object.freeze({ aggregate: Object.freeze({ op: "pack" as const, over }) })
+}
+
+export type { Aggregate, AggregateData, FoldOp, RowOf, SelectEntryInput, SelectShape, SelectValue }
+export { argmax, argmin, count, countDistinct, max, min, pack, sum }

package/src/relation.ts

@@ -0,0 +1,252 @@
+/**
+ * `relation()` — the ordinary-relation half of the theory's signature. A
+ * relation value is a frozen plain object carrying its name, its ordered
+ * field metadata (declaration order = ordinal ids, the macro's law), typed
+ * field references (`R.fields.holder`), and — since selections are the
+ * relation's own vocabulary — `where()`, which resolves a selection into
+ * lowered bindings eagerly (handles re-verified against their roster at
+ * construction). `Fact<>`/`InsertFact<>` are the inferred row object
+ * types: fresh fields are optional on insert input (omit-to-mint) and
+ * present on read (resupply-to-preserve-identity), typed exactly.
+ */
+
+import * as errors from "@superbuilders/errors"
+import { phantom } from "#brand.ts"
+import type { OneOf } from "#face.ts"
+import { type AnyField, assertDeclarationOrderKey, type FieldData, type FieldValue, literalOf } from "#fields.ts"
+import type { LiteralSetSpec, LiteralSpec } from "#spec.ts"
+
+/** Flattens an intersection into one displayed object type (hover legibility). */
+type Flatten<T> = { [K in keyof T]: T[K] }
+
+/**
+ * The one nominal step of `relation()`: the reference record is built by
+ * iterating the declared fields, and this guard verifies the checkable
+ * facts — one reference per declared field, each carrying its own name —
+ * before the record is admitted as the typed {@link FieldRefs}. The
+ * phantom halves (brands) are carried by construction; this is the
+ * module's single trusted seam, the macro-emission analog.
+ */
+function refsComplete<RName extends string, Fields extends FieldsShape>(
+	refs: Record<string, unknown>,
+	fields: Fields
+): refs is FieldRefs<RName, Fields> {
+	return Object.keys(fields).every(function hasRef(fieldName) {
+		const ref = refs[fieldName]
+		return typeof ref === "object" && ref !== null && "field" in ref && ref.field === fieldName
+	})
+}
+
+/**
+ * Resolves one selection entry to its lowered literal set: an `oneOf`
+ * value (detected by its `literals` tuple — no field value is ever an
+ * object carrying `literals`) becomes a disjunctive set (≥ 2 by the
+ * `oneOf` signature — the one-element set is unwritable); anything else is
+ * the bare literal.
+ */
+function resolveEntry(field: FieldData, entry: unknown): LiteralSetSpec {
+	if (typeof entry === "object" && entry !== null && "literals" in entry && Array.isArray(entry.literals)) {
+		const literals: LiteralSpec[] = entry.literals.map(function lowerSetLiteral(literal: unknown) {
+			return Object.freeze(literalOf(field, literal))
+		})
+		return Object.freeze({ kind: "many", literals: Object.freeze(literals) })
+	}
+	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).
+ */
+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 errors.new(`relation ${name} has no field ${fieldName}`)
+		}
+		bindings.push(Object.freeze({ field: fieldName, set: resolveEntry(declared.field, entry) }))
+	}
+	if (bindings.length === 0) {
+		throw errors.new(
+			`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)
+}
+
+/** The field block of a relation: field name to field constructor value. */
+type FieldsShape = Record<string, AnyField>
+
+/**
+ * A typed field reference (`Account.fields.holder`) — the value statements,
+ * selections, and queries address a field through; its hover shows the
+ * field's brand in the phantom position.
+ */
+interface FieldRef<Rel extends string, Name extends string, V> {
+	readonly relation: Rel
+	readonly field: Name
+	readonly [phantom]?: V
+}
+
+/** The typed field-reference record of a relation. */
+type FieldRefs<RName extends string, Fields extends FieldsShape> = {
+	readonly [K in keyof Fields & string]: FieldRef<RName, K, FieldValue<Fields[K]>>
+}
+
+/** One declared field: name plus its runtime description, in declaration order. */
+interface RelationField {
+	readonly name: string
+	readonly field: FieldData
+}
+
+/** 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 branded literal of that field's
+ * type (a closed handle constant IS such a literal — it carries the closed
+ * relation's brand, so it is legal exactly where the field is that closed
+ * relation's id type), an `oneOf(a, b, ...)` literal set, or a `span(start,
+ * end)` interval literal. Equality-only by construction: no operator
+ * parameter exists anywhere.
+ */
+type SelectionInput<Fields extends FieldsShape> = {
+	readonly [K in keyof Fields]?: FieldValue<Fields[K]> | OneOf<FieldValue<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
+	readonly fields: FieldRefs<Name, Fields>
+	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> ? F : never
+
+/**
+ * The inferred row object type of a relation as READ: every field present,
+ * branded. 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>]: FieldValue<RelationFields<R>[K]>
+}
+
+/** The field names of `R` that carry the fresh mint mark. */
+type FreshKeys<R extends AnyRelation> = {
+	[K in keyof RelationFields<R>]: RelationFields<R>[K] extends {
+		readonly data: { readonly minted: true }
+	}
+		? K
+		: never
+}[keyof RelationFields<R>]
+
+/**
+ * The inferred row object type of a relation as INSERTED: fresh fields
+ * optional — omitted, the engine mints; supplied, identity is preserved
+ * (the ETL resupply idiom).
+ */
+type InsertFact<R extends AnyRelation> = Flatten<Omit<Fact<R>, FreshKeys<R>> & Partial<Pick<Fact<R>, FreshKeys<R>>>>
+
+/**
+ * Declares one relation: `relation("Account", { id: AccountId.fresh,
+ * holder: HolderId, ... })` — every field references a declared newtype
+ * (`const AccountId = u64.newtype("AccountId")`) or a bare constructor.
+ * Field declaration order is ordinal-id order (macro parity); the returned
+ * value is frozen and side-effect free.
+ */
+function relation<const Name extends string, Fields extends FieldsShape>(
+	name: Name,
+	fields: Fields
+): Relation<Name, Fields> {
+	const ordered: RelationField[] = []
+	for (const [fieldName, field] of Object.entries(fields)) {
+		assertDeclarationOrderKey(`relation ${name} field`, fieldName)
+		ordered.push(Object.freeze({ name: fieldName, field: field.data }))
+	}
+	const data: RelationData = Object.freeze({ name, fields: Object.freeze(ordered) })
+	const refs: Record<string, unknown> = {}
+	for (const declared of ordered) {
+		refs[declared.name] = Object.freeze({ relation: name, field: declared.name })
+	}
+	Object.freeze(refs)
+	if (!refsComplete<Name, Fields>(refs, fields)) {
+		throw errors.new(`relation ${name}: field-reference construction incomplete`)
+	}
+	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 errors.new(`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, fields: refs, where })
+	holder.value = value
+	return value
+}
+
+export type {
+	AnyRelation,
+	AnySelected,
+	Fact,
+	FieldRef,
+	FieldRefs,
+	FieldsShape,
+	FreshKeys,
+	InsertFact,
+	Relation,
+	RelationData,
+	RelationField,
+	RelationFields,
+	Selected,
+	SelectionBinding,
+	SelectionInput
+}
+export { relation }

package/src/schema.ts

@@ -0,0 +1,297 @@
+/**
+ * `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.
+ */
+
+import * as errors from "@superbuilders/errors"
+import type { AnyClosed } from "#closed.ts"
+import type { FaceData } from "#face.ts"
+import { assertDeclarationOrderKey, type FieldData } from "#fields.ts"
+import type { AnyRelation } from "#relation.ts"
+import type { LiteralSetSpec, LiteralSpec } from "#spec.ts"
+import { 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> {
+	const implied = new Set<string>()
+	for (const [recordKey, member] of Object.entries(relations)) {
+		assertDeclarationOrderKey(`schema ${name} relation`, recordKey)
+		if (member.name !== recordKey) {
+			throw errors.new(
+				`schema ${name}: record key ${recordKey} holds relation ${member.name} — the key must equal the relation's declared name`
+			)
+		}
+		if ("handles" in member.data) {
+			implied.add(`${member.name}(id) -> ${member.name}`)
+			continue
+		}
+		for (const declared of member.data.fields) {
+			if (declared.field.minted) {
+				implied.add(`${member.name}(${declared.name}) -> ${member.name}`)
+			}
+		}
+	}
+	return implied
+}
+
+/** The relation values a statement addresses, for membership checking. */
+function statementOwners(statement: Statement): readonly SchemaRelation[] {
+	const data = statement.data
+	if (data.kind === "key") {
+		return [data.owner]
+	}
+	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]
+		if (member === undefined) {
+			throw errors.new(`schema ${name}: relation ${owner.name} is not declared in this schema — ${rendered}`)
+		}
+		if (member !== owner) {
+			throw errors.new(
+				`schema ${name}: statement references a different relation value named ${owner.name} than the one this schema declares — ${rendered}`
+			)
+		}
+	}
+}
+
+/** Finds a face's field description by name, across both relation kinds. */
+function faceField(face: FaceData, fieldName: string): FieldData | undefined {
+	const data = face.owner.data
+	if ("handles" in data) {
+		const column = data.columns.find(function byName(candidate) {
+			return candidate.name === fieldName
+		})
+		return column?.field
+	}
+	const declared = data.fields.find(function byName(candidate) {
+		return candidate.name === fieldName
+	})
+	return declared?.field
+}
+
+/** Flattens one binding's literal set into its literals. */
+function bindingLiterals(set: LiteralSetSpec): readonly LiteralSpec[] {
+	if (set.kind === "one") {
+		return [set.literal]
+	}
+	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,
+	binding: { readonly field: string; readonly set: LiteralSetSpec },
+	rendered: string
+): void {
+	const field = faceField(face, binding.field)
+	for (const literal of bindingLiterals(binding.set)) {
+		if (literal.kind !== "handle") {
+			continue
+		}
+		if (field?.closed === undefined) {
+			throw errors.new(
+				`schema ${name}: ${face.owner.name}.${binding.field} is not a closed-relation reference — the handle literal ${literal.handle} is legal only on a field whose newtype is a closed relation's handle newtype — ${rendered}`
+			)
+		}
+		if (!field.closed.handles.includes(literal.handle)) {
+			throw errors.new(
+				`schema ${name}: closed relation ${field.closed.name} has no handle ${literal.handle} — ${rendered}`
+			)
+		}
+	}
+}
+
+/** 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") {
+		return
+	}
+	for (const face of [data.source, data.target]) {
+		for (const binding of face.selection) {
+			verifyBindingHandles(name, face, binding, rendered)
+		}
+	}
+}
+
+/**
+ * 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
+		if (data.kind !== "containment") {
+			continue
+		}
+		const pairs: Array<readonly [FaceData, FaceData]> = [[data.source, data.target]]
+		if (data.bidirectional) {
+			pairs.push([data.target, data.source])
+		}
+		for (const [source, target] of pairs) {
+			if (
+				source.owner.name === owner &&
+				source.projection.length === 1 &&
+				source.projection[0] === field &&
+				target.projection.length === 1 &&
+				target.projection[0] === "id" &&
+				"handles" in target.owner.data
+			) {
+				return target.owner.name
+			}
+		}
+	}
+	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
+		if (data.kind === "key") {
+			continue
+		}
+		const rendered = renderStatement(statement)
+		for (const face of [data.source, data.target]) {
+			for (const binding of face.selection) {
+				verifyClosedReferenceBinding(name, statements, face, binding, rendered)
+			}
+		}
+	}
+}
+
+/** One binding's closed-reference resolution check (the {@link verifyClosedReferences} leaf). */
+function verifyClosedReferenceBinding(
+	name: string,
+	statements: readonly Statement[],
+	face: FaceData,
+	binding: { readonly field: string; readonly set: LiteralSetSpec },
+	rendered: string
+): void {
+	const spellsHandle = bindingLiterals(binding.set).some(function isHandle(literal) {
+		return literal.kind === "handle"
+	})
+	if (!spellsHandle) {
+		return
+	}
+	const roster = faceField(face, binding.field)?.closed
+	if (roster === undefined) {
+		return
+	}
+	if ("handles" in face.owner.data && binding.field === "id") {
+		return
+	}
+	const resolved = closedTargetOf(statements, face.owner.name, binding.field)
+	if (resolved !== roster.name) {
+		throw errors.new(
+			`schema ${name}: ${face.owner.name}.${binding.field} spells a ${roster.name} handle, but no declared containment resolves the closed reference — a closed reference is the plain u64 column plus its declared containment; declare contained(on(${face.owner.name}, "${binding.field}"), on(${roster.name}, "id")) — ${rendered}`
+		)
+	}
+}
+
+/** One member of a schema's relation record. */
+type SchemaRelation = AnyRelation | AnyClosed
+
+/** The relation record a schema is generic over — what `Db` and queries key on. */
+type SchemaRelations = Record<string, SchemaRelation>
+
+/** A theory value: named relations plus the DECLARED dependency statements. */
+interface Schema<Rels extends SchemaRelations> {
+	readonly name: string
+	readonly relations: Rels
+	readonly statements: readonly Statement[]
+}
+
+/** Any schema value, whatever its relation record. */
+type AnySchema = Schema<SchemaRelations>
+
+/**
+ * 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.
+ */
+function schema<const Rels extends SchemaRelations>(
+	name: string,
+	relations: Rels,
+	statements: readonly Statement[]
+): Schema<Rels> {
+	const implied = collectImplied(name, relations)
+	const seen = new Set<string>()
+	for (const statement of statements) {
+		const rendered = renderStatement(statement)
+		verifyMembership(name, relations, statement, rendered)
+		if (implied.has(rendered)) {
+			throw errors.new(
+				`schema ${name}: ${rendered} is redundant here (the fresh mark or closedness already implies it) — and rejected as a duplicate`
+			)
+		}
+		if (seen.has(rendered)) {
+			throw errors.new(`schema ${name}: duplicate statement — ${rendered}`)
+		}
+		seen.add(rendered)
+		verifyHandles(name, statement, rendered)
+	}
+	verifyClosedReferences(name, statements)
+	return Object.freeze({ name, relations, statements: Object.freeze([...statements]) })
+}
+
+export type { AnySchema, Schema, SchemaRelation, SchemaRelations }
+export { schema }