@bjornpagen/bumbledb 0.1.0 → 0.2.0

package/src/query/predicate.ts

@@ -1,195 +1,232 @@
 /**
- * IDB predicates (PRD-08) — engine recursion as values, mirroring the IR's
+ * Stratified recursion — 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.
+ * `docs/architecture/20-query-ir.md` § engine recursion):
+ *
+ *   program(S, (p) => {
+ *     const reach = p.rec("reach")
+ *     reach.rule((r) => r.match(Node, { id: r.var("c") })
+ *       .where(r.eq(r.var("c"), r.param("root"))).select("c"))
+ *     reach.rule((r) => r.match(Parent, { child: r.var("c"), parent: r.var("m") })
+ *       .idb(reach, r.var("m")).select("c"))
+ *     return p.output((r) => r.match(Posting, { account: r.var("a"), minor: r.var("m") })
+ *       .idb(reach, r.var("a")).select(r.sum("m")))
+ *   })
+ *
+ * `p.rec(name)` declares one recursive predicate (declaration order = its
+ * dense `PredId`); `rec.rule(...)` attaches one clause — its builder's
+ * `idb` accepts ONLY the rec itself (the self-recursion cut as a
+ * type-level boundary: mutual recursion is unwritable) and its head
+ * projects bound variable NAMES only (aggregation/measure through a cycle
+ * is unrepresentable — the strata judge's roster, made unwritable);
+ * `p.output(...)` seals the recs and builds the output rules, whose `idb`
+ * folds any FINISHED stratum (recipe 25's form). The rec value `.rule`
+ * returns carries the params its rules used — thread it into the output's
+ * `idb` and the program's inferred `Params` stays exactly the params the
+ * rules use. Everything deeper — strata legality, signature sealing, the
+ * three oracles — is the ENGINE's judge, surfacing typed 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"
+import type { RecData } from "#query/atom.ts"
+import type {
+	AnyRuleValue,
+	HeadOf,
+	HeadShape,
+	OutputRuleScope,
+	ParamsOf,
+	ProgramState,
+	Query,
+	RawScope,
+	RecRef,
+	RecRuleScope,
+	RowOf,
+	RuleValue
+} from "#query/lower.ts"
+import { makeOutputRuleScope, makeQuery, makeRawScope } from "#query/lower.ts"
+import type { Flatten, ParamsRecord, ShapeOf } from "#query/scope.ts"
+import { inferred } from "#query/scope.ts"
+import type { Schema, SchemaRelations } from "#schema.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[]
+/**
+ * One recursive predicate HANDLE: `rec.rule(...)` attaches a clause and
+ * returns the SAME rec under a widened params type (the runtime data is
+ * shared — either handle is the self-reference; the returned one carries
+ * the rules' params for the output to thread) and under the head signature
+ * the FIRST rule sealed (every later rule derives the same head — the
+ * runtime alignment check's law), so a threaded handle's `idb` joins are
+ * arity- and domain-checked against the head.
+ */
+interface Rec<
+	Rels extends SchemaRelations,
+	Name extends string,
+	P extends ParamsRecord,
+	Head extends HeadShape = undefined
+> extends RecRef<Name, P, Head> {
+	rule<RV extends AnyRuleValue>(
+		build: (r: RecRuleScope<Rels, Name>) => RV
+	): Rec<Rels, Name, Flatten<P & ParamsOf<RV>>, Head extends undefined ? HeadOf<RV> : Head>
+	readonly [inferred]?: { readonly params: P; readonly head: Head }
 }
 
-/** Any field reference, whatever its brand — the column-declaration position. */
-type AnyFieldRef = FieldRef<string, string, unknown>
+/** One output-rule builder function. */
+type OutputBuild<Rels extends SchemaRelations> = (r: OutputRuleScope<Rels>) => AnyRuleValue
 
-/** The columns record `$.predicate` takes: column name to typing field reference. */
-type PredicateColumnsInput = Readonly<Record<string, AnyFieldRef>>
+/** A build function's rule value. */
+type BuiltRule<F> = F extends (r: never) => infer RV ? RV : never
 
-/** Extracts a field reference's host value type. */
-type RefValue<T> = T extends { readonly [phantom]?: infer V } ? Exclude<V, undefined> : never
+/** The union row of a tuple of output builds. */
+type OutputRow<Builds extends readonly OutputBuild<SchemaRelations>[]> = RowOf<BuiltRule<Builds[number]>>
 
-/** The head's typed column record, derived from the declaration. */
-type ColumnValues<Cols> = { [K in keyof Cols]: RefValue<Cols[K]> }
+/** The intersected params record of a tuple of output builds. */
+type OutputParams<Builds extends readonly OutputBuild<SchemaRelations>[]> = ShapeOf<ParamsOf<BuiltRule<Builds[number]>>>
 
 /**
- * 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.
+ * The program scope: declare recs, attach their rules, then declare the
+ * output — which seals the recs (a later `rec`/`rule` is a construction
+ * error) and returns the program as an ordinary query value.
  */
