@bjornpagen/bumbledb 0.4.0 → 0.5.0

package/src/relation.ts

@@ -2,12 +2,14 @@
  * `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),
- * 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 verified against their roster at
- * construction). `Fact<>`/`InsertFact<>` are the inferred row object
- * types at BARE structural value types (no brands): fresh fields are
- * optional on insert input (omit-to-mint) and present on read
+ * 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<>`/`InsertFact<>` are the inferred
+ * row object types at BARE structural value types (no brands): fresh
+ * fields are optional on insert input (omit-to-mint) and present on read
  * (resupply-to-preserve-identity), typed exactly.
  */
 
@@ -18,23 +20,6 @@ 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] }
 
-/**
- * The one trusted seam 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
- * 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: a plain ARRAY
  * (detected by `Array.isArray` — no field's value type is an array;
@@ -117,22 +102,6 @@ function resolveSelection(
 /** The field block of a relation: field name to field descriptor. */
 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 is read off the
- * relation's schema type structurally.
- */
-interface FieldRef<Rel extends string, Name extends string> {
-	readonly relation: Rel
-	readonly field: Name
-}
-
-/** 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>
-}
-
 /** One declared field: name plus its descriptor, in declaration order. */
 interface RelationField {
 	readonly name: string
@@ -178,7 +147,6 @@ interface Selected<Name extends string, Fields extends FieldsShape> {
 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>
 }
 
@@ -236,14 +204,6 @@ function relation<const Name extends string, Fields extends FieldsShape>(
 		ordered.push(Object.freeze({ name: fieldName, field }))
 	}
 	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
@@ -255,7 +215,7 @@ function relation<const Name extends string, Fields extends FieldsShape>(
 			selection: resolveSelection(name, ordered, Object.entries(selection))
 		})
 	}
-	const value: Relation<Name, Fields> = Object.freeze({ name, data, fields: refs, where })
+	const value: Relation<Name, Fields> = Object.freeze({ name, data, where })
 	holder.value = value
 	return value
 }
@@ -264,8 +224,6 @@ export type {
 	AnyRelation,
 	AnySelected,
 	Fact,
-	FieldRef,
-	FieldRefs,
 	FieldsShape,
 	FreshKeys,
 	InsertFact,

package/src/schema.ts

@@ -11,8 +11,9 @@
 
 import * as errors from "@superbuilders/errors"
 import type { AnyClosed } from "#closed.ts"
+import { isClosedMember, sealedFieldOf } from "#closed.ts"
 import type { FaceData } from "#face.ts"
-import { type AnyField, assertDeclarationOrderKey, type ClosedRoster } from "#fields.ts"
+import { assertDeclarationOrderKey, rosterOf } 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"
@@ -34,7 +35,7 @@ function collectImplied(name: string, relations: SchemaRelations): Set<string> {
 				`schema ${name}: record key ${recordKey} holds relation ${member.name} — the key must equal the relation's declared name`
 			)
 		}
-		if ("handles" in member.data) {
+		if (isClosedMember(member)) {
 			implied.add(`${member.name}(id) -> ${member.name}`)
 			continue
 		}
@@ -75,33 +76,6 @@ function verifyMembership(name: string, relations: SchemaRelations, statement: S
 	}
 }
 
-/** Finds a face's field descriptor by name, across both relation kinds. */
-function faceField(face: FaceData, fieldName: string): AnyField | 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
-}
-
-/**
- * The roster a field resolves handles through: present exactly on a closed
- * reference descriptor (the structural `closed` property — S1's
- * `ClosedIdField`), absent on every other field kind.
- */
-function rosterOf(field: AnyField | undefined): ClosedRoster | undefined {
-	if (field !== undefined && "closed" in field) {
-		return field.closed
-	}
-	return undefined
-}
-
 /** Flattens one binding's literal set into its literals. */
 function bindingLiterals(set: LiteralSetSpec): readonly LiteralSpec[] {
 	if (set.kind === "one") {
@@ -122,7 +96,7 @@ function verifyBindingHandles(
 	binding: { readonly field: string; readonly set: LiteralSetSpec },
 	rendered: string
 ): void {
-	const roster = rosterOf(faceField(face, binding.field))
+	const roster = rosterOf(sealedFieldOf(face.owner, binding.field))
 	for (const literal of bindingLiterals(binding.set)) {
 		if (literal.kind !== "handle") {
 			continue
@@ -177,7 +151,7 @@ function closedTargetOf(statements: readonly Statement[], owner: string, field:
 				source.projection[0] === field &&
 				target.projection.length === 1 &&
 				target.projection[0] === "id" &&
-				"handles" in target.owner.data
+				isClosedMember(target.owner)
 			) {
 				return target.owner.name
 			}
@@ -227,11 +201,11 @@ function verifyClosedReferenceBinding(
 	if (!spellsHandle) {
 		return
 	}
-	const roster = rosterOf(faceField(face, binding.field))
+	const roster = rosterOf(sealedFieldOf(face.owner, binding.field))
 	if (roster === undefined) {
 		return
 	}
-	if ("handles" in face.owner.data && binding.field === "id") {
+	if (isClosedMember(face.owner) && binding.field === "id") {
 		return
 	}
 	const resolved = closedTargetOf(statements, face.owner.name, binding.field)

package/src/statements.ts

@@ -12,8 +12,11 @@
  * 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} —
+ * 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
@@ -32,9 +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 { AnyField, ClosedRoster } from "#fields.ts"
+import { type ClosedRoster, rosterOf } from "#fields.ts"
 import type { AnyRelation, RelationFields } from "#relation.ts"
 import { renderWindow, type WindowSpec } from "#spec.ts"
 
@@ -105,43 +109,28 @@ interface KeyStatement<R extends AnyRelation, Projection extends readonly string
 	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 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
@@ -154,6 +143,9 @@ function renderRosterSide(roster: ClosedRoster | undefined): string {
  * 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) {
@@ -161,8 +153,8 @@ function assertRosterAgreement(source: FaceData, target: FaceData, statement: St
 		if (targetField === undefined) {
 			return
 		}
-		const sourceRoster = rosterOfField(projectedFieldOf(source, fieldName))
-		const targetRoster = rosterOfField(projectedFieldOf(target, targetField))
+		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)}`
@@ -186,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`
 		)
@@ -219,6 +211,7 @@ function contained<A extends AnyFace, B extends AnyFace>(
 		bidirectional: false
 	})
 	const statement = Object.freeze({ data })
+	assertArityAgreement(data.source, data.target, statement)
 	assertRosterAgreement(data.source, data.target, statement)
 	return statement
 }
@@ -243,6 +236,7 @@ function mirrors<A extends AnyFace, B extends AnyFace>(
 		bidirectional: true
 	})
 	const statement = Object.freeze({ data })
+	assertArityAgreement(data.source, data.target, statement)
 	assertRosterAgreement(data.source, data.target, statement)
 	return statement
 }
@@ -269,6 +263,7 @@ function window<B extends AnyFace, A extends AnyFace>(
 		source: source.data
 	})
 	const statement = Object.freeze({ data })
+	assertArityAgreement(data.source, data.target, statement)
 	assertRosterAgreement(data.source, data.target, statement)
 	return statement
 }