@bjornpagen/bumbledb 1.2.1 → 1.3.0

package/src/query/description.ts

@@ -10,9 +10,19 @@ 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, scalarNegate } from "#scalar.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"
@@ -39,6 +49,12 @@ interface DescriptionParameter {
 
 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}`,
@@ -237,6 +253,11 @@ function replayRule(
 			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")
@@ -259,6 +280,10 @@ function replayRule(
 						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":
@@ -281,6 +306,11 @@ function replayRule(
 			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]
@@ -293,7 +323,7 @@ function queryFromDescription<Rels extends SchemaRelations, Classes extends Sche
 	schema: Schema<Rels, Classes>,
 	input: unknown,
 	result: F
-): Query<Rels, DescriptionRow<F>, ParamsRecord, Classes> {
+): Query<Rels, DescriptionRow<F>, ParamsRecord, Classes, DescriptionHead<F>> {
 	const theory = schemaDescriptor(schema)
 	const description = checkedDescription(input)
 	const resultRecord = recordValue(
@@ -387,8 +417,8 @@ function queryFromDescription<Rels extends SchemaRelations, Classes extends Sche
 	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>
+	return value as unknown as Query<Rels, DescriptionRow<F>, ParamsRecord, Classes, DescriptionHead<F>>
 }
 
-export type { DescriptionParameter, DescriptionRow, DescriptionTable, QueryDescription }
+export type { DescriptionHead, DescriptionParameter, DescriptionRow, DescriptionTable, QueryDescription }
 export { describeQuery, queryFromDescription }

package/src/query/find.ts

@@ -1,8 +1,9 @@
-import type { BoolField, F64Field, I64Field, Infer, U64Field } from "#fields.ts"
+import type { BoolField, F64Field, I64Field, Infer, IntervalField, U64Field } from "#fields.ts"
 import type { SchemaClasses } from "#law.ts"
 import type { IntervalVarOk, NumericVarOk } from "#query/atom.ts"
 import type { AnyComputeExpr, ComputeExpr, ComputeValue } from "#query/compute.ts"
 import type { AnyVar, MintSlotOf } from "#query/scope.ts"
+import type { Segments } from "#query/segments.ts"
 import type { ScalarKind } from "#scalar.ts"
 
 type FoldOpName = "sum" | "mean" | "min" | "max" | "pack"
@@ -18,7 +19,7 @@ interface Agg<Op extends FoldOpName, Over extends AnyVar> {
 
 type AnyAgg = CountAgg | Agg<FoldOpName, AnyVar>
 
-type FindEntry = AnyVar | AnyAgg | AnyComputeExpr
+type FindEntry = AnyVar | AnyAgg | AnyComputeExpr | Segments
 
 type FindShape = Readonly<Record<string, FindEntry>>
 
@@ -33,7 +34,7 @@ function count(): CountAgg {
 /**
  * Exact checked sum over a NUMERIC (u64/i64/f64) variable — wide accumulator,
  * one finalize range check; overflow is the engine's typed runtime error —
- * or over the measure (`r.sum(r.duration(w))`). Bool stays refused: a
+ * of a measured interval in a following stage. Bool stays refused: a
  * quantifier is not an addition (R3).
  */
 function sum<const O extends AnyVar>(over: O): Agg<"sum", O> {
@@ -69,7 +70,7 @@ type FindEntryOk<E> = E extends AnyVar
 				? NumericVarOk<O>
 				: E extends Agg<"pack", infer V extends AnyVar>
 					? IntervalVarOk<V>
-					: E extends AnyComputeExpr
+					: E extends AnyComputeExpr | Segments
 						? true
 						: false
 
@@ -81,17 +82,20 @@ type CheckRecFind<F extends FindShape> = {
 	readonly [K in keyof F]: F[K] extends AnyVar ? F[K] : never
 }
 
-type FindValue<E> = E extends AnyVar
-	? Infer<E["field"]>
-	: E extends CountAgg
-		? bigint
-		: E extends Agg<"sum" | "mean" | "min" | "max", infer O extends AnyVar>
-			? Infer<O["field"]>
-			: E extends Agg<"pack", infer V extends AnyVar>
-				? Infer<V["field"]>
-				: E extends ComputeExpr<infer K extends ScalarKind>
-					? ComputeValue<K>
-					: never
+type FindValue<E> =
+	E extends Segments<infer Element>
+		? Infer<IntervalField<Element, undefined>>
+		: E extends AnyVar
+			? Infer<E["field"]>
+			: E extends CountAgg
+				? bigint
+				: E extends Agg<"sum" | "mean" | "min" | "max", infer O extends AnyVar>
+					? Infer<O["field"]>
+					: E extends Agg<"pack", infer V extends AnyVar>
+						? Infer<V["field"]>
+						: E extends ComputeExpr<infer K extends ScalarKind>
+							? ComputeValue<K>
+							: never
 
 type RowOfFind<F extends FindShape> = { readonly [K in keyof F]: FindValue<F[K]> }
 
@@ -108,17 +112,24 @@ type ComputeFields = {
  * produce bare values, matching findColumnSlotOf at runtime.
  */
 type HeadRecordOf<Classes extends SchemaClasses, F extends FindShape> = {
-	readonly [K in keyof F]: F[K] extends AnyVar
-		? MintSlotOf<Classes, F[K]>
-		: F[K] extends ComputeExpr<infer Kind extends ScalarKind>
-			? { readonly field: ComputeFields[Kind]; readonly class: undefined }
-			: F[K] extends CountAgg
-				? { readonly field: U64Field; readonly class: undefined }
-				: F[K] extends Agg<"mean", AnyVar>
-					? { readonly field: F64Field; readonly class: undefined }
-					: F[K] extends Agg<FoldOpName, infer Over extends AnyVar>
-						? { readonly field: Over["field"]; readonly class: undefined }
-						: never
+	readonly [K in keyof F]: F[K] extends Segments<infer Element>
+		? { readonly field: IntervalField<Element, undefined>; readonly class: undefined }
+		: F[K] extends AnyVar
+			? MintSlotOf<Classes, F[K]>
+			: F[K] extends ComputeExpr<infer Kind extends ScalarKind>
+				? { readonly field: ComputeFields[Kind]; readonly class: undefined }
+				: F[K] extends CountAgg
+					? { readonly field: U64Field; readonly class: undefined }
+					: F[K] extends Agg<"mean", AnyVar>
+						? { readonly field: F64Field; readonly class: undefined }
+						: F[K] extends Agg<"pack", infer Over extends AnyVar>
+							? {
+									readonly field: IntervalField<Over["field"] extends IntervalField<infer E> ? E : never, undefined>
+									readonly class: undefined
+								}
+							: F[K] extends Agg<FoldOpName, infer Over extends AnyVar>
+								? { readonly field: Over["field"]; readonly class: undefined }
+								: never
 }
 
 export type { Agg, CheckFind, CheckRecFind, FindEntry, FindShape, HeadRecordOf, RowOfFind }

package/src/query/lower.ts

@@ -1,6 +1,6 @@
 import { membersAgree, sealedFieldsOf } from "#closed.ts"
 import { AuthoringError, SdkInvariantError } from "#errors.ts"
-import type { AnyClosedRoster, AnyField } from "#fields.ts"
+import type { AnyClosedRoster, AnyField, IntervalField } from "#fields.ts"
 import {
 	assertDeclarationOrderKey,
 	f64 as f64Field,
@@ -87,7 +87,8 @@ import {
 	renderFieldKind,
 	term
 } from "#query/scope.ts"
-import { literalWireOf } from "#scalar.ts"
+import { difference, intersection, isSegments, segmentField } from "#query/segments.ts"
+import { scalarWire } from "#scalar.ts"
 import type { AnySchema, Schema, SchemaRelations } from "#schema.ts"
 import { schemaDescriptor, schemasAgree } from "#schema.ts"
 import { arrayValue, recordValue, taggedValueOf } from "#values.ts"
@@ -147,6 +148,8 @@ interface TermOps {
 	readonly mean: typeof mean
 	readonly min: typeof min
 	readonly max: typeof max
+	readonly intersection: typeof intersection
+	readonly difference: typeof difference
 	readonly pack: typeof pack
 }
 
@@ -476,7 +479,9 @@ const termOps: TermOps = Object.freeze({
 	mean,
 	min,
 	max,
-	pack
+	pack,
+	intersection,
+	difference
 })
 
 interface RuleBuildState {
@@ -865,6 +870,8 @@ function findColumnOf(name: string, entry: unknown): FindColumn {
 			message: `find ${name}: a ${entry[term]} is not projectable — find takes variables, aggregates or Compute expressions`
 		})
 	}
+	if (isSegments(entry))
+		return Object.freeze({ name, entry: Object.freeze({ ...entry }), closed: undefined, slot: undefined })
 	if (isComputeExpr(entry)) {
 		return Object.freeze({
 			name,
@@ -940,6 +947,7 @@ function assertNumeric(where: string, position: string, ref: AnyVar): void {
  */
 function findColumnSlotOf(context: ChainContext, column: FindColumn): ClassedField | undefined {
 	const entry = column.entry
+	if (entry.kind === "segments") return { field: segmentField(entry), class: undefined }
 	if (entry.kind === "var") {
 		return mintSlotOf(context, entry.over)
 	}
@@ -957,13 +965,21 @@ function findColumnSlotOf(context: ChainContext, column: FindColumn): ClassedFie
 			return { field: agg.over.field, class: undefined }
 		}
 		case "pack":
-			return { field: agg.over.field, class: undefined }
+			return {
+				field: { kind: "interval", element: (agg.over.field as IntervalField).element, width: undefined },
+				class: undefined
+			}
 	}
 }
 
 function validateColumn(context: ChainContext, bound: ReadonlySet<AnyVar>, column: FindColumn): void {
 	const where = `${contextLabel(context)} find ${column.name}`
 	const entry = column.entry
+	if (entry.kind === "segments") {
+		assertBound(where, bound, entry.left)
+		assertBound(where, bound, entry.right)
+		return
+	}
 	if (entry.kind === "var") {
 		assertBound(where, bound, entry.over)
 		return
@@ -1085,6 +1101,13 @@ function completeRule(context: ChainContext, state: RuleBuildState, rawColumns:
 	if (rawColumns.length === 0) {
 		throw new AuthoringError({ message: `${label}: a find needs at least one entry` })
 	}
+	const aggregates = rawColumns.flatMap((column) => (column.entry.kind === "aggregate" ? [column.entry.agg] : []))
+	const packs = aggregates.filter((agg) => agg.op === "pack").length
+	if (packs > 1) throw new AuthoringError({ message: "a query stage can pack one interval column" })
+	if (packs !== 0 && aggregates.length !== packs)
+		throw new AuthoringError({ message: "pack intervals and compute numeric aggregates in separate query stages" })
+	if (rawColumns.some((c) => c.entry.kind === "segments") && aggregates.length !== 0)
+		throw new AuthoringError({ message: "aggregate generated segments in a following query stage" })
 	const columns = rawColumns.map(function enrichColumn(column): FindColumn {
 		assertDeclarationOrderKey(`${label} find column`, column.name)
 		validateColumn(context, state.bound, column)
@@ -1521,6 +1544,7 @@ function renderClosedSlice(closed: AnyClosedRoster | undefined): string {
 
 function headSignature(column: FindColumn): string {
 	const entry = column.entry
+	if (entry.kind === "segments") return `${column.name}:compute`
 	if (entry.kind === "var") {
 		return `${column.name}:var`
 	}
@@ -2186,34 +2210,15 @@ function lowerComputeNode(node: QueryNode, ids: VarIds): ScalarExprIr {
 }
 
 function lowerComputeGrammar(node: QueryNode, ids: VarIds): ScalarExprIr {
-	switch (node.kind) {
-		case "var":
-			return { kind: "var", var: ids.of(node.ref as AnyVar) }
-		case "literal":
-			return { kind: "literal", value: literalWireOf(node.value) }
-		case "negate":
-		case "isNaN":
-		case "isFinite":
-			return { kind: node.kind, expr: lowerComputeGrammar(node.expr, ids) }
-		case "cast":
-			return { kind: "cast", cast: node.cast, expr: lowerComputeGrammar(node.expr, ids) }
-		case "add":
-		case "subtract":
-		case "multiply":
-		case "divide":
-			return {
-				kind: node.kind,
-				left: lowerComputeGrammar(node.left, ids),
-				right: lowerComputeGrammar(node.right, ids)
-			}
-		default:
-			throw new AuthoringError({
-				message: "query lowering: a query-var tree cannot carry a source-field leaf — use Compute over bound variables"
-			})
-	}
+	return scalarWire(node, (leaf) => {
+		if (leaf.kind !== "var") throw new AuthoringError({ message: "query expressions require bound variables" })
+		return ids.of(leaf.ref as AnyVar)
+	})
 }
 
 function lowerFind(entry: FindEntryData, ids: VarIds): FindTermIr {
+	if (entry.kind === "segments")
+		return { kind: entry.kind, op: entry.op, left: ids.of(entry.left), right: ids.of(entry.right) }
 	if (entry.kind === "var") {
 		return { kind: "var", var: ids.of(entry.over) }
 	}
@@ -2244,6 +2249,7 @@ function headOpOf(agg: AggData): HeadOpIr {
 
 function headTermOf(column: FindColumn): HeadTermIr {
 	const entry = column.entry
+	if (entry.kind === "segments") return { kind: "compute" }
 	if (entry.kind === "var") {
 		return { kind: "var" }
 	}

package/src/query/parse-ir.ts

@@ -11,6 +11,7 @@ import type {
 	ScalarExprIr,
 	TermIr
 } from "#native.ts"
+import { roundingMode } from "#scalar.ts"
 import { arrayValue as array, recordValue, valueDescriptor } from "#values.ts"
 
 function fail(context: string, expected: string): never {
@@ -59,6 +60,7 @@ function scalar(context: string, input: unknown, depth = 1): ScalarExprIr {
 		case "literal":
 			recordValue(context, raw, ["kind", "value"])
 			return Object.freeze({ kind: raw.kind, value: valueDescriptor(`${context}.value`, raw.value) })
+		case "measure":
 		case "negate":
 		case "isNaN":
 		case "isFinite":
@@ -74,6 +76,15 @@ function scalar(context: string, input: unknown, depth = 1): ScalarExprIr {
 				left: scalar(`${context}.left`, raw.left, depth + 1),
 				right: scalar(`${context}.right`, raw.right, depth + 1)
 			})
+		case "mulDiv":
+			recordValue(context, raw, ["kind", "a", "b", "divisor", "rounding"])
+			return Object.freeze({
+				kind: raw.kind,
+				a: scalar(`${context}.a`, raw.a, depth + 1),
+				b: scalar(`${context}.b`, raw.b, depth + 1),
+				divisor: scalar(`${context}.divisor`, raw.divisor, depth + 1),
+				rounding: roundingMode(raw.rounding)
+			})
 		case "cast": {
 			recordValue(context, raw, ["kind", "cast", "expr"])
 			const cast = raw.cast
@@ -102,6 +113,16 @@ function headTerm(context: string, input: unknown): HeadTermIr {
 
 function find(context: string, input: unknown): FindTermIr {
 	const raw = tagged(context, input)
+	if (raw.kind === "segments") {
+		recordValue(context, raw, ["kind", "op", "left", "right"])
+		if (raw.op !== "intersection" && raw.op !== "difference") return fail(context, "unknown segment operator")
+		return Object.freeze({
+			kind: raw.kind,
+			op: raw.op,
+			left: ordinal(context, raw.left),
+			right: ordinal(context, raw.right)
+		})
+	}
 	switch (raw.kind) {
 		case "var":
 			recordValue(context, raw, ["kind", "var"])
@@ -210,7 +231,8 @@ function align(context: string, head: readonly HeadTermIr[], rules: readonly Rul
 		if (rule.finds.length !== head.length) fail(`${context}.rules[${index}]`, "finds width does not match head width")
 		for (const [position, find] of rule.finds.entries()) {
 			const term = head[position]
-			const family = find.kind === "var" || find.kind === "compute" ? find.kind : "aggregate"
+			const plainFamily = find.kind === "var" || find.kind === "compute" ? find.kind : "aggregate"
+			const family = find.kind === "segments" ? "compute" : plainFamily
 			if (term?.kind !== family)
 				fail(`${context}.rules[${index}].finds[${position}]`, "find family does not match head")
 			if (term.kind === "aggregate") {

package/src/query/segments.ts

@@ -0,0 +1,61 @@
+import { AuthoringError } from "#errors.ts"
+import type { IntervalElementKind, IntervalField } from "#fields.ts"
+import { type AnyVar, isTerm, term } from "#query/scope.ts"
+import { recordValue } from "#values.ts"
+
+type IntervalVar<E extends IntervalElementKind = IntervalElementKind> = AnyVar & { readonly field: IntervalField<E> }
+type SegmentOp = "intersection" | "difference"
+
+/** A relational find output, using the native binary segment operator directly. */
+interface Segments<E extends IntervalElementKind = IntervalElementKind> {
+	readonly kind: "segments"
+	readonly op: SegmentOp
+	readonly left: IntervalVar<E>
+	readonly right: IntervalVar<E>
+}
+
+function segments<E extends IntervalElementKind>(
+	op: SegmentOp,
+	left: IntervalVar<E>,
+	right: IntervalVar<NoInfer<E>>
+): Segments<E> {
+	if (
+		!isTerm(left) ||
+		left[term] !== "var" ||
+		!isTerm(right) ||
+		right[term] !== "var" ||
+		left.field.kind !== "interval" ||
+		right.field.kind !== "interval" ||
+		left.field.element !== right.field.element
+	)
+		throw new AuthoringError({ message: `${op}: expected interval variables of the same element kind` })
+	return Object.freeze({ kind: "segments", op, left, right })
+}
+
+function intersection<E extends IntervalElementKind>(
+	left: IntervalVar<E>,
+	right: IntervalVar<NoInfer<E>>
+): Segments<E> {
+	return segments("intersection", left, right)
+}
+
+function difference<E extends IntervalElementKind>(left: IntervalVar<E>, right: IntervalVar<NoInfer<E>>): Segments<E> {
+	return segments("difference", left, right)
+}
+
+function isSegments(input: unknown): input is Segments {
+	if (typeof input !== "object" || input === null || !("kind" in input) || input.kind !== "segments") return false
+	recordValue("segments", input, ["kind", "op", "left", "right"])
+	const value = input as Segments
+	if (value.op !== "intersection" && value.op !== "difference")
+		throw new AuthoringError({ message: "unknown segment operator" })
+	segments(value.op, value.left, value.right)
+	return true
+}
+
+function segmentField(value: Segments): IntervalField<IntervalElementKind, undefined> {
+	return Object.freeze({ kind: "interval", element: value.left.field.element, width: undefined })
+}
+
+export type { IntervalVar, SegmentOp, Segments }
+export { difference, intersection, isSegments, segmentField }