@bjornpagen/bumbledb 0.15.0 → 0.17.0

package/src/db.ts

@@ -8,7 +8,7 @@
  * A store read is one callback: `db.read((instance, witness) => …)`. The
  * instance is invalid the moment the callback returns; the witness is a
  * cloneable token and may escape. There is no handle-shaped read and no
- * `using snap = db.read()`. Builder, owned instance, and witness
+ * `using snap = db.read`. Builder, owned instance, and witness
  * implement `Symbol.dispose`. Prepared plans are plain values whose
  * engine-side half is reclaimed by a GC finalizer — reclamation only,
  * never correctness.
@@ -48,9 +48,9 @@ import type {
 	PreparedHandle,
 	TxHandle,
 	WireFreshRange,
+	WireMutationReport,
 	Violation as WireViolation,
 	ViolationFact as WireViolationFact,
-	WireMutationReport,
 	WitnessHandle
 } from "#native.ts"
 import { bridged, bridgedAsync, errorFromThrow, native } from "#native.ts"
@@ -63,86 +63,60 @@ 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"
 
-/**
- * The ordinary (writable, scannable) relations of a schema's record — the
- * only values the runtime methods accept: closed relations lack the
- * relation shape entirely, so passing one is a type error.
- */
 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
 }
 
-/**
- * Column-major collection write: one array per declared field, every
- * column the same length. The second transport of `load` / `insert` —
- * objects and columns are two ways to spell the same batch.
- */
-type ColumnBatch<R extends AnyRelation> = {
-	readonly [K in keyof Fact<R> & string]: readonly Fact<R>[K][]
-}
-
-type CollectionWrite<R extends AnyRelation> = Iterable<Fact<R>> | ColumnBatch<R>
-
-function isColumnBatch(value: object): boolean {
-	return !(Symbol.iterator in value)
-}
+type CollectionWrite<R extends AnyRelation> = Iterable<Fact<R>>
 
