@bjornpagen/bumbledb 0.2.0 → 0.4.0

package/src/relation.ts

@@ -12,9 +12,8 @@
  */
 
 import * as errors from "@superbuilders/errors"
-import type { OneOf } from "#face.ts"
 import { type AnyField, assertDeclarationOrderKey, type Infer, literalOf } from "#fields.ts"
-import type { LiteralSetSpec, LiteralSpec } from "#spec.ts"
+import { type LiteralSetSpec, type LiteralSpec, renderLiteral } from "#spec.ts"
 
 /** Flattens an intersection into one displayed object type (hover legibility). */
 type Flatten<T> = { [K in keyof T]: T[K] }
@@ -37,16 +36,41 @@ function refsComplete<RName extends string, Fields extends FieldsShape>(
 }
 
 /**
- * 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.
+ * 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(field: AnyField, 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))
+function resolveEntry(context: string, field: AnyField, entry: unknown): LiteralSetSpec {
+	if (Array.isArray(entry)) {
+		if (entry.length < 2) {
+			throw errors.new(
+				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 errors.new(
+					`${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) })
 	}
@@ -57,7 +81,10 @@ function resolveEntry(field: AnyField, entry: unknown): LiteralSetSpec {
  * 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).
+ * 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,
@@ -75,7 +102,9 @@ function resolveSelection(
 		if (declared === undefined) {
 			throw errors.new(`relation ${name} has no field ${fieldName}`)
 		}
-		bindings.push(Object.freeze({ field: fieldName, set: resolveEntry(declared.field, entry) }))
+		bindings.push(
+			Object.freeze({ field: fieldName, set: resolveEntry(`relation ${name}.${fieldName}`, declared.field, entry) })
+		)
 	}
 	if (bindings.length === 0) {
 		throw errors.new(
@@ -91,8 +120,8 @@ type FieldsShape = Record<string, AnyField>
 /**
  * A typed field reference (`Account.fields.holder`) — the value statements,
  * selections, and queries address a field through. Purely positional
- * (relation name + field name); the field's descriptor (domain label
- * included) is read off the relation's schema type structurally.
+ * (relation name + field name); the field's descriptor is read off the
+ * relation's schema type structurally.
  */
 interface FieldRef<Rel extends string, Name extends string> {
 	readonly relation: Rel
@@ -128,13 +157,15 @@ interface SelectionBinding {
 
 /**
  * The `where()` argument: per field, a bare structural literal of that
- * field's value type (a closed handle constant IS such a literal — a
- * bigint verified against the roster at construction), an `oneOf(a, b,
- * ...)` literal set, or a `span(start, end)` interval literal.
- * Equality-only by construction: no operator parameter exists anywhere.
+ * 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]> | OneOf<Infer<Fields[K]>>
+	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. */
@@ -186,11 +217,14 @@ type FreshKeys<R extends AnyRelation> = {
 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
- * domain-labeled descriptor (`const AccountId = u64.as("AccountId")`) or a
- * bare constructor. Field declaration order is ordinal-id order (macro
- * parity); the returned value is frozen and side-effect free.
+ * 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,
@@ -243,4 +277,4 @@ export type {
 	SelectionBinding,
 	SelectionInput
 }
-export { relation }
+export { relation, resolveSelection }

package/src/schema.ts

@@ -13,6 +13,7 @@ import * as errors from "@superbuilders/errors"
 import type { AnyClosed } from "#closed.ts"
 import type { FaceData } from "#face.ts"
 import { type AnyField, assertDeclarationOrderKey, type ClosedRoster } from "#fields.ts"
+import { type ClassesOf, classesComplete, computeClasses, type LawfulStatements, type SchemaClasses } from "#law.ts"
 import type { AnyRelation } from "#relation.ts"
 import type { LiteralSetSpec, LiteralSpec } from "#spec.ts"
 import { renderStatement, type Statement } from "#statements.ts"
@@ -128,7 +129,7 @@ function verifyBindingHandles(
 		}
 		if (roster === 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 domain is a closed relation's handle domain — ${rendered}`
+				`schema ${name}: ${face.owner.name}.${binding.field} is not a closed-relation reference — the handle literal ${literal.handle} is legal only on a field carrying a closed relation's roster — ${rendered}`
 			)
 		}
 		if (!roster.handles.includes(literal.handle)) {
@@ -247,16 +248,43 @@ 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> {
+/**
+ * A theory value: named relations, the DECLARED dependency statements, and
+ * the LAW-COMPUTED class map (`classes` — relation → field → class name,
+ * `undefined` = bare). The class map is THE domain authority: `schema()`
+ * computes it FROM the statement list at both tiers (the type through
+ * {@link ClassesOf}, the value through the union-find twin), queries
+ * compare class names off it, and the wire lowering emits it as the spec
+ * `newtype` labels. Nothing is ever synthesized: `statements` is exactly
+ * the declared list, in written order.
+ */
+interface Schema<Rels extends SchemaRelations, Classes extends SchemaClasses = SchemaClasses> {
 	readonly name: string
 	readonly relations: Rels
 	readonly statements: readonly Statement[]
+	readonly classes: Classes
 }
 
 /** Any schema value, whatever its relation record. */
 type AnySchema = Schema<SchemaRelations>
 
+/**
+ * Forces the class map to EVALUATE at the `schema()` boundary: a two-level
+ * mapped copy, type-identical to `C` — but instantiation resolves it to
+ * the finished relation → field → class record, so hovering a schema value
+ * (or anything carrying its `Classes` parameter — queries, `Db`) shows the
+ * computed record instead of the unevaluated `ClassesOf<...>` application
+ * dragging the whole statement-tuple type along. The conditional wrapper
+ * is the display mechanism, not a judgment: resolving it drops the alias
+ * reference, so tsc renders the finished record (measured against tsc's
+ * own type rendering; a bare mapped alias still displays by name).
+ * Display-only by construction; `classesComplete` guards the same type at
+ * the value tier.
+ */
+type EvaluatedClasses<C extends SchemaClasses> = C extends SchemaClasses
+	? { readonly [N in keyof C]: { readonly [F in keyof C[N]]: C[N][F] } }
+	: never
+
 /**
  * Assembles a theory:
  * `schema("Ledger", { Kind, Account, Holder }, [ ...statements ])`.
@@ -277,12 +305,21 @@ type AnySchema = Schema<SchemaRelations>
  * list: the engine materializes them itself, in its own pinned order
  * (`SchemaDescriptor::materialized_statements`), and restating them would
  * double them.
+ *
+ * THE LAW-TYPING happens here too (rulings 2/3 — the laws type the
+ * columns): the statement list induces the equivalence classes over field
+ * slots, at the TYPE level ({@link ClassesOf} — spell the statement list
+ * inline so the tuple type stays precise) and at runtime (the union-find
+ * twin), and the one-generator-per-class wall holds at both tiers — the
+ * {@link LawfulStatements} verdict lands the compile error on the
+ * statements argument; `computeClasses` throws the same content naming the
+ * exact statement.
  */
-function schema<const Rels extends SchemaRelations>(
+function schema<const Rels extends SchemaRelations, const Stmts extends readonly Statement[]>(
 	name: string,
 	relations: Rels,
-	statements: readonly Statement[]
-): Schema<Rels> {
+	statements: Stmts & LawfulStatements<Rels, Stmts>
+): Schema<Rels, EvaluatedClasses<ClassesOf<Rels, Stmts>>> {
 	const implied = collectImplied(name, relations)
 	const seen = new Set<string>()
 	for (const statement of statements) {
@@ -300,7 +337,11 @@ function schema<const Rels extends SchemaRelations>(
 		verifyHandles(name, statement, rendered)
 	}
 	verifyClosedReferences(name, statements)
-	return Object.freeze({ name, relations, statements: Object.freeze([...statements]) })
+	const classes = computeClasses(name, relations, statements)
+	if (!classesComplete<EvaluatedClasses<ClassesOf<Rels, Stmts>>>(classes, relations)) {
+		throw errors.new(`schema ${name}: class-map construction incomplete`)
+	}
+	return Object.freeze({ name, relations, statements: Object.freeze([...statements]), classes })
 }
 
 export type { AnySchema, Schema, SchemaRelation, SchemaRelations }

package/src/spec.ts

@@ -62,8 +62,9 @@ type LiteralSpec =
 
 /**
  * One σ binding's right side: a single literal or a literal set (read
- * disjunctively). The SDK's selection constructors make the degenerate sets
- * unwritable (`oneOf` demands two leading literals), so a lowered `many`
+ * disjunctively). The SDK's selection resolver refuses the degenerate sets
+ * (a membership array needs two members — the empty set selects nothing,
+ * the one-element set is the bare literal respelled), so a lowered `many`
  * always carries ≥ 2 literals.
  */
 type LiteralSetSpec =
@@ -95,10 +96,10 @@ type WindowSpec =
 	| { readonly kind: "floor"; readonly lo: bigint }
 
 /**
- * One field: name, structural type, host newtype name — the descriptor's
- * DOMAIN label (the macro's `as NewType`; the SDK's `.as("Domain")`),
- * carried for handle resolution only, dropped by the engine at descriptor
- * lowering and never fingerprinted — and the `fresh` mint mark.
+ * One field: name, structural type, host newtype name — the field's
+ * DOMAIN (the macro's declared `as NewType`; the SDK's law-computed class
+ * name), carried for handle resolution only, dropped by the engine at
+ * descriptor lowering and never fingerprinted — and the `fresh` mint mark.
  */
 interface FieldSpec {
 	readonly name: string
@@ -121,8 +122,9 @@ interface RowSpec {
  * kind); a closed relation's `fields` are its declared intrinsic columns
  * only — the synthetic (`id`, u64) handle field is materialized by the
  * engine's schema validation. `newtype` is the handle newtype of a closed
- * relation (the SDK emits its handle DOMAIN, `` `${name}Id` `` — the same
- * label every referencing field carries), undefined on an ordinary one.
+ * relation (the SDK emits the id's law-computed generator class,
+ * `` `${name}.id` `` — the same label every referencing field carries by
+ * law), undefined on an ordinary one.
  */
 interface RelationSpec {
 	readonly name: string

package/src/statements.ts

@@ -7,12 +7,22 @@
  *
  * Every field reference is checked against the relation it names in the
  * TYPE — existence through {@link FaceFields} (`on(R, "nope")` does not
- * compile) and DOMAIN compatibility through {@link SameDomains}: the two
- * faces' projected domain labels are read structurally off the schema type
- * (S1's `F["domain"]`) and constrained positionwise equal, so a
- * cross-domain pair is a compile error by string-literal comparison of
- * descriptor shapes — never by a value brand (the structural design's
- * ratified check). What is only a SEMANTIC property — the target side of a
+ * compile) and STRUCTURAL compatibility through {@link SameShapes}: the two
+ * faces' projected kind/width/element/roster quadruples are read off the
+ * schema type (the minimal kernel — descriptors are pure structure) and
+ * constrained positionwise equal, so a u64 face against a str face, a
+ * bytes width mismatch, an interval element mismatch, or a bare column
+ * against a closed reference is a compile error. The ROSTER slot carries a
+ * construction-time runtime twin here ({@link assertRosterAgreement} —
+ * roster IDENTITY, positionwise: a closed vocabulary's referencing column
+ * is spelled with the vocabulary's own id descriptor, the ONE spelling, so
+ * a plain u64 column can never alias a vocabulary through a declared law
+ * and the SDK's descriptor-keyed closed judgments stay sound). Domains are
+ * NOT compared here — there is no domain to compare at construction: the
+ * statements themselves are what define the equivalence classes, and the
+ * domain wall lives where they aggregate — `schema()` (the
+ * one-generator-per-class law) and query joins (class names off the schema
+ * type). What is only a SEMANTIC property — the target side of a
  * containment resolving a declared key of its relation — is DELIBERATELY
  * not (and cannot be) stated here: whether `B(y)` is a key of `B` depends
  * on which `key()` statements the surrounding `schema()` collects, a set no
@@ -23,7 +33,8 @@
 
 import * as errors from "@superbuilders/errors"
 import type { Count } from "#count.ts"
-import { type AnyFace, type FaceData, renderFace, type SameArity, type SameDomains } from "#face.ts"
+import { type AnyFace, type FaceData, renderFace, type SameArity, type SameShapes } from "#face.ts"
+import type { AnyField, ClosedRoster } from "#fields.ts"
 import type { AnyRelation, RelationFields } from "#relation.ts"
 import { renderWindow, type WindowSpec } from "#spec.ts"
 
@@ -34,40 +45,132 @@ interface KeyData<R extends AnyRelation, Projection extends readonly string[]> {
 	readonly projection: Projection
 }
 
+/**
+ * A containment statement's runtime description — the two faces carried at
+ * their EXACT types (owner names and projection tuples are honest runtime
+ * properties, and they are the type-level carrier `schema()`'s law-typing
+ * pairs slots through). The defaults are the wide shape renderers and the
+ * wire lowering consume.
+ */
+interface ContainmentData<Src extends FaceData = FaceData, Tgt extends FaceData = FaceData> {
+	readonly kind: "containment"
+	readonly source: Src
+	readonly target: Tgt
+	readonly bidirectional: boolean
+}
+
+/** A window statement's runtime description — target-left, faces at exact types like {@link ContainmentData}. */
+interface WindowData<Tgt extends FaceData = FaceData, Src extends FaceData = FaceData> {
+	readonly kind: "window"
+	readonly target: Tgt
+	readonly window: WindowSpec
+	readonly source: Src
+}
+
 /** One statement's runtime description, tagged by form. */
-type StatementData =
-	| KeyData<AnyRelation, readonly string[]>
-	| {
-			readonly kind: "containment"
-			readonly source: FaceData
-			readonly target: FaceData
-			readonly bidirectional: boolean
-	  }
-	| {
-			readonly kind: "window"
-			readonly target: FaceData
-			readonly window: WindowSpec
-			readonly source: FaceData
-	  }
+type StatementData = KeyData<AnyRelation, readonly string[]> | ContainmentData | WindowData
 
 /** An opaque statement value — what `schema()` assembles into a theory. */
 interface Statement {
 	readonly data: StatementData
 }
 
+/**
+ * A containment (or `==` bijection) statement as a TYPED value: `data`
+ * carries both faces at their exact types, so the schema-level class laws
+ * can read every paired (relation, field) slot off the statement type —
+ * spell the statement list inline in `schema()` and the equivalence
+ * classes compute at the type level too. Structurally still a plain
+ * {@link Statement}.
+ */
+interface ContainedStatement<Src extends FaceData, Tgt extends FaceData> extends Statement {
+	readonly data: ContainmentData<Src, Tgt>
+}
+
+/** A window statement as a TYPED value — the {@link ContainedStatement} of the window form. */
+interface WindowStatement<Tgt extends FaceData, Src extends FaceData> extends Statement {
+	readonly data: WindowData<Tgt, Src>
+}
+
 /**
  * A `key()` statement as a TYPED value: its `data` carries the owner
  * relation and the projection tuple at their EXACT types (honest runtime
  * properties — no phantom), which is what the key-statement-selected
  * `get(relation, keyStatement, key)` overload types its key object by
  * (`docs/architecture/70-api.md` § the freeze, the multi-key typed get) and
- * what resolves each projected field's domain label through the owner's
+ * what resolves each projected field's descriptor through the owner's
  * schema type. Structurally still a plain {@link Statement}.
  */
 interface KeyStatement<R extends AnyRelation, Projection extends readonly string[]> extends Statement {
 	readonly data: KeyData<R, Projection>
 }
 
+/**
+ * The field descriptor one face position projects: an ordinary relation's
+ * declared field; a closed relation's SEALED shape — the synthetic `id`
+ * (the value's own roster-carrying descriptor, by identity) or a declared
+ * payload column. `undefined` when the name is foreign (the type tier makes
+ * that unwritable; the engine re-judges projections at `Db.create`).
+ */
+function projectedFieldOf(face: FaceData, fieldName: string): AnyField | undefined {
+	const owner = face.owner
+	if ("axioms" in owner) {
+		if (fieldName === "id") {
+			return owner.id
+		}
+		const column = owner.data.columns.find(function byName(candidate) {
+			return candidate.name === fieldName
+		})
+		return column?.field
+	}
+	const declared = owner.data.fields.find(function byName(candidate) {
+		return candidate.name === fieldName
+	})
+	return declared?.field
+}
+
+/** The roster a descriptor carries: present exactly on a closed reference, absent on every other kind. */
+function rosterOfField(field: AnyField | undefined): ClosedRoster | undefined {
+	if (field !== undefined && "closed" in field) {
+		return field.closed
+	}
+	return undefined
+}
+
+/** Renders one face position's closedness for the roster-agreement diagnostics. */
+function renderRosterSide(roster: ClosedRoster | undefined): string {
+	return roster === undefined ? "a bare column" : `a ${roster.name} reference`
+}
+
+/**
+ * The runtime twin of {@link SameShapes}'s roster slot: the two faces'
+ * projected descriptors must agree POSITIONWISE on closedness — the same
+ * roster (value identity — vocabulary identity is value identity, the
+ * SDK's membership rule everywhere) or none. Without this wall a plain u64
+ * column could alias a closed vocabulary through a declared containment
+ * (`docs/architecture/10-data-model.md` spells the ENGINE encoding that
+ * way), and every descriptor-keyed closed judgment — the orderable ban,
+ * the name↔id marshal, answer decode — would silently miss it. The
+ * vocabulary's own descriptor (`Kind.id`) is the ONE spelling of a closed
+ * reference at this surface (the canonical-utterance law); the engine
+ * cannot backstop this one — the wire carries plain u64s, no rosters.
+ */
+function assertRosterAgreement(source: FaceData, target: FaceData, statement: Statement): void {
+	source.projection.forEach(function agreeAt(fieldName, position) {
+		const targetField = target.projection[position]
+		if (targetField === undefined) {
+			return
+		}
+		const sourceRoster = rosterOfField(projectedFieldOf(source, fieldName))
+		const targetRoster = rosterOfField(projectedFieldOf(target, targetField))
+		if (sourceRoster !== targetRoster) {
+			throw errors.new(
+				`${source.owner.name}.${fieldName} is ${renderRosterSide(sourceRoster)} but ${target.owner.name}.${targetField} is ${renderRosterSide(targetRoster)} — closedness rides the descriptor: a closed reference is spelled with the vocabulary's own id descriptor (one meaning, one spelling), so faces pair closed-with-closed through one roster or bare-with-bare, never across — ${renderStatement(statement)}`
+			)
+		}
+	})
+}
+
 /**
  * `R(X) -> R` — the FD key form, composite keys as tuples. No selection
  * parameter exists (the FD-with-selection shape is unrepresentable, as in
@@ -76,7 +179,7 @@ interface KeyStatement<R extends AnyRelation, Projection extends readonly string
  * explicit one would only ever be a duplicate. Every projected name is
  * checked against `R`'s field block in the type, and the tuple is carried
  * in the returned value's type ({@link KeyStatement}) — keyed point reads
- * through THIS statement are typed field-for-field, domains resolvable
+ * through THIS statement are typed field-for-field, descriptors resolvable
  * through the owner's schema type.
  */
 function key<
@@ -98,24 +201,26 @@ function key<
 
 /**
  * `A(X|φ) <= B(Y|ψ)` — conditional inclusion, source left. Arity mismatch
- * between the two faces is a type error ({@link SameArity}); a cross-domain
- * pair is a type error ({@link SameDomains} — positionwise string-literal
- * equality of the projected S1 domain labels). The target side must
- * resolve a declared key of B — a SEMANTIC property of the whole statement
- * set that no face type can state, DELIBERATELY judged by the engine at
- * `Db.create`/`Db.open` (`SchemaError`), never re-checked here.
+ * between the two faces is a type error ({@link SameArity}); a structurally
+ * mismatched pair is a type error ({@link SameShapes} — positionwise
+ * equality of the projected kind/width/element triples). The target side
+ * must resolve a declared key of B — a SEMANTIC property of the whole
+ * statement set that no face type can state, DELIBERATELY judged by the
+ * engine at `Db.create`/`Db.open` (`SchemaError`), never re-checked here.
  */
 function contained<A extends AnyFace, B extends AnyFace>(
 	source: A,
-	target: B & SameArity<A, B> & SameDomains<A, B>
-): Statement {
-	const data: StatementData = Object.freeze({
+	target: B & SameArity<A, B> & SameShapes<A, B>
+): ContainedStatement<A["data"], B["data"]> {
+	const data: ContainmentData<A["data"], B["data"]> = Object.freeze({
 		kind: "containment",
 		source: source.data,
 		target: target.data,
 		bidirectional: false
 	})
-	return Object.freeze({ data })
+	const statement = Object.freeze({ data })
+	assertRosterAgreement(data.source, data.target, statement)
+	return statement
 }
 
 /**
@@ -124,20 +229,22 @@ function contained<A extends AnyFace, B extends AnyFace>(
  * two faces (each side contains the other). It lowers to the two adjacent
  * containments in the `A <= B` first order (macro parity — the engine
  * performs the split, source-first) and renders as `==` once, in the
- * written orientation. Faces pair by arity AND domain, exactly as
- * {@link contained}.
+ * written orientation. Faces pair by arity AND structural shape, exactly
+ * as {@link contained}.
  */
 function mirrors<A extends AnyFace, B extends AnyFace>(
 	source: A,
-	target: B & SameArity<A, B> & SameDomains<A, B>
-): Statement {
-	const data: StatementData = Object.freeze({
+	target: B & SameArity<A, B> & SameShapes<A, B>
+): ContainedStatement<A["data"], B["data"]> {
+	const data: ContainmentData<A["data"], B["data"]> = Object.freeze({
 		kind: "containment",
 		source: source.data,
 		target: target.data,
 		bidirectional: true
 	})
-	return Object.freeze({ data })
+	const statement = Object.freeze({ data })
+	assertRosterAgreement(data.source, data.target, statement)
+	return statement
 }
 
 /**
@@ -146,21 +253,24 @@ function mirrors<A extends AnyFace, B extends AnyFace>(
  * target-left — macro parity), and the RIGHT face is the counted source.
  * `window(on(Holder, "id"), atMost(3n), on(Account, "holder"))` says: each
  * Holder id groups at most three Account rows by holder. The two faces
- * pair by arity AND domain ({@link SameDomains}), exactly as containment —
- * the grouping join reads the same positionwise field pairing.
+ * pair by arity AND structural shape ({@link SameShapes}), exactly as
+ * containment — the grouping join reads the same positionwise field
+ * pairing.
  */
 function window<B extends AnyFace, A extends AnyFace>(
 	target: B,
 	count: Count,
-	source: A & SameArity<B, A> & SameDomains<B, A>
-): Statement {
-	const data: StatementData = Object.freeze({
+	source: A & SameArity<B, A> & SameShapes<B, A>
+): WindowStatement<B["data"], A["data"]> {
+	const data: WindowData<B["data"], A["data"]> = Object.freeze({
 		kind: "window",
 		target: target.data,
 		window: count.window,
 		source: source.data
 	})
-	return Object.freeze({ data })
+	const statement = Object.freeze({ data })
+	assertRosterAgreement(data.source, data.target, statement)
+	return statement
 }
 
 /**
@@ -187,5 +297,14 @@ function renderStatement(statement: Statement): string {
 	}
 }
 
-export type { KeyData, KeyStatement, Statement, StatementData }
+export type {
+	ContainedStatement,
+	ContainmentData,
+	KeyData,
+	KeyStatement,
+	Statement,
+	StatementData,
+	WindowData,
+	WindowStatement
+}
 export { contained, key, mirrors, renderStatement, window }