-type PredicateBindings<ColsV> = { readonly [K in keyof ColsV]?: TermInput<ColsV[K]> }
+interface ProgramScope<Rels extends SchemaRelations> {
+	/** Declares one recursive predicate; declaration order = its dense `PredId`. */
+	rec<const Name extends string>(name: Name): Rec<Rels, Name, Record<never, never>>
+	/**
+	 * Declares the output predicate (one rule per build; multiple rules =
+	 * set union) and seals the program. Must be what the `program()`
+	 * callback returns.
+	 */
+	output<const Builds extends readonly OutputBuild<Rels>[]>(
+		...builds: Builds
+	): Query<Rels, OutputRow<Builds>, OutputParams<Builds>>
+}
 
-/**
- * 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 runtime rec-handle shape beneath the typed `Rec` face. */
+interface RawRec<Name extends string> {
+	readonly name: Name
+	readonly data: RecData
+	rule(build: (r: RawScope) => RuleValue<never, never>): RawRec<Name>
 }
 
-/**
- * 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>>
+/** Builds the runtime rec handle over shared rec data. */
+function makeRawRec<Name extends string>(state: ProgramState, name: Name, data: RecData): RawRec<Name> {
+	const rec: RawRec<Name> = {
+		name,
+		data,
+		rule(build) {
+			if (state.sealed) {
+				throw errors.new(
+					`rec ${name}: the program's output is already declared — recursive rules attach before p.output`
+				)
+			}
+			const built = build(makeRawScope({ kind: "rec", self: data }))
+			const head = data.rules[0]
+			if (head !== undefined) {
+				const declared = head.select.map(function columnName(column) {
+					return column.name
+				})
+				const candidate = built.rule.select.map(function columnName(column) {
+					return column.name
+				})
+				if (declared.join(", ") !== candidate.join(", ")) {
+					throw errors.new(
+						`rec ${name}: every rule derives the same head — rule 0 projects (${declared.join(", ")}), this rule projects (${candidate.join(", ")})`
+					)
+				}
+			}
+			data.rules.push(built.rule)
+			return makeRawRec<Name>(state, name, data)
+		}
+	}
+	Object.freeze(rec)
+	return rec
 }
 
 /**
- * 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.
+ * The rec handles' trusted admission seam (the `refsComplete` pattern):
+ * the checkable fact — the handle owns exactly the rec data it names — is
+ * verified before the raw handle is admitted at its typed face.
  */
-interface Predicate<ColsV, P extends ParamsRecord> {
-	readonly data: PredicateData
-	match<const B extends PredicateBindings<ColsV>>(bindings: B): MatchAtom<Flatten<P & BindingsParams<B>>>
+function isRecHandle<Rels extends SchemaRelations, Name extends string, P extends ParamsRecord>(
+	data: RecData,
+	rec: RawRec<Name>
+): rec is RawRec<Name> & Rec<Rels, Name, P> {
+	return rec.data === data
 }
 
-/** 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
-		)
-	})
+/** Builds one typed rec handle over shared rec data. */
+function makeRec<Rels extends SchemaRelations, Name extends string, P extends ParamsRecord>(
+	state: ProgramState,
+	name: Name,
+	data: RecData
+): Rec<Rels, Name, P> {
+	const raw = makeRawRec<Name>(state, name, data)
+	if (!isRecHandle<Rels, Name, P>(data, raw)) {
+		throw errors.new(`rec ${name}: handle construction incomplete`)
+	}
+	return raw
 }
 
 /**
- * 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`).
+ * Builds a stratified program over a schema. The callback declares recs
+ * and their rules through the scope and MUST return `p.output(...)` — the
+ * sealed program is an ordinary query value: `db.prepare` lowers it to
+ * the one `ProgramIr` shape the engine executes under the per-stratum
+ * fixpoint driver.
  */
-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") {
+function program<Rels extends SchemaRelations, Q extends Query<Rels, unknown, ParamsRecord>>(
+	theory: Schema<Rels>,
+	build: (p: ProgramScope<Rels>) => Q
+): Q {
+	const state: ProgramState = { recs: [], sealed: false }
+	const names = new Set<string>()
+	const made: { query: unknown } = { query: undefined }
+	const scope: ProgramScope<Rels> = {
+		rec<const Name extends string>(name: Name): Rec<Rels, Name, Record<never, never>> {
+			if (state.sealed) {
+				throw errors.new(`program: the output is already declared — rec ${name} would be unreachable`)
+			}
+			if (names.has(name)) {
 				throw errors.new(
-					`predicate ${name}: rule finds must project a scope variable for column ${column.name} (interior heads project bound variables only)`
+					`program: a rec named ${name} is already declared — rec names are the self-recursion cut's identity`
 				)
 			}
-			finds.push(found)
+			names.add(name)
+			const data: RecData = { name, rules: [] }
+			state.recs.push(data)
+			return makeRec<Rels, Name, Record<never, never>>(state, name, data)
+		},
+		output<const Builds extends readonly OutputBuild<Rels>[]>(
+			...builds: Builds
+		): Query<Rels, OutputRow<Builds>, OutputParams<Builds>> {
+			if (state.sealed) {
+				throw errors.new("program: output is declared once — multiple rules are multiple builds of the one output")
+			}
+			state.sealed = true
+			for (const rec of state.recs) {
+				if (rec.rules.length === 0) {
+					throw errors.new(
+						`program: rec ${rec.name} has no rules — a predicate with no defining clause seals no signature`
+					)
+				}
+				Object.freeze(rec.rules)
+			}
+			if (builds.length === 0) {
+				throw errors.new("program: the output needs at least one rule")
+			}
+			const rules = builds.map(function buildRule(buildOne) {
+				return buildOne(makeOutputRuleScope<Rels>(state)).rule
+			})
+			const q = makeQuery<Rels, OutputRow<Builds>, OutputParams<Builds>>(theory, state.recs, rules)
+			made.query = q
+			return q
 		}
-		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)
-		}
-	})
+	Object.freeze(scope)
+	const result = build(scope)
+	if (made.query !== result) {
+		throw errors.new("program: the build callback must return p.output(...) — the sealed program IS the query value")
+	}
+	return result
 }
 
