@bjornpagen/bumbledb 0.1.0 → 0.2.0

package/src/query/scope.ts

@@ -1,102 +1,143 @@
 /**
- * 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, STRUCTURAL edition: string-named variables and
+ * parameters as plain frozen values. A `Var` is a NAME — it is typed by the
+ * field it first binds (structurally, off the schema type, through the rule
+ * builder's environment), reuse of the name within one rule IS the join,
+ * and a domain-mismatched reuse is a compile error (the structural analog
+ * of the old brand-equal join — now domain-equal, no value brands
+ * anywhere). 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 → field descriptor), the domain-equality
+ * judgment, 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. */
+/** 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)
+}
+
+/** 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)
+}
+
+/** 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)
+}
+
+/** 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)
+}
+
+/** 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)
+}
+
+/**
+ * A rule's typing environment: variable name → the field descriptor it
+ * first bound. Purely a TYPE — the runtime twin is the rule's `varFields`
+ * record, and the two are built by the same walk.
+ */
+type EnvShape = Record<string, AnyField>
+
+/** A params object type — what `execute` takes and inference carries. */
 type ParamsRecord = Readonly<Record<string, unknown>>
 
 /** Flattens an intersection into one displayed object type (hover legibility). */
@@ -108,194 +149,123 @@ type UnionToIntersection<U> = (U extends unknown ? (member: U) => void : never)
 	: never
 
 /**
- * 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.
+ * Folds a union of per-position record fragments into one flattened record
+ * (the machinery both `Params` and `Row` inference ride).
  */
-type TermContribution<T> = T extends {
-	readonly [term]: "param"
-	readonly name: infer N extends string
-	readonly [phantom]?: infer V
-}
-	? { 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>
+type ShapeOf<U> = [U] extends [never] ? Record<never, never> : Flatten<UnionToIntersection<U>>
 
-/**
- * Folds a union of per-term/per-item params objects into the one flattened
- * params record (the query's `Params` type).
- */
-type ParamsShape<U> = [U] extends [never] ? Record<never, never> : Flatten<UnionToIntersection<U>>
+/** Reads a field descriptor's domain label (S1: the label IS the domain check). */
+type DomainOf<F extends AnyField> = F["domain"]
 
-/** 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>
+/** 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
 
-/** One registered parameter: name, wire shape, and the declaring field. */
-interface ParamEntry {
-	readonly name: string
-	readonly shape: "value" | "set" | "mask"
-	readonly data: FieldData | 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 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).
+ * The structural join judgment: two field descriptors join iff kind,
+ * domain label, width label, and interval element all agree — the
+ * string-literal comparison of descriptor shapes that replaced the value
+ * brand (design ruling 3).
  */
-interface QueryRegistry {
-	readonly theory: AnySchema
-	readonly vars: Set<AnyVar>
-	readonly params: ParamEntry[]
-	readonly paramIndex: Map<AnyTerm, number>
-	readonly predicates: PredicateData[]
-}
-
-/** 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: []
-	}
-}
+type JoinOk<A extends AnyField, B extends AnyField> = [A["kind"], DomainOf<A>, WidthOf<A>, ElementOf<A>] extends [
+	B["kind"],
+	DomainOf<B>,
+	WidthOf<B>,
+	ElementOf<B>
+]
+	? [B["kind"], DomainOf<B>, WidthOf<B>, ElementOf<B>] extends [A["kind"], DomainOf<A>, WidthOf<A>, ElementOf<A>]
+		? true
+		: false
+	: false
 
 /**
- * The relation-kind discriminant: a closed relation's runtime description
- * carries its handle roster, an ordinary relation's never does.
+ * The runtime twin of {@link JoinOk}: two field descriptors join iff kind,
+ * domain label, width label, and interval element all agree — the same
+ * structural comparison the type tier makes, judged on the descriptor
+ * VALUES (S1 descriptors are honest at runtime). The rule builders throw
+ * through this on a domain-unequal variable reuse, so the wall holds for
+ * untyped callers too, not only where the compiler can see.
  */
-function isClosedMember(member: SchemaRelation): member is AnyClosed {
-	return "handles" in member.data
+function fieldJoins(a: AnyField, b: AnyField): boolean {
+	const widthA = "width" in a ? a.width : undefined
+	const widthB = "width" in b ? b.width : undefined
+	const elementA = "element" in a ? a.element : undefined
+	const elementB = "element" in b ? b.element : undefined
+	return a.kind === b.kind && a.domain === b.domain && widthA === widthB && elementA === elementB
 }
 
 /**
- * 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).
+ * Renders one field descriptor for join-mismatch diagnostics — the schema
+ * grammar's own spelling (`u64 as HolderId`, `interval<i64, 7> as Window`).
  */
-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}`)
+function renderFieldKind(field: AnyField): string {
+	let base: string = field.kind
+	if (field.kind === "bytes") {
+		base = `bytes<${field.width}>`
 	}
-	return declared.field
-}
-
-/** A field reference's runtime half, as the scope factories consume it. */
-interface RefNames {
-	readonly relation: string
-	readonly field: string
-}
-
-/** 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
-}
-
-/** 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`
-		)
+	if (field.kind === "interval") {
+		base = field.width === undefined ? `interval<${field.element}>` : `interval<${field.element}, ${field.width}>`
 	}
+	return field.domain === undefined ? base : `${base} as ${field.domain}`
 }
 
-/** 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,
+	DomainOf,
+	Duration,
+	EnvShape,
 	Flatten,
-	ItemParams,
+	InferredOf,
+	JoinOk,
 	MaskParam,
 	Param,
 	ParamEntry,
-	ParamSet,
 	ParamsRecord,
-	ParamsShape,
-	QueryRegistry,
-	TermContribution,
+	ParamValueAt,
+	SetParam,
+	ShapeOf,
 	UnionToIntersection,
 	Var
 }
-export { createRegistry, isTerm, resolveFieldData, scopeAllenParam, scopeParam, scopeParamSet, scopeVar, term }
+export {
+	fieldJoins,
+	inferred,
+	isTerm,
+	makeDuration,
+	makeMaskParam,
+	makeParam,
+	makeSetParam,
+	makeVar,
+	renderFieldKind,
+	term
+}