-function rowsOf<R extends AnyRelation>(relation: R, facts: Iterable<Fact<R>>): FactValue[][] {
-	const rows: FactValue[][] = []
-	for (const fact of facts) {
-		rows.push(rowOf(relation.data, recordOf(fact)))
-	}
-	return rows
+interface FlatCollection {
+	readonly rows: bigint
+	readonly cells: readonly FactValue[]
 }
 
 /**
- * Lowers a column batch to per-field wire arrays in sealed field order.
- * Allocates one array per field — never a JS array per row.
+ * The flat projector: every fact's cells land in ONE row-major
+ * `FactValue` array (length rows×arity) — no JS array per fact exists
+ * anywhere between the caller's objects and the native crossing
+ * (proposals/one-representation/20, V1) — and the row count is counted
+ * while projecting (the {@link FlatCollection} law: the stated count is
+ * what the bridge verifies against `rows × arity`, exactly, for every
+ * arity). The per-cell judgment is `cellOf` — the one cell judge `rowOf`
+ * also speaks (closed handle→id, well-formedness, interval shape) — and
+ * the missing-field refusal is `rowOf`'s, byte for byte; only the output
+ * form differs (flat, never per-row).
  */
-function columnsOf(relation: AnyRelation, batch: object): FactValue[][] {
-	const record = recordOf(batch)
-	let count: number | undefined
-	return relation.data.fields.map(function marshalColumn(declared) {
-		const raw = record[declared.name]
-		if (!Array.isArray(raw)) {
-			throw errors.new(`relation ${relation.name}: column ${declared.name} is not an array`)
-		}
-		if (count === undefined) {
-			count = raw.length
-		} else if (raw.length !== count) {
-			throw errors.new(
-				`relation ${relation.name}: column ${declared.name} has length ${raw.length}, expected ${count}`
-			)
+function rowsOf<R extends AnyRelation>(relation: R, facts: Iterable<Fact<R>>): FlatCollection {
+	const data = relation.data
+	const cells: FactValue[] = []
+	let rows = 0n
+	for (const fact of facts) {
+		rows += 1n
+		const record = recordOf(fact)
+		for (const declared of data.fields) {
+			const value = record[declared.name]
+			if (value === undefined) {
+				throw errors.new(`relation ${data.name}: fact is missing field ${declared.name}`)
+			}
+			cells.push(cellOf(`relation ${data.name} field ${declared.name}`, declared.field, value))
 		}
-		return raw.map(function marshalCell(value: unknown) {
-			return cellOf(`relation ${relation.name} field ${declared.name}`, declared.field, value)
-		})
-	})
+	}
+	return { rows, cells }
 }
 
 function mutateCollection<R extends AnyRelation>(
 	relation: R,
 	facts: CollectionWrite<R>,
-	applyRows: (rows: readonly FactValue[][]) => WireMutationReport,
-	applyColumns: (columns: readonly FactValue[][]) => WireMutationReport
+	apply: (rows: bigint, cells: readonly FactValue[]) => WireMutationReport
 ): MutationReport {
-	const report = isColumnBatch(facts)
-		? applyColumns(columnsOf(relation, facts))
-		: applyRows(rowsOf(relation, facts as Iterable<Fact<R>>))
+	const flat = rowsOf(relation, facts)
+	const report = apply(flat.rows, flat.cells)
 	return Object.freeze({ submitted: report.submitted, changed: report.changed })
 }
 
-/**
- * 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
@@ -194,80 +168,36 @@ function freshRangeOf(wire: WireFreshRange): FreshRange {
 	})
 }
 
-/**
- * The key object of a key-statement-selected `get`: exactly the selected
- * `key()` statement's projection fields, each at the relation's own BARE
- * structural value type — the {@link KeyFact} rule generalized from the
- * primary key to ANY declared key statement.
- */
 type DeclaredKeyFact<R extends AnyRelation, Projection extends readonly string[]> = {
 	readonly [K in Projection[number] & keyof Fact<R>]: Fact<R>[K]
 }
 
-/**
- * One offending fact of a violation: the cited relation's name (a member
- * of the schema's record) and the fact decoded to a named natural-value
- * object — partial exactly as the engine cites it. Closed-referencing
- * cells arrive as handle NAMES (the marshal bijection's read half), so the
- * record and the violation's `canonical` string — which the engine already
- * renders with handle names — agree on the one spelling.
- */
 interface OffendingFact<Rels extends SchemaRelations> {
 	readonly relation: keyof Rels & string
 	readonly fact: Readonly<Record<string, FactValue>>
 }
 
-/**
- * Shared body of every violation arm: the engine's canonical rendering and
- * the cited facts. `statement` is NOT here — its presence is the
- * discriminant. Implied auto-keys have no SDK spelling (`statement` is
- * the value `undefined`); every declared form carries the IDENTICAL
- * statement value the schema declared (consumers `===`-match it).
- */
 type ViolationBody<Rels extends SchemaRelations> = {
 	readonly canonical: string
 	readonly facts: readonly OffendingFact<Rels>[]
 }
 
-/**
- * A functionality violation of an engine-materialized fresh-implied or
- * closed auto-key. These slots have no declared spelling (`schema()`
- * rejects an explicit duplicate); `statement` is present and `undefined`.
- */
 type ImpliedKeyViolation<Rels extends SchemaRelations> = ViolationBody<Rels> & {
 	readonly kind: "functionality"
 	readonly statement: undefined
 }
 
-/**
- * A functionality violation of a declared `key()` statement. `statement`
- * is the IDENTICAL SDK value the schema declared.
- */
 type DeclaredKeyViolation<Rels extends SchemaRelations> = ViolationBody<Rels> & {
 	readonly kind: "functionality"
 	readonly statement: Statement
 }
 
-/**
- * A containment violation of a declared `contained()` statement (no
- * `orientation` — that property exists exactly on {@link MirrorViolation}).
- */
 type ContainmentViolation<Rels extends SchemaRelations> = ViolationBody<Rels> & {
 	readonly kind: "containment"
 	readonly statement: Statement
 	readonly direction: "sourceUnsatisfied" | "targetRequired"
 }
 
-/**
- * A containment violation of one slot of a declared `mirrors()` statement.
- * BOTH materialized slots render as the one `==` utterance in the written
- * orientation (identical `canonical` strings; the engine's `render.rs`
- * never emits a bare `<=` for a mirrored pair). `direction` is relative
- * to the violated SLOT's own orientation, so it alone cannot say which
- * side of the `==` was violated: `written` is the `source <= target` slot
- * as the statement was spelled, `mirrored` the engine-materialized
- * `target <= source` partner.
- */
 type MirrorViolation<Rels extends SchemaRelations> = ViolationBody<Rels> & {
 	readonly kind: "containment"
 	readonly statement: Statement
@@ -275,25 +205,12 @@ type MirrorViolation<Rels extends SchemaRelations> = ViolationBody<Rels> & {
 	readonly orientation: "written" | "mirrored"
 }
 
-/**
- * A capacity violation of a declared `capacity()` statement. `measure` is
- * the engine's witnessed group total — u128-wide, crossing whole as
- * bigint (C3: truncation is unrepresentable).
- */
 type CapacityViolation<Rels extends SchemaRelations> = ViolationBody<Rels> & {
 	readonly kind: "capacity"
 	readonly statement: Statement
 	readonly measure: bigint
 }
 
-/**
- * One violated statement of a rejected commit, as a typed value. The
- * arms are a true discriminant: `statement === undefined` is exactly the
- * implied-auto-key arm; every declared form carries `Statement` (not
- * `Statement | undefined`, not an omit-optional). `canonical` is the
- * ENGINE's rendering. `direction` / `measure` pass through from the
- * engine VERBATIM.
- */
 type Violation<Rels extends SchemaRelations> =
 	| ImpliedKeyViolation<Rels>
 	| DeclaredKeyViolation<Rels>
@@ -310,7 +227,6 @@ type Violation<Rels extends SchemaRelations> =
  */
 type AbandonedArm<R> = R extends Abandon<infer P> ? { readonly tag: "abandoned"; readonly abandoned: P } : never
 
-/** A callback return that is not Promise-like. TypeScript `never` is not a runtime boundary. */
 type SyncResult<R> = R extends PromiseLike<unknown> ? never : R
 
 interface Committed<T> {
@@ -322,10 +238,6 @@ type Admission<Rels extends SchemaRelations, T> =
 	| { readonly tag: "accepted"; readonly value: T }
 	| { readonly tag: "rejected"; readonly violations: readonly Violation<Rels>[] }
 
-/**
- * A write's domain outcome. One discriminant: narrow on `tag`. The
- * abandoned arm is present exactly when the callback can abandon.
- */
 type WriteOutcome<Rels extends SchemaRelations, R> =
 	| { readonly tag: "accepted"; readonly value: Committed<Exclude<R, Abandon<unknown>>> }
 	| { readonly tag: "rejected"; readonly violations: readonly Violation<Rels>[] }
@@ -335,19 +247,8 @@ type WriteFromOutcome<Rels extends SchemaRelations, R> =
 	| WriteOutcome<Rels, R>
 	| { readonly tag: "moved"; readonly witnessed: bigint; readonly current: bigint }
 
-/**
- * The delta-building callback of a write: runs synchronously against the
- * live transaction. Returning {@link abandon}`(payload)` rolls the
- * transaction back (R10) — the result type carries the payload arm exactly
- * then.
- */
 type DeltaBuild<Rels extends SchemaRelations, R = void> = (tx: WriteTx<Rels>) => R
 
-/**
- * The runtime discriminant of {@link Abandon} values — a property probe is
- * how `write`/`writeFrom` distinguish "abort without committing" from an
- * ordinary callback result, never a guess about the host's own value shapes.
- */
 const abandonMark: unique symbol = Symbol("bumbledb.abandon")
 
 /**
@@ -362,43 +263,16 @@ interface Abandon<P> {
 	readonly payload: P
 }
 
-/**
- * Wraps a payload in the {@link Abandon} sentinel — the one way a write
- * callback declines to commit: `return abandon(payload)` aborts the delta
- * (nothing is committed, not even an empty commit) and the write resolves
- * to `{ tag: "abandoned", abandoned: payload }`, from `write` and `writeFrom`
- * alike (R10).
- */
 function abandon<P>(payload: P): Abandon<P> {
 	return Object.freeze({ [abandonMark]: true as const, payload })
 }
 
-/**
- * The abandon payload type a write callback's return type implies: the
- * payload of its `Abandon` arm, `never` when the callback can never
- * abandon (the `abandoned` outcome is then statically unreachable and
- * {@link AbandonedArm} erases it from the sum).
- */
 type AbandonedPayload<R> = R extends Abandon<infer P> ? P : never
 
-/**
- * Narrows a write callback result to the abandon sentinel. The probe is
- * the private {@link abandonMark} symbol only {@link abandon} sets, and
- * `R`'s `Abandon` arm is the only way a sentinel can flow out of the
- * callback — so the narrowed payload type is sound by construction.
- */
 function isAbandon<R>(value: R): value is R & Abandon<AbandonedPayload<R>> {
 	return typeof value === "object" && value !== null && abandonMark in value
 }
 
-/**
- * The abandon outcome's trusted admission seam: the value's shape is the
- * checkable half (the sentinel mark only {@link abandon} mints, and the
- * outcome carrying that sentinel's own payload), and the sentinel's
- * existence IS the proof `R` carries an `Abandon` arm — so the outcome is
- * admitted at the conditional {@link AbandonedArm} face the type tier
- * cannot resolve over an open `R`.
- */
 function isAbandonedOutcome<Rels extends SchemaRelations, R>(
 	outcome: { readonly tag: "abandoned"; readonly abandoned: AbandonedPayload<R> },
 	sentinel: Abandon<AbandonedPayload<R>>
@@ -406,7 +280,6 @@ function isAbandonedOutcome<Rels extends SchemaRelations, R>(
 	return isAbandon(sentinel) && outcome.abandoned === sentinel.payload
 }
 
-/** Builds the abandoned write outcome from the callback's own sentinel (the R10 arm's one mint). */
 function abandonedOutcome<Rels extends SchemaRelations, R>(
 	sentinel: Abandon<AbandonedPayload<R>>
 ): WriteOutcome<Rels, R> {
@@ -417,43 +290,16 @@ function abandonedOutcome<Rels extends SchemaRelations, R>(
 	return outcome
 }
 
-/**
- * One live write transaction: the submitted delta with the engine's
- * FINAL-STATE point-read view (base + pending delta — the exact state the
- * commit judgment judges, so check-then-act is race-free by construction).
- * Spent when its owning `write`/`writeFrom` call resolves the attempt;
- * any later use throws.
- */
 interface WriteTx<Rels extends SchemaRelations> {
-	/**
-	 * 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 WriteTx.reserve}.
-	 */
 	insert<R extends MemberRelation<Rels>>(relation: R, facts: CollectionWrite<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.
-	 */
+
 	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
-	/**
-	 * Final-state point lookup through the relation's primary key (the
-	 * {@link KeyFact} rule); `undefined` on a miss.
-	 */
+
 	get<R extends MemberRelation<Rels>>(relation: R, key: KeyFact<R>): Fact<R> | undefined
-	/**
-	 * Final-state point lookup through a DECLARED `key()` statement of this
-	 * schema — the key object is typed by the statement's own projection;
-	 * `undefined` on a miss.
-	 */
 	get<R extends MemberRelation<Rels>, const P extends readonly string[]>(
 		relation: R,
 		keyStatement: KeyStatement<R, P>,
@@ -461,74 +307,40 @@ interface WriteTx<Rels extends SchemaRelations> {
 	): Fact<R> | undefined
 }
 
-type Tx<Rels extends SchemaRelations> = WriteTx<Rels>
-
 const witnessTypes: unique symbol = Symbol("bumbledb.witness.types")
 
-/**
- * Cloneable generation evidence from one store read. May cross `await`.
- * Disposal is idempotent; later use throws {@link ErrSpentHandle}.
- */
 interface Witness<Rels extends SchemaRelations> extends Disposable {
 	readonly [witnessTypes]?: Rels
 }
 
-/**
- * The borrowed instance one `db.read((instance, witness) => …)` callback
- * receives. Invalid the moment the callback returns. A stashed value
- * throws {@link ErrUseAfterScope}. Not a handle: there is no `db.read()`.
- */
 interface ReadInstance<Rels extends SchemaRelations> {
-	/**
-	 * The committed generation this instance witnessed — read inside the
-	 * lease's own transaction.
-	 */
 	readonly generation: bigint
-	/** Full-relation export in row-id order, decoded to bare structural facts. */
+
 	scan<R extends MemberRelation<Rels>>(relation: R): Fact<R>[]
-	/**
-	 * Committed-state point lookup through the relation's primary key
-	 * (the {@link KeyFact} rule); `undefined` on a miss.
-	 */
+
+	count<R extends MemberRelation<Rels>>(relation: R): bigint
+
 	get<R extends MemberRelation<Rels>>(relation: R, key: KeyFact<R>): Fact<R> | undefined
-	/**
-	 * Committed-state point lookup through a DECLARED `key()` statement of
-	 * this schema — the key object is typed by the statement's own
-	 * projection; `undefined` on a miss.
-	 */
+
 	get<R extends MemberRelation<Rels>, const P extends readonly string[]>(
 		relation: R,
 		keyStatement: KeyStatement<R, P>,
 		key: DeclaredKeyFact<R, P>
 	): Fact<R> | undefined
-	/** Committed-state membership of one complete fact. */
+
 	contains<R extends MemberRelation<Rels>>(relation: R, fact: Fact<R>): boolean
-	/**
-	 * Executes a prepared query against this instance with the typed
-	 * params object; returns the answer SET as plain rows with bare
-	 * structural values (no order — the host sorts). This is the ONE
-	 * execution spelling ({@link Prepared} carries no `execute`).
-	 */
+
 	execute<Row, Params extends ParamsRecord>(prepared: Prepared<Rels, Row, Params>, params: Params): Row[]
 	prepare<Row, Params extends ParamsRecord>(q: Query<Rels, Row, Params>): Prepared<Rels, Row, Params>
 }
 
-/**
- * The module-private inference slot of {@link Prepared}: an optional symbol
- * property (never set at runtime) that keeps the prepared value's `Row` and
- * `Params` type arguments load-bearing, so `execute` infers the typed rows
- * and the typed params object from the value alone — the query module's
- * `inferred` pattern, local to this module. A type-level carrier only:
- * values stay bare, nothing is asserted.
- */
 const preparedTypes: unique symbol = Symbol("bumbledb.prepared.types")
 
 /**
  * One prepared query as a plain VALUE: explicit visible compilation
  * (`db.prepare(q)` lowers, pins the plan, and surfaces every engine roster
  * refusal), no lifecycle. Execution happens ONLY through
- * `instance.execute(prepared, params)` / `db.execute(prepared, params)` — the
- * symmetry rule's one spelling. The engine-side plan is reclaimed by a GC
+ * `instance.execute(prepared, params)`. The engine-side plan is reclaimed by a GC
  * finalizer when this value becomes unreachable (reclamation only, never
  * correctness — an unreclaimed plan is idle memory, and process exit frees
  * everything).
@@ -537,38 +349,10 @@ interface Prepared<Rels extends SchemaRelations, Row, Params extends ParamsRecor
 	readonly [preparedTypes]?: { readonly rels: Rels; readonly row: Row; readonly params: Params }
 }
 
-/**
- * An open store. There is no close: read through `read`/the read sugar,
- * write through `write`/`writeFrom`, and let the process own the
- * environment's lifetime (the engine fsyncs every commit, so durability
- * never waits on a close). A second `open`/`create` of the same path
- * while this handle lives is the engine's `EnvironmentLocked`.
- */
 interface Db<Rels extends SchemaRelations> {
-	/** The theory this store was opened with (fingerprint-verified by the engine). */
 	readonly schema: Schema<Rels>
-	/**
-	 * One store read: runs `body` SYNCHRONOUSLY inside the engine lease
-	 * and returns its result. The {@link ReadInstance} is invalidated
-	 * when `body` returns — a stashed use throws {@link ErrUseAfterScope}.
-	 * The {@link Witness} is a clone and may escape. A thenable return
-	 * throws {@link ErrAsyncCallback}.
-	 */
+
 	read<R>(body: (instance: ReadInstance<Rels>, witness: Witness<Rels>) => SyncResult<R>): SyncResult<R>
-	/** `db.scan(r)` === `db.read(instance => instance.scan(r))` — the symmetry rule. */
-	scan<R extends MemberRelation<Rels>>(relation: R): Fact<R>[]
-	/** `db.get(r, k)` === `db.read(instance => instance.get(r, k))` — the symmetry rule. */
-	get<R extends MemberRelation<Rels>>(relation: R, key: KeyFact<R>): Fact<R> | undefined
-	/** `db.get(r, s, k)` === `db.read(instance => instance.get(r, s, k))` — the symmetry rule, keyed form. */
-	get<R extends MemberRelation<Rels>, const P extends readonly string[]>(
-		relation: R,
-		keyStatement: KeyStatement<R, P>,
-		key: DeclaredKeyFact<R, P>
-	): Fact<R> | undefined
-	/** `db.contains(r, f)` === `db.read(instance => instance.contains(r, f))` — the symmetry rule. */
-	contains<R extends MemberRelation<Rels>>(relation: R, fact: Fact<R>): boolean
-	/** `db.execute(p, params)` === `db.read(instance => instance.execute(p, params))` — the symmetry rule. */
-	execute<Row, Params extends ParamsRecord>(prepared: Prepared<Rels, Row, Params>, params: Params): Row[]
 	/**
 	 * One delta transaction: builds the delta synchronously through `fn`,
 	 * commits, and returns the domain outcome. A throw from `fn` aborts
@@ -578,11 +362,7 @@ interface Db<Rels extends SchemaRelations> {
 	 * outcome is `{ tag: "abandoned", abandoned: payload }`.
 	 */
 	write<R>(fn: (tx: WriteTx<Rels>) => SyncResult<R>): WriteOutcome<Rels, SyncResult<R>>
-	/**
-	 * Witnessed write: commits only if no state-changing commit landed
-	 * since `witness` was minted. A moved generation is
-	 * `{ tag: "moved" }` — retry is host policy; this method never loops.
-	 */
+
 	writeFrom<R>(witness: Witness<Rels>, fn: (tx: WriteTx<Rels>) => SyncResult<R>): WriteFromOutcome<Rels, SyncResult<R>>
 	/**
 	 * Prepares a query value built against THIS schema (identity is the
@@ -594,7 +374,6 @@ interface Db<Rels extends SchemaRelations> {
 	prepare<Row, Params extends ParamsRecord>(q: Query<Rels, Row, Params>): Prepared<Rels, Row, Params>
 }
 
-/** One relation's runtime tables: engine id, the identical schema member, field ids, primary key. */
 interface RelationEntry {
 	readonly id: number
 	readonly member: SchemaRelation
@@ -602,19 +381,11 @@ interface RelationEntry {
 	readonly primaryKey: PrimaryKey | undefined
 }
 
-/** One relation's primary candidate key: its materialized statement id and projection. */
 interface PrimaryKey {
 	readonly statementId: number
 	readonly projection: readonly string[]
 }
 
-/**
- * One materialized-statement slot as the SDK mirrors it. Implied auto-keys
- * omit `statement` (the engine owns those slots); every declared form
- * carries the SDK value that lowered to it. Functionality forms also
- * carry the key's owner and projection (what keyed point reads resolve
- * through).
- */
 type ImpliedKeyEntry = {
 	readonly kind: "functionality"
 	readonly owner: string
@@ -635,17 +406,72 @@ type StatementEntry =
 	| { readonly kind: "mirrors"; readonly statement: Statement; readonly orientation: "written" | "mirrored" }
 	| { readonly kind: "capacity"; readonly statement: Statement }
 
-/**
- * Mirrors the engine's materialized statement order
- * (`SchemaDescriptor::materialized_statements`, pinned by the fingerprint):
- * one auto-key per fresh field (relation declaration order, then field
- * order), one closed auto-key per closed relation (declaration order),
- * then the declared statements in declaration order — a `mirrors`
- * statement occupying TWO adjacent slots (the engine lowers `==` to two
- * containments, `source <= target` first), both owned by the one SDK
- * value. This positional match is how statement ids resolve back to SDK
- * statement values without the engine ever learning a wire format.
- */
+function decodeOffendingFact<Rels extends SchemaRelations>(
+	member: SchemaRelation,
+	relation: keyof Rels & string,
+	fact: WireViolationFact
+): OffendingFact<Rels> {
+	const declared = sealedFieldsOf(member)
+	const decoded: Record<string, FactValue> = {}
+	for (const cell of fact.fields) {
+		const cited = declared.find(function byName(candidate) {
+			return candidate.name === cell.name
+		})
+		const roster = rosterOf(cited?.field)
+		decoded[cell.name] =
+			roster !== undefined
+				? handleOf(`violation fact ${fact.relation} field ${cell.name}`, roster, cell.value)
+				: cell.value
+	}
+	return Object.freeze({ relation, fact: Object.freeze(decoded) })
+}
+
+function violationFromEntry<Rels extends SchemaRelations>(
+	entry: StatementEntry,
+	wire: WireViolation,
+	facts: readonly OffendingFact<Rels>[]
+): Violation<Rels> {
+	const canonical = wire.canonical
+	if (entry.kind === "functionality") {
+		if (!("statement" in entry)) {
+			return Object.freeze({ kind: "functionality", statement: undefined, canonical, facts })
+		}
+		return Object.freeze({ kind: "functionality", statement: entry.statement, canonical, facts })
+	}
+	if (entry.kind === "capacity") {
+		if (wire.kind !== "capacity") {
+			throw errors.new(`bumbledb violation ${wire.statementId} is a capacity slot without a measure`)
+		}
+		return Object.freeze({
+			kind: "capacity",
+			statement: entry.statement,
+			canonical,
+			measure: wire.measure,
+			facts
+		})
+	}
+	if (wire.kind !== "containment") {
+		throw errors.new(`bumbledb violation ${wire.statementId} is a containment slot without a direction`)
+	}
+	if (entry.kind === "mirrors") {
+		return Object.freeze({
+			kind: "containment",
+			statement: entry.statement,
+			canonical,
+			direction: wire.direction,
+			orientation: entry.orientation,
+			facts
+		})
+	}
+	return Object.freeze({
+		kind: "containment",
+		statement: entry.statement,
+		canonical,
+		direction: wire.direction,
+		facts
+	})
+}
+
 function materializedEntries(theory: AnySchema): StatementEntry[] {
 	const entries = impliedKeyEntries(theory)
 	for (const statement of theory.statements) {
@@ -654,13 +480,6 @@ function materializedEntries(theory: AnySchema): StatementEntry[] {
 	return entries
 }
 
-/**
- * The engine-materialized implied keys, in the engine's pinned order: one
- * auto-key per fresh field (relation declaration order, then field order),
- * then one closed auto-key `R(id) -> R` per closed relation (declaration
- * order). These slots carry no SDK statement value — the engine owns them
- * (`schema()` rejects an explicit duplicate).
- */
 function impliedKeyEntries(theory: AnySchema): StatementEntry[] {
 	const entries: StatementEntry[] = []
 	for (const member of Object.values(theory.relations)) {
@@ -689,12 +508,6 @@ function impliedKeyEntries(theory: AnySchema): StatementEntry[] {
 	return entries
 }
 
-/**
- * One declared statement's materialized slots: a key or capacity statement
- * occupies one, a `mirrors` occupies two adjacent slots (the engine lowers
- * `==` to two containments, `source <= target` first), both owned by the
- * one SDK value.
- */
 function declaredEntries(statement: Statement): StatementEntry[] {
 	const data = statement.data
 	switch (data.kind) {
@@ -733,29 +546,12 @@ function isThenable(value: unknown): boolean {
 	return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function"
 }
 
-/**
- * Narrows a keyed-get middle argument to a statement value (vs a key
- * object) through the statement module's admission brand — a
- * REPRESENTATION, never a shape probe: fact cell shapes are structurally
- * OPEN (an interval value carrying an excess `kind` property is a legal
- * cell), so no property probe could ever be sound here, but no host-built
- * key object can spell the module-private brand symbol.
- */
 function isStatementValue<R extends AnyRelation, P extends readonly string[]>(
 	value: KeyFact<R> | KeyStatement<R, P>
 ): value is KeyStatement<R, P> {
 	return isStatement(value)
 }
 
-/**
- * THE one selector dispatch of the `get` overload pair (primary-key vs
- * key-statement, `docs/architecture/70-api.md` § the freeze): judges the
- * middle argument once and hands the narrowed pieces to the chosen
- * continuation. `Db.get` and the read scope's `get` both dispatch through
- * here, so the two mismatch refusals speak with one voice and the symmetry
- * rule (`db.get(...) === db.read(snap => snap.get(...))`) holds by
- * construction.
- */
 function selectKeyRead<R extends AnyRelation, P extends readonly string[], T>(
 	keyOrStatement: KeyFact<R> | KeyStatement<R, P>,
 	declaredKey: DeclaredKeyFact<R, P> | undefined,
@@ -774,22 +570,11 @@ function selectKeyRead<R extends AnyRelation, P extends readonly string[], T>(
 	return byPrimary(keyOrStatement)
 }
 
-/** The id-resolution tables one open builds: relation entries by name, statement slots by id. */
 interface Tables {
 	readonly relations: ReadonlyMap<string, RelationEntry>
 	readonly statements: readonly StatementEntry[]
 }
 
-/**
- * Builds the id-resolution tables from the manifest, verifying the SDK's
- * positional mirror against the engine's reported order — any drift
- * (count, kind, id, or membership) is a construction-time failure, never a
- * silent misattribution of a violation to the wrong statement value. The
- * declaration-ordinal law the query lowering leans on is verified in the
- * same walks: relation ids and sealed field ids both equal declaration
- * order, so a constructed `Tables` IS the proof and `prepare` inherits it
- * structurally — never a silently misaddressed query.
- */
 function tablesOf(theory: AnySchema, manifest: Manifest): Tables {
 	const entries = materializedEntries(theory)
 	if (entries.length !== manifest.statements.length) {
@@ -873,16 +658,11 @@ function tablesFromTheory(theory: AnySchema): Tables {
 	return Object.freeze({ relations, statements: Object.freeze(entries) })
 }
 
-/** The point-read half a transaction and a read scope share, over their own handle. */
 interface PointReads {
 	contains(relationId: number, row: readonly FactValue[]): boolean
 	get(relationId: number, statementId: number, key: readonly FactValue[]): FactValue[] | null
 }
 
-/**
- * One borrowed instance's PRIVATE lifetime record. Held in
- * {@link instanceStates} — the native handle is never a public value.
- */
 interface InstanceState {
 	readonly handle: InstanceHandle
 	live: boolean
@@ -908,12 +688,6 @@ const witnessReclaimer = new FinalizationRegistry<WitnessHandle>(function reclai
 	}
 })
 
-/**
- * One prepared value's PRIVATE engine half: the pinned plan handle, the
- * owning store's identity token, and the query's marshaling tables (params
- * in declaration order, select columns in head order). Held in
- * {@link preparedPlans} — the plan handle is never a public value.
- */
 interface PreparedPlan {
 	readonly handle: PreparedHandle
 	readonly owner: object
@@ -921,15 +695,8 @@ interface PreparedPlan {
 	readonly finds: readonly FindColumn[]
 }
 
-/** The private engine halves of this module's prepared values. */
 const preparedPlans = new WeakMap<object, PreparedPlan>()
 
-/**
- * Reclaims the engine-side plan of a garbage-collected {@link Prepared}
- * value. RECLAMATION ONLY, never correctness: a plan the collector never
- * visits is idle engine memory until process exit, and a failure to close
- * is swallowed (there is no one left to care — the owning value is gone).
- */
 const planReclaimer = new FinalizationRegistry<PreparedHandle>(function reclaimPlan(handle) {
 	const closed = errors.trySync(function closePlan() {
 		native.preparedClose(handle)
@@ -949,13 +716,9 @@ const ErrUseAfterScope = errors.new(
 const ErrForeignPrepared = errors.new("bumbledb foreignPrepared: a prepared query met a foreign instance")
 const ErrForeignWitness = errors.new("bumbledb foreignWitness: a witness met a foreign store")
 
-/**
- * The shared typed read surface: store leases and owned instances both
- * expose scan/get/contains/execute/prepare. The native ops are the only
- * difference — one way to read, two handle kinds.
- */
 interface CatalogNative {
 	scan(relationId: number): FactValue[][]
+	count(relationId: number): bigint
 	contains(relationId: number, values: readonly FactValue[]): boolean
 	get(relationId: number, statementId: number, keyValues: readonly FactValue[]): FactValue[] | null
 	prepare(query: ReturnType<typeof lowerQuery>): ReturnType<typeof native.instancePrepare>
@@ -968,39 +731,7 @@ function catalogMethods<Rels extends SchemaRelations>(
 	owner: object,
 	assertLive: () => void,
 	ops: CatalogNative
-): Pick<ReadInstance<Rels>, "scan" | "get" | "contains" | "execute" | "prepare"> {
-	function resolveOrdinary(relation: AnyRelation): RelationEntry {
-		const entry = tables.relations.get(relation.name)
-		if (entry === undefined || entry.member !== relation) {
-			throw errors.new(`relation ${relation.name} is not a member of schema ${theory.name}`)
-		}
-		if (isClosedMember(relation)) {
-			throw errors.new(
-				`relation ${relation.name} is closed — its extension is schema data (axioms), never scanned or written`
-			)
-		}
-		return entry
-	}
-	function declaredKeyOf(relation: AnyRelation, statement: Statement): PrimaryKey {
-		const statementId = tables.statements.findIndex(function byIdentity(candidate) {
-			return "statement" in candidate && candidate.statement === statement
-		})
-		const entry = tables.statements[statementId]
-		if (entry === undefined) {
-			throw errors.new(
-				`keyed get statement is not a declared statement of schema ${theory.name} — statement identity is the membership rule`
-			)
-		}
-		if (entry.kind !== "functionality") {
-			throw errors.new("keyed get takes a key() statement — containments and capacity statements key nothing")
-		}
-		if (entry.owner !== relation.name) {
-			throw errors.new(
-				`keyed get statement keys ${entry.owner}, not ${relation.name} — the statement must be a declared key of the relation it reads`
-			)
-		}
-		return Object.freeze({ statementId, projection: entry.projection })
-	}
+): Pick<ReadInstance<Rels>, "scan" | "count" | "get" | "contains" | "execute" | "prepare"> {
 	function planOf(prepared: object): PreparedPlan {
 		const plan = preparedPlans.get(prepared)
 		if (plan === undefined) {
@@ -1016,7 +747,7 @@ function catalogMethods<Rels extends SchemaRelations>(
 	}
 	function contains<R extends MemberRelation<Rels>>(relation: R, fact: Fact<R>): boolean {
 		assertLive()
-		const entry = resolveOrdinary(relation)
+		const entry = ordinaryEntry(tables, theory, relation)
 		return bridged("bumbledb instance contains", function readContains() {
 			return ops.contains(entry.id, rowOf(relation.data, recordOf(fact)))
 		})
@@ -1027,12 +758,12 @@ function catalogMethods<Rels extends SchemaRelations>(
 		declaredKey?: DeclaredKeyFact<R, P>
 	): Fact<R> | undefined {
 		assertLive()
-		const entry = resolveOrdinary(relation)
+		const entry = ordinaryEntry(tables, theory, relation)
 		return selectKeyRead(
 			keyOrStatement,
 			declaredKey,
 			function byStatement(statement, key) {
-				const selected = declaredKeyOf(relation, statement)
+				const selected = declaredKeyOf(tables, theory, relation, statement)
 				const row = bridged("bumbledb instance get", function readGet() {
 					return ops.get(entry.id, selected.statementId, keyRowOf(relation.data, selected.projection, recordOf(key)))
 				})
@@ -1058,7 +789,7 @@ function catalogMethods<Rels extends SchemaRelations>(
 	}
 	function scan<R extends MemberRelation<Rels>>(relation: R): Fact<R>[] {
 		assertLive()
-		const entry = resolveOrdinary(relation)
+		const entry = ordinaryEntry(tables, theory, relation)
 		const rows = bridged("bumbledb instance scan", function readScan() {
 			return ops.scan(entry.id)
 		})
@@ -1066,6 +797,13 @@ function catalogMethods<Rels extends SchemaRelations>(
 			return factOf(relation, row)
 		})
 	}
+	function count<R extends MemberRelation<Rels>>(relation: R): bigint {
+		assertLive()
+		const entry = ordinaryEntry(tables, theory, relation)
+		return bridged("bumbledb instance count", function readCount() {
+			return ops.count(entry.id)
+		})
+	}
 	function execute<Row, Params extends ParamsRecord>(prepared: Prepared<Rels, Row, Params>, params: Params): Row[] {
 		assertLive()
 		const plan = planOf(prepared)
@@ -1102,7 +840,7 @@ function catalogMethods<Rels extends SchemaRelations>(
 		planReclaimer.register(prepared, outcome.prepared)
 		return prepared
 	}
-	return { scan, get, contains, execute, prepare }
+	return { scan, count, get, contains, execute, prepare }
 }
 
 function ordinaryEntry(tables: Tables, theory: AnySchema, relation: AnyRelation): RelationEntry {
@@ -1118,32 +856,33 @@ function ordinaryEntry(tables: Tables, theory: AnySchema, relation: AnyRelation)
 	return entry
 }
 
+function declaredKeyOf(tables: Tables, theory: AnySchema, relation: AnyRelation, statement: Statement): PrimaryKey {
+	const statementId = tables.statements.findIndex(function byIdentity(candidate) {
+		return "statement" in candidate && candidate.statement === statement
+	})
+	const entry = tables.statements[statementId]
+	if (entry === undefined) {
+		throw errors.new(
+			`keyed get statement is not a declared statement of schema ${theory.name} — statement identity is the membership rule`
+		)
+	}
+	if (entry.kind !== "functionality") {
+		throw errors.new("keyed get takes a key() statement — containments and capacity statements key nothing")
+	}
+	if (entry.owner !== relation.name) {
+		throw errors.new(
+			`keyed get statement keys ${entry.owner}, not ${relation.name} — the statement must be a declared key of the relation it reads`
+		)
+	}
+	return Object.freeze({ statementId, projection: entry.projection })
+}
+
 function overlayMethods<Rels extends SchemaRelations>(
 	theory: Schema<Rels>,
 	tables: Tables,
 	assertLive: () => void,
 	reads: PointReads
 ): Pick<WriteTx<Rels>, "contains" | "get"> {
-	function declaredKeyOf(relation: AnyRelation, statement: Statement): PrimaryKey {
-		const statementId = tables.statements.findIndex(function byIdentity(candidate) {
-			return "statement" in candidate && candidate.statement === statement
-		})
-		const entry = tables.statements[statementId]
-		if (entry === undefined) {
-			throw errors.new(
-				`keyed get statement is not a declared statement of schema ${theory.name} — statement identity is the membership rule`
-			)
-		}
-		if (entry.kind !== "functionality") {
-			throw errors.new("keyed get takes a key() statement — containments and capacity statements key nothing")
-		}
-		if (entry.owner !== relation.name) {
-			throw errors.new(
-				`keyed get statement keys ${entry.owner}, not ${relation.name} — the statement must be a declared key of the relation it reads`
-			)
-		}
-		return Object.freeze({ statementId, projection: entry.projection })
-	}
 	function contains<R extends MemberRelation<Rels>>(relation: R, fact: Fact<R>): boolean {
 		assertLive()
 		const entry = ordinaryEntry(tables, theory, relation)
@@ -1178,7 +917,7 @@ function overlayMethods<Rels extends SchemaRelations>(
 			keyOrStatement,
 			declaredKey,
 			function byStatement(statement, key) {
-				return readThroughKey(relation, entry, declaredKeyOf(relation, statement), recordOf(key))
+				return readThroughKey(relation, entry, declaredKeyOf(tables, theory, relation, statement), recordOf(key))
 			},
 			function byPrimary(key) {
 				const primaryKey = entry.primaryKey
@@ -1213,6 +952,9 @@ function createReadInstance<Rels extends SchemaRelations>(
 		scan(relationId) {
 			return native.instanceScan(state.handle, relationId)
 		},
+		count(relationId) {
+			return native.instanceCount(state.handle, relationId)
+		},
 		contains(relationId, values) {
 			return native.instanceContains(state.handle, relationId, values)
 		},
@@ -1239,12 +981,6 @@ function createReadInstance<Rels extends SchemaRelations>(
 	return instance
 }
 
-/**
- * Constructs one open `Db` over an already-admitted handle: builds the
- * id-resolution tables once and closes over them — the `Db` owns handle
- * and tables and nothing else. Handle lifetime is the process's: the store
- * cache holds the environment handle until the exit hook closes it.
- */
 function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<Rels>, manifest: Manifest): Db<Rels> {
 	const tables = tablesOf(theory, manifest)
 	/** This store's identity token: read scopes and prepared values carry it, so cross-store use is a typed refusal. */
@@ -1254,121 +990,30 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		return tables.relations.has(name)
 	}
 
-	function resolveOrdinary(relation: AnyRelation): RelationEntry {
-		const entry = tables.relations.get(relation.name)
-		if (entry === undefined || entry.member !== relation) {
-			throw errors.new(`relation ${relation.name} is not a member of schema ${theory.name}`)
-		}
-		if (isClosedMember(relation)) {
-			throw errors.new(
-				`relation ${relation.name} is closed — its extension is schema data (axioms), never scanned or written`
-			)
-		}
-		return entry
-	}
-
-	function offendingFactOf(fact: WireViolationFact): OffendingFact<Rels> {
-		const entry = tables.relations.get(fact.relation)
-		if (entry === undefined || !isMemberName(fact.relation)) {
-			throw errors.new(`bumbledb violation cites unknown relation ${fact.relation}`)
-		}
-		const declared = sealedFieldsOf(entry.member)
-		const decoded: Record<string, FactValue> = {}
-		for (const cell of fact.fields) {
-			const cited = declared.find(function byName(candidate) {
-				return candidate.name === cell.name
-			})
-			const roster = rosterOf(cited?.field)
-			decoded[cell.name] =
-				roster !== undefined
-					? handleOf(`violation fact ${fact.relation} field ${cell.name}`, roster, cell.value)
-					: cell.value
-		}
-		return Object.freeze({ relation: fact.relation, fact: Object.freeze(decoded) })
-	}
-
 	function violationOf(wire: WireViolation): Violation<Rels> {
 		const entry = tables.statements[wire.statementId]
 		if (entry === undefined) {
 			throw errors.new(`bumbledb violation cites unknown statement id ${wire.statementId}`)
 		}
-		const facts = Object.freeze(wire.facts.map(offendingFactOf))
-		const canonical = wire.canonical
-		if (entry.kind === "functionality") {
-			if (!("statement" in entry)) {
-				return Object.freeze({ kind: "functionality", statement: undefined, canonical, facts })
-			}
-			return Object.freeze({ kind: "functionality", statement: entry.statement, canonical, facts })
-		}
-		if (entry.kind === "capacity") {
-			if (wire.kind !== "capacity") {
-				throw errors.new(`bumbledb violation ${wire.statementId} is a capacity slot without a measure`)
-			}
-			return Object.freeze({
-				kind: "capacity",
-				statement: entry.statement,
-				canonical,
-				measure: wire.measure,
-				facts
-			})
-		}
-		if (wire.kind !== "containment") {
-			throw errors.new(`bumbledb violation ${wire.statementId} is a containment slot without a direction`)
-		}
-		if (entry.kind === "mirrors") {
-			return Object.freeze({
-				kind: "containment",
-				statement: entry.statement,
-				canonical,
-				direction: wire.direction,
-				orientation: entry.orientation,
-				facts
+		const facts = Object.freeze(
+			wire.facts.map(function offending(fact) {
+				const rel = tables.relations.get(fact.relation)
+				if (rel === undefined || !isMemberName(fact.relation)) {
+					throw errors.new(`bumbledb violation cites unknown relation ${fact.relation}`)
+				}
+				return decodeOffendingFact<Rels>(rel.member, fact.relation, fact)
 			})
-		}
-		return Object.freeze({
-			kind: "containment",
-			statement: entry.statement,
-			canonical,
-			direction: wire.direction,
-			facts
-		})
-	}
-
-	/**
-	 * Resolves a key-statement-selected read: the statement must be the
-	 * IDENTICAL `key()` value this schema declared (identity is the
-	 * membership rule) and must key `relation` — its materialized statement
-	 * id comes from the positional mirror, so the engine point-reads through
-	 * exactly the declared projection.
-	 */
-	function declaredKeyOf(relation: AnyRelation, statement: Statement): PrimaryKey {
-		const statementId = tables.statements.findIndex(function byIdentity(candidate) {
-			return "statement" in candidate && candidate.statement === statement
-		})
-		const entry = tables.statements[statementId]
-		if (entry === undefined) {
-			throw errors.new(
-				`keyed get statement is not a declared statement of schema ${theory.name} — statement identity is the membership rule`
-			)
-		}
-		if (entry.kind !== "functionality") {
-			throw errors.new("keyed get takes a key() statement — containments and capacity statements key nothing")
-		}
-		if (entry.owner !== relation.name) {
-			throw errors.new(
-				`keyed get statement keys ${entry.owner}, not ${relation.name} — the statement must be a declared key of the relation it reads`
-			)
-		}
-		return Object.freeze({ statementId, projection: entry.projection })
+		)
+		return violationFromEntry(entry, wire, facts)
 	}
 
 	function pointReadsOf(assertLive: () => void, reads: PointReads) {
 		function contains<R extends MemberRelation<Rels>>(relation: R, fact: Fact<R>): boolean {
 			assertLive()
-			const entry = resolveOrdinary(relation)
+			const entry = ordinaryEntry(tables, theory, relation)
 			return reads.contains(entry.id, rowOf(relation.data, recordOf(fact)))
 		}
-		/** One keyed point read through an already-resolved key, decoded to a fact (`undefined` on a miss). */
+
 		function readThroughKey<R extends MemberRelation<Rels>>(
 			relation: R,
 			entry: RelationEntry,
@@ -1393,12 +1038,12 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 			declaredKey?: DeclaredKeyFact<R, P>
 		): Fact<R> | undefined {
 			assertLive()
-			const entry = resolveOrdinary(relation)
+			const entry = ordinaryEntry(tables, theory, relation)
 			return selectKeyRead(
 				keyOrStatement,
 				declaredKey,
 				function byStatement(statement, key) {
-					return readThroughKey(relation, entry, declaredKeyOf(relation, statement), recordOf(key))
+					return readThroughKey(relation, entry, declaredKeyOf(tables, theory, relation, statement), recordOf(key))
 				},
 				function byPrimary(key) {
 					const primaryKey = entry.primaryKey
@@ -1475,51 +1120,6 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		return (captured ?? result) as SyncResult<R>
 	}
 
-	function scan<R extends MemberRelation<Rels>>(relation: R): Fact<R>[] {
-		return read(function scanInScope(instance) {
-			return instance.scan(relation)
-		})
-	}
-
-	function get<R extends MemberRelation<Rels>>(relation: R, key: KeyFact<R>): Fact<R> | undefined
-	function get<R extends MemberRelation<Rels>, const P extends readonly string[]>(
-		relation: R,
-		keyStatement: KeyStatement<R, P>,
-		key: DeclaredKeyFact<R, P>
-	): Fact<R> | undefined
-	function get<R extends MemberRelation<Rels>, const P extends readonly string[]>(
-		relation: R,
-		keyOrStatement: KeyFact<R> | KeyStatement<R, P>,
-		declaredKey?: DeclaredKeyFact<R, P>
-	): Fact<R> | undefined {
-		let found: Fact<R> | undefined
-		read(function getInScope(instance) {
-			found = selectKeyRead(
-				keyOrStatement,
-				declaredKey,
-				function byStatement(statement, key) {
-					return instance.get(relation, statement, key)
-				},
-				function byPrimary(key) {
-					return instance.get(relation, key)
-				}
-			)
-		})
-		return found
-	}
-
-	function contains<R extends MemberRelation<Rels>>(relation: R, fact: Fact<R>): boolean {
-		return read(function containsInScope(instance) {
-			return instance.contains(relation, fact)
-		})
-	}
-
-	function execute<Row, Params extends ParamsRecord>(prepared: Prepared<Rels, Row, Params>, params: Params): Row[] {
-		return read(function executeInScope(instance) {
-			return instance.execute(prepared, params)
-		})
-	}
-
 	function makeTx(resolveTx: () => TxHandle): { readonly tx: WriteTx<Rels>; spend(): void } {
 		const txState = { spent: false }
 		function assertLive(): void {
@@ -1543,29 +1143,21 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		})
 		function insert<R extends MemberRelation<Rels>>(relation: R, facts: CollectionWrite<R>): MutationReport {
 			assertLive()
-			const entry = resolveOrdinary(relation)
+			const entry = ordinaryEntry(tables, theory, relation)
 			const txHandle = resolveTx()
-			return mutateCollection(
-				relation,
-				facts,
-				function applyRows(rows) {
-					return bridged("bumbledb tx insert", function record() {
-						return native.txInsert(txHandle, entry.id, rows)
-					})
-				},
-				function applyColumns(columns) {
-					return bridged("bumbledb tx insert", function recordColumns() {
-						return native.txInsertColumns(txHandle, entry.id, columns)
-					})
-				}
-			)
+			return mutateCollection(relation, facts, function applyCells(rows, cells) {
+				return bridged("bumbledb tx insert", function record() {
+					return native.txInsert(txHandle, entry.id, rows, cells)
+				})
+			})
 		}
 		function remove<R extends MemberRelation<Rels>>(relation: R, facts: Iterable<Fact<R>>): MutationReport {
 			assertLive()
-			const entry = resolveOrdinary(relation)
+			const entry = ordinaryEntry(tables, theory, relation)
 			const txHandle = resolveTx()
+			const flat = rowsOf(relation, facts)
 			const report = bridged("bumbledb tx delete", function record() {
-				return native.txDelete(txHandle, entry.id, rowsOf(relation, facts))
+				return native.txDelete(txHandle, entry.id, flat.rows, flat.cells)
 			})
 			return Object.freeze({ submitted: report.submitted, changed: report.changed })
 		}
@@ -1575,7 +1167,7 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 			count: bigint
 		): FreshRange {
 			assertLive()
-			const entry = resolveOrdinary(relation)
+			const entry = ordinaryEntry(tables, theory, relation)
 			const declared = relation.data.fields.find(function byName(candidate) {
 				return candidate.name === field
 			})
@@ -1712,33 +1304,17 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 	return Object.freeze({
 		schema: theory,
 		read,
-		scan,
-		get,
-		contains,
-		execute,
 		write,
 		writeFrom,
 		prepare
 	})
 }
 
-/**
- * The engine twin of the schema-level class wall, as a matchable value
- * (`errors.is`): the shared lowering rejected a spec whose statement pairs
- * faces with disagreeing newtype labels — the faces of a dependency agree
- * on their newtype, or neither carries one. UNREACHABLE through the typed
- * builder (the SDK computes every label from the laws, so its lowered
- * specs cohere by construction); a raw spec handed to the bridge is the
- * one road here, and the runtime referee that proves the engine judges
- * what the types claim.
- */
 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"
 )
 const ErrSchemaError = errors.new("bumbledb schemaError: the declaration failed validation")
-const ErrFingerprintMismatch = errors.new(
-	"bumbledb fingerprintMismatch: the store's schema does not match this theory"
-)
+const ErrFingerprintMismatch = errors.new("bumbledb fingerprintMismatch: the store's schema does not match this theory")
 const ErrIrError = errors.new("bumbledb irError: the query failed validation")
 
 function throwOpenRefusal(
@@ -1802,71 +1378,19 @@ function mapViolationWithoutStore<Rels extends SchemaRelations>(
 	if (entry === undefined) {
 		throw errors.new(`bumbledb violation cites unknown statement id ${wire.statementId}`)
 	}
-	function offending(fact: WireViolationFact): OffendingFact<Rels> {
-		const member = theory.relations[fact.relation]
-		if (member === undefined || !(fact.relation in theory.relations)) {
-			throw errors.new(`bumbledb violation cites unknown relation ${fact.relation}`)
-		}
-		const declared = sealedFieldsOf(member)
-		const decoded: Record<string, FactValue> = {}
-		for (const cell of fact.fields) {
-			const cited = declared.find(function byName(candidate) {
-				return candidate.name === cell.name
-			})
-			const roster = rosterOf(cited?.field)
-			decoded[cell.name] =
-				roster !== undefined
-					? handleOf(`violation fact ${fact.relation} field ${cell.name}`, roster, cell.value)
-					: cell.value
-		}
-		return Object.freeze({ relation: fact.relation as keyof Rels & string, fact: Object.freeze(decoded) })
-	}
-	const facts = Object.freeze(wire.facts.map(offending))
-	const canonical = wire.canonical
-	if (entry.kind === "functionality") {
-		if (!("statement" in entry)) {
-			return Object.freeze({ kind: "functionality", statement: undefined, canonical, facts })
-		}
-		return Object.freeze({ kind: "functionality", statement: entry.statement, canonical, facts })
-	}
-	if (entry.kind === "capacity") {
-		if (wire.kind !== "capacity") {
-			throw errors.new(`bumbledb violation ${wire.statementId} is a capacity slot without a measure`)
-		}
-		return Object.freeze({
-			kind: "capacity",
-			statement: entry.statement,
-			canonical,
-			measure: wire.measure,
-			facts
-		})
-	}
-	if (wire.kind !== "containment") {
-		throw errors.new(`bumbledb violation ${wire.statementId} is a containment slot without a direction`)
-	}
-	if (entry.kind === "mirrors") {
-		return Object.freeze({
-			kind: "containment",
-			statement: entry.statement,
-			canonical,
-			direction: wire.direction,
-			orientation: entry.orientation,
-			facts
+	const facts = Object.freeze(
+		wire.facts.map(function offending(fact) {
+			const member = theory.relations[fact.relation]
+			if (member === undefined || !(fact.relation in theory.relations)) {
+				throw errors.new(`bumbledb violation cites unknown relation ${fact.relation}`)
+			}
+			return decodeOffendingFact<Rels>(member, fact.relation as keyof Rels & string, fact)
 		})
-	}
-	return Object.freeze({
-		kind: "containment",
-		statement: entry.statement,
-		canonical,
-		direction: wire.direction,
-		facts
-	})
+	)
+	return violationFromEntry(entry, wire, facts)
 }
 
-async function openStore<Rels extends SchemaRelations>(
-	storePath: string,
-	theory: Schema<Rels>
-): Promise<Db<Rels>> {
+async function openStore<Rels extends SchemaRelations>(storePath: string, theory: Schema<Rels>): Promise<Db<Rels>> {
 	const canonical = path.resolve(storePath)
 	const spec = lower(theory)
 	const opened = await bridgedAsync(`open bumbledb store at ${canonical}`, function callBridge() {
@@ -1882,7 +1406,9 @@ interface OwnedInstance<Rels extends SchemaRelations> extends Disposable {
 	prepare<Row, Params extends ParamsRecord>(q: Query<Rels, Row, Params>): Prepared<Rels, Row, Params>
 	execute<Row, Params extends ParamsRecord>(prepared: Prepared<Rels, Row, Params>, params: Params): Row[]
 	scan<R extends MemberRelation<Rels>>(relation: R): Fact<R>[]
+	count<R extends MemberRelation<Rels>>(relation: R): bigint
 	contains<R extends MemberRelation<Rels>>(relation: R, fact: Fact<R>): boolean
+
 	get<R extends MemberRelation<Rels>>(relation: R, key: KeyFact<R>): Fact<R> | undefined
 	get<R extends MemberRelation<Rels>, const P extends readonly string[]>(
 		relation: R,
@@ -1896,6 +1422,7 @@ interface InstanceBuilder<Rels extends SchemaRelations> extends Disposable {
 	delete<R extends MemberRelation<Rels>>(relation: R, facts: Iterable<Fact<R>>): MutationReport
 	reserve<R extends MemberRelation<Rels>>(relation: R, field: FreshKeys<R> & string, count: bigint): FreshRange
 	contains<R extends MemberRelation<Rels>>(relation: R, fact: Fact<R>): boolean
+
 	get<R extends MemberRelation<Rels>>(relation: R, key: KeyFact<R>): Fact<R> | undefined
 	get<R extends MemberRelation<Rels>, const P extends readonly string[]>(
 		relation: R,
@@ -1939,6 +1466,9 @@ function wrapOwned<Rels extends SchemaRelations>(nativeHandle: OwnedHandle, theo
 		scan(relationId) {
 			return native.ownedScan(nativeHandle, relationId)
 		},
+		count(relationId) {
+			return native.ownedCount(nativeHandle, relationId)
+		},
 		contains(relationId, values) {
 			return native.ownedContains(nativeHandle, relationId, values)
 		},
@@ -2003,34 +1533,22 @@ function wrapBuilder<Rels extends SchemaRelations>(
 		load<R extends MemberRelation<Rels>>(relation: R, facts: CollectionWrite<R>): MutationReport {
 			assertLive()
 			const entry = ordinaryEntry(tables, theory, relation)
-			return mutateCollection(
-				relation,
-				facts,
-				function applyRows(rows) {
-					return bridged("bumbledb builder load", function loadRows() {
-						return native.instanceBuilderLoad(nativeHandle, entry.id, rows)
-					})
-				},
-				function applyColumns(columns) {
-					return bridged("bumbledb builder load", function loadColumns() {
-						return native.instanceBuilderLoadColumns(nativeHandle, entry.id, columns)
-					})
-				}
-			)
+			return mutateCollection(relation, facts, function applyCells(rows, cells) {
+				return bridged("bumbledb builder load", function loadCells() {
+					return native.instanceBuilderLoad(nativeHandle, entry.id, rows, cells)
+				})
+			})
 		},
 		delete<R extends MemberRelation<Rels>>(relation: R, facts: Iterable<Fact<R>>): MutationReport {
 			assertLive()
 			const entry = ordinaryEntry(tables, theory, relation)
+			const flat = rowsOf(relation, facts)
 			const report = bridged("bumbledb builder delete", function remove() {
-				return native.instanceBuilderDelete(nativeHandle, entry.id, rowsOf(relation, facts))
+				return native.instanceBuilderDelete(nativeHandle, entry.id, flat.rows, flat.cells)
 			})
 			return Object.freeze({ submitted: report.submitted, changed: report.changed })
 		},
-		reserve<R extends MemberRelation<Rels>>(
-			relation: R,
-			field: FreshKeys<R> & string,
-			count: bigint
-		): FreshRange {
+		reserve<R extends MemberRelation<Rels>>(relation: R, field: FreshKeys<R> & string, count: bigint): FreshRange {
 			assertLive()
 			const entry = ordinaryEntry(tables, theory, relation)
 			const declared = relation.data.fields.find(function byName(candidate) {
@@ -2113,18 +1631,13 @@ const InstanceBuilder = Object.freeze({
  * hold the `Db` this process opened.
  */
 const Db = Object.freeze({
-	/** Creates a fresh durable store at `path` from the schema. */
 	async create<Rels extends SchemaRelations>(
 		storePath: string,
 		theory: Schema<Rels>
 	): Promise<Admission<Rels, Db<Rels>>> {
 		return createStore(storePath, theory)
 	},
-	/**
-	 * Opens an existing durable store at `path` with the same theory.
-	 * Format 8 open never back-fills a descriptor. A second open of a
-	 * still-live path is `EnvironmentLocked`.
-	 */
+
 	async open<Rels extends SchemaRelations>(storePath: string, theory: Schema<Rels>): Promise<Db<Rels>> {
 		return openStore(storePath, theory)
 	},
@@ -2152,7 +1665,6 @@ export type {
 	AbandonedArm,
 	Admission,
 	CapacityViolation,
-	ColumnBatch,
 	Committed,
 	ContainmentViolation,
 	DeclaredKeyFact,
@@ -2168,7 +1680,6 @@ export type {
 	Prepared,
 	ReadInstance,
 	SyncResult,
-	Tx,
 	Violation,
 	Witness,
 	WriteFromOutcome,
@@ -2179,9 +1690,9 @@ export {
 	abandon,
 	Db,
 	ErrAsyncCallback,
+	ErrFingerprintMismatch,
 	ErrForeignPrepared,
 	ErrForeignWitness,
-	ErrFingerprintMismatch,
 	ErrIrError,
 	ErrNewtypeMismatch,
 	ErrSchemaError,