@bjornpagen/bumbledb 1.3.1 → 2.0.0-rc.1

package/src/query/description.ts

@@ -1,424 +0,0 @@
-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 { difference, type IntervalVar, intersection } from "#query/segments.ts"
-import type { FieldsShape } from "#relation.ts"
-import { handleOf } from "#rows.ts"
-import {
-	queryVarLeaf,
-	scalarBinary,
-	scalarCast,
-	scalarFloatPredicate,
-	scalarLiteral,
-	scalarMeasure,
-	scalarMulDiv,
-	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]> }
-
-/** Checked result fields remain exact through v(imported), just as at runtime.
- * Carrier classes come from the replayed head and remain runtime-checked. */
-type DescriptionHead<F extends FieldsShape> = {
-	readonly [K in keyof F]: { readonly field: F[K]; readonly class: string | undefined }
-}
-
-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 (variable.field.kind === "interval")
-					return queryVarLeaf(
-						variable,
-						({ u64: "intervalU64", i64: "intervalI64", f64: "intervalF64" } as const)[variable.field.element]
-					)
-				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({ u64: value.value })
-					case "i64":
-						return scalarLiteral({ i64: value.value })
-					case "f64":
-						return scalarLiteral({ f64: value.value })
-					case "bool":
-						return scalarLiteral({ bool: value.value })
-					default:
-						return refused("query compute", "requires a scalar literal")
-				}
-			}
-			case "measure":
-				return scalarMeasure("query compute", scalar(input.expr))
-			case "mulDiv":
-				return scalarMulDiv("query compute", scalar(input.a), scalar(input.b), scalar(input.divisor), input.rounding)
-			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 === "segments")
-				value = (find.op === "intersection" ? intersection : difference)(
-					variableAt(find.left) as IntervalVar,
-					variableAt(find.right) as IntervalVar
-				)
-			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, DescriptionHead<F>> {
-	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, DescriptionHead<F>>
-}
-
-export type { DescriptionHead, DescriptionParameter, DescriptionRow, DescriptionTable, QueryDescription }
-export { describeQuery, queryFromDescription }