-export type {
-	AnyFieldRef,
-	ColumnValues,
-	Predicate,
-	PredicateBindings,
-	PredicateColumn,
-	PredicateColumnsInput,
-	PredicateData,
-	PredicateParams,
-	PredicateRuleData,
-	PredicateRuleInput,
-	PredicateSelf
-}
-export { makePredicate }
+export type { OutputBuild, ProgramScope, Rec }
+export { program }

package/src/query/run.ts

@@ -1,19 +1,22 @@
 /**
- * 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`.
+ * Prepared-query marshaling seams, the two rides every execution takes —
+ * the typed params object down to the bridge's positional `QueryParam[]`
+ * (registry order = dense `ParamId`s, values tagged by each param's
+ * ANCHORING use: the field position or comparison sibling that typed it,
+ * op-aware exactly as comparison literals tag), and answer rows
+ * (positional, head order) back up to plain objects of BARE structural
+ * values — the marshal boundary is pure both ways: the engine computed
+ * the answer under the prepared head, so a decoded row that carries every
+ * select column IS a row (the trusted read seam), and nothing is asserted
+ * on any value. 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 { SelectColumn } from "#query/atom.ts"
+import { taggedCmpLiteral } 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). */
@@ -27,12 +30,22 @@ function wireMask(name: string, value: unknown): TaggedValue {
 	return { kind: "allenMask", mask: value }
 }
 
+/** Tags one supplied value-param cell by its anchoring use. */
+function wireValue(entry: ParamEntry, context: string, value: unknown): TaggedValue {
+	if (entry.anchor === undefined) {
+		throw errors.new(
+			`param ${entry.name} has no field-anchored use — bind it in an atom or compare it against a bound variable`
+		)
+	}
+	return taggedCmpLiteral(context, entry.anchor, value, entry.op)
+}
+
 /**
  * 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).
+ * in registry order (= the lowering's dense `ParamId`s). A missing entry
+ * is a typed error naming the param; values tag by the anchoring use'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 {
@@ -43,30 +56,27 @@ function wireParams(entries: readonly ParamEntry[], supplied: Readonly<Record<st
 		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 wireValue(entry, `param ${entry.name}[${index}]`, element)
 				})
 			}
 		}
-		return taggedLiteral(`param ${entry.name}`, entry.data, value)
+		return wireValue(entry, `param ${entry.name}`, 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).
+ * head, and the values are BARE structural values, so nothing is asserted
+ * beyond presence (the store is the proof carrier; no brand exists to
+ * re-derive).
  */
 function isAnswerRow<Row>(
 	select: readonly SelectColumn[],
@@ -79,8 +89,8 @@ function isAnswerRow<Row>(
 
 /**
  * Decodes positional answer rows (column order = the program's head order
- * = the select record's written order) to named, branded, frozen row
- * objects.
+ * = the select's written order) to named, frozen row objects of bare
+ * structural values.
  */
 function decodeAnswers<Row>(select: readonly SelectColumn[], rows: FactValue[][]): Row[] {
 	return rows.map(function decodeRow(row) {