@bjornpagen/bumbledb 0.12.2 → 0.14.0

package/src/db.ts

@@ -37,17 +37,7 @@ import type { Exhumed } from "#exhume.ts"
 import { exhumeStore } from "#exhume.ts"
 import { rosterOf } from "#fields.ts"
 import { lower } from "#lower.ts"
-import {
-	factOf,
-	handleOf,
-	isFreshField,
-	isInserted,
-	type KeyFact,
-	keyRowOf,
-	type Minted,
-	recordOf,
-	rowOf
-} from "#marshal.ts"
+import { factOf, handleOf, isFreshField, type KeyFact, keyRowOf, recordOf, rowOf } from "#marshal.ts"
 
 import type {
 	DbHandle,
@@ -56,6 +46,7 @@ import type {
 	PreparedHandle,
 	SnapshotHandle,
 	TxHandle,
+	WireFreshRange,
 	Violation as WireViolation,
 	ViolationFact as WireViolationFact
 } from "#native.ts"
@@ -65,7 +56,7 @@ import type { Query } from "#query/lower.ts"
 import { lowerQuery } from "#query/lower.ts"
 import { decodeAnswers, wireParams } from "#query/run.ts"
 import type { ParamEntry, ParamsRecord } from "#query/scope.ts"
-import type { AnyRelation, Fact, InsertFact } from "#relation.ts"
+import type { AnyRelation, Fact, FreshKeys } from "#relation.ts"
 import type { AnySchema, Schema, SchemaRelation, SchemaRelations } from "#schema.ts"
 import { isStatement, type KeyStatement, type Statement } from "#statements.ts"
 
@@ -76,6 +67,70 @@ import { isStatement, type KeyStatement, type Statement } from "#statements.ts"
  */
 type MemberRelation<Rels extends SchemaRelations> = Extract<Rels[keyof Rels], AnyRelation>
 
+/**
+ * Facts consumed vs facts that changed the in-memory final-state view.
+ * The length-1 report is `{ submitted: 1n, changed: 0n | 1n }`.
+ */
+interface MutationReport {
+	readonly submitted: bigint
+	readonly changed: bigint
+}
+
+/**
+ * Half-open fresh-id range from one `reserve`. Empty cannot yield a
+ * minted id — `start` exists only on the nonempty arm.
+ */
+type FreshRange =
+	| {
+			readonly empty: true
+			readonly count: 0n
+			at(index: bigint): undefined
+			[Symbol.iterator](): IterableIterator<bigint>
+	  }
+	| {
+			readonly empty: false
+			readonly start: bigint
+			readonly endExclusive: bigint
+			readonly count: bigint
+			at(index: bigint): bigint | undefined
+			[Symbol.iterator](): IterableIterator<bigint>
+	  }
+
+function freshRangeOf(wire: WireFreshRange): FreshRange {
+	if (wire.empty) {
+		return Object.freeze({
+			empty: true,
+			count: 0n,
+			at(_index: bigint) {
+				return undefined
+			},
+			*[Symbol.iterator](): IterableIterator<bigint> {}
+		})
+	}
+	const start = wire.start
+	const endExclusive = wire.endExclusive
+	const count = endExclusive - start
+	return Object.freeze({
+		empty: false,
+		start,
+		endExclusive,
+		get count() {
+			return count
+		},
+		at(index: bigint) {
+			if (index < 0n || index >= count) {
+				return undefined
+			}
+			return start + index
+		},
+		*[Symbol.iterator](): IterableIterator<bigint> {
+			for (let id = start; id < endExclusive; id++) {
+				yield id
+			}
+		}
+	})
+}
+
 /**
  * The key object of a key-statement-selected `get`: exactly the selected
  * `key()` statement's projection fields, each at the relation's own BARE
@@ -297,21 +352,22 @@ function abandonedOutcome<Rels extends SchemaRelations, R>(
  */
 interface Tx<Rels extends SchemaRelations> {
 	/**
-	 * Records one insert. Omitted fresh fields are MINTED through the
-	 * engine's alloc lane and returned as bare bigints; supplying them instead
-	 * preserves identity (the resupply idiom). Returns `{ changed, ...fresh }`
-	 * (ruled 2026-07-23, R11): the engine's changed-state report — the Rust
-	 * surface's `insert(&fact) -> bool` bijection `delete` always honored —
-	 * beside the relation's fresh cells, minted or resupplied. The
-	 * idempotent-replay lane reads the bit from the insert itself; no extra
-	 * `contains` round trip exists. The flattened shape cannot carry a FRESH
-	 * cell literally named `changed` beside the report, so admission refuses
-	 * that one spelling ({@link refuseShadowedChanged}) — never a silent
-	 * shadow here.
+	 * Records a collection of inserts. Singleton is `[fact]`. Empty is
+	 * lawful. Returns how many facts were consumed and how many changed
+	 * the in-memory final-state view. Every fact is complete — omitted
+	 * fresh cells are a type error; mint first with {@link Tx.reserve}.
+	 */
+	insert<R extends MemberRelation<Rels>>(relation: R, facts: Iterable<Fact<R>>): MutationReport
+	/**
+	 * Records a collection of deletes. Singleton is `[fact]`. Returns
+	 * how many facts were consumed and how many changed the view.
+	 */
+	delete<R extends MemberRelation<Rels>>(relation: R, facts: Iterable<Fact<R>>): MutationReport
+	/**
+	 * Mints `count` consecutive fresh values for a `.fresh` field.
+	 * `count === 0n` is empty and does not yield a start.
 	 */
-	insert<R extends MemberRelation<Rels>>(relation: R, fact: InsertFact<R>): { readonly changed: boolean } & Minted<R>
-	/** Records one delete; `true` iff the final state changed. */
-	delete<R extends MemberRelation<Rels>>(relation: R, fact: Fact<R>): boolean
+	reserve<R extends MemberRelation<Rels>>(relation: R, field: FreshKeys<R> & string, count: bigint): FreshRange
 	/** Final-state membership of one complete fact. */
 	contains<R extends MemberRelation<Rels>>(relation: R, fact: Fact<R>): boolean
 	/**
@@ -791,44 +847,6 @@ const ErrGenerationMoved = errors.new(
 	"bumbledb generationMoved: a state-changing commit landed since the witness snapshot"
 )
 
-/**
- * Fills one insert's omitted fresh cells through the engine's
- * alloc-then-insert dyn lane (there is no insert-with-omitted-fields wire
- * spelling) and collects every fresh cell — minted or resupplied — for the
- * insert's return. Mutates `values` in place with the minted cells.
- */
-function mintFreshCells(
-	txHandle: TxHandle,
-	entry: RelationEntry,
-	relation: AnyRelation,
-	values: Record<string, unknown>
-): Record<string, FactValue> {
-	const fresh: Record<string, FactValue> = {}
-	for (const declared of relation.data.fields) {
-		if (!isFreshField(declared.field)) {
-			continue
-		}
-		let cell = values[declared.name]
-		if (cell === undefined) {
-			const fieldId = entry.fieldIds.get(declared.name)
-			if (fieldId === undefined) {
-				throw errors.new(`bumbledb manifest drift: relation ${relation.name} has no field id for ${declared.name}`)
-			}
-			cell = bridged("bumbledb tx alloc", function mint() {
-				return native.txAlloc(txHandle, entry.id, fieldId)
-			})
-			values[declared.name] = cell
-		}
-		if (typeof cell !== "bigint") {
-			throw errors.new(
-				`relation ${relation.name} field ${declared.name}: a fresh cell is a u64 bigint, got ${typeof cell}`
-			)
-		}
-		fresh[declared.name] = cell
-	}
-	return fresh
-}
-
 /**
  * Constructs one open `Db` over an already-admitted handle: builds the
  * id-resolution tables once and closes over them — the `Db` owns handle
@@ -1215,38 +1233,59 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 				})
 			}
 		})
-		function insert<R extends MemberRelation<Rels>>(
-			relation: R,
-			fact: InsertFact<R>
-		): { readonly changed: boolean } & Minted<R> {
+		function insert<R extends MemberRelation<Rels>>(relation: R, facts: Iterable<Fact<R>>): MutationReport {
 			assertLive()
+			const rows: FactValue[][] = []
+			for (const fact of facts) {
+				rows.push(rowOf(relation.data, recordOf(fact)))
+			}
 			const entry = resolveOrdinary(relation)
 			const txHandle = resolveTx()
-			/** The one spread copy of the write path: `mintFreshCells` writes minted cells in place, and they must never land in the caller's own fact object. */
-			const values: Record<string, unknown> = { ...recordOf(fact) }
-			const fresh = mintFreshCells(txHandle, entry, relation, values)
-			const row = rowOf(relation.data, values)
-			const changed = bridged("bumbledb tx insert", function record() {
-				return native.txInsert(txHandle, entry.id, row)
+			const report = bridged("bumbledb tx insert", function record() {
+				return native.txInsert(txHandle, entry.id, rows)
 			})
-			const inserted: Readonly<Record<string, FactValue | boolean>> = Object.freeze({ changed, ...fresh })
-			if (!isInserted(relation, inserted)) {
-				throw errors.new(`relation ${relation.name}: insert return record is incomplete`)
+			return Object.freeze({ submitted: report.submitted, changed: report.changed })
+		}
+		function remove<R extends MemberRelation<Rels>>(relation: R, facts: Iterable<Fact<R>>): MutationReport {
+			assertLive()
+			const rows: FactValue[][] = []
+			for (const fact of facts) {
+				rows.push(rowOf(relation.data, recordOf(fact)))
 			}
-			return inserted
+			const entry = resolveOrdinary(relation)
+			const txHandle = resolveTx()
+			const report = bridged("bumbledb tx delete", function record() {
+				return native.txDelete(txHandle, entry.id, rows)
+			})
+			return Object.freeze({ submitted: report.submitted, changed: report.changed })
 		}
-		function remove<R extends MemberRelation<Rels>>(relation: R, fact: Fact<R>): boolean {
+		function reserve<R extends MemberRelation<Rels>>(
+			relation: R,
+			field: FreshKeys<R> & string,
+			count: bigint
+		): FreshRange {
 			assertLive()
 			const entry = resolveOrdinary(relation)
+			const declared = relation.data.fields.find(function byName(candidate) {
+				return candidate.name === field
+			})
+			if (declared === undefined || !isFreshField(declared.field)) {
+				throw errors.new(`relation ${relation.name}: field ${field} is not a fresh cell`)
+			}
+			const fieldId = entry.fieldIds.get(field)
+			if (fieldId === undefined) {
+				throw errors.new(`bumbledb manifest drift: relation ${relation.name} has no field id for ${field}`)
+			}
 			const txHandle = resolveTx()
-			const row = rowOf(relation.data, recordOf(fact))
-			return bridged("bumbledb tx delete", function record() {
-				return native.txDelete(txHandle, entry.id, row)
+			const range = bridged("bumbledb tx reserve", function mint() {
+				return native.txReserve(txHandle, entry.id, fieldId, count)
 			})
+			return freshRangeOf(range)
 		}
 		const tx: Tx<Rels> = Object.freeze({
 			insert,
 			delete: remove,
+			reserve,
 			contains: reads.contains,
 			get: reads.get
 		})
@@ -1418,27 +1457,6 @@ const ErrNewtypeMismatch = errors.new(
 	"bumbledb newtypeMismatch: a statement pairs faces whose newtypes disagree — the faces of a dependency agree on their newtype, or neither carries one"
 )
 
-/**
- * `Tx.insert` returns the flattened `{ changed, ...fresh }` record (R11),
- * where the spread wins: a FRESH field literally named `changed` would
- * shadow the engine's changed-state report on every insert of its
- * relation. No field name is reserved SILENTLY — the one unspeakable
- * spelling is refused here at admission, before any store is touched.
- * Supplied (non-fresh) fields named `changed` never enter the return
- * record and stay legal.
- */
-function refuseShadowedChanged(theory: AnySchema): void {
-	for (const [name, member] of Object.entries(theory.relations)) {
-		for (const declared of sealedFieldsOf(member)) {
-			if (declared.name === "changed" && isFreshField(declared.field)) {
-				throw errors.new(
-					`relation ${name}: a fresh field named "changed" would shadow tx.insert's changed-state report in its { changed, ...fresh } return (R11) — rename the fresh field; a supplied field named "changed" stays legal (only fresh cells ride the return)`
-				)
-			}
-		}
-	}
-}
-
 /**
  * The one admission path both verbs share: lower the theory, run one
  * bridge call, and wrap the domain refusals — `schemaError` (spec
@@ -1455,7 +1473,6 @@ function admit<Rels extends SchemaRelations>(
 	storePath: string,
 	theory: Schema<Rels>
 ): Db<Rels> {
-	refuseShadowedChanged(theory)
 	const canonical = path.resolve(storePath)
 	const spec = lower(theory)
 	const opened = bridged(`${verb} bumbledb store at ${canonical}`, function callBridge() {
@@ -1527,9 +1544,11 @@ export type {
 	DeclaredKeyFact,
 	DeclaredKeyViolation,
 	DeltaBuild,
+	FreshRange,
 	ImpliedKeyViolation,
 	MemberRelation,
 	MirrorViolation,
+	MutationReport,
 	OffendingFact,
 	Prepared,
 	ReadScope,

package/src/index.ts

@@ -56,9 +56,11 @@ export type {
 	DeclaredKeyFact,
 	DeclaredKeyViolation,
 	DeltaBuild,
+	FreshRange,
 	ImpliedKeyViolation,
 	MemberRelation,
 	MirrorViolation,
+	MutationReport,
 	OffendingFact,
 	Prepared,
 	ReadScope,
@@ -114,7 +116,7 @@ export type {
 export { bool, bytes, i64, interval, span, str, u64 } from "#fields.ts"
 export type { ClassesOf, ClassWall, LawfulStatements, RelationClasses, SchemaClasses } from "#law.ts"
 export { lower, lowerClosed, lowerRelation } from "#lower.ts"
-export type { KeyFact, Minted } from "#marshal.ts"
+export type { KeyFact } from "#marshal.ts"
 export type { FactValue, ParsedQuery, QueryIr, StatementKindTag } from "#native.ts"
 
 export type {
@@ -169,7 +171,6 @@ export type {
 	Fact,
 	FieldsShape,
 	FreshKeys,
-	InsertFact,
 	Relation,
 	RelationData,
 	RelationField,

package/src/marshal.ts

@@ -43,13 +43,6 @@ function isFreshField(field: AnyField): boolean {
 	return "fresh" in field && field.fresh === true
 }
 
-/**
- * The inferred object type `tx.insert` returns: one property per
- * fresh-marked field of `R`, carrying the minted (or resupplied) id as a
- * bare `bigint`. A relation with no fresh field returns the empty object.
- */
-type Minted<R extends AnyRelation> = { [K in FreshKeys<R>]: Fact<R>[K] }
-
 /**
  * The key object `get` reads through. THE PRIMARY-KEY RULE: `get` always
  * reads through the PRIMARY candidate key — the first-declared one in the
@@ -74,10 +67,7 @@ type KeyFact<R extends AnyRelation> = [FreshKeys<R>] extends [never]
  * ALLOCATION-FREE IDENTITY (the admission predicate is the type
  * reprojection; the value passes through untouched): every consumer
  * downstream — `rowOf`, `keyRowOf`, the query param marshal — only READS
- * properties, so no copy is warranted. The one mutating consumer
- * (`mintFreshCells` on the insert path) takes its own spread copy at the
- * call site, so the caller's fact object is never written through this
- * seam.
+ * properties, so no copy is warranted.
  */
 function recordOf(fact: object): Readonly<Record<string, unknown>> {
 	if (!isStringIndexed(fact)) {
@@ -203,9 +193,8 @@ function cellOf(context: string, field: AnyField, value: unknown): FactValue {
 
 /**
  * Marshals one complete fact object to its positional row, in field
- * declaration order (= ordinal ids). Every declared field must be present;
- * fresh minting happens BEFORE this point (the transaction fills omitted
- * fresh cells via the engine's alloc lane).
+ * declaration order (= ordinal ids). Every declared field must be present.
+ * Mint with `tx.reserve` first; insert takes complete facts.
  */
 function rowOf(relation: RelationData, fact: Readonly<Record<string, unknown>>): FactValue[] {
 	return relation.fields.map(function marshalCell(declared) {
@@ -260,25 +249,6 @@ function isCompleteFact<R extends AnyRelation>(
 	})
 }
 
-/**
- * The insert-return trusted seam (R11): one insert's return carries the
- * engine's changed-state report beside the collected fresh cells (minted by
- * the engine or resupplied by the caller) — the bit is verified boolean and
- * the fresh ids present, same presence-only direction as
- * {@link isCompleteFact}.
- */
-function isInserted<R extends AnyRelation>(
-	relation: R,
-	value: Readonly<Record<string, FactValue | boolean>>
-): value is Readonly<Record<string, FactValue | boolean>> & { readonly changed: boolean } & Minted<R> {
-	return (
-		typeof value.changed === "boolean" &&
-		relation.data.fields.every(function presentWhenFresh(declared) {
-			return !isFreshField(declared.field) || value[declared.name] !== undefined
-		})
-	)
-}
-
 /**
  * Unmarshals one positional row to the relation's named, frozen fact object
  * of bare structural values — the inverse of {@link rowOf},
@@ -310,5 +280,5 @@ function factOf<R extends AnyRelation>(relation: R, row: readonly FactValue[]):
 	return decoded
 }
 
-export type { KeyFact, Minted }
-export { cellOf, factOf, handleOf, isFreshField, isInserted, keyRowOf, recordOf, rowOf }
+export type { KeyFact }
+export { cellOf, factOf, handleOf, isFreshField, keyRowOf, recordOf, rowOf }

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"