@bjornpagen/bumbledb 0.3.0 → 0.5.0

package/src/statements.ts

@@ -8,10 +8,19 @@
  * Every field reference is checked against the relation it names in the
  * TYPE — existence through {@link FaceFields} (`on(R, "nope")` does not
  * compile) and STRUCTURAL compatibility through {@link SameShapes}: the two
- * faces' projected kind/width/element triples 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, or an interval element mismatch is a compile error. Domains are
+ * 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. TWO of those walls carry
+ * construction-time runtime twins here for untyped callers: ARITY
+ * ({@link assertArityAgreement} — cleanup-0.5.0 ruling 9: an
+ * arity-mismatched pairing fails at the statement, never by silent
+ * truncation) and the ROSTER slot ({@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
@@ -26,8 +35,10 @@
  */
 
 import * as errors from "@superbuilders/errors"
+import { isClosedMember, sealedFieldOf } from "#closed.ts"
 import type { Count } from "#count.ts"
 import { type AnyFace, type FaceData, renderFace, type SameArity, type SameShapes } from "#face.ts"
+import { type ClosedRoster, rosterOf } from "#fields.ts"
 import type { AnyRelation, RelationFields } from "#relation.ts"
 import { renderWindow, type WindowSpec } from "#spec.ts"
 
@@ -98,6 +109,60 @@ interface KeyStatement<R extends AnyRelation, Projection extends readonly string
 	readonly data: KeyData<R, Projection>
 }
 
+/** 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 SameArity} (cleanup-0.5.0 ruling 9): the two
+ * faces must project equally many fields, judged at CONSTRUCTION for
+ * untyped callers too — without it an arity-mismatched containment
+ * silently truncates to the shorter projection (this module's positionwise
+ * walk and `law.ts`'s `unionSlot` both skip unpaired positions) until
+ * `Db.create`'s colder engine refusal. The error carries the two faces'
+ * own facts: names, arities, and the rendered statement.
+ */
+function assertArityAgreement(source: FaceData, target: FaceData, statement: Statement): void {
+	if (source.projection.length !== target.projection.length) {
+		throw errors.new(
+			`${source.owner.name}(${source.projection.join(", ")}) and ${target.owner.name}(${target.projection.join(", ")}) project ${source.projection.length} vs ${target.projection.length} fields — positional pairing requires both faces to project equally many — ${renderStatement(statement)}`
+		)
+	}
+}
+
+/**
+ * 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.
+ * Arity agreement ({@link assertArityAgreement}) runs first, so the
+ * positionwise walk here never sees an unpaired position from a well-typed
+ * OR an untyped caller.
+ */
+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 = rosterOf(sealedFieldOf(source.owner, fieldName))
+		const targetRoster = rosterOf(sealedFieldOf(target.owner, 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
@@ -113,7 +178,7 @@ function key<
 	R extends AnyRelation,
 	const Projection extends readonly [keyof RelationFields<R> & string, ...(keyof RelationFields<R> & string)[]]
 >(relation: R, fields: Projection): KeyStatement<R, Projection> {
-	if (!("fields" in relation.data)) {
+	if (isClosedMember(relation)) {
 		throw errors.new(
 			`key(${relation.name}, ...): closedness already materializes ${relation.name}(id) -> ${relation.name} — an explicit key on a closed relation is rejected as a duplicate`
 		)
@@ -145,7 +210,10 @@ function contained<A extends AnyFace, B extends AnyFace>(
 		target: target.data,
 		bidirectional: false
 	})
-	return Object.freeze({ data })
+	const statement = Object.freeze({ data })
+	assertArityAgreement(data.source, data.target, statement)
+	assertRosterAgreement(data.source, data.target, statement)
+	return statement
 }
 
 /**
@@ -167,7 +235,10 @@ function mirrors<A extends AnyFace, B extends AnyFace>(
 		target: target.data,
 		bidirectional: true
 	})
-	return Object.freeze({ data })
+	const statement = Object.freeze({ data })
+	assertArityAgreement(data.source, data.target, statement)
+	assertRosterAgreement(data.source, data.target, statement)
+	return statement
 }
 
 /**
@@ -191,7 +262,10 @@ function window<B extends AnyFace, A extends AnyFace>(
 		window: count.window,
 		source: source.data
 	})
-	return Object.freeze({ data })
+	const statement = Object.freeze({ data })
+	assertArityAgreement(data.source, data.target, statement)
+	assertRosterAgreement(data.source, data.target, statement)
+	return statement
 }
 
 /**