@bjornpagen/bumbledb 1.2.0 → 1.3.0

package/src/query/scope.ts

@@ -122,9 +122,23 @@ function isImportedSource(value: unknown): value is ImportedSource {
 
 type RowOfImport<Q> = InferredOf<Q> extends { readonly row: infer R } ? R : never
 
+type HeadOfImport<Q> = InferredOf<Q> extends { readonly head: infer H } ? H : never
+
+/** Named imported slot so downstream declarations need not spell its private marker. */
+interface ImportedFieldVar<S extends ClassedField, K extends string> extends Var<S["field"], string, K> {
+	readonly [inferred]?: { readonly slot: S }
+}
+
+// Retain the same descriptor and carrier class as the runtime import facade.
+// A host bigint alone cannot distinguish i64 from u64 or a closed identifier.
+type ImportedVar<Q, K extends string> =
+	HeadOfImport<Q> extends Readonly<Record<K, infer S extends ClassedField>>
+		? ImportedFieldVar<S, K>
+		: Var<AnyField, string, K>
+
 type ImportVars<Q> = [RowOfImport<Q>] extends [never]
 	? Readonly<Record<string, Var<AnyField, string, string>>>
-	: { readonly [K in keyof RowOfImport<Q> & string]: Var<AnyField, string, K> }
+	: { readonly [K in keyof RowOfImport<Q> & string]: ImportedVar<Q, K> }
 
 interface ImportFacade {
 	/** The pseudo-owner every import var carries (structurally an owner). */
@@ -241,10 +255,11 @@ type MintClassOf<Classes extends SchemaClasses, V> =
 		? ClassLookup<ClassRecordOf<Classes, RN>, K>
 		: never
 
-type MintSlotOf<Classes extends SchemaClasses, V extends AnyVar> = {
-	readonly field: V["field"]
-	readonly class: MintClassOf<Classes, V>
-}
+type MintSlotOf<Classes extends SchemaClasses, V extends AnyVar> = [InferredOf<V>] extends [never]
+	? { readonly field: V["field"]; readonly class: MintClassOf<Classes, V> }
+	: InferredOf<V> extends { readonly slot: infer S extends ClassedField }
+		? S
+		: { readonly field: V["field"]; readonly class: MintClassOf<Classes, V> }
 
 type ParamsRecord = Readonly<Record<string, unknown>>
 
@@ -257,15 +272,8 @@ type UnionToIntersection<U> = (U extends unknown ? (member: U) => void : never)
 type ShapeOf<U> = [U] extends [never] ? Record<never, never> : Flatten<UnionToIntersection<U>>
 
 /**
- * A slot's identity for the positive-join judgment: the field's structural
- * signature ({@link SignatureOf} — the ONE interpreter, shared with the
- * face pairing wall) plus the slot's law class.
- */
-type SlotSignature<S extends ClassedField> = readonly [SignatureOf<S["field"]>, S["class"]]
-
-/**
- * A widened slot — a variable minted from an imported query template (its
- * facade columns carry `AnyField`) or fully generic code — cannot be judged
+ * A widened slot — an explicitly erased query template or fully generic
+ * code with no retained descriptor — cannot be judged
  * at the type tier. The degradation law applies: best effort degrades to
  * SILENT, never to a wrong refusal; the runtime join judgment (real
  * descriptors off the imported head's slots) stays authoritative.
@@ -273,7 +281,15 @@ type SlotSignature<S extends ClassedField> = readonly [SignatureOf<S["field"]>,
 type WidenedSlot<S extends ClassedField> = [AnyField] extends [S["field"]] ? true : false
 
 type JoinOk<A extends ClassedField, B extends ClassedField> =
-	WidenedSlot<A> extends true ? true : WidenedSlot<B> extends true ? true : Same<SlotSignature<A>, SlotSignature<B>>
+	WidenedSlot<A> extends true
+		? true
+		: WidenedSlot<B> extends true
+			? true
+			: Same<SignatureOf<A["field"]>, SignatureOf<B["field"]>> extends true
+				? string extends A["class"] | B["class"]
+					? true
+					: Same<A["class"], B["class"]>
+				: false
 
 type U64Wire<F extends AnyField> = F extends { readonly kind: "u64" }
 	? F extends { readonly closed: unknown }
@@ -390,6 +406,7 @@ export type {
 	ClassedField,
 	ExactVars,
 	Flatten,
+	ImportedFieldVar,
 	ImportedSource,
 	ImportVars,
 	InferredOf,

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 }

package/src/scalar.ts

@@ -16,6 +16,7 @@
  *   query IR — `{ kind: "literal", value: ValueSpec }` via `literalWireOf`
  */
 import { AuthoringError } from "#errors.ts"
+import type { ScalarExprIr } from "#native.ts"
 import type { ValueSpec } from "#spec.ts"
 
 /** F0: leaf scope for the shared AST (C1). Query vars are typed; source fields stay unresolved. */
@@ -25,7 +26,10 @@ export type ScalarLeafScope = "query-var" | "source-field"
 type ScalarKind = "u64" | "i64" | "f64" | "bool"
 
 /** Cached result kind: known only when derivable; otherwise honestly unresolved. */
-type ScalarResultKind = ScalarKind | "unresolved"
+type IntervalKind = "intervalU64" | "intervalI64" | "intervalF64"
+type ScalarInputKind = ScalarKind | IntervalKind
+type ScalarResultKind = ScalarInputKind | "unresolved"
+type Rounding = "towardZero" | "nearestTiesAwayFromZero" | "nearestTiesToEven"
 
 /** Host value for a derived scalar kind. */
 type ScalarValue<K extends ScalarKind> = K extends "f64" ? number : K extends "bool" ? boolean : bigint
@@ -60,7 +64,18 @@ type ScalarLiteral =
 	| { readonly i64: bigint }
 	| { readonly f64: number }
 
-type ScalarOpKind = "literal" | "negate" | "isNaN" | "isFinite" | "add" | "subtract" | "multiply" | "divide" | "cast"
+type ScalarOpKind =
+	| "literal"
+	| "negate"
+	| "isNaN"
+	| "isFinite"
+	| "add"
+	| "subtract"
+	| "multiply"
+	| "divide"
+	| "cast"
+	| "mulDiv"
+	| "measure"
 
 /**
  * Structural query-variable leaf. The query layer supplies a bound variable
@@ -79,6 +94,14 @@ type SourceFieldLeaf = { readonly kind: "field"; readonly name: string }
 type ScalarLeaf<S extends ScalarLeafScope> = S extends "query-var" ? QueryVarLeaf : SourceFieldLeaf
 
 type ScalarNodeBody<S extends ScalarLeafScope> =
+	| { readonly kind: "measure"; readonly expr: ScalarNode<S> }
+	| {
+			readonly kind: "mulDiv"
+			readonly a: ScalarNode<S>
+			readonly b: ScalarNode<S>
+			readonly divisor: ScalarNode<S>
+			readonly rounding: Rounding
+	  }
 	| ScalarLeaf<S>
 	| { readonly kind: "literal"; readonly value: ScalarLiteral }
 	| { readonly kind: "negate"; readonly expr: ScalarNode<S> }
@@ -197,13 +220,13 @@ function assertDepth(where: string, depth: number): void {
 	}
 }
 
-function assertNumeric(where: string, kind: ScalarKind): void {
-	if (kind === "bool") {
+function assertNumeric(where: string, kind: ScalarInputKind): asserts kind is NumericKind {
+	if (kind !== "u64" && kind !== "i64" && kind !== "f64") {
 		throw new AuthoringError({ message: `${where}: the operand is bool, not numeric (u64/i64/f64)` })
 	}
 }
 
-function assertSameKind(where: string, left: ScalarKind, right: ScalarKind): ScalarKind {
+function assertSameKind(where: string, left: ScalarInputKind, right: ScalarInputKind): ScalarInputKind {
 	if (left !== right) {
 		throw new AuthoringError({
 			message: `${where}: operand kinds differ (${left} vs ${right}) — the engine has no mixed promotion; cast explicitly (Scalar.toF64/ toF64Exact/ toI64Exact/ toU64Exact)`
@@ -294,7 +317,7 @@ function sourceField(name: string): ScalarFieldRef {
 }
 
 /** Query-var leaf — kind is the variable's schema kind, already known. */
-function queryVarLeaf<K extends ScalarKind>(ref: ScalarQueryVar, kind: K): ScalarNode<"query-var", K> {
+function queryVarLeaf<K extends ScalarInputKind>(ref: ScalarQueryVar, kind: K): ScalarNode<"query-var", K> {
 	return admit("Scalar.queryVar", {
 		kind: "var",
 		ref,
@@ -334,6 +357,56 @@ function scalarBinary<S extends ScalarLeafScope>(
 	})
 }
 
+function roundingMode(value: unknown): Rounding {
+	if (value !== "towardZero" && value !== "nearestTiesAwayFromZero" && value !== "nearestTiesToEven")
+		throw new AuthoringError({ message: "unknown integer rounding mode" })
+	return value
+}
+
+function scalarMulDiv<S extends ScalarLeafScope>(
+	where: string,
+	a: ScalarNode<S>,
+	b: ScalarNode<S>,
+	divisor: ScalarNode<S>,
+	rounding: Rounding
+): ScalarNode<S> {
+	const scope = assertScope(where, a, b)
+	assertScope(where, a, divisor)
+	let known: "i64" | "u64" | undefined
+	for (const operand of [a, b, divisor]) {
+		if (operand.result === "unresolved") continue
+		if ((operand.result !== "i64" && operand.result !== "u64") || (known !== undefined && known !== operand.result))
+			throw new AuthoringError({ message: `${where}: operands must have one matching integer kind` })
+		known = operand.result
+	}
+	return admit(where, {
+		kind: "mulDiv",
+		a,
+		b,
+		divisor,
+		rounding: roundingMode(rounding),
+		scope,
+		result:
+			a.result === "unresolved" || b.result === "unresolved" || divisor.result === "unresolved"
+				? "unresolved"
+				: a.result,
+		depth: Math.max(a.depth, b.depth, divisor.depth) + 1
+	})
+}
+
+function scalarMeasure<S extends ScalarLeafScope>(where: string, expr: ScalarNode<S>): ScalarNode<S> {
+	const kind = expr.result
+	if (kind !== "unresolved" && kind !== "intervalU64" && kind !== "intervalI64" && kind !== "intervalF64")
+		throw new AuthoringError({ message: `${where}: measure requires an interval` })
+	return admit(where, {
+		kind: "measure",
+		expr,
+		scope: expr.scope,
+		result: ({ unresolved: "unresolved", intervalF64: "f64", intervalI64: "u64", intervalU64: "u64" } as const)[kind],
+		depth: expr.depth + 1
+	})
+}
+
 function scalarNegate<S extends ScalarLeafScope>(where: string, expr: ScalarNode<S>): ScalarNode<S, ScalarResultKind> {
 	return admit(where, {
 		kind: "negate",
@@ -391,12 +464,16 @@ function queryVarsOf(node: ScalarNode<"query-var">): readonly ScalarQueryVar[] {
 				break
 			case "literal":
 				break
+			case "measure":
 			case "negate":
 			case "isNaN":
 			case "isFinite":
 			case "cast":
 				pending.push(next.expr)
 				break
+			case "mulDiv":
+				pending.push(next.a, next.b, next.divisor)
+				break
 			case "add":
 			case "subtract":
 			case "multiply":
@@ -472,6 +549,27 @@ function divide<
 	return scalarBinary("Scalar.divide", "divide", left, right) as ScalarExpr<CombineNumeric<L, R>>
 }
 
+function mulDiv<
+	L extends "i64" | "u64" | "unresolved",
+	R extends CombineNumeric<L, R> extends never ? never : "i64" | "u64" | "unresolved",
+	D extends CombineNumeric<L, D> extends never
+		? never
+		: CombineNumeric<R, D> extends never
+			? never
+			: "i64" | "u64" | "unresolved"
+>(
+	a: ScalarExpr<L>,
+	b: ScalarExpr<R>,
+	divisor: ScalarExpr<D>,
+	rounding: Rounding
+): ScalarExpr<CombineNumeric<CombineNumeric<L, R>, D>> {
+	return scalarMulDiv("Scalar.mulDiv", a, b, divisor, rounding) as ScalarExpr<CombineNumeric<CombineNumeric<L, R>, D>>
+}
+
+function measure(expr: ScalarFieldRef): ScalarExpr<"unresolved"> {
+	return scalarMeasure("Scalar.measure", expr) as ScalarExpr<"unresolved">
+}
+
 function toF64(expr: ScalarExpr<NumericOrUnresolved>): ScalarExpr<"f64"> {
 	return scalarCast("Scalar.toF64", "toF64", "f64", expr) as ScalarExpr<"f64">
 }
@@ -496,6 +594,32 @@ function isFiniteExpr(expr: ScalarExpr<"f64" | "unresolved">): ScalarExpr<"bool"
 	return scalarFloatPredicate("Scalar.isFinite", "isFinite", expr)
 }
 
+/** One lowering walk for query variables and row-field bindings. */
+function scalarWire(node: ScalarNode, leaf: (node: QueryVarLeaf | SourceFieldLeaf) => number): ScalarExprIr {
+	const walk = (expr: ScalarNode): ScalarExprIr => scalarWire(expr, leaf)
+	switch (node.kind) {
+		case "var":
+		case "field":
+			return { kind: "var", var: leaf(node) }
+		case "literal":
+			return { kind: "literal", value: literalWireOf(node.value) }
+		case "measure":
+		case "negate":
+		case "isNaN":
+		case "isFinite":
+			return { kind: node.kind, expr: walk(node.expr) }
+		case "cast":
+			return { kind: node.kind, cast: node.cast, expr: walk(node.expr) }
+		case "mulDiv":
+			return { kind: node.kind, a: walk(node.a), b: walk(node.b), divisor: walk(node.divisor), rounding: node.rounding }
+		case "add":
+		case "subtract":
+		case "multiply":
+		case "divide":
+			return { kind: node.kind, left: walk(node.left), right: walk(node.right) }
+	}
+}
+
 /** The authoring namespace: `Scalar.field("units")`, `Scalar.add(...)`. */
 const Scalar = Object.freeze({
 	field,
@@ -509,6 +633,8 @@ const Scalar = Object.freeze({
 	subtract,
 	multiply,
 	divide,
+	mulDiv,
+	measure,
 	toF64,
 	toF64Exact,
 	toI64Exact,
@@ -519,12 +645,15 @@ const Scalar = Object.freeze({
 
 export type {
 	CombineNumeric,
+	IntervalKind,
 	NumericCast,
 	NumericKind,
 	NumericOrUnresolved,
 	QueryVarLeaf,
+	Rounding,
 	ScalarExpr,
 	ScalarFieldRef,
+	ScalarInputKind,
 	ScalarKind,
 	ScalarLiteral,
 	ScalarNode,
@@ -550,11 +679,15 @@ export {
 	MAX_SCALAR_DEPTH,
 	queryVarLeaf,
 	queryVarsOf,
+	roundingMode,
 	Scalar,
 	scalarAuthoringWork,
 	scalarBinary,
 	scalarCast,
 	scalarFloatPredicate,
 	scalarLiteral,
-	scalarNegate
+	scalarMeasure,
+	scalarMulDiv,
+	scalarNegate,
+	scalarWire
 }

package/src/shape.ts

@@ -1,5 +1,5 @@
 import type { Query } from "#query/lower.ts"
-import type { ParamsRecord } from "#query/scope.ts"
+import type { inferred, ParamsRecord } from "#query/scope.ts"
 /**
  * Shared derived types: `S` is a
  * declared core schema value's type, `Rel<S>` its ordinary (writable)
@@ -24,7 +24,13 @@ type Key<K extends KeyStatement<AnyRelation, readonly string[]>> = Pick<
 	Extract<K["projection"][number], keyof Fact<K["owner"]>>
 >
 
-/** Immutable typed query template. */
-type QueryTemplate<S extends AnySchema, P extends ParamsRecord, A> = Query<S["relations"], A, P>
+/** The immutable executable view of a query. Readers consume its schema/data
+ * and inferred result/parameters, not the author's rule-building methods.
+ * Runtime schema identity remains authoritative for dynamically built schemas.
+ */
+type QueryTemplate<S extends AnySchema, P extends ParamsRecord, A> = Pick<
+	Query<S["relations"], A, P>,
+	"schema" | "data" | typeof inferred
+>
 
 export type { Key, QueryTemplate, Rel }