@bjornpagen/bumbledb 0.3.0 → 0.4.0

package/src/query/scope.ts

@@ -228,25 +228,38 @@ type WidthOf<F extends AnyField> = F extends { readonly width: infer W } ? W : u
 /** Reads an interval descriptor's element kind; `undefined` on scalar kinds. */
 type ElementOf<F extends AnyField> = F extends { readonly element: infer E } ? E : undefined
 
+/** Reads a closed reference's handle union; `undefined` on every non-closed kind (the roster IS descriptor structure). */
+type RosterOf<F extends AnyField> = F extends {
+	readonly closed: { readonly handles: readonly (infer H extends string)[] }
+}
+	? H
+	: undefined
+
 /**
  * The join judgment: two bound slots join iff their descriptors' structure
- * agrees (kind, width label, interval element) AND their law-computed
- * classes agree — same class name joins, and bare (`undefined`) pairs only
- * with bare (ruling 3: a field in no law has no class; a bare↔classed
- * pairing refuses). The class names come off the SCHEMA type's class map —
- * the statements are the typing; no descriptor label exists to compare.
+ * agrees (kind, width label, interval element, and the closed ROSTER — a
+ * closed reference pairs only with the same vocabulary, never with a bare
+ * u64: the roster keys every closed judgment downstream, so a join across
+ * it would decode/order/translate incoherently by binding order) AND their
+ * law-computed classes agree — same class name joins, and bare
+ * (`undefined`) pairs only with bare (ruling 3: a field in no law has no
+ * class; a bare↔classed pairing refuses). The class names come off the
+ * SCHEMA type's class map — the statements are the typing; no descriptor
+ * label beyond the roster exists to compare.
  */
 type JoinOk<A extends ClassedField, B extends ClassedField> = [
 	A["field"]["kind"],
 	A["class"],
 	WidthOf<A["field"]>,
-	ElementOf<A["field"]>
-] extends [B["field"]["kind"], B["class"], WidthOf<B["field"]>, ElementOf<B["field"]>]
-	? [B["field"]["kind"], B["class"], WidthOf<B["field"]>, ElementOf<B["field"]>] extends [
+	ElementOf<A["field"]>,
+	RosterOf<A["field"]>
+] extends [B["field"]["kind"], B["class"], WidthOf<B["field"]>, ElementOf<B["field"]>, RosterOf<B["field"]>]
+	? [B["field"]["kind"], B["class"], WidthOf<B["field"]>, ElementOf<B["field"]>, RosterOf<B["field"]>] extends [
 			A["field"]["kind"],
 			A["class"],
 			WidthOf<A["field"]>,
-			ElementOf<A["field"]>
+			ElementOf<A["field"]>,
+			RosterOf<A["field"]>
 		]
 		? true
 		: false
