@bjornpagen/bumbledb 0.1.0

package/src/query/predicate.ts

@@ -0,0 +1,195 @@
+/**
+ * IDB predicates (PRD-08) — engine recursion as values, mirroring the IR's
+ * cut exactly (`ir::Program`/`PredicateDef`/`AtomSource::Idb`;
+ * `docs/architecture/20-query-ir.md` § engine recursion): `$.predicate`
+ * declares a predicate with a named, field-typed head; its rules are given
+ * IN the declaration (a callback receiving the predicate's own reference,
+ * so self-recursion is writable and the rules are data the type system can
+ * see — the params they use flow into the query's inferred `Params`); and
+ * `.match({...})` uses it as a body atom, bindings addressing head
+ * positions by the declared column names (lowered positionally —
+ * `FieldId(i)` is head position i, exactly as the IR reads it). Strata
+ * legality (no negation/aggregation through a cycle) is the ENGINE's
+ * judge; its typed error surfaces at prepare.
+ */
+
+import * as errors from "@superbuilders/errors"
+import { phantom } from "#brand.ts"
+import { assertDeclarationOrderKey, type FieldData } from "#fields.ts"
+import type { AnyBodyItem, BindingsParams, MatchAtom, TermInput } from "#query/atom.ts"
+import { resolveBindings } from "#query/atom.ts"
+import type { AnyVar, Flatten, ItemParams, ParamsRecord, ParamsShape, QueryRegistry, Var } from "#query/scope.ts"
+import { isTerm, resolveFieldData, term } from "#query/scope.ts"
+import type { FieldRef } from "#relation.ts"
+
+/** One declared head column: name plus the field description that types it. */
+interface PredicateColumn {
+	readonly name: string
+	readonly data: FieldData
+}
+
+/** One clause of a predicate: head projections (column order) and the body. */
+interface PredicateRuleData {
+	readonly finds: readonly AnyVar[]
+	readonly body: readonly AnyBodyItem[]
+}
+
+/** A predicate's runtime description; identity keys the dense `PredId` at lowering. */
+interface PredicateData {
+	readonly name: string
+	readonly columns: readonly PredicateColumn[]
+	readonly rules: readonly PredicateRuleData[]
+}
+
+/** Any field reference, whatever its brand — the column-declaration position. */
+type AnyFieldRef = FieldRef<string, string, unknown>
+
+/** The columns record `$.predicate` takes: column name to typing field reference. */
+type PredicateColumnsInput = Readonly<Record<string, AnyFieldRef>>
+
+/** Extracts a field reference's host value type. */
+type RefValue<T> = T extends { readonly [phantom]?: infer V } ? Exclude<V, undefined> : never
+
+/** The head's typed column record, derived from the declaration. */
+type ColumnValues<Cols> = { [K in keyof Cols]: RefValue<Cols[K]> }
+
+/**
+ * The `.match` bindings of a predicate atom: per head column, a term of
+ * the column's brand; unmentioned columns are wildcards, exactly as
+ * relation atoms.
+ */
+type PredicateBindings<ColsV> = { readonly [K in keyof ColsV]?: TermInput<ColsV[K]> }
+
+/**
+ * One rule of a predicate as the declaration callback returns it: `finds`
+ * names the projected variable per head column (interior heads project
+ * bound variables only — the creation quarantine; the engine's strata
+ * judge enforces it), `body` is the clause's conjunction.
+ */
+interface PredicateRuleInput<ColsV> {
+	readonly finds: { readonly [K in keyof ColsV]: Var<ColsV[K]> }
+	readonly body: readonly AnyBodyItem[]
+}
+
+/**
+ * The predicate's own reference, passed INTO its rules callback — the
+ * fixpoint spelling: `self.match({...})` inside a rule of the same
+ * predicate is the recursive atom.
+ */
+interface PredicateSelf<ColsV> {
+	readonly data: PredicateData
+	match<const B extends PredicateBindings<ColsV>>(bindings: B): MatchAtom<BindingsParams<B>>
+}
+
+/**
+ * A declared predicate. `.match({...})` uses it as a body atom — in
+ * another predicate's rules or in the output rules; the phantom `P`
+ * carries the params its own rules contributed, so a query's `Params`
+ * type sees through predicates it only reaches transitively.
+ */
+interface Predicate<ColsV, P extends ParamsRecord> {
+	readonly data: PredicateData
+	match<const B extends PredicateBindings<ColsV>>(bindings: B): MatchAtom<Flatten<P & BindingsParams<B>>>
+}
+
+/** The params contributed by a predicate's declared rules. */
+type PredicateParams<Rules extends readonly { readonly body: readonly AnyBodyItem[] }[]> = ParamsShape<
+	ItemParams<Rules[number]["body"][number]>
+>
+
+/** Builds one predicate atom (shared by `self.match` and `.match`). */
+function predicateAtom(data: PredicateData, bindings: Readonly<Record<string, unknown>>): MatchAtom<never> {
+	return Object.freeze({
+		item: "atom" as const,
+		negated: false,
+		source: Object.freeze({ kind: "predicate" as const, pred: data }),
+		bindings: resolveBindings(
+			`predicate ${data.name}`,
+			data.columns.map(function asField(column) {
+				return { name: column.name, field: column.data }
+			}),
+			bindings
+		)
+	})
+}
+
+/**
+ * Declares one predicate in the scope (the `$.predicate` implementation):
+ * resolves the head columns, runs the rules callback against the
+ * predicate's own reference, verifies every rule projects a declared
+ * scope variable per column, and registers the predicate in declaration
+ * order (= its dense `PredId`).
+ */
+function makePredicate<
+	const Cols extends PredicateColumnsInput,
+	const Rules extends readonly PredicateRuleInput<ColumnValues<Cols>>[]
+>(
+	registry: QueryRegistry,
+	name: string,
+	columns: Cols,
+	rules: (self: PredicateSelf<ColumnValues<Cols>>) => Rules
+): Predicate<ColumnValues<Cols>, PredicateParams<Rules>> {
+	const ordered: PredicateColumn[] = []
+	for (const [columnName, ref] of Object.entries(columns)) {
+		assertDeclarationOrderKey(`predicate ${name} column`, columnName)
+		ordered.push(
+			Object.freeze({
+				name: columnName,
+				data: resolveFieldData(registry.theory, ref.relation, ref.field)
+			})
+		)
+	}
+	if (ordered.length === 0) {
+		throw errors.new(`predicate ${name}: a predicate head needs at least one column`)
+	}
+	const ruleSlots: PredicateRuleData[] = []
+	const data: PredicateData = Object.freeze({
+		name,
+		columns: Object.freeze(ordered),
+		rules: ruleSlots
+	})
+	const self: PredicateSelf<ColumnValues<Cols>> = Object.freeze({
+		data,
+		match(bindings: Readonly<Record<string, unknown>>) {
+			return predicateAtom(data, bindings)
+		}
+	})
+	const declared = rules(self)
+	for (const rule of declared) {
+		const finds: AnyVar[] = []
+		const record: Readonly<Record<string, unknown>> = Object.fromEntries(Object.entries(rule.finds))
+		for (const column of ordered) {
+			const found = record[column.name]
+			if (!isTerm(found) || found[term] !== "var") {
+				throw errors.new(
+					`predicate ${name}: rule finds must project a scope variable for column ${column.name} (interior heads project bound variables only)`
+				)
+			}
+			finds.push(found)
+		}
+		ruleSlots.push(Object.freeze({ finds: Object.freeze(finds), body: Object.freeze([...rule.body]) }))
+	}
+	Object.freeze(ruleSlots)
+	registry.predicates.push(data)
+	return Object.freeze({
+		data,
+		match(bindings: Readonly<Record<string, unknown>>) {
+			return predicateAtom(data, bindings)
+		}
+	})
+}
+
+export type {
+	AnyFieldRef,
+	ColumnValues,
+	Predicate,
+	PredicateBindings,
+	PredicateColumn,
+	PredicateColumnsInput,
+	PredicateData,
+	PredicateParams,
+	PredicateRuleData,
+	PredicateRuleInput,
+	PredicateSelf
+}
+export { makePredicate }

