@bjornpagen/bumbledb 1.3.0 → 2.0.0-rc.1

package/src/native/json.ts

@@ -0,0 +1,100 @@
+/**
+ * Spellings for the addon's JSON inputs. 64-bit integers cross as decimal strings, `f64` as its
+ * 16-hex-digit IEEE bit pattern (so -0, NaN and the infinities stay exact) and bytes as lowercase
+ * hex; JSON numbers only ever carry ordinals.
+ */
+import type {
+	CapacityBoundSpec,
+	CapacityWindowSpec,
+	LiteralSetSpec,
+	LiteralSpec,
+	ValueSpec,
+	WeightSpec
+} from "../spec.ts"
+import { f64BitsHex } from "../spec.ts"
+import type {
+	BoundSpecIn,
+	CapacityWindowSpecIn,
+	LiteralSetSpecIn,
+	LiteralSpecIn,
+	ValueIn,
+	WeightSpecIn
+} from "./binding.d.ts"
+
+function hex(bytes: Uint8Array): string {
+	let out = ""
+	for (const byte of bytes) out += byte.toString(16).padStart(2, "0")
+	return out
+}
+
+function valueIn(value: ValueSpec): ValueIn {
+	switch (value.kind) {
+		case "bool":
+			return { kind: "Bool", value: value.value }
+		case "u64":
+			return { kind: "U64", value: value.value.toString() }
+		case "i64":
+			return { kind: "I64", value: value.value.toString() }
+		case "f64":
+			return { kind: "F64", value: f64BitsHex(value.value) }
+		case "string":
+			return { kind: "String", value: value.value }
+		case "uuid":
+			return { kind: "Uuid", value: value.value }
+		case "fixedBytes":
+			return { kind: "FixedBytes", value: hex(value.value) }
+		case "intervalU64":
+			return { kind: "IntervalU64", start: value.start.toString(), end: value.end.toString() }
+		case "intervalI64":
+			return { kind: "IntervalI64", start: value.start.toString(), end: value.end.toString() }
+		case "intervalF64":
+			return { kind: "IntervalF64", start: f64BitsHex(value.start), end: f64BitsHex(value.end) }
+	}
+}
+
+function literalIn(literal: LiteralSpec): LiteralSpecIn {
+	return literal.kind === "handle"
+		? { kind: "Handle", handle: literal.handle }
+		: { kind: "Value", value: valueIn(literal.value) }
+}
+
+function literalSetIn(set: LiteralSetSpec): LiteralSetSpecIn {
+	return set.kind === "one"
+		? { kind: "One", literal: literalIn(set.literal) }
+		: { kind: "Many", literals: set.literals.map(literalIn) }
+}
+
+function boundIn(bound: CapacityBoundSpec): BoundSpecIn {
+	switch (bound.kind) {
+		case "lit":
+			return { kind: "Lit", value: bound.value.toString() }
+		case "field":
+			return { kind: "Field", field: bound.field }
+		case "durationField":
+			return { kind: "Duration", field: bound.field }
+	}
+}
+
+function windowIn(window: CapacityWindowSpec): CapacityWindowSpecIn {
+	switch (window.kind) {
+		case "exact":
+			return { kind: "Exact", n: boundIn(window.n) }
+		case "range":
+			return { kind: "Range", lo: boundIn(window.lo), hi: boundIn(window.hi) }
+		case "floor":
+			return { kind: "Floor", lo: boundIn(window.lo) }
+	}
+}
+
+function weightIn(weight: WeightSpec): WeightSpecIn {
+	switch (weight.kind) {
+		case "unit":
+			return { kind: "Unit" }
+		case "field":
+			return { kind: "Field", field: weight.field }
+		case "durationField":
+			return { kind: "Duration", field: weight.field }
+	}
+}
+
+export { literalIn, literalSetIn, valueIn, weightIn, windowIn }

package/src/native/load.ts

@@ -0,0 +1,31 @@
+import { existsSync } from "node:fs"
+import { createRequire } from "node:module"
+import { fileURLToPath } from "node:url"
+import { NativeLoadError } from "../errors.ts"
+
+const require = createRequire(import.meta.url)
+
+/** The platforms that ship a prebuilt addon package. */
+export const SHIPPED_PLATFORMS = ["darwin-arm64", "linux-arm64", "linux-x64"] as const
+
+/**
+ * Loads the addon for `platform-arch`: a development build at the package root
+ * (`bdb.<platform>-<arch>.node`, written by `scripts/build.ts dev`) wins over the
+ * installed `@bjornpagen/bumbledb-<platform>-<arch>` package.
+ */
+export function loadAddon<T>(platform: string, arch: string): T {
+	const target = `${platform}-${arch}`
+	const dev = fileURLToPath(new URL(`../../bdb.${target}.node`, import.meta.url))
+	const source = existsSync(dev) ? dev : `@bjornpagen/bumbledb-${target}`
+	try {
+		return require(source) as T
+	} catch (cause) {
+		throw new NativeLoadError({
+			target,
+			message: SHIPPED_PLATFORMS.some((shipped) => shipped === target)
+				? `load the bumbledb addon from ${source}`
+				: `no bumbledb addon for ${target}; prebuilt addons ship for ${SHIPPED_PLATFORMS.join(", ")}`,
+			cause
+		})
+	}
+}

