@bjornpagen/bumbledb 0.12.2 → 0.15.0

package/src/native.ts

@@ -22,28 +22,46 @@ import type { SchemaSpec, ValueSpec, ValueTypeSpec } from "#spec.ts"
 /** The opaque database handle (owns the LMDB environment + exclusive lock). */
 type DbHandle = { readonly __brand: "bumbledb.db" }
 
-/** One live MVCC read snapshot. */
-type SnapshotHandle = { readonly __brand: "bumbledb.snapshot" }
+/** One live borrowed instance valid only inside a read callback. */
+type InstanceHandle = { readonly __brand: "bumbledb.instance" }
 
-/**
- * One exhumed store — the read-only, theory-less open (engine 70-api.md
- * § exhume). Lifetimes are disposables (ruled 2026-07-23, R12):
- * `exhumeClose` is the deterministic teardown the SDK's `Symbol.dispose`
- * rides — releasing the environment (and the store's exclusive lock)
- * scope-shaped, never a GC race; the engine-side drop remains the
- * reclamation-only backstop for a collected-but-undisposed handle.
- */
-type ExhumeHandle = { readonly __brand: "bumbledb.exhume" }
+/** One cloneable generation witness. May outlive the read that minted it. */
+type WitnessHandle = { readonly __brand: "bumbledb.witness" }
+
+/** One unproved heap builder. Spent by `instanceBuilderAdmit` / close. */
+type BuilderHandle = { readonly __brand: "bumbledb.builder" }
+
+/** One admitted heap instance. */
+type OwnedHandle = { readonly __brand: "bumbledb.owned" }
 
 /**
  * One live write transaction — the submitted delta with the engine's
- * final-state point-read view. Spent by `txCommit`/`txAbort`.
+ * final-state point-read view. Valid only inside a write callback.
  */
 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
+ * `BDB_FRESH_RANGE_TAG_EMPTY`. The JS wire is `{ empty: true }`, not that
+ * C sentinel.)
+ */
+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 }
 
@@ -278,14 +295,22 @@ type Violation =
 	  }
 
 /**
- * `dbCreate`/`dbOpen`'s domain outcome. `schemaError` spans both spec
+ * `dbCreate`'s domain outcome. Admission is `accepted` / `rejected`.
+ * Declaration-boundary refusals ride as their own tags (not theory
+ * admission) and the SDK throws them.
+ */
+type CreateResult =
+	| { readonly tag: "accepted"; readonly db: DbHandle }
+	| { readonly tag: "rejected"; readonly violations: readonly Violation[] }
+	| { readonly tag: "schemaError"; readonly message: string }
+	| { readonly tag: "newtypeMismatch"; readonly message: string }
+
+/**
+ * `dbOpen`'s domain outcome. `schemaError` spans both spec
  * resolution (unresolvable names, banned spellings — every issue in one
  * message) and schema validation at the declaration boundary;
- * `newtypeMismatch` is the coherence wall's own kind — a spec whose
- * statement pairs faces with disagreeing newtype labels (the engine twin
- * of the schema-level class wall; unreachable through the typed builder,
- * which computes every label from the laws, so only a raw spec can reach
- * it); `fingerprintMismatch` is `dbOpen`'s stored-theory refusal.
+ * `newtypeMismatch` is the coherence wall's own kind; `fingerprintMismatch`
+ * is `dbOpen`'s stored-theory refusal.
  */
 type DbOpenResult =
 	| { readonly ok: true; readonly db: DbHandle }