package/src/query/run.ts

@@ -0,0 +1,106 @@
+/**
+ * Prepared-query marshaling seams (PRD-08), the two rides every execution
+ * takes — the typed params object down to the bridge's positional
+ * `QueryParam[]` (declaration order = dense `ParamId`s, values tagged by
+ * each param's declaring field), and answer rows (positional, head order)
+ * back up to plain objects with branded values (the store is the proof
+ * carrier: the engine computed the answer, so readback asserts the brand,
+ * the same trust direction as fact readback in `#marshal.ts`). Answers are
+ * SETS — no order or limit exists anywhere; hosts sort. The `Prepared`
+ * VALUE itself (no lifecycle, GC-reclaimed plan) lives in `#db.ts`.
+ */
+
+import * as errors from "@superbuilders/errors"
+import type { FactValue, QueryParam, TaggedValue } from "#native.ts"
+import type { SelectColumn } from "#query/lower.ts"
+import { taggedLiteral } from "#query/lower.ts"
+import type { ParamEntry } from "#query/scope.ts"
+
+/** The 13-bit Allen mask ceiling (`bumbledb/crates/bumbledb/src/allen.rs`: bits above the low 13 are unrepresentable). */
+const ALLEN_ALL_BITS = (1 << 13) - 1
+
+/** Tags one supplied mask-param value. */
+function wireMask(name: string, value: unknown): TaggedValue {
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > ALLEN_ALL_BITS) {
+		throw errors.new(`param ${name}: an Allen-mask param binds a 13-bit mask number built from the ALLEN constants`)
+	}
+	return { kind: "allenMask", mask: value }
+}
+
+/**
+ * Marshals the typed params object to the bridge's positional arguments,
+ * in param declaration order (= the lowering's dense `ParamId`s). A
+ * missing entry is a typed error naming the param; values tag by the
+ * declaring field's structural type; a set param takes a readonly array
+ * (the empty set is legal and matches nothing — the engine's rule).
+ */
+function wireParams(entries: readonly ParamEntry[], supplied: Readonly<Record<string, unknown>>): QueryParam[] {
+	return entries.map(function wireOne(entry): QueryParam {
+		const value = supplied[entry.name]
+		if (value === undefined) {
+			throw errors.new(`execute params object is missing param ${entry.name}`)
+		}
+		if (entry.shape === "mask") {
+			return wireMask(entry.name, value)
+		}
+		if (entry.data === undefined) {
+			throw errors.new(`param ${entry.name}: registry entry carries no declaring field`)
+		}
+		if (entry.shape === "set") {
+			if (!Array.isArray(value)) {
+				throw errors.new(`param ${entry.name}: a set param binds a readonly array of values`)
+			}
+			const data = entry.data
+			return {
+				kind: "set",
+				values: value.map(function wireElement(element, index) {
+					return taggedLiteral(`param ${entry.name}[${index}]`, data, element)
+				})
+			}
+		}
+		return taggedLiteral(`param ${entry.name}`, entry.data, value)
+	})
+}
+
+/**
+ * The read-side trusted seam of answers: a decoded row carrying every
+ * select column IS a `Row` — the engine computed it under the prepared
+ * head, so the brands are asserted, not re-derived (the `#marshal.ts`
+ * trust direction).
+ */
+function isAnswerRow<Row>(
+	select: readonly SelectColumn[],
+	decoded: Readonly<Record<string, FactValue>>
+): decoded is Readonly<Record<string, FactValue>> & Row {
+	return select.every(function present(column) {
+		return decoded[column.name] !== undefined
+	})
+}
+
+/**
+ * Decodes positional answer rows (column order = the program's head order
+ * = the select record's written order) to named, branded, frozen row
+ * objects.
+ */
+function decodeAnswers<Row>(select: readonly SelectColumn[], rows: FactValue[][]): Row[] {
+	return rows.map(function decodeRow(row) {
+		if (row.length !== select.length) {
+			throw errors.new(`query answer arity ${row.length} does not match the ${select.length} select columns`)
+		}
+		const decoded: Record<string, FactValue> = {}
+		select.forEach(function decodeCell(column, ordinal) {
+			const cell = row[ordinal]
+			if (cell === undefined) {
+				throw errors.new(`query answer cell ${ordinal} (${column.name}) is absent`)
+			}
+			decoded[column.name] = cell
+		})
+		Object.freeze(decoded)
+		if (!isAnswerRow<Row>(select, decoded)) {
+			throw errors.new("query answer row is not a complete select record")
+		}
+		return decoded
+	})
+}
+
+export { decodeAnswers, wireParams }

