@bjornpagen/bumbledb 0.1.0 → 0.3.0

package/src/query/scope.ts

@@ -1,301 +1,347 @@
 /**
- * Query scope terms (PRD-08): typed variables and parameters, declared
- * inside a `query()` scope callback so identity is lexical. A `Var` is
- * typed by the field it is declared from and joins are brand-equal by
- * construction (the nominal join discipline); var identity is OBJECT
- * identity — two `$.var` calls are two variables even from the same field,
- * and no name-collision machinery exists. Params are query-global, carry a
- * mandatory literal name (the key of `execute`'s params object), and lower
- * to dense positional `ParamId`s in declaration order. This module also
- * owns the type-level params extraction: every atom and condition value
- * carries its contributed params object in a phantom, and the query's
- * `Params` type is the flattened intersection over the returned rules —
- * inference rides the return value, never a mutable type accumulator.
+ * Query scope terms, LAW-TYPED edition: string-named variables and
+ * parameters as plain frozen values. A `Var` is a NAME — it is typed by the
+ * field slot it first binds (the descriptor AND the slot's law-computed
+ * CLASS, read off the schema's class map through the rule builder's
+ * environment), reuse of the name within one rule IS the join, and a
+ * class-mismatched reuse is a compile error: a var joins only class-equal
+ * slots, and BARE PAIRS ONLY WITH BARE (ruling 3 — a slot in no law has no
+ * class and never joins a classed slot; the deliberate sum-domain pointer
+ * stays legal against other bare slots). Params are query-global by name
+ * and typed BY USE: the field position or comparison sibling that anchors
+ * a param types it, the query's inferred `Params` object is exactly the
+ * params the rules use, and a param value that no rule uses simply never
+ * registers — the query executes under its own inferred type (the
+ * bug-hunt law). This module also owns the environment/typing utilities
+ * the whole surface shares: the env shape (var name → classed slot), the
+ * class-equality judgment {@link JoinOk} with its runtime twin
+ * {@link fieldJoins}, and the record-folding helpers `Params` and `Row`
+ * inference ride.
  */
 
 import * as errors from "@superbuilders/errors"
-import { phantom } from "#brand.ts"
-import type { AnyClosed } from "#closed.ts"
-import type { FieldData } from "#fields.ts"
-import type { PredicateData } from "#query/predicate.ts"
-import type { AnySchema, SchemaRelation } from "#schema.ts"
+import type { AnyField, Infer } from "#fields.ts"
 
 /**
  * The runtime discriminant of query term values. Host literals (bigints,
- * strings, interval objects, `oneOf` sets) never carry it, so "is this
- * binding a term or a literal" is one property probe, never a guess.
+ * strings, interval objects) never carry it, so "is this position a term
+ * or a literal" is one property probe, never a guess.
  */
 const term: unique symbol = Symbol("bumbledb.query.term")
 
 /**
- * A query variable, typed by the field it was declared from
- * (`$.var(Holder.fields.id)` → `Var<Brand<bigint, "HolderId">>`). Usable in
- * any atom position whose field carries the same brand; a brand-mismatched
- * placement is a TYPE error. Identity is object identity.
+ * The carrier of a value's INFERRED types (a rule's row/params, a query's
+ * row/params, a rec's params). The property is never present at runtime —
+ * it exists so inference rides plain values without any brand on any
+ * field value.
  */
