@bjornpagen/bumbledb 1.1.0 → 1.2.0

package/src/native.ts

@@ -663,6 +663,7 @@ export type {
 	FindTermIr,
 	HeadOpIr,
 	HeadTermIr,
+	InteriorIr,
 	IntervalValue,
 	LogAccess,
 	LogActivation,
@@ -692,6 +693,7 @@ export type {
 	PrepareKind,
 	QueryIr,
 	QueryParam,
+	RecIr,
 	RuleIr,
 	ScalarExprIr,
 	SealedDescriptor,

package/src/query/atom.ts

@@ -582,6 +582,7 @@ type CondParamsShape<C> = ShapeOf<CondParams<C>>
 export type {
 	AggData,
 	AnyCond,
+	AnyTreeChild,
 	AtomData,
 	BindingEntry,
 	BindingInput,

package/src/query/description.ts

@@ -0,0 +1,394 @@
+import { isDeepStrictEqual } from "node:util"
+import { sealedFieldsOf } from "#closed.ts"
+import { AuthoringError } from "#errors.ts"
+import { type AnyField, fieldDescriptor, type Infer, rosterOf, signaturesAgree } from "#fields.ts"
+import type { SchemaClasses } from "#law.ts"
+import type { AtomIr, ConditionTreeIr, QueryIr, RuleIr, ScalarExprIr, TaggedValue, TermIr } from "#native.ts"
+import type { AnyTreeChild, DerivedTable, FindColumn, InteriorData, RecData, RuleData } from "#query/atom.ts"
+import type { QueryNode } from "#query/compute.ts"
+import type { AnyQuery, ChainContext, Query } from "#query/lower.ts"
+import { alignedHeadOf, EMPTY_RULE, lowerQuery, makeRawChain, makeRawQuery, taggedCmpLiteral } from "#query/lower.ts"
+import { parseQueryIr } from "#query/parse-ir.ts"
+import { type AnyVar, type MatchOwner, makeParam, makeSetParam, type ParamsRecord, v } from "#query/scope.ts"
+import type { FieldsShape } from "#relation.ts"
+import { handleOf } from "#rows.ts"
+import { queryVarLeaf, scalarBinary, scalarCast, scalarFloatPredicate, scalarLiteral, scalarNegate } from "#scalar.ts"
+import type { Schema, SchemaRelations } from "#schema.ts"
+import { schemaDescriptor } from "#schema.ts"
+import { arrayValue, recordValue, valueDescriptor } from "#values.ts"
+
+/** Logical ordinals are scoped to this description and the schema's ordered declarations. */
+interface QueryDescription {
+	readonly ir: QueryIr
+	readonly columns: readonly string[]
+	readonly interiors: readonly DescriptionTable[]
+	readonly recursion: DescriptionTable | undefined
+	readonly parameters: readonly DescriptionParameter[]
+}
+
+interface DescriptionTable {
+	readonly name: string
+	readonly columns: readonly string[]
+}
+
+interface DescriptionParameter {
+	readonly name: string
+	/** Closed-membership literals generated by the typed builder; absent for supplied parameters. */
+	readonly members: readonly TaggedValue[] | undefined
+}
+
+type DescriptionRow<F extends FieldsShape> = { readonly [K in keyof F]: Infer<F[K]> }
+
+function refused(context: string, expected: string): never {
+	throw new AuthoringError({
+		message: `${context}: ${expected}`,
+		diagnostic: { code: "InvalidQuery", context, expected }
+	})
+}
+
+function name(context: string, input: unknown): string {
+	if (typeof input !== "string" || !input.isWellFormed()) return refused(context, "expected a well-formed string name")
+	return input
+}
+
+function names(context: string, input: unknown): readonly string[] {
+	const values = arrayValue(context, input, name)
+	if (new Set(values).size !== values.length) refused(context, "names must be unique")
+	return values
+}
+
+function table(context: string, input: unknown): DescriptionTable {
+	const raw = recordValue(context, input, ["name", "columns"])
+	return Object.freeze({ name: name(`${context}.name`, raw.name), columns: names(`${context}.columns`, raw.columns) })
+}
+
+function checkedDescription(input: unknown): QueryDescription {
+	const raw = recordValue("query description", input, ["ir", "columns", "interiors", "recursion", "parameters"])
+	const ir = parseQueryIr(raw.ir)
+	const columns = names("query columns", raw.columns)
+	if (columns.length !== ir.head.length) refused("query columns", "column names must match the query head width")
+	const interiors = arrayValue("query interiors", raw.interiors, table)
+	if (interiors.length !== ir.interiors.length) refused("query interiors", "names must match the IR interiors")
+	for (const [ordinal, interior] of interiors.entries()) {
+		if (interior.columns.length !== ir.interiors[ordinal]?.head.length)
+			refused(`query interiors[${ordinal}]`, "column names must match the interior head width")
+	}
+	const recursion = raw.recursion === undefined ? undefined : table("query recursion", raw.recursion)
+	if (
+		ir.kind === "cq"
+			? recursion !== undefined
+			: recursion === undefined || recursion.columns.length !== ir.rec.head.length
+	)
+		refused("query recursion", "recursion names must match the IR recursion head")
+	const tableNames = [...interiors.map((entry) => entry.name), ...(recursion === undefined ? [] : [recursion.name])]
+	if (new Set(tableNames).size !== tableNames.length) refused("query tables", "names must be unique")
+	const parameters = arrayValue("query parameters", raw.parameters, (context, value): DescriptionParameter => {
+		const record = recordValue(context, value, ["name", "members"])
+		return Object.freeze({
+			name: name(`${context}.name`, record.name),
+			members:
+				record.members === undefined ? undefined : arrayValue(`${context}.members`, record.members, valueDescriptor)
+		})
+	})
+	if (new Set(parameters.map((entry) => entry.name)).size !== parameters.length)
+		refused("query parameters", "names must be unique")
+	return Object.freeze({ ir, columns, interiors, recursion, parameters })
+}
+
+/** Return an owned logical description; no builder variables or native resource handles escape. */
+function describeQuery(query: AnyQuery): QueryDescription {
+	return checkedDescription({
+		ir: lowerQuery(query),
+		columns: query.data.finds.map((column) => column.name),
+		interiors: query.data.interiors.map((entry, ordinal) => ({
+			name: `interior${ordinal}`,
+			columns: entry.finds.map((column) => column.name)
+		})),
+		recursion:
+			query.data.kind === "cq"
+				? undefined
+				: { name: "recursion", columns: query.data.rec.finds.map((column) => column.name) },
+		parameters: query.data.params.map((entry) => ({
+			name: entry.name,
+			members: entry.membership?.kind === "set" ? entry.membership.values : undefined
+		}))
+	})
+}
+
+function hostLiteral(
+	field: AnyField,
+	value: TaggedValue,
+	op: "binding" | "eq" | "ne" | "lt" | "le" | "gt" | "ge" | "pointIn" | "allen"
+): unknown {
+	const roster = rosterOf(field)
+	let host: unknown = "value" in value ? value.value : { start: value.start, end: value.end }
+	if (roster !== undefined) host = handleOf("query literal", roster, host)
+	if (!isDeepStrictEqual(taggedCmpLiteral("query literal", field, host, op), value))
+		refused("query literal", "literal tag must match the field domain")
+	return host
+}
+
+/** Rehydrate into the existing checked rule builder, then use its ordinary lowering and execution. */
+function replayRule(
+	context: ChainContext,
+	rule: RuleIr,
+	columns: readonly string[],
+	parameters: readonly DescriptionParameter[],
+	usedParameters: Set<number>
+): RuleData {
+	const relations = Object.values(context.theory.relations)
+	const derived: readonly DerivedTable[] = [
+		...context.interiors,
+		...("rec" in context && "finds" in context.rec ? [context.rec] : [])
+	]
+	const variables = new Map<number, AnyVar>()
+	const relationAt = (ordinal: number): MatchOwner =>
+		relations[ordinal] ?? refused("query atom", `unknown relation ordinal ${ordinal}`)
+	const derivedAt = (ordinal: number): DerivedTable =>
+		derived[ordinal] ?? refused("query atom", `unavailable interior ordinal ${ordinal}`)
+	const variableAt = (ordinal: number): AnyVar =>
+		variables.get(ordinal) ?? refused("query variable", `variable ${ordinal} has no positive binding`)
+	const fieldsAt = (atom: AtomIr): readonly { readonly name: string; readonly field: AnyField }[] => {
+		if (atom.source.kind === "edb") return sealedFieldsOf(relationAt(atom.source.relation))
+		return derivedAt(atom.source.interior).finds.map((column) => ({
+			name: column.name,
+			field: column.slot?.field ?? refused("query interior", "column has no field")
+		}))
+	}
+	// Establish each variable's source domain from a positive occurrence. The
+	// shared builder verifies every other occurrence and all provenance joins.
+	for (const atom of rule.atoms) {
+		const fields = fieldsAt(atom)
+		const minted: Readonly<Record<string, AnyVar>> =
+			atom.source.kind === "edb"
+				? v(relationAt(atom.source.relation))
+				: v({ schema: context.theory, data: { kind: "cq", finds: derivedAt(atom.source.interior).finds } })
+		for (const [ordinal, term] of atom.bindings) {
+			const field = fields[ordinal] ?? refused("query atom", `unknown field ordinal ${ordinal}`)
+			if (term.kind === "var" && !variables.has(term.var)) {
+				const variable = minted[field.name] ?? refused("query atom", "variable mint missing")
+				variables.set(term.var, variable)
+			}
+		}
+	}
+	let chain = makeRawChain(context, EMPTY_RULE)
+	const termValue = (term: TermIr, field: AnyField, op: Parameters<typeof hostLiteral>[2]): unknown => {
+		if (term.kind === "var") return variableAt(term.var)
+		if (term.kind === "literal") return hostLiteral(field, term.value, op)
+		const parameter = parameters[term.param] ?? refused("query parameter", `unknown parameter ordinal ${term.param}`)
+		usedParameters.add(term.param)
+		if (parameter.members !== undefined) {
+			if (term.kind !== "paramSet" || op !== "binding")
+				refused("query parameter", "fixed membership belongs in a set binding")
+			return parameter.members.map((value) => hostLiteral(field, value, "binding"))
+		}
+		return term.kind === "param" ? makeParam(parameter.name) : makeSetParam(parameter.name)
+	}
+	const bindingsOf = (atom: AtomIr): Readonly<Record<string, unknown>> => {
+		const fields = fieldsAt(atom)
+		return Object.fromEntries(
+			atom.bindings.map(([ordinal, term]) => {
+				const field = fields[ordinal] ?? refused("query atom", `unknown field ordinal ${ordinal}`)
+				if (atom.source.kind === "interior" && term.kind !== "var")
+					refused("query interior", "interior bindings require variables")
+				return [field.name, termValue(term, field.field, "binding")]
+			})
+		)
+	}
+	for (const atom of rule.atoms) {
+		chain =
+			atom.source.kind === "edb"
+				? chain.match(relationAt(atom.source.relation), bindingsOf(atom))
+				: chain.interior(derivedAt(atom.source.interior).name, bindingsOf(atom))
+	}
+	for (const atom of rule.negated) {
+		chain = chain.where(
+			atom.source.kind === "edb"
+				? { cond: "not", relation: relationAt(atom.source.relation), bindings: bindingsOf(atom) }
+				: { cond: "notInterior", name: derivedAt(atom.source.interior).name, bindings: bindingsOf(atom) }
+		)
+	}
+	const condition = (input: ConditionTreeIr): AnyTreeChild => {
+		if (input.kind !== "leaf") {
+			const children = input.children.map(condition)
+			// This grammar contains comparisons and trees only, never negated atoms.
+			return {
+				cond: "tree",
+				op: input.kind,
+				children
+			}
+		}
+		const { lhs, rhs, op } = input.cmp
+		let anchor: AnyField
+		if (lhs.kind === "var") anchor = variableAt(lhs.var).field
+		else if (rhs.kind === "var") anchor = variableAt(rhs.var).field
+		else return refused("query comparison", "requires a variable operand")
+		return {
+			cond: "cmp",
+			op: op.kind,
+			lhs: termValue(lhs, anchor, op.kind),
+			rhs: termValue(rhs, anchor, op.kind),
+			mask: op.kind === "allen" ? op.mask : undefined
+		}
+	}
+	for (const input of rule.conditions) chain = chain.where(condition(input))
+	const scalar = (input: ScalarExprIr): QueryNode => {
+		switch (input.kind) {
+			case "var": {
+				const variable = variableAt(input.var)
+				const kind = variable.field.kind
+				if (
+					rosterOf(variable.field) !== undefined ||
+					(kind !== "bool" && kind !== "u64" && kind !== "i64" && kind !== "f64")
+				)
+					refused("query compute", "requires a scalar variable")
+				return queryVarLeaf(variable, kind)
+			}
+			case "literal": {
+				const value = input.value
+				switch (value.kind) {
+					case "u64":
+						return scalarLiteral("query-var", { u64: value.value })
+					case "i64":
+						return scalarLiteral("query-var", { i64: value.value })
+					case "f64":
+						return scalarLiteral("query-var", { f64: value.value })
+					case "bool":
+						return scalarLiteral("query-var", { bool: value.value })
+					default:
+						return refused("query compute", "requires a scalar literal")
+				}
+			}
+			case "negate":
+				return scalarNegate("query compute", scalar(input.expr))
+			case "isNaN":
+			case "isFinite":
+				return scalarFloatPredicate("query compute", input.kind, scalar(input.expr))
+			case "cast":
+				return scalarCast(
+					"query compute",
+					input.cast,
+					({ toI64Exact: "i64", toU64Exact: "u64", toF64: "f64", toF64Exact: "f64" } as const)[input.cast],
+					scalar(input.expr)
+				)
+			default:
+				return scalarBinary("query compute", input.kind, scalar(input.left), scalar(input.right))
+		}
+	}
+	const finds = Object.fromEntries(
+		rule.finds.map((find, ordinal) => {
+			const column = columns[ordinal] ?? refused("query find", "column name missing")
+			let value: unknown
+			if (find.kind === "var") value = variableAt(find.var)
+			else if (find.kind === "compute") value = scalar(find.expr)
+			else if (find.kind === "count") value = { agg: "count" }
+			else value = { agg: find.kind === "pack" ? "pack" : find.op.kind, over: variableAt(find.over) }
+			return [column, value]
+		})
+	)
+	return chain.find(finds).rule
+}
+
+function queryFromDescription<Rels extends SchemaRelations, Classes extends SchemaClasses, const F extends FieldsShape>(
+	schema: Schema<Rels, Classes>,
+	input: unknown,
+	result: F
+): Query<Rels, DescriptionRow<F>, ParamsRecord, Classes> {
+	const theory = schemaDescriptor(schema)
+	const description = checkedDescription(input)
+	const resultRecord = recordValue(
+		"query result",
+		result,
+		typeof result === "object" && result !== null ? Object.keys(result) : []
+	)
+	const fields = Object.fromEntries(
+		Object.entries(resultRecord).map(([name, field]) => [name, fieldDescriptor(`query result.${name}`, field)])
+	)
+	const interiors: InteriorData[] = []
+	const usedParameters = new Set<number>()
+	for (const [ordinal, item] of description.ir.interiors.entries()) {
+		const names = description.interiors[ordinal] ?? refused("query interior", "names missing")
+		const rules = item.rules.map((rule) =>
+			replayRule(
+				{ theory, classes: theory.classes, kind: "interior", self: names.name, interiors },
+				rule,
+				names.columns,
+				description.parameters,
+				usedParameters
+			)
+		)
+		interiors.push(
+			Object.freeze({
+				name: names.name,
+				finds: alignedHeadOf(`interior ${names.name}`, rules),
+				rules: Object.freeze(rules)
+			})
+		)
+	}
+	let rec: RecData | undefined
+	if (description.ir.kind === "reach") {
+		const names = description.recursion ?? refused("query recursion", "names missing")
+		const self = { name: names.name }
+		const base = description.ir.rec.base.map((rule) =>
+			replayRule(
+				{ theory, classes: theory.classes, kind: "rec-base", self, rec: self, interiors },
+				rule,
+				names.columns,
+				description.parameters,
+				usedParameters
+			)
+		)
+		const baseHead = alignedHeadOf("recursion base", base)
+		const first = baseHead[0] ?? refused("query recursion", "requires a nonempty head")
+		const head: { readonly name: string; readonly finds: readonly [FindColumn, ...FindColumn[]] } = {
+			name: names.name,
+			finds: [first, ...baseHead.slice(1)]
+		}
+		const steps = description.ir.rec.rec.map((rule) =>
+			replayRule(
+				{ theory, classes: theory.classes, kind: "rec-arm", self: head, rec: head, interiors },
+				rule,
+				names.columns,
+				description.parameters,
+				usedParameters
+			)
+		)
+		const finds = alignedHeadOf("recursion", [...base, ...steps])
+		const firstFind = finds[0] ?? refused("query recursion", "requires a nonempty head")
+		const firstBase = base[0] ?? refused("query recursion", "requires a base rule")
+		const firstStep = steps[0] ?? refused("query recursion", "requires a recursive rule")
+		rec = Object.freeze({
+			name: names.name,
+			finds: Object.freeze([firstFind, ...finds.slice(1)] as const),
+			base: Object.freeze([firstBase, ...base.slice(1)] as const),
+			rec: Object.freeze([firstStep, ...steps.slice(1)] as const)
+		})
+	}
+	const context: ChainContext = {
+		theory,
+		classes: theory.classes,
+		kind: "query",
+		interiors,
+		...(rec === undefined ? {} : { rec })
+	}
+	const rules = description.ir.rules.map((rule) =>
+		replayRule(context, rule, description.columns, description.parameters, usedParameters)
+	)
+	const value = makeRawQuery(theory, interiors, rec, rules)
+	const expected = Object.entries(fields)
+	if (
+		expected.length !== value.data.finds.length ||
+		expected.some(([name, field], ordinal) => {
+			const column = value.data.finds[ordinal]
+			return column?.name !== name || column.slot === undefined || !signaturesAgree(column.slot.field, field)
+		})
+	)
+		refused("query result", "result names and field domains must match the derived query head in order")
+	if (usedParameters.size !== description.parameters.length) refused("query parameters", "declared parameter is unused")
+	// Complete shared lowering also checks tagged literals and ordinal bounds.
+	lowerQuery(value)
+	return value as unknown as Query<Rels, DescriptionRow<F>, ParamsRecord, Classes>
+}
+
+export type { DescriptionParameter, DescriptionRow, DescriptionTable, QueryDescription }
+export { describeQuery, queryFromDescription }