package/src/native/op.ts

@@ -0,0 +1,73 @@
+/**
+ * Effect over the addon's callback protocol. A native verb registers work and returns its lease
+ * before any completion can reach JS; the addon then calls back exactly once. Interruption cancels
+ * the lease and joins its drain, and a drain that does not close cleanly is a `CloseFailure`
+ * defect beside the interrupt.
+ */
+import type { Scope } from "effect"
+import { Effect } from "effect"
+import type { DbError } from "../errors.ts"
+import { CloseFailure, dbError } from "../errors.ts"
+import type { OperationRef } from "./addon.ts"
+import { addon } from "./addon.ts"
+import type { CloseOut } from "./binding.d.ts"
+
+/** Registers one native operation; the addon calls `done` once its result can be taken. */
+type Start = (done: () => void) => OperationRef
+
+/** Starts one native close or cancel transition; the addon reports how it drained. */
+type Drain = (done: (report: CloseOut) => void) => void
+
+/** Runs a native close or cancel transition to completion. It cannot be interrupted and never fails. */
+function drain(start: Drain): Effect.Effect<CloseOut> {
+	return Effect.callback<CloseOut>((resume) => {
+		try {
+			start((report) => resume(Effect.succeed(report)))
+		} catch {
+			resume(Effect.succeed({ _tag: "Failed" }))
+		}
+	}).pipe(Effect.uninterruptible)
+}
+
+/** Drains, then dies with `CloseFailure` unless the transition closed cleanly. */
+function release(operation: string, start: Drain): Effect.Effect<void> {
+	return Effect.flatMap(drain(start), (report) =>
+		report._tag === "Closed" ? Effect.void : Effect.die(new CloseFailure({ operation, report }))
+	)
+}
+
+/**
+ * One native operation. A completion that arrives after interruption is left to the cancel drain
+ * the interruption already started.
+ */
+function call<A>(operation: string, start: Start, take: (lease: OperationRef) => A): Effect.Effect<A, DbError> {
+	return Effect.callback<A, DbError>((resume, signal) => {
+		let lease: OperationRef
+		try {
+			lease = start(() => {
+				if (signal.aborted) return
+				try {
+					resume(Effect.succeed(take(lease)))
+				} catch (cause) {
+					resume(Effect.fail(dbError(operation, cause)))
+				}
+			})
+		} catch (cause) {
+			resume(Effect.fail(dbError(operation, cause)))
+			return
+		}
+		return release(`${operation}.cancel`, (done) => addon.runtimeCancel(lease, done))
+	})
+}
+
+/** A native resource owned by the current scope, released by its native close transition. */
+function scoped<A, E, R>(
+	operation: string,
+	acquire: Effect.Effect<A, E, R>,
+	close: (resource: A) => Drain
+): Effect.Effect<A, E, R | Scope.Scope> {
+	return Effect.acquireRelease(acquire, (resource) => release(operation, close(resource)), { interruptible: true })
+}
+
+export type { Drain, Start }
+export { call, drain, release, scoped }

package/src/query/atom.ts

@@ -1,7 +1,10 @@
-import { AuthoringError } from "#errors.ts"
-import type { AnyClosedRoster, AnyField, FloatIntervalValue, Infer, IntervalValue } from "#fields.ts"
-import type { ClassLookup, ClassRecordOf, SchemaClasses } from "#law.ts"
-import type { QueryNode } from "#query/compute.ts"
+import { AuthoringError } from "../errors.ts"
+import type { AnyClosedRoster, AnyField, FloatIntervalValue, Infer, IntervalValue } from "../fields.ts"
+import type { ClassLookup, ClassRecordOf, SchemaClasses } from "../law.ts"
+import type { FieldsShape } from "../relation.ts"
+import type { ScalarKind } from "../scalar.ts"
+import type { Uuid } from "../uuid.ts"
+import type { QueryNode } from "./compute.ts"
 import type {
 	AntiJoinOk,
 	AnyVar,
@@ -14,12 +17,9 @@ import type {
 	ParamValueAt,
 	SetParam,
 	ShapeOf
-} from "#query/scope.ts"
-import { isTerm, term } from "#query/scope.ts"
-import type { Segments } from "#query/segments.ts"
-import type { FieldsShape } from "#relation.ts"
-import type { ScalarKind } from "#scalar.ts"
-import type { Uuid } from "#uuid.ts"
+} from "./scope.ts"
+import { isTerm, term } from "./scope.ts"
+import type { Segments } from "./segments.ts"
 
 type BindingTermData =
 	| { readonly kind: "var"; readonly ref: AnyVar }
