@bjornpagen/bumbledb 0.12.0 → 0.14.0

package/src/native.ts

@@ -44,6 +44,24 @@ type TxHandle = { readonly __brand: "bumbledb.tx" }
 /** One prepared query (plan pinned at prepare). */
 type PreparedHandle = { readonly __brand: "bumbledb.prepared" }
 
+/**
+ * Engine mutation report as it crosses napi: both counts are engine
+ * values, never reconstructed from JS length.
+ */
+interface WireMutationReport {
+	readonly submitted: bigint
+	readonly changed: bigint
+}
+
+/**
+ * Engine fresh-id range as it crosses napi. Empty cannot yield a start —
+ * `start` is a minted id only on the nonempty arm. (C wires empty as
+ * `{ start: 0, end_exclusive: 0 }` at that boundary only.)
+ */
+type WireFreshRange =
+	| { readonly empty: true }
+	| { readonly empty: false; readonly start: bigint; readonly endExclusive: bigint }
+
 /** A half-open interval `[start, end)` as it crosses the boundary. */
 interface IntervalValue {
 	readonly start: bigint
@@ -118,15 +136,14 @@ interface RuleIr {
 	readonly conditions: readonly ConditionTreeIr[]
 }
 
-/** One find term (mirrors `ir::FindTerm`). Count carries no `over`; folds require it. */
+/** One find term (mirrors `ir::FindTerm`). Count is nullary; pack and folds carry `over`. */
 type FoldOpIr = { readonly kind: "sum" } | { readonly kind: "min" } | { readonly kind: "max" }
 
-type ArgOpIr = FoldOpIr | { readonly kind: "pack" }
-
 type FindTermIr =
 	| { readonly kind: "var"; readonly var: number }
-	| { readonly kind: "aggregate"; readonly op: { readonly kind: "count" } }
-	| { readonly kind: "aggregate"; readonly op: ArgOpIr; readonly over: number }
+	| { readonly kind: "count" }
+	| { readonly kind: "aggregate"; readonly op: FoldOpIr; readonly over: number }
+	| { readonly kind: "pack"; readonly over: number }
 	| { readonly kind: "measure"; readonly var: number }
 	| { readonly kind: "aggregateMeasure"; readonly op: FoldOpIr; readonly over: number }
 
@@ -497,12 +514,14 @@ interface Native {
 	 */
 	dbWriteFrom(db: DbHandle, snap: SnapshotHandle): WriteFromResult
 	/**
-	 * Records an insert into the delta; `true` iff the final state changed.
-	 * Nothing is judged until commit; shape violations throw typed.
+	 * Records a collection of inserts into the delta; returns the engine
+	 * `{ submitted, changed }` report. `rows` is an array of value-arrays
+	 * in sealed field order. Empty is lawful and still a mutation (poison
+	 * is observed). Nothing is judged until commit; shape violations throw typed.
 	 */
-	txInsert(tx: TxHandle, relationId: number, values: readonly FactValue[]): boolean
-	/** Records a delete into the delta; `true` iff the final state changed. */
-	txDelete(tx: TxHandle, relationId: number, values: readonly FactValue[]): boolean
+	txInsert(tx: TxHandle, relationId: number, rows: readonly (readonly FactValue[])[]): WireMutationReport
+	/** Records a collection of deletes; returns the engine `{ submitted, changed }` report. */
+	txDelete(tx: TxHandle, relationId: number, rows: readonly (readonly FactValue[])[]): WireMutationReport
 	/**
 	 * Final-state membership (base + pending delta — the exact view the
 	 * commit judgment judges; check-then-act is race-free by construction).
@@ -511,12 +530,10 @@ interface Native {
 	/** Final-state point lookup through a key statement; `null` on a miss. */
 	txGet(tx: TxHandle, relationId: number, keyStatementId: number, keyValues: readonly FactValue[]): FactValue[] | null
 	/**
-	 * Mints the next fresh value for `(relationId, fieldId)` and returns it
-	 * — the engine's alloc-then-insert dyn-lane mint (there is no
-	 * insert-with-omitted-fields spelling; include the minted id in the
-	 * full row).
+	 * Mints `count` consecutive fresh values for `(relationId, fieldId)`.
+	 * `count === 0n` is empty and does not yield a start.
 	 */
-	txAlloc(tx: TxHandle, relationId: number, fieldId: number): bigint
+	txReserve(tx: TxHandle, relationId: number, fieldId: number, count: bigint): WireFreshRange
 	/**
 	 * Commits the delta: every dependency statement judged against the
 	 * final state; a rejection carries the complete violation rendering.
@@ -641,7 +658,6 @@ function bridged<T>(context: string, run: () => T): T {
 
 export type {
 	AggOpIr,
-	ArgOpIr,
 	AtomIr,
 	AtomSourceIr,
 	CmpOpIr,
@@ -683,6 +699,8 @@ export type {
 	TxHandle,
 	Violation,
 	ViolationFact,
+	WireFreshRange,
+	WireMutationReport,
 	WriteFromResult
 }
 export { bridged, loadNativeBinding, native, SHIPPED_PLATFORMS }

package/src/query/find.ts

@@ -24,19 +24,25 @@ import type { IntervalVarOk, NumericVarOk, OrderVarOk } from "#query/atom.ts"
 import type { AnyVar, Duration, MintSlotOf } from "#query/scope.ts"
 
 /** One aggregate operator name of the find vocabulary. */
-type AggOpName = "count" | "sum" | "min" | "max" | "pack"
+type FoldOpName = "sum" | "min" | "max" | "pack"
+type AggOpName = "count" | FoldOpName
+
+/** Nullary count: no `over` exists to inhabit. */
+interface CountAgg {
+	readonly agg: "count"
+}
 
 /**
- * One aggregate find VALUE: the op and the variable (or measure) it folds
- * BY REFERENCE. The variable's own descriptor types the result.
+ * One fold aggregate: the op and the variable (or measure) it folds
+ * BY REFERENCE. Count is [`CountAgg`], not this type with `undefined`.
  */
-interface Agg<Op extends AggOpName, Over extends AnyVar | Duration | undefined> {
+interface Agg<Op extends FoldOpName, Over extends AnyVar | Duration> {
 	readonly agg: Op
 	readonly over: Over
 }
 
 /** Any aggregate find value. */
-type AnyAgg = Agg<AggOpName, AnyVar | Duration | undefined>
+type AnyAgg = CountAgg | Agg<FoldOpName, AnyVar | Duration>
 
 /** One find entry: a projected variable, the measure, or an aggregate. */
 type FindEntry = AnyVar | Duration | AnyAgg
@@ -44,17 +50,14 @@ type FindEntry = AnyVar | Duration | AnyAgg
 /** The `find` record: column name → find entry. Keys ARE the answer columns. */
 type FindShape = Readonly<Record<string, FindEntry>>
 
-/** Builds one aggregate value. */
-function aggregate<Op extends AggOpName, Over extends AnyVar | Duration | undefined>(
-	op: Op,
-	over: Over
-): Agg<Op, Over> {
+/** Builds one fold aggregate value. */
+function aggregate<Op extends FoldOpName, Over extends AnyVar | Duration>(op: Op, over: Over): Agg<Op, Over> {
 	return Object.freeze({ agg: op, over })
 }
 
 /** Nullary count: |the group's set of distinct full bindings|, `bigint`. */
-function count(): Agg<"count", undefined> {
-	return aggregate("count", undefined)
+function count(): CountAgg {
+	return Object.freeze({ agg: "count" })
 }
 
 /**
@@ -119,7 +122,7 @@ type FindEntryOk<E> = E extends AnyVar
 	? true
 	: E extends Duration<infer V extends AnyVar>
 		? IntervalVarOk<V>
-		: E extends Agg<"count", undefined>
+		: E extends CountAgg
 			? true
 			: E extends Agg<"sum", infer O>
 				? SumOverOk<O>
@@ -151,7 +154,7 @@ type FindValue<E> = E extends AnyVar
 	? Infer<E["field"]>
 	: E extends Duration<AnyVar>
 		? bigint
-		: E extends Agg<"count", undefined>
+		: E extends CountAgg
 			? bigint
 			: E extends Agg<"sum" | "min" | "max", infer O>
 				? O extends AnyVar
@@ -179,10 +182,12 @@ export type {
 	AnyAgg,
 	CheckFind,
 	CheckRecFind,
+	CountAgg,
 	FindEntry,
 	FindEntryOk,
 	FindShape,
 	FindValue,
+	FoldOpName,
 	HeadRecordOf,
 	RowOfFind
 }

package/src/query/lower.ts

@@ -772,7 +772,7 @@ function advanceInterior(
 }
 
 /** Narrows a find entry to an aggregate value. */
-function isAggregateEntry(value: unknown): value is { readonly agg: string; readonly over: unknown } {
+function isAggregateEntry(value: unknown): value is { readonly agg: string; readonly over?: unknown } {
 	return typeof value === "object" && value !== null && "agg" in value
 }
 
@@ -785,11 +785,12 @@ function asVarTerm(context: string, value: unknown): AnyVar {
 }
 
 /** Classifies one aggregate find entry into its runtime data (variables ride by reference). */
-function aggDataOf(name: string, entry: { readonly agg: string; readonly over: unknown }): AggData {
+function aggDataOf(name: string, entry: { readonly agg: string; readonly over?: unknown }): AggData {
+	if (entry.agg === "count") {
+		return Object.freeze({ op: "count" as const })
+	}
 	const over = entry.over
 	switch (entry.agg) {
-		case "count":
-			return Object.freeze({ op: "count" as const })
 		case "sum":
 		case "min":
 		case "max": {
@@ -2051,7 +2052,7 @@ function lowerFind(entry: FindEntryData, ids: VarIds): FindTermIr {
 	const agg = entry.agg
 	switch (agg.op) {
 		case "count":
-			return { kind: "aggregate", op: { kind: "count" } }
+			return { kind: "count" }
 		case "fold": {
 			if ("duration" in agg.over) {
 				return { kind: "aggregateMeasure", op: { kind: agg.fold }, over: ids.of(agg.over.duration) }
@@ -2059,7 +2060,7 @@ function lowerFind(entry: FindEntryData, ids: VarIds): FindTermIr {
 			return { kind: "aggregate", op: { kind: agg.fold }, over: ids.of(agg.over) }
 		}
 		case "pack":
-			return { kind: "aggregate", op: { kind: "pack" }, over: ids.of(agg.over) }
+			return { kind: "pack", over: ids.of(agg.over) }
 	}
 }
 

package/src/query/parse-ir.ts

@@ -50,28 +50,30 @@ function align(context: string, head: readonly HeadTermIr[], rules: readonly Rul
 	}
 }
 
-/** Count forbids `over`; every other aggregate requires it. */
+/** Count is nullary; pack and folds require `over`. */
 function parseFind(context: string, find: FindTermIr): void {
-	if (find.kind !== "aggregate") {
-		return
-	}
-	if (find.op.kind === "count") {
-		if ("over" in find) {
+	const raw = find as Record<string, unknown>
+	if (find.kind === "count") {
+		if ("over" in raw) {
 			throw errors.new(`${context}: Count carries no over`)
 		}
 		return
 	}
-	if (!("over" in find)) {
-		throw errors.new(`${context}: fold aggregate requires over`)
+	if (find.kind === "pack" || find.kind === "aggregate" || find.kind === "aggregateMeasure") {
+		if (!("over" in raw)) {
+			throw errors.new(`${context}: ${find.kind} requires over`)
+		}
 	}
 }
 
-/** Head family of one find term: measure is a var slot; measure-folds are aggregates. */
+/** Head family of one find term: measure is a var slot; count/pack/folds are aggregates. */
 function findFamily(find: FindTermIr): "var" | "aggregate" {
 	switch (find.kind) {
 		case "var":
 		case "measure":
 			return "var"
+		case "count":
+		case "pack":
 		case "aggregate":
 		case "aggregateMeasure":
 			return "aggregate"

package/src/relation.ts

@@ -7,19 +7,15 @@
  * verified against their roster at construction). Fields are addressed by
  * NAME everywhere — statements (`on(R, "holder")`), selections, and match
  * records all spell the field's own name, checked by type
- * (`FaceFields`/`MatchShape`). `Fact<>`/`InsertFact<>` are the inferred
- * row object types at BARE structural value types (no brands): fresh
- * fields are optional on insert input (omit-to-mint) and present on read
- * (resupply-to-preserve-identity), typed exactly.
+ * (`FaceFields`/`MatchShape`). `Fact<>` is the inferred row object type
+ * at BARE structural value types (no brands): every field is present,
+ * including fresh cells. Mint with `tx.reserve` before insert.
  */
 
 import * as errors from "@superbuilders/errors"
 import { type AnyField, assertDeclarationOrderKey, assertDeclarationRecord, type Infer, literalOf } from "#fields.ts"
 import { type LiteralSetSpec, type LiteralSpec, renderLiteral } from "#spec.ts"
 
-/** Flattens an intersection into one displayed object type (hover legibility). */
-type Flatten<T> = { [K in keyof T]: T[K] }
-
 /**
  * Resolves one selection entry to its lowered literal set: a plain ARRAY
  * (detected by `Array.isArray` — no field's value type is an array;
@@ -177,13 +173,6 @@ type FreshKeys<R extends AnyRelation> = {
 	[K in keyof RelationFields<R>]: RelationFields<R>[K] extends { readonly fresh: true } ? K : never
 }[keyof RelationFields<R>]
 
-/**
- * The inferred row object type of a relation as INSERTED: fresh fields
- * optional — omitted, the engine mints; supplied, identity is preserved
- * (the ETL resupply idiom).
- */
-type InsertFact<R extends AnyRelation> = Flatten<Omit<Fact<R>, FreshKeys<R>> & Partial<Pick<Fact<R>, FreshKeys<R>>>>
-
 /**
  * Declares one relation: `relation("Account", { id: u64.fresh,
  * holder: u64, kind: Kind.id, ... })` — every field is a pure-structure
@@ -228,7 +217,6 @@ export type {
 	Fact,
 	FieldsShape,
 	FreshKeys,
-	InsertFact,
 	Relation,
 	RelationData,
 	RelationField,