-interface Var<V> {
+const inferred: unique symbol = Symbol("bumbledb.query.inferred")
+
+/**
+ * A query variable — a NAME. Its type comes from the field it first binds
+ * in the rule (the builder's environment); reusing the name joins, and a
+ * cross-domain reuse is a compile error. Identity is the name, strictly
+ * rule-scoped: the same name in two rules names two unrelated variables
+ * (exactly as the IR scopes `VarId`).
+ */
+interface Var<Name extends string = string> {
 	readonly [term]: "var"
-	readonly relation: string
-	readonly field: string
-	readonly data: FieldData
-	readonly [phantom]?: V
+	readonly name: Name
 }
 
 /**
- * A scalar query parameter — `$.param("root", Holder.fields.id)`. The name
- * literal is the key of the typed params object `execute` takes; the value
- * is marshaled by the declaring field's structural type at bind.
+ * A scalar query parameter — `r.param("root")`. The name is the key of the
+ * typed params object `execute` takes; the type is the element type of the
+ * position that anchors it (a field binding, or the bound-variable side of
+ * a comparison).
  */
-interface Param<Name extends string, V> {
+interface Param<Name extends string = string> {
 	readonly [term]: "param"
 	readonly name: Name
-	readonly relation: string
-	readonly field: string
-	readonly data: FieldData
-	readonly [phantom]?: V
 }
 
 /**
- * A set-valued query parameter (the IR's `ParamSet` term): bound at
- * execution to an ARRAY of values of the declaring field's type; a binding
- * position matches iff the field value is in the set. Legal in atom
- * bindings (positive and negated) and as the right side of `is` — nowhere
- * else, exactly as the IR rules it.
+ * A set-valued query parameter (the IR's `ParamSet` term) — `r.inSet("frontier")`:
+ * bound at execution to a readonly ARRAY of values of the anchoring field's
+ * type; a binding position matches iff the field value is in the set. Legal
+ * in atom bindings (positive and negated) and as the right side of `eq` —
+ * nowhere else, exactly as the IR rules it.
  */
-interface ParamSet<Name extends string, V> {
-	readonly [term]: "paramSet"
+interface SetParam<Name extends string = string> {
+	readonly [term]: "setParam"
 	readonly name: Name
-	readonly relation: string
-	readonly field: string
-	readonly data: FieldData
-	readonly [phantom]?: V
 }
 
 /**
- * An Allen-mask parameter (the IR's `MaskTerm::Param`): the temporal
- * relation as a bind-time argument — one prepared query answers any of the
+ * An Allen-mask parameter (the IR's `MaskTerm::Param`) — the temporal
+ * relation as a bind-time argument: one prepared query answers any of the
  * mask questions per execution. Bound to a 13-bit mask number built from
  * the `ALLEN` constants.
  */
-interface MaskParam<Name extends string> {
+interface MaskParam<Name extends string = string> {
 	readonly [term]: "maskParam"
 	readonly name: Name
 }
 
-/** Any query variable, whatever its brand. */
-type AnyVar = Var<unknown>
-
-/** Any parameter term of the scope, whatever its name and brand. */
-type AnyParamTerm = Param<string, unknown> | ParamSet<string, unknown> | MaskParam<string>
+/**
+ * The measure of an interval-typed variable (`ir::Term::Measure`):
+ * `|[s, e)| = e − s`, u64 — legal as one side of an order comparison, as a
+ * select entry, and as the input of `sum`/`min`/`max`; every other position
+ * is unwritable, exactly as the IR rejects it typed. A ray has no finite
+ * measure — the engine's `MeasureOfRay` execution error; exclude rays first
+ * (`allen` against a bounded window).
+ */
+interface Duration<Name extends string = string> {
+	readonly [term]: "duration"
+	readonly name: Name
+}
 
 /** Any scope term value. */
-type AnyTerm = AnyVar | AnyParamTerm
+type AnyTerm = Var | Param | SetParam | MaskParam | Duration
 
-/** Narrows an unknown binding value to a scope term (vs a host literal). */
+/** Narrows an unknown position value to a scope term (vs a host literal). */
 function isTerm(value: unknown): value is AnyTerm {
 	return typeof value === "object" && value !== null && term in value
 }
 
-/** A params object type — what `execute` takes and the phantoms carry. */
-type ParamsRecord = Readonly<Record<string, unknown>>
+/** Builds one variable term. */
+function makeVar<const Name extends string>(name: Name): Var<Name> {
+	const value: Var<Name> = { [term]: "var", name }
+	return Object.freeze(value)
+}
 
-/** Flattens an intersection into one displayed object type (hover legibility). */
-type Flatten<T> = { [K in keyof T]: T[K] }
-
-/** The standard union-to-intersection fold (distributes over `U`). */
-type UnionToIntersection<U> = (U extends unknown ? (member: U) => void : never) extends (member: infer I) => void
-	? I
-	: never
+/** The record `makeVars` mints: one own frozen `Var<Name>` per requested name, each typed exactly. */
+type VarsRecord<Names extends string> = { readonly [N in Names]: Var<N> }
 
 /**
- * One term's contribution to the query's params object type: a `Param`
- * contributes its value type under its name, a `ParamSet` the readonly
- * array of it, a `MaskParam` a mask number; everything else contributes
- * nothing.
+ * The trusted seam of the vars mint: every requested name reads back as an
+ * own var term of exactly that name — verified before the record is
+ * admitted at the {@link VarsRecord} type (a name riding the
+ * object-protocol accessor instead of an own definition would fail exactly
+ * this check).
  */
-type TermContribution<T> = T extends {
-	readonly [term]: "param"
-	readonly name: infer N extends string
-	readonly [phantom]?: infer V
+function varsMinted<Names extends string>(
+	record: Readonly<Record<string, unknown>>,
+	names: readonly Names[]
+): record is Readonly<Record<string, unknown>> & VarsRecord<Names> {
+	return names.every(function varMinted(name) {
+		if (!Object.hasOwn(record, name)) {
+			return false
+		}
+		const value = record[name]
+		return isTerm(value) && value[term] === "var" && value.name === name
+	})
 }
-	? { readonly [K in N]: Exclude<V, undefined> }
-	: T extends {
-				readonly [term]: "paramSet"
-				readonly name: infer N extends string
-				readonly [phantom]?: infer V
-			}
-		? { readonly [K in N]: readonly Exclude<V, undefined>[] }
-		: T extends { readonly [term]: "maskParam"; readonly name: infer N extends string }
-			? { readonly [K in N]: number }
-			: Record<never, never>
 
 /**
- * Folds a union of per-term/per-item params objects into the one flattened
- * params record (the query's `Params` type).
+ * Mints several variables at once — `const { service, w } = r.vars("service",
+ * "w")`: tuple-to-object, each name typed exactly (`Var<"service">`),
+ * inference identical to the one-at-a-time `r.var` spelling (one lowering,
+ * two entry flavors). Each key is defined as an OWN property (a name like
+ * `"__proto__"` is a record key like any other, never a prototype write),
+ * and a duplicate name in one call is a construction error: each name mints
+ * one variable — write it once and reuse the binding.
  */
-type ParamsShape<U> = [U] extends [never] ? Record<never, never> : Flatten<UnionToIntersection<U>>
+function makeVars<const Names extends readonly string[]>(...names: Names): VarsRecord<Names[number]> {
+	const out: Record<string, unknown> = {}
+	const seen = new Set<string>()
+	for (const name of names) {
+		if (seen.has(name)) {
+			throw errors.new(
+				`vars: duplicate name ${name} — each name mints one variable; write it once and reuse the binding`
+			)
+		}
+		seen.add(name)
+		Object.defineProperty(out, name, { value: makeVar(name), enumerable: true })
+	}
+	Object.freeze(out)
+	if (!varsMinted<Names[number]>(out, names)) {
+		throw errors.new("vars: variable minting incomplete")
+	}
+	return out
+}
 
-/** Reads an atom's/condition's contributed params object off its phantom. */
-type ItemParams<T> = T extends { readonly [phantom]?: infer P } ? Exclude<P, undefined> : Record<never, never>
+/** Builds one scalar-parameter term. */
+function makeParam<const Name extends string>(name: Name): Param<Name> {
+	const value: Param<Name> = { [term]: "param", name }
+	return Object.freeze(value)
+}
 
-/** One registered parameter: name, wire shape, and the declaring field. */
-interface ParamEntry {
-	readonly name: string
-	readonly shape: "value" | "set" | "mask"
-	readonly data: FieldData | undefined
+/** Builds one set-parameter term. */
+function makeSetParam<const Name extends string>(name: Name): SetParam<Name> {
+	const value: SetParam<Name> = { [term]: "setParam", name }
+	return Object.freeze(value)
 }
 
-/**
- * The mutable build-time registry one `query()` scope owns: declared vars
- * (membership polices cross-scope smuggling), params in declaration order
- * (= dense `ParamId`s), and declared predicates in declaration order
- * (= dense `PredId`s; the output predicate is appended by lowering).
- */
-interface QueryRegistry {
-	readonly theory: AnySchema
-	readonly vars: Set<AnyVar>
-	readonly params: ParamEntry[]
-	readonly paramIndex: Map<AnyTerm, number>
-	readonly predicates: PredicateData[]
+/** Builds one Allen-mask-parameter term. */
+function makeMaskParam<const Name extends string>(name: Name): MaskParam<Name> {
+	const value: MaskParam<Name> = { [term]: "maskParam", name }
+	return Object.freeze(value)
 }
 
-/** Creates one empty scope registry over the query's theory. */
-function createRegistry(theory: AnySchema): QueryRegistry {
-	return {
-		theory,
-		vars: new Set(),
-		params: [],
-		paramIndex: new Map(),
-		predicates: []
-	}
+/** Builds one measure term over an interval-typed variable's name. */
+function makeDuration<const Name extends string>(name: Name): Duration<Name> {
+	const value: Duration<Name> = { [term]: "duration", name }
+	return Object.freeze(value)
 }
 
 /**
- * The relation-kind discriminant: a closed relation's runtime description
- * carries its handle roster, an ordinary relation's never does.
+ * One bound field slot: the field's descriptor plus the slot's
+ * law-computed CLASS (`undefined` = bare — the slot is in no law). The one
+ * shape the rule environment carries per variable, at the TYPE level (env
+ * entries hold the schema type's class-map lookups) and at RUNTIME alike
+ * (the rule's `varFields` record holds exactly this shape, read off the
+ * schema value's frozen class map) — one shape, two tiers, one walk.
  */
-function isClosedMember(member: SchemaRelation): member is AnyClosed {
-	return "handles" in member.data
+interface ClassedField {
+	readonly field: AnyField
+	readonly class: string | undefined
 }
 
 /**
- * Resolves a field reference's runtime description through the schema —
- * the seam that types `$.var`/`$.param` declarations at runtime (the type
- * level already carries the brand; this recovers the structural type the
- * lowering and the param marshaler direct by).
+ * A rule's typing environment: variable name → the classed slot it first
+ * bound. Purely a TYPE — the runtime twin is the rule's `varFields`
+ * record, and the two are built by the same walk.
  */
-function resolveFieldData(theory: AnySchema, relationName: string, fieldName: string): FieldData {
-	const member: SchemaRelation | undefined = theory.relations[relationName]
-	if (member === undefined) {
-		throw errors.new(`schema ${theory.name} has no relation ${relationName}`)
-	}
-	if (isClosedMember(member)) {
-		if (fieldName === "id") {
-			return member.id.data
-		}
-		const column = member.data.columns.find(function byName(candidate) {
-			return candidate.name === fieldName
-		})
-		if (column === undefined) {
-			throw errors.new(`closed relation ${relationName} has no column ${fieldName}`)
-		}
-		return column.field
-	}
-	const declared = member.data.fields.find(function byName(candidate) {
-		return candidate.name === fieldName
-	})
-	if (declared === undefined) {
-		throw errors.new(`relation ${relationName} has no field ${fieldName}`)
-	}
-	return declared.field
-}
+type EnvShape = Record<string, ClassedField>
 
-/** A field reference's runtime half, as the scope factories consume it. */
-interface RefNames {
-	readonly relation: string
-	readonly field: string
-}
+/** A params object type — what `execute` takes and inference carries. */
+type ParamsRecord = Readonly<Record<string, unknown>>
 
-/** Declares one variable in the scope (the `$.var` implementation). */
-function scopeVar<V>(registry: QueryRegistry, ref: RefNames): Var<V> {
-	const value: Var<V> = Object.freeze({
-		[term]: "var" as const,
-		relation: ref.relation,
-		field: ref.field,
-		data: resolveFieldData(registry.theory, ref.relation, ref.field)
-	})
-	registry.vars.add(value)
-	return value
+/** Flattens an intersection into one displayed object type (hover legibility). */
+type Flatten<T> = { [K in keyof T]: T[K] }
+
+/** The standard union-to-intersection fold (distributes over `U`). */
+type UnionToIntersection<U> = (U extends unknown ? (member: U) => void : never) extends (member: infer I) => void
+	? I
+	: never
+
+/**
+ * Folds a union of per-position record fragments into one flattened record
+ * (the machinery both `Params` and `Row` inference ride).
+ */
+type ShapeOf<U> = [U] extends [never] ? Record<never, never> : Flatten<UnionToIntersection<U>>
+
+/** Reads a field descriptor's width label (`bytes<N>`, `interval<E, W>`); `undefined` when the kind carries none. */
+type WidthOf<F extends AnyField> = F extends { readonly width: infer W } ? W : undefined
+
+/** Reads an interval descriptor's element kind; `undefined` on scalar kinds. */
+type ElementOf<F extends AnyField> = F extends { readonly element: infer E } ? E : 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.
+ */
+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 [
+			A["field"]["kind"],
+			A["class"],
+			WidthOf<A["field"]>,
+			ElementOf<A["field"]>
+		]
+		? true
+		: false
+	: false
+
+/**
+ * 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
+ * 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.
+ */
+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
+	return a.field.kind === b.field.kind && a.class === b.class && widthA === widthB && elementA === elementB
 }
 
-/** Rejects a second parameter under an already-taken name. */
-function assertFreshParamName(registry: QueryRegistry, name: string): void {
-	const taken = registry.params.some(function byName(entry) {
-		return entry.name === name
-	})
-	if (taken) {
-		throw errors.new(
-			`query scope already declares a param named ${name} — param names key the execute params object, one declaration each`
-		)
+/**
+ * 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`).
+ */
+function renderFieldKind(slot: ClassedField): string {
+	const field = slot.field
+	let base: string = field.kind
+	if (field.kind === "bytes") {
+		base = `bytes<${field.width}>`
+	}
+	if (field.kind === "interval") {
+		base = field.width === undefined ? `interval<${field.element}>` : `interval<${field.element}, ${field.width}>`
 	}
+	return slot.class === undefined ? `${base} (bare)` : `${base} in class ${slot.class}`
 }
 
-/** Declares one scalar parameter (the `$.param` implementation). */
-function scopeParam<Name extends string, V>(registry: QueryRegistry, name: Name, ref: RefNames): Param<Name, V> {
-	assertFreshParamName(registry, name)
-	const data = resolveFieldData(registry.theory, ref.relation, ref.field)
-	const value: Param<Name, V> = Object.freeze({
-		[term]: "param" as const,
-		name,
-		relation: ref.relation,
-		field: ref.field,
-		data
-	})
-	registry.paramIndex.set(value, registry.params.length)
-	registry.params.push(Object.freeze({ name, shape: "value" as const, data }))
-	return value
-}
+/**
+ * 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
+ * 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.
+ */
+type ParamValueAt<F extends AnyField> = Infer<F>
 
-/** Declares one set parameter (the `$.paramSet` implementation). */
-function scopeParamSet<Name extends string, V>(registry: QueryRegistry, name: Name, ref: RefNames): ParamSet<Name, V> {
-	assertFreshParamName(registry, name)
-	const data = resolveFieldData(registry.theory, ref.relation, ref.field)
-	const value: ParamSet<Name, V> = Object.freeze({
-		[term]: "paramSet" as const,
-		name,
-		relation: ref.relation,
-		field: ref.field,
-		data
-	})
-	registry.paramIndex.set(value, registry.params.length)
-	registry.params.push(Object.freeze({ name, shape: "set" as const, data }))
-	return value
-}
+/** Reads a value's inferred-types carrier (rules, queries, recs). */
+type InferredOf<T> = T extends { readonly [inferred]?: infer S } ? Exclude<S, undefined> : never
 
-/** Declares one Allen-mask parameter (the `$.allenParam` implementation). */
-function scopeAllenParam<Name extends string>(registry: QueryRegistry, name: Name): MaskParam<Name> {
-	assertFreshParamName(registry, name)
-	const value: MaskParam<Name> = Object.freeze({ [term]: "maskParam" as const, name })
-	registry.paramIndex.set(value, registry.params.length)
-	registry.params.push(Object.freeze({ name, shape: "mask" as const, data: undefined }))
-	return value
+/**
+ * One registered parameter of a query, as the wire marshal reads it: the
+ * name, the wire shape, the field descriptor (or the measure) that anchored
+ * it, and the comparison op the anchor came from (`"binding"` for atom
+ * 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.
+ */
+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"
 }
 
 export type {
-	AnyParamTerm,
 	AnyTerm,
-	AnyVar,
+	ClassedField,
+	Duration,
+	EnvShape,
 	Flatten,
-	ItemParams,
+	InferredOf,
+	JoinOk,
 	MaskParam,
 	Param,
 	ParamEntry,
-	ParamSet,
 	ParamsRecord,
-	ParamsShape,
-	QueryRegistry,
-	TermContribution,
+	ParamValueAt,
+	SetParam,
+	ShapeOf,
 	UnionToIntersection,
-	Var
+	Var,
+	VarsRecord
+}
+export {
+	fieldJoins,
+	inferred,
+	isTerm,
+	makeDuration,
+	makeMaskParam,
+	makeParam,
+	makeSetParam,
+	makeVar,
+	makeVars,
+	renderFieldKind,
+	term
 }
-export { createRegistry, isTerm, resolveFieldData, scopeAllenParam, scopeParam, scopeParamSet, scopeVar, term }