@@ -387,12 +387,11 @@ function not(
  * Whether a variable's OWN field is NUMERIC (u64/i64/f64) — the judgment the
  * point side of `pointIn` and the `sum` input read: a point lives in the
  * interval's element domain, and a quantifier is not an addition, so bool
- * (orderable, never numeric) is exactly here refused. A CLOSED reference
- * is excluded even though its kind is `u64`: a vocabulary's declaration-id
- * order is an accident, not semantics
- * § orderability), so every order-comparison and fold position refuses
- * closed-bound terms — the construction-time validations in
- * `#query/lower.ts` are that ban's runtime twin.
+ * (orderable, never numeric) is refused here. A CLOSED reference is
+ * excluded even though its kind is `u64`: a vocabulary's declaration-id
+ * order carries no meaning, so every order-comparison and fold position
+ * refuses closed-bound terms; `query/lower.ts` checks the same at
+ * construction.
  */
 type NumericVarOk<V extends AnyVar> = V["field"] extends { readonly closed: AnyClosedRoster }
 	? false

package/src/query/compute.ts

@@ -1,19 +1,9 @@
-/**
- * Query-scoped scalar expressions (C05 `FindTerm::Compute`): the
- * variable-addressed leaf scope over the ONE shared operator roster in
- * `#scalar.ts`. Leaves are bound query variables that lower to `VarId`s.
- * Operators are the shared constructors — this module only admits known
- * schema kinds at query-var leaves.
- *
- * `ComputeExpr<K>` is a `ScalarNode<"query-var", K>`. Distinct I64 and U64
- * survive host inference; they do not collapse to plain `bigint`.
- */
-import { AuthoringError } from "#errors.ts"
-import type { AnyField } from "#fields.ts"
-import { bool as boolField, f64 as f64Field, i64 as i64Field, rosterOf, u64 as u64Field } from "#fields.ts"
-import type { AnyVar } from "#query/scope.ts"
-import { isTerm, term } from "#query/scope.ts"
-import type { Rounding, ScalarKind, ScalarLiteral, ScalarNode } from "#scalar.ts"
+/** Query scalar expressions use the same nodes that native preparation reads.
+ * Distinct i64 and u64 kinds survive TypeScript's shared bigint carrier. */
+import { AuthoringError } from "../errors.ts"
+import type { AnyField } from "../fields.ts"
+import { bool as boolField, f64 as f64Field, i64 as i64Field, rosterOf, u64 as u64Field } from "../fields.ts"
+import type { Rounding, ScalarKind, ScalarLiteral, ScalarNode } from "../scalar.ts"
 import {
 	checkBool,
 	checkF64,
@@ -30,15 +20,17 @@ import {
 	scalarMeasure,
 	scalarMulDiv,
 	scalarNegate
-} from "#scalar.ts"
+} from "../scalar.ts"
+import type { AnyVar } from "./scope.ts"
+import { isTerm, term } from "./scope.ts"
 
-/** Query-var tree: the shared AST restricted to this leaf scope. */
-type QueryNode = ScalarNode<"query-var">
+/** Query expression, including interval leaves consumed by measure. */
+type QueryNode = ScalarNode
 
 /** Host value for a derived query compute kind. */
 type ComputeValue<K extends ScalarKind> = K extends "f64" ? number : K extends "bool" ? boolean : bigint
 
-type ComputeExpr<K extends ScalarKind> = ScalarNode<"query-var", K>
+type ComputeExpr<K extends ScalarKind> = ScalarNode<K>
 
 type AnyComputeExpr = ComputeExpr<"u64"> | ComputeExpr<"i64"> | ComputeExpr<"f64"> | ComputeExpr<"bool">
 
@@ -65,7 +57,6 @@ type OperandKind<O> =
 function isComputeExpr(value: unknown): value is AnyComputeExpr {
 	return (
 		isScalarNode(value) &&
-		value.scope === "query-var" &&
 		(value.result === "u64" || value.result === "i64" || value.result === "f64" || value.result === "bool")
 	)
 }
@@ -99,7 +90,7 @@ function asQueryNode(where: string, operand: Operand): QueryNode {
 }
 
 function literal<K extends ScalarKind>(value: ScalarLiteral): ComputeExpr<K> {
-	return scalarLiteral("query-var", value) as ComputeExpr<K>
+	return scalarLiteral(value) as ComputeExpr<K>
 }
 
 function u64(value: bigint): ComputeExpr<"u64"> {

package/src/query/find.ts

@@ -1,10 +1,10 @@
-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"
+import type { BoolField, F64Field, I64Field, Infer, IntervalField, U64Field } from "../fields.ts"
+import type { SchemaClasses } from "../law.ts"
+import type { ScalarKind } from "../scalar.ts"
+import type { IntervalVarOk, NumericVarOk } from "./atom.ts"
+import type { AnyComputeExpr, ComputeExpr, ComputeValue } from "./compute.ts"
+import type { AnyVar, MintSlotOf } from "./scope.ts"
+import type { Segments } from "./segments.ts"
 
 type FoldOpName = "sum" | "mean" | "min" | "max" | "pack"
 
@@ -35,7 +35,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 —
  * of a measured interval in a following stage. Bool stays refused: a
- * quantifier is not an addition (R3).
+ * quantifier is not an addition.
  */
 function sum<const O extends AnyVar>(over: O): Agg<"sum", O> {
 	return aggregate("sum", over)