package/src/query/scope.ts

@@ -0,0 +1,301 @@
+/**
+ * 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.
+ */
+
+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"
+
+/**
+ * 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.
+ */
+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.
+ */
+interface Var<V> {
+	readonly [term]: "var"
+	readonly relation: string
+	readonly field: string
+	readonly data: FieldData
+	readonly [phantom]?: V
+}
+
+/**
+ * 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.
+ */
+interface Param<Name extends string, V> {
+	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.
+ */
+interface ParamSet<Name extends string, V> {
+	readonly [term]: "paramSet"
+	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
+ * mask questions per execution. Bound to a 13-bit mask number built from
+ * the `ALLEN` constants.
+ */
+interface MaskParam<Name extends 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>
+
+/** Any scope term value. */
+type AnyTerm = AnyVar | AnyParamTerm
+
+/** Narrows an unknown binding 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>>
+
+/** 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
+
+/**
+ * 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.
+ */
+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>
+
+/**
+ * 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 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>
+
+/** One registered parameter: name, wire shape, and the declaring field. */
+interface ParamEntry {
+	readonly name: string
+	readonly shape: "value" | "set" | "mask"
+	readonly data: FieldData | 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).
+ */
+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: []
+	}
+}
+
+/**
+ * The relation-kind discriminant: a closed relation's runtime description
+ * carries its handle roster, an ordinary relation's never does.
+ */
+function isClosedMember(member: SchemaRelation): member is AnyClosed {
+	return "handles" in member.data
+}
+
+/**
+ * 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).
+ */
+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
+}
+
+/** 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`
+		)
+	}
+}
+
+/** 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
+}
+
+/** 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
+}
+
+/** 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
+}
+
+export type {
+	AnyParamTerm,
+	AnyTerm,
+	AnyVar,
+	Flatten,
+	ItemParams,
+	MaskParam,
+	Param,
+	ParamEntry,
+	ParamSet,
+	ParamsRecord,
+	ParamsShape,
+	QueryRegistry,
+	TermContribution,
+	UnionToIntersection,
+	Var
+}
+export { createRegistry, isTerm, resolveFieldData, scopeAllenParam, scopeParam, scopeParamSet, scopeVar, term }