@@ -296,46 +321,23 @@ type DbOpenResult =
 	  }
 
 /**
- * `dbExhume`'s domain outcome: the live exhume handle, or one of the three
- * adoption-era refusals as data — `descriptorMissing` (the store predates
- * self-describing stores and has not been adopted; the remedy is one
- * fingerprint-matching `dbOpen` under the creating schema),
- * `formatMismatch`, and `corruption` (the persisted descriptor fails its
- * integrity gates). Genuine failures — a missing path, a held exclusive
- * lock — throw.
- */
-type ExhumeResult =
-	| { readonly ok: true; readonly exhume: ExhumeHandle }
-	| {
-			readonly ok: false
-			readonly kind: "descriptorMissing" | "formatMismatch" | "corruption"
-			readonly message: string
-	  }
-
-/**
- * `dbWriteFrom`'s domain outcome: the live witnessed transaction, or the
- * typed stale-premise verdict (a state-changing commit landed after the
- * witness snapshot; retry policy is host-side).
+ * `dbWrite` / `dbWriteFrom` native outcome. The SDK attaches the callback
+ * return onto the accepted arm. Moved is data, never an error kind.
  */
-type WriteFromResult =
-	| { readonly ok: true; readonly tx: TxHandle }
-	| {
-			readonly ok: false
-			readonly kind: "generationMoved"
-			readonly witnessed: bigint
-			readonly current: bigint
-	  }
+type NativeWriteOutcome =
+	| { readonly tag: "accepted"; readonly generation: bigint }
+	| { readonly tag: "rejected"; readonly violations: readonly Violation[] }
+	| { readonly tag: "abandoned" }
+	| { readonly tag: "moved"; readonly witnessed: bigint; readonly current: bigint }
 
 /**
- * `txCommit`'s domain outcome: the committed generation, or the COMPLETE
- * violation set (every violated statement cited once, per direction for a
- * containment, in materialized statement order).
+ * Builder `admit` native outcome.
  */
-type CommitResult =
-	| { readonly ok: true; readonly generation: bigint }
-	| { readonly ok: false; readonly violations: readonly Violation[] }
+type AdmitResult =
+	| { readonly tag: "accepted"; readonly value: OwnedHandle }
+	| { readonly tag: "rejected"; readonly violations: readonly Violation[] }
 
-/** `dbPrepare`'s domain outcome (IR roster errors are data). */
+/** `dbPrepare`/`instancePrepare`'s domain outcome (IR roster errors are data). */
 type PrepareResult =
 	| { readonly ok: true; readonly prepared: PreparedHandle }
 	| { readonly ok: false; readonly kind: "irError"; readonly message: string }
@@ -357,13 +359,37 @@ interface Staleness {
 	readonly maxRatio: number
 }
 
-/**
- * `dbSnapshot`'s reply: the live handle WITH its witnessed generation —
- * one crossing carries both (read inside the snapshot's own transaction,
- * the race-closing rule of 50-storage.md), so no second `dbGeneration`
- * call exists to pay or defend (finding 016's bridge shape).
- */
-type SnapshotOpened = { readonly ok: true; readonly snapshot: SnapshotHandle; readonly generation: bigint }
+type ErrorFamilyKind =
+	| "formatMismatch"
+	| "schemaMismatch"
+	| "alreadyInitialized"
+	| "destinationExists"
+	| "publishedButUnsynced"
+	| "environmentLocked"
+	| "io"
+	| "lmdb"
+	| "readersFull"
+	| "schema"
+	| "validation"
+	| "factShape"
+	| "freshExhausted"
+	| "closedRelationWrite"
+	| "commitSync"
+	| "transactionPoisoned"
+	| "foreignPrepared"
+	| "foreignWitness"
+	| "param"
+	| "measureOfRay"
+	| "capacityRayMeasure"
+	| "derivedBudgetExceeded"
+	| "overflow"
+	| "resultBytesOverflow"
+	| "corruption"
+
+type AdmissionTag = "accepted" | "rejected"
+type WriteTag = "accepted" | "rejected" | "abandoned" | "moved"
+type OpenKind = "schemaError" | "newtypeMismatch" | "fingerprintMismatch"
+type PrepareKind = "irError"
 
 /**
  * The plan-as-data report (ruled 2026-07-23, R13): the engine's
@@ -394,16 +420,15 @@ interface Native {
 	engineVersion(): string
 
 	/**
-	 * Creates a fresh DURABLE store at `path` (frozen ruling 3: no ephemeral
-	 * kind crosses this bridge). Refuses an already-initialized directory
-	 * (throws); schema failures return as data.
+	 * Creates a fresh durable store at `path`. Refuses an already-initialized
+	 * directory (throws); schema failures return as data.
 	 */
