@bjornpagen/bumbledb 0.19.1 → 0.20.0

package/src/query/lower.ts

@@ -1,6 +1,6 @@
 import * as errors from "@superbuilders/errors"
 import { sealedFieldsOf } from "#closed.ts"
-import type { AnyField, ClosedRoster } from "#fields.ts"
+import type { AnyClosedRoster, AnyField } from "#fields.ts"
 import { assertDeclarationOrderKey, isIntervalValue, literalShapeError, rosterOf } from "#fields.ts"
 import type { ClassRecordOf, SchemaClasses } from "#law.ts"
 import type {
@@ -61,6 +61,7 @@ import type {
 import {
 	fieldAntiJoins,
 	fieldJoins,
+	headFieldJoins,
 	inferred,
 	isTerm,
 	makeParam,
@@ -85,9 +86,6 @@ interface RuleValue<Row, P extends ParamsRecord, Head extends HeadShape = undefi
 
 type AnyRuleValue = RuleValue<unknown, ParamsRecord, HeadShape>
 
-type HeadOf<T> =
-	InferredOf<T> extends { readonly head: infer H extends Readonly<Record<string, ClassedField>> } ? H : undefined
-
 type InteriorBindingOk<V> = V extends AnyVar ? true : false
 
 type CheckInteriorBindings<B> = {
@@ -1171,7 +1169,7 @@ function makeRecRuleScope<Rels extends SchemaRelations, Classes extends SchemaCl
 	return raw
 }
 
-function renderClosedSlice(closed: ClosedRoster | undefined): string {
+function renderClosedSlice(closed: AnyClosedRoster | undefined): string {
 	return closed === undefined ? "a bare value" : `a ${closed.name} reference`
 }
 
@@ -1187,7 +1185,7 @@ function headSignature(column: FindColumn): string {
 	return `${column.name}:${agg.op}`
 }
 
-function renderParamAnchor(roster: ClosedRoster | undefined): string {
+function renderParamAnchor(roster: AnyClosedRoster | undefined): string {
 	return roster === undefined ? "a non-closed position" : `a ${roster.name} reference`
 }
 
@@ -1307,7 +1305,15 @@ interface RawQuery {
 	reach(name: string, arms: never): never
 }
 
-function assertAlignedHeads(label: string, rules: readonly RuleData[]): void {
+/**
+ * Verifies every rule derives the same head and returns the MERGED head:
+ * the meet of the rules' column slots. A head column joins class-equal
+ * slots, and — the anti-join law's head twin — same-identity u64 wire
+ * with at least one side bare; when the bare arm admits the pair, the
+ * merged column's class claim demotes to bare, so a consumer joining
+ * the head cannot inherit provenance a rule never proved.
+ */
+function alignedHeadOf(label: string, rules: readonly RuleData[]): readonly FindColumn[] {
 	const first = rules[0]
 	if (first === undefined) {
 		throw errors.new(`${label} needs at least one rule`)
@@ -1330,13 +1336,33 @@ function assertAlignedHeads(label: string, rules: readonly RuleData[]): void {
 			if (lead === undefined) {
 				return
 			}
-			if (lead.slot !== undefined && column.slot !== undefined && !fieldJoins(lead.slot, column.slot)) {
+			if (lead.slot !== undefined && column.slot !== undefined && !headFieldJoins(lead.slot, column.slot)) {
 				throw errors.new(
-					`every rule of ${label} derives the same head — the head column ${lead.name} is bound at ${renderFieldKind(lead.slot)} in rule 0 but at ${renderFieldKind(column.slot)} in rule ${index} (a head column joins only class-equal slots; bare pairs only with bare)`
+					`every rule of ${label} derives the same head — the head column ${lead.name} is bound at ${renderFieldKind(lead.slot)} in rule 0 but at ${renderFieldKind(column.slot)} in rule ${index} (a head column joins class-equal slots; same-wire u64 admits a bare side, and the merged head is bare)`
 				)
 			}
 		})
 	})
+	const merged = first.finds.map(function meetColumn(lead, position) {
+		const slot = lead.slot
+		if (slot === undefined || slot.class === undefined) {
+			return lead
+		}
+		const demoted = rules.some(function bareElsewhere(rule) {
+			const column = rule.finds[position]
+			return column !== undefined && column.slot !== undefined && column.slot.class !== slot.class
+		})
+		if (!demoted) {
+			return lead
+		}
+		return Object.freeze({
+			name: lead.name,
+			entry: lead.entry,
+			closed: lead.closed,
+			slot: Object.freeze({ field: slot.field, class: undefined })
+		})
+	})
+	return Object.freeze(merged)
 }
 
 function afterMainError(what: string): Error {
@@ -1351,7 +1377,7 @@ function makeRawQuery(
 	rec: RecData | undefined,
 	rules: readonly RuleData[]
 ): RawQuery {
-	assertAlignedHeads("a query", rules)
+	const mergedFinds = alignedHeadOf("a query", rules)
 	const first = rules[0]
 	if (first === undefined) {
 		throw errors.new("a query needs at least one rule")
@@ -1366,7 +1392,7 @@ function makeRawQuery(
 					kind: "cq" as const,
 					interiors: frozenInteriors,
 					rules: frozenRules,
-					finds: first.finds,
+					finds: mergedFinds,
 					params
 				})
 			: Object.freeze({
@@ -1374,7 +1400,7 @@ function makeRawQuery(
 					interiors: frozenInteriors,
 					rec,
 					rules: frozenRules,
-					finds: first.finds,
+					finds: mergedFinds,
 					params
 				})
 	const value: RawQuery = {
@@ -1416,12 +1442,8 @@ function collectInterior<Rels extends SchemaRelations, Classes extends SchemaCla
 	const rules = builds.map(function buildRule(buildOne) {
 		return buildOne(makeInteriorRuleScope<Rels, Classes>(theory, env, name)).rule
 	})
-	assertAlignedHeads(`interior ${name}`, rules)
-	const first = rules[0]
-	if (first === undefined) {
-		throw errors.new(`query: interior ${name} needs at least one rule`)
-	}
-	return Object.freeze({ name, finds: first.finds, rules: Object.freeze(rules) })
+	const mergedFinds = alignedHeadOf(`interior ${name}`, rules)
+	return Object.freeze({ name, finds: mergedFinds, rules: Object.freeze(rules) })
 }
 
 function collectRec<Rels extends SchemaRelations, Classes extends SchemaClasses>(
@@ -1442,22 +1464,27 @@ function collectRec<Rels extends SchemaRelations, Classes extends SchemaClasses>
 	const base = baseBuilds.map(function buildBase(buildOne) {
 		return buildOne(makeRecRuleScope<Rels, Classes>(theory, baseEnv, handle, "rec-base")).rule
 	})
-	assertAlignedHeads(`rec ${name}`, base)
+	const baseFinds = alignedHeadOf(`rec ${name}`, base)
 	const first = base[0]
 	if (first === undefined) {
 		throw errors.new(`query: rec ${name} has no base arms`)
 	}
-	const firstFind = first.finds[0]
+	const firstFind = baseFinds[0]
 	if (firstFind === undefined) {
 		throw errors.new(`query: rec ${name} has no head`)
 	}
-	const finds: RecHead["finds"] = [firstFind, ...first.finds.slice(1)]
+	const finds: RecHead["finds"] = [firstFind, ...baseFinds.slice(1)]
 	const head: RecHead = Object.freeze({ name, finds })
 	const recEnv: DerivedEnv = { interiors, rec: head }
 	const rec = recBuilds.map(function buildRec(buildOne) {
 		return buildOne(makeRecRuleScope<Rels, Classes>(theory, recEnv, head, "rec-arm")).rule
 	})
-	assertAlignedHeads(`rec ${name}`, [...base, ...rec])
+	const mergedAll = alignedHeadOf(`rec ${name}`, [...base, ...rec])
+	const mergedFirst = mergedAll[0]
+	if (mergedFirst === undefined) {
+		throw errors.new(`query: rec ${name} has no head`)
+	}
+	const sealedFinds: RecHead["finds"] = [mergedFirst, ...mergedAll.slice(1)]
 	const firstRec = rec[0]
 	if (firstRec === undefined) {
 		throw errors.new(`query: rec ${name} has no rec arms`)
@@ -1466,7 +1493,7 @@ function collectRec<Rels extends SchemaRelations, Classes extends SchemaClasses>
 	const sealedRec: RecData["rec"] = [firstRec, ...rec.slice(1)]
 	const recData: RecData = Object.freeze({
 		name,
-		finds,
+		finds: sealedFinds,
 		base: sealedBase,
 		rec: sealedRec
 	})
@@ -1949,11 +1976,6 @@ function lowerQuery(q: AnyQuery): ParsedQuery {
 export type {
 	AnyQuery,
 	AnyRuleValue,
-	HeadOf,
-	HeadShape,
-	InteriorRuleChain,
-	InteriorRuleScope,
-	ParamsOf,
 	Query,
 	QueryData,
 	QueryParams,
@@ -1963,12 +1985,9 @@ export type {
 	QueryRuleChain,
 	QueryRuleScope,
 	QueryStart,
-	RawChain,
-	RawScope,
 	RecRuleChain,
 	RecRuleScope,
-	RowOf,
 	RuleValue,
 	TermOps
 }
-export { lowerQuery, makeRawScope, query, taggedCmpLiteral, taggedLiteral }
+export { lowerQuery, query, taggedCmpLiteral }

package/src/query/scope.ts

@@ -1,8 +1,9 @@
 import * as errors from "@superbuilders/errors"
 import type { AnyClosed } from "#closed.ts"
 import { sealedFieldsOf } from "#closed.ts"
-import type { AnyField, Infer } from "#fields.ts"
-import { rosterOf } from "#fields.ts"
+import type { AnyField, Infer, SignatureOf } from "#fields.ts"
+import { rosterOf, signaturesAgree } from "#fields.ts"
+import type { Same, SameLen } from "#judgment.ts"
 import type { ClassLookup, ClassRecordOf, SchemaClasses } from "#law.ts"
 import type { QueryParam } from "#native.ts"
 import type { AnyRelation, RelationFields } from "#relation.ts"
@@ -19,7 +20,7 @@ type MatchFields<R extends MatchOwner> = R extends AnyClosed
 		? RelationFields<R>
 		: never
 
-interface Var<F extends AnyField = AnyField, RN extends string = string, K extends string = string> {
+interface Var<F extends AnyField, RN extends string, K extends string> {
 	readonly [term]: "var"
 	readonly owner: MatchOwner & { readonly name: RN }
 	readonly column: K
@@ -27,19 +28,19 @@ interface Var<F extends AnyField = AnyField, RN extends string = string, K exten
 	readonly label: string
 }
 
-type AnyVar = Var
+type AnyVar = Var<AnyField, string, string>
 
-interface Param<Name extends string = string> {
+interface Param<Name extends string> {
 	readonly [term]: "param"
 	readonly name: Name
 }
 
-interface SetParam<Name extends string = string> {
+interface SetParam<Name extends string> {
 	readonly [term]: "setParam"
 	readonly name: Name
 }
 
-type AnyTerm = Var | Param | SetParam
+type AnyTerm = AnyVar | Param<string> | SetParam<string>
 
 function isTerm(value: unknown): value is AnyTerm {
 	return typeof value === "object" && value !== null && term in value
@@ -147,84 +148,94 @@ type UnionToIntersection<U> = (U extends unknown ? (member: U) => void : never)
 
 type ShapeOf<U> = [U] extends [never] ? Record<never, never> : Flatten<UnionToIntersection<U>>
 
-type WidthOf<F extends AnyField> = F extends { readonly width: infer W } ? W : undefined
-
-type ElementOf<F extends AnyField> = F extends { readonly element: infer E } ? E : undefined
+/**
+ * A slot's identity for the positive-join judgment: the field's structural
+ * signature ({@link SignatureOf} — the ONE interpreter, shared with the
+ * face pairing wall) plus the slot's law class.
+ */
+type SlotSignature<S extends ClassedField> = readonly [SignatureOf<S["field"]>, S["class"]]
 
-type RosterOf<F extends AnyField> = F extends {
-	readonly closed: { readonly name: infer N extends string; readonly handles: readonly (infer H extends string)[] }
-}
-	? readonly [N, H]
-	: undefined
-
-type JoinOk<A extends ClassedField, B extends ClassedField> = [
-	A["field"]["kind"],
-	A["class"],
-	WidthOf<A["field"]>,
-	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"]>,
-			RosterOf<A["field"]>
-		]
-		? true
-		: false
-	: false
+type JoinOk<A extends ClassedField, B extends ClassedField> = Same<SlotSignature<A>, SlotSignature<B>>
 
 type U64Wire<F extends AnyField> = F extends { readonly kind: "u64" }
-	? RosterOf<F> extends undefined
-		? true
-		: false
+	? F extends { readonly closed: unknown }
+		? false
+		: true
 	: false
 
+type ClosedHandles<F extends AnyField> = F extends {
+	readonly closed: { readonly handles: infer H extends readonly string[] }
+}
+	? H
+	: never
+
+/**
+ * Two closed ids anti-join when their handle vectors carry the same Peano
+ * length ({@link SameLen}: zero equals zero, successor recurses on
+ * successor). A bare field has no vector and proves nothing.
+ */
+type ClosedIdOk<A extends AnyField, B extends AnyField> = [ClosedHandles<A>] extends [never]
+	? false
+	: [ClosedHandles<B>] extends [never]
+		? false
+		: SameLen<ClosedHandles<A>, ClosedHandles<B>>
+
 /**
  * Anti-join class safety: class-equal slots, plus same-identity u64
- * (fresh mint, foreign-key copy, or bare u64) when one side is bare.
- * Two distinct generators stay refused. Closed-roster u64 is not a
- * wire identity.
+ * (fresh mint, foreign-key copy, or bare u64) when one side is bare,
+ * plus two closed-id fields whose handle tuples have the same length.
+ * Two distinct generators stay refused.
  */
 type AntiJoinOk<A extends ClassedField, B extends ClassedField> =
 	JoinOk<A, B> extends true
 		? true
-		: U64Wire<A["field"]> extends true
-			? U64Wire<B["field"]> extends true
-				? [A["class"]] extends [undefined]
-					? true
-					: [B["class"]] extends [undefined]
+		: ClosedIdOk<A["field"], B["field"]> extends true
+			? true
+			: U64Wire<A["field"]> extends true
+				? U64Wire<B["field"]> extends true
+					? [A["class"]] extends [undefined]
 						? true
-						: false
+						: [B["class"]] extends [undefined]
+							? true
+							: false
+					: false
 				: false
-			: false
 
 function fieldJoins(a: ClassedField, b: ClassedField): boolean {
-	const widthA = "width" in a.field ? a.field.width : undefined
-	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
-	const rosterA = rosterOf(a.field)
-	const rosterB = rosterOf(b.field)
-	return (
-		a.field.kind === b.field.kind &&
-		a.class === b.class &&
-		widthA === widthB &&
-		elementA === elementB &&
-		rosterA === rosterB
-	)
+	return a.class === b.class && signaturesAgree(a.field, b.field)
 }
 
 function u64Wire(field: AnyField): boolean {
 	return field.kind === "u64" && rosterOf(field) === undefined
 }
 
+function closedIdAntiJoins(a: AnyField, b: AnyField): boolean {
+	const rosterA = rosterOf(a)
+	const rosterB = rosterOf(b)
+	return rosterA !== undefined && rosterB !== undefined && rosterA.handles.length === rosterB.handles.length
+}
+
+function u64BareWirePair(a: ClassedField, b: ClassedField): boolean {
+	return u64Wire(a.field) && u64Wire(b.field) && (a.class === undefined || b.class === undefined)
+}
+
 function fieldAntiJoins(a: ClassedField, b: ClassedField): boolean {
-	if (fieldJoins(a, b)) {
+	if (fieldJoins(a, b) || closedIdAntiJoins(a.field, b.field)) {
 		return true
 	}
-	return u64Wire(a.field) && u64Wire(b.field) && (a.class === undefined || b.class === undefined)
+	return u64BareWirePair(a, b)
+}
+
+/**
+ * Union-head class safety, the anti-join law's head twin: class-equal
+ * slots, plus same-identity u64 wire when one side is bare. A head cell
+ * is a value that flows to the caller either way — the class is
+ * provenance, not wire shape — and the merged head carries the meet:
+ * a bare rule demotes the column's class claim to bare, so downstream
+ * joins cannot inherit provenance a rule never proved.
+ */
+function headFieldJoins(a: ClassedField, b: ClassedField): boolean {
+	return fieldJoins(a, b) || u64BareWirePair(a, b)
 }
 
 function renderFieldKind(slot: ClassedField): string {
@@ -257,7 +268,6 @@ interface ParamEntry {
 
 export type {
 	AntiJoinOk,
-	AnyTerm,
 	AnyVar,
 	ClassedField,
 	ExactVars,
@@ -266,7 +276,6 @@ export type {
 	JoinOk,
 	MatchFields,
 	MatchOwner,
-	MintClassOf,
 	MintSlotOf,
 	Param,
 	ParamEntry,
@@ -274,8 +283,18 @@ export type {
 	ParamValueAt,
 	SetParam,
 	ShapeOf,
-	UnionToIntersection,
 	Var,
 	VarsOf
 }
-export { fieldAntiJoins, fieldJoins, inferred, isTerm, makeParam, makeSetParam, renderFieldKind, term, v }
+export {
+	fieldAntiJoins,
+	fieldJoins,
+	headFieldJoins,
+	inferred,
+	isTerm,
+	makeParam,
+	makeSetParam,
+	renderFieldKind,
+	term,
+	v
+}

package/src/spec.ts

@@ -233,7 +233,6 @@ function renderWeight(weight: WeightSpec): string {
 export type {
 	CapacityBoundSpec,
 	CapacityWindowSpec,
-	ClosedSpec,
 	FieldSpec,
 	LiteralSetSpec,
 	LiteralSpec,

package/src/statements.ts

@@ -12,7 +12,7 @@ import {
 } from "#capacity.ts"
 import { isClosedMember, sealedFieldOf } from "#closed.ts"
 import { type AnyFace, type FaceData, renderFace, type SameArity, type SameShapes } from "#face.ts"
-import { type ClosedRoster, rosterOf } from "#fields.ts"
+import { type AnyClosedRoster, rosterOf, rostersAgree } from "#fields.ts"
 import type { AnyRelation, RelationFields } from "#relation.ts"
 import { type CapacityWindowSpec, renderCapacityWindow, renderWeight, type WeightSpec } from "#spec.ts"
 
@@ -67,7 +67,7 @@ interface KeyStatement<R extends AnyRelation, Projection extends readonly string
 	readonly data: KeyData<R, Projection>
 }
 
-function renderRosterSide(roster: ClosedRoster | undefined): string {
+function renderRosterSide(roster: AnyClosedRoster | undefined): string {
 	return roster === undefined ? "a bare column" : `a ${roster.name} reference`
 }
 
@@ -96,7 +96,7 @@ function assertRosterAgreement(source: FaceData, target: FaceData, statement: St
 		}
 		const sourceRoster = rosterOf(sealedFieldOf(source.owner, fieldName))
 		const targetRoster = rosterOf(sealedFieldOf(target.owner, targetField))
-		if (sourceRoster !== targetRoster) {
+		if (!rostersAgree(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)}`
 			)
@@ -312,7 +312,6 @@ export type {
 	ContainmentData,
 	KeyData,
 	KeyStatement,
-	MirrorsData,
 	Statement,
 	StatementData
 }