@@ -255,7 +268,8 @@ type JoinOk<A extends ClassedField, B extends ClassedField> = [
 /**
  * The runtime twin of {@link JoinOk}: two bound slots join iff descriptor
  * structure and class agree — the same comparison the type tier makes,
- * judged on the honest runtime values (the descriptor and the schema
+ * judged on the honest runtime values (the descriptor, the roster by VALUE
+ * IDENTITY — vocabulary identity is value identity — and the schema
  * value's frozen class map). The rule builders throw through this on a
  * class-unequal variable reuse, so the wall holds for untyped callers too,
  * not only where the compiler can see.
@@ -265,17 +279,30 @@ function fieldJoins(a: ClassedField, b: ClassedField): boolean {
 	const widthB = "width" in b.field ? b.field.width : undefined
 	const elementA = "element" in a.field ? a.field.element : undefined
 	const elementB = "element" in b.field ? b.field.element : undefined
-	return a.field.kind === b.field.kind && a.class === b.class && widthA === widthB && elementA === elementB
+	const rosterA = "closed" in a.field ? a.field.closed : undefined
+	const rosterB = "closed" in b.field ? b.field.closed : undefined
+	return (
+		a.field.kind === b.field.kind &&
+		a.class === b.class &&
+		widthA === widthB &&
+		elementA === elementB &&
+		rosterA === rosterB
+	)
 }
 
 /**
  * Renders one bound slot for join-mismatch diagnostics — the structural
- * kind in the schema grammar's spelling plus the slot's law-computed class
- * (`u64 in class Holder.id`; a lawless slot renders `bare`).
+ * kind in the schema grammar's spelling (a closed reference names its
+ * vocabulary: the roster is part of the structure being compared) plus the
+ * slot's law-computed class (`u64 in class Holder.id`; a lawless slot
+ * renders `bare`).
  */
 function renderFieldKind(slot: ClassedField): string {
 	const field = slot.field
 	let base: string = field.kind
+	if ("closed" in field) {
+		base = `u64 referencing ${field.closed.name}`
+	}
 	if (field.kind === "bytes") {
 		base = `bytes<${field.width}>`
 	}
@@ -287,7 +314,10 @@ function renderFieldKind(slot: ClassedField): string {
 
 /**
  * What a PARAM anchored at field `F` accepts at execution: the field's
- * bare value type, exactly. At an interval field the engine resolves the
+ * bare value type, exactly — at a CLOSED-reference field that is the
+ * handle-name union (`"DirectPass" | "Failed"`), translated name → row id
+ * at execute through the one roster-verification point
+ * (`taggedHandleId`). At an interval field the engine resolves the
  * bivalent anchor to the INTERVAL reading (value equality) — the point
  * reading of a param is spelled `pointIn(r.param(...), w)`, whose sibling
  * anchors it element-typed.
@@ -304,13 +334,17 @@ type InferredOf<T> = T extends { readonly [inferred]?: infer S } ? Exclude<S, un
  * positions) — the op keeps literal tagging op-aware at `pointIn`
  * (the bug-hunt fix, preserved). `anchor` is `undefined` only on a query
  * built but not yet anchored by any rule; lowering and the wire both refuse
- * that state typed.
+ * that state typed. `members` is present exactly on a MEMBERSHIP-ARRAY
+ * entry (a literal set at a closed field, folded into the program): the
+ * SDK itself translates and supplies the set at every execute — the entry
+ * is never read from, and never demanded of, the host's params object.
  */
 interface ParamEntry {
 	readonly name: string
 	readonly shape: "value" | "set" | "mask"
 	readonly anchor: AnyField | "measure" | undefined
 	readonly op: "binding" | "eq" | "ne" | "lt" | "le" | "gt" | "ge" | "pointIn" | "allen"
+	readonly members: readonly string[] | undefined
 }
 
 export type {

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) })
 	}
@@ -78,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(
@@ -131,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. */

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 =

package/src/statements.ts

@@ -8,10 +8,16 @@
  * 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. 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
@@ -28,6 +34,7 @@
 import * as errors from "@superbuilders/errors"
 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 { AnyRelation, RelationFields } from "#relation.ts"
 import { renderWindow, type WindowSpec } from "#spec.ts"
 
@@ -98,6 +105,72 @@ 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 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
@@ -145,7 +218,9 @@ function contained<A extends AnyFace, B extends AnyFace>(
 		target: target.data,
 		bidirectional: false
 	})
-	return Object.freeze({ data })
+	const statement = Object.freeze({ data })
+	assertRosterAgreement(data.source, data.target, statement)
+	return statement
 }
 
 /**
@@ -167,7 +242,9 @@ function mirrors<A extends AnyFace, B extends AnyFace>(
 		target: target.data,
 		bidirectional: true
 	})
-	return Object.freeze({ data })
+	const statement = Object.freeze({ data })
+	assertRosterAgreement(data.source, data.target, statement)
+	return statement
 }
 
 /**
@@ -191,7 +268,9 @@ function window<B extends AnyFace, A extends AnyFace>(
 		window: count.window,
 		source: source.data
 	})
-	return Object.freeze({ data })
+	const statement = Object.freeze({ data })
+	assertRosterAgreement(data.source, data.target, statement)
+	return statement
 }
 
 /**