-	dbCreate(path: string, spec: SchemaSpec): DbOpenResult
+	dbCreate(path: string, spec: SchemaSpec): Promise<CreateResult>
 	/**
-	 * Opens an existing durable store, verifying format version, store
-	 * kind, and schema fingerprint (`fingerprintMismatch` as data).
+	 * Opens an existing durable store, verifying format version and
+	 * schema fingerprint (`fingerprintMismatch` as data).
 	 */
-	dbOpen(path: string, spec: SchemaSpec): DbOpenResult
+	dbOpen(path: string, spec: SchemaSpec): Promise<DbOpenResult>
 	/**
 	 * Closes the handle. Dependent handles each hold the engine alive; the
 	 * environment (and its exclusive lock) releases when the last closes.
@@ -422,87 +447,59 @@ interface Native {
 	dbFingerprint(db: DbHandle): string
 	/**
 	 * The current committed generation — diagnostics only. The write-side
-	 * witness is always the SNAPSHOT handle (`dbWriteFrom`), never this
-	 * integer: an integer witness would be a claim a caller could fabricate
-	 * or stale-cache (the engine's recorded refusal).
+	 * witness is always a {@link WitnessHandle}, never this integer.
 	 */
 	dbGeneration(db: DbHandle): bigint
+	/** Publishes an admitted heap instance at `path` without re-judgment. */
+	dbFromInstance(path: string, instance: OwnedHandle): Promise<DbHandle>
 
 	/**
-	 * Opens a store FROM ITS OWN PERSISTED DESCRIPTOR (the read-only,
-	 * theory-less open; engine 70-api.md § exhume) — no schema crosses in.
-	 * The three adoption-era refusals return as data ({@link ExhumeResult});
-	 * genuine failures throw. The handle's deterministic teardown is
-	 * `exhumeClose` (R12); GC reclamation remains the backstop only.
-	 */
-	dbExhume(path: string): ExhumeResult
-	/**
-	 * Closes the exhume handle, releasing its environment (and the store's
-	 * exclusive lock) deterministically — the native teardown under the
-	 * SDK's `Symbol.dispose` (ruled 2026-07-23, R12: lifetimes are
-	 * disposables, never `close()` methods to remember).
-	 */
-	exhumeClose(exhume: ExhumeHandle): void
-	/**
-	 * The exhumed store's persisted schema as manifest-shaped data — the
-	 * engine's own manifest rendering of the STORED descriptor: relations
-	 * in engine-id order, sealed field lists (a closed relation opens with
-	 * the synthetic (`id`, u64) handle field) with structural value types,
-	 * and closed-relation rosters.
+	 * Runs `callback` synchronously inside the engine read lease. The
+	 * instance handle is invalid after the callback returns; the witness
+	 * handle is a clone and may escape.
 	 */
-	exhumeDescriptor(exhume: ExhumeHandle): Manifest
-	/**
-	 * Full-relation export by NAME in row-id order, values marshaled per
-	 * the STORED descriptor (str already resolved through `_dict` inside
-	 * the engine; a closed relation scans its sealed roster). Each call is
-	 * one self-contained snapshot read; an unknown relation name throws.
-	 */
-	exhumeScan(exhume: ExhumeHandle, relationName: string): FactValue[][]
-
-	/**
-	 * Opens one MVCC read snapshot as a live handle, returned WITH its
-	 * witnessed generation — one crossing carries both (finding 016), so
-	 * no separate `dbGeneration` call (with its own transient read
-	 * transaction and fault-pairing close branch) exists on this path.
-	 */
-	dbSnapshot(db: DbHandle): SnapshotOpened
-	/** Closes the snapshot, releasing its LMDB reader slot. */
-	snapshotClose(snap: SnapshotHandle): void
-	/** Full-relation export in row-id order (one row per fact). */
-	snapshotScan(snap: SnapshotHandle, relationId: number): FactValue[][]
-	/** Committed-state membership of one fact (sealed field order). */
-	snapshotContains(snap: SnapshotHandle, relationId: number, values: readonly FactValue[]): boolean
-	/**
-	 * Committed-state point lookup through a key statement (`keyValues` in
-	 * the statement's projection order); `null` on a miss.
-	 */
-	snapshotGet(
-		snap: SnapshotHandle,
+	dbRead<R>(db: DbHandle, callback: (instance: InstanceHandle, witness: WitnessHandle) => R): R
+	instanceGeneration(instance: InstanceHandle): bigint
+	instanceScan(instance: InstanceHandle, relationId: number): FactValue[][]
+	instanceContains(instance: InstanceHandle, relationId: number, values: readonly FactValue[]): boolean
+	instanceGet(
+		instance: InstanceHandle,
 		relationId: number,
 		keyStatementId: number,
 		keyValues: readonly FactValue[]
 	): FactValue[] | null
+	instancePrepare(instance: InstanceHandle, query: ParsedQuery): PrepareResult
+	witnessClose(witness: WitnessHandle): void
 
 	/**
-	 * Begins a write transaction: the submitted delta. One write
-	 * transaction may be open per db handle at a time (single-writer
-	 * engine; a second begin throws rather than deadlocking the process).
+	 * Runs `callback` synchronously inside the engine write region.
+	 * Return `true` to commit, `false` to abandon. Nested writes throw.
 	 */
-	dbWriteBegin(db: DbHandle): TxHandle
+	dbWrite(db: DbHandle, callback: (tx: TxHandle) => boolean): NativeWriteOutcome
 	/**
-	 * Begins a WITNESSED write transaction: commits only if no
-	 * state-changing commit landed since `snap` was taken —
-	 * `generationMoved` as data otherwise (the optimistic
-	 * read-compute-write loop's entry; retry policy stays host-side).
+	 * Witnessed write: `moved` is data when the store advanced since the
+	 * witness was minted. The callback does not run on that arm.
 	 */
-	dbWriteFrom(db: DbHandle, snap: SnapshotHandle): WriteFromResult
+	dbWriteFrom(db: DbHandle, witness: WitnessHandle, callback: (tx: TxHandle) => boolean): NativeWriteOutcome
 	/**
-	 * 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 inserts from per-column arrays in sealed
+	 * field order — the column transport, same parse-all-first batch as
+	 * {@link Native.txInsert}.
+	 */
+	txInsertColumns(
+		tx: TxHandle,
+		relationId: number,
+		columns: 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,20 +508,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).
-	 */
-	txAlloc(tx: TxHandle, relationId: number, fieldId: number): bigint
-	/**
-	 * Commits the delta: every dependency statement judged against the
-	 * final state; a rejection carries the complete violation rendering.
-	 * The handle is spent either way.
+	 * Mints `count` consecutive fresh values for `(relationId, fieldId)`.
+	 * `count === 0n` is empty and does not yield a start.
 	 */
-	txCommit(tx: TxHandle): CommitResult
-	/** Aborts the delta (LMDB was never touched). The handle is spent. */
-	txAbort(tx: TxHandle): void
+	txReserve(tx: TxHandle, relationId: number, fieldId: number, count: bigint): WireFreshRange
 
 	/**
 	 * Prepares a query (IR as data, ids only; plan pinned at prepare).
@@ -532,24 +519,64 @@ interface Native {
 	 */
 	dbPrepare(db: DbHandle, query: ParsedQuery): PrepareResult
 	/**
-	 * Executes against a snapshot with positional params. One-copy owned
+	 * Executes against a live instance with positional params. One-copy owned
 	 * rows out, column order = the query's head order; answers are a set
 	 * — the host sorts.
 	 */
-	preparedExecute(prepared: PreparedHandle, snap: SnapshotHandle, params: readonly QueryParam[]): FactValue[][]
+	preparedExecute(prepared: PreparedHandle, instance: InstanceHandle, params: readonly QueryParam[]): FactValue[][]
 	/**
 	 * Plan introspection as data (ruled 2026-07-23, R13): runs the prepared
-	 * query against the snapshot with counting instrumentation (the
-	 * engine's `Snapshot::profile`, ANALYZE semantics) and returns the
-	 * structured stats — plan sections and counters as plain values.
-	 * Scalar params only (the engine's profile entry has no param-set
-	 * spelling).
+	 * query against a store read with counting instrumentation and returns
+	 * the structured stats. Store-read only.
 	 */
-	preparedExplain(prepared: PreparedHandle, snap: SnapshotHandle, params: readonly QueryParam[]): Explain
-	/** The pull-based plan-drift signal against a snapshot. */
-	preparedStaleness(prepared: PreparedHandle, snap: SnapshotHandle): Staleness
+	preparedExplain(prepared: PreparedHandle, instance: InstanceHandle, params: readonly QueryParam[]): Explain
+	/** The pull-based plan-drift signal against a store read. */
+	preparedStaleness(prepared: PreparedHandle, instance: InstanceHandle): Staleness
 	/** Releases the prepared query. */
 	preparedClose(prepared: PreparedHandle): void
+
+	instanceBuilderNew(spec: SchemaSpec): BuilderHandle
+	instanceBuilderLoad(
+		builder: BuilderHandle,
+		relationId: number,
+		rows: readonly (readonly FactValue[])[]
+	): WireMutationReport
+	instanceBuilderLoadColumns(
+		builder: BuilderHandle,
+		relationId: number,
+		columns: readonly (readonly FactValue[])[]
+	): WireMutationReport
+	instanceBuilderDelete(
+		builder: BuilderHandle,
+		relationId: number,
+		rows: readonly (readonly FactValue[])[]
+	): WireMutationReport
+	instanceBuilderReserve(
+		builder: BuilderHandle,
+		relationId: number,
+		fieldId: number,
+		count: bigint
+	): WireFreshRange
+	instanceBuilderContains(builder: BuilderHandle, relationId: number, values: readonly FactValue[]): boolean
+	instanceBuilderGet(
+		builder: BuilderHandle,
+		relationId: number,
+		keyStatementId: number,
+		keyValues: readonly FactValue[]
+	): FactValue[] | null
+	instanceBuilderClose(builder: BuilderHandle): void
+	instanceBuilderAdmit(builder: BuilderHandle): Promise<AdmitResult>
+	ownedInstanceClose(instance: OwnedHandle): void
+	ownedScan(instance: OwnedHandle, relationId: number): FactValue[][]
+	ownedContains(instance: OwnedHandle, relationId: number, values: readonly FactValue[]): boolean
+	ownedGet(
+		instance: OwnedHandle,
+		relationId: number,
+		keyStatementId: number,
+		keyValues: readonly FactValue[]
+	): FactValue[] | null
+	ownedPrepare(instance: OwnedHandle, query: ParsedQuery): PrepareResult
+	ownedExecute(prepared: PreparedHandle, instance: OwnedHandle, params: readonly QueryParam[]): FactValue[][]
 }
 
 /**
@@ -626,38 +653,79 @@ function loadNativeBinding(platform: string, arch: string): Native {
 const native: Native = loadNativeBinding(process.platform, process.arch)
 
 /**
- * The bridge guard — THE one wrapper every native call crosses (db.ts and
- * exhume.ts both import it): runs one native call and wraps anything it
+ * Engine throw identity: a real `Error` carrying `kind` from the
+ * `ErrorFamily` table, or a leftover `{ kind, message }` object.
+ */
+function isEngineThrow(value: unknown): value is { kind: ErrorFamilyKind; message: string } {
+	if (typeof value !== "object" || value === null) {
+		return false
+	}
+	const rec = value as { kind?: unknown; message?: unknown }
+	return typeof rec.kind === "string" && typeof rec.message === "string"
+}
+
+function errorFromThrow(caught: unknown): Error {
+	if (caught instanceof Error) {
+		return caught
+	}
+	if (isEngineThrow(caught)) {
+		const error = errors.new(`bumbledb ${caught.kind}: ${caught.message}`)
+		Object.defineProperty(error, "kind", { value: caught.kind, enumerable: true })
+		return error
+	}
+	return errors.new(String(caught))
+}
+
+/**
+ * The bridge guard — THE one wrapper every native call crosses (db.ts
+ * imports it): runs one native call and wraps anything it
  * throws, so marshal-shape refusals and handle-lifecycle refusals cross as
- * genuine typed failures, never bare foreign errors.
+ * genuine typed failures, never bare foreign errors. Engine throws keep
+ * their forced kind.
  */
 function bridged<T>(context: string, run: () => T): T {
-	const result = errors.trySync(run)
-	if (result.error) {
-		throw errors.wrap(result.error, context)
+	try {
+		return run()
+	} catch (caught) {
+		const inner = errorFromThrow(caught)
+		throw errors.wrap(inner, `${context}: ${inner.message}`)
+	}
+}
+
+/**
+ * The async twin of {@link bridged}: every control-plane native is an
+ * `AsyncTask` Promise, and this is the one wrapper those awaits cross.
+ */
+async function bridgedAsync<T>(context: string, run: () => Promise<T>): Promise<T> {
+	try {
+		return await run()
+	} catch (caught) {
+		const inner = errorFromThrow(caught)
+		throw errors.wrap(inner, `${context}: ${inner.message}`)
 	}
-	return result.data
 }
 
 export type {
+	AdmissionTag,
+	AdmitResult,
 	AggOpIr,
-	ArgOpIr,
 	AtomIr,
 	AtomSourceIr,
+	BuilderHandle,
 	CmpOpIr,
-	CommitResult,
 	ComparisonIr,
 	ConditionTreeIr,
+	CreateResult,
 	DbHandle,
 	DbOpenResult,
-	ExhumeHandle,
-	ExhumeResult,
+	ErrorFamilyKind,
 	Explain,
 	FactValue,
 	FindTermIr,
 	FoldOpIr,
 	HeadOpIr,
 	HeadTermIr,
+	InstanceHandle,
 	InteriorIr,
 	IntervalValue,
 	Manifest,
@@ -666,16 +734,18 @@ export type {
 	ManifestRow,
 	ManifestStatement,
 	Native,
+	NativeWriteOutcome,
 	OccurrenceDrift,
+	OpenKind,
+	OwnedHandle,
 	ParsedQuery,
 	PreparedHandle,
+	PrepareKind,
 	PrepareResult,
 	QueryIr,
 	QueryParam,
 	RecIr,
 	RuleIr,
-	SnapshotHandle,
-	SnapshotOpened,
 	Staleness,
 	StatementKindTag,
 	TaggedValue,
@@ -683,6 +753,9 @@ export type {
 	TxHandle,
 	Violation,
 	ViolationFact,
-	WriteFromResult
+	WireFreshRange,
+	WireMutationReport,
+	WitnessHandle,
+	WriteTag
 }
-export { bridged, loadNativeBinding, native, SHIPPED_PLATFORMS }
+export { bridged, bridgedAsync, errorFromThrow, 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
 }