@bjornpagen/bumbledb 0.12.0 → 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
@@ -100,56 +155,88 @@ interface OffendingFact<Rels extends SchemaRelations> {
 }
 
 /**
- * One violated statement of a rejected commit, as a typed value.
- * `statement` is the IDENTICAL SDK statement value the schema declared —
- * consumers `===`-match it against their own constants; it is `undefined`
- * exactly for the engine-materialized fresh-implied and closed auto-keys,
- * which have no declared spelling (`schema()` rejects an explicit
- * duplicate of them). `canonical` is the ENGINE's rendering of the
- * violated materialized statement — for a `mirrors` statement BOTH
- * materialized slots render as the one `==` utterance in the written
- * orientation (identical strings; the engine's `render.rs` renders each
- * partner of a mirrored pair as the `==` spelling, never a bare `<=`
- * direction). `direction` (`sourceUnsatisfied` | `targetRequired`) and
- * `measure` are the containment/capacity form payloads, passed through
- * from the engine VERBATIM (`measure` the capacity form's witnessed group
- * total — u128-wide, crossing whole as bigint, C3) — `direction` is
- * relative to the violated SLOT's
- * own orientation, so for a `mirrors` statement it alone cannot say which
- * side of the `==` was violated: the slot identity is carried by
- * `orientation`, present exactly for `mirrors` slots — `written` is the
- * `source <= target` slot as the statement was spelled, `mirrored` the
- * engine-materialized `target <= source` partner.
+ * 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
+	readonly direction: "sourceUnsatisfied" | "targetRequired"
+	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> =
-	| {
-			readonly kind: "functionality"
-			readonly statement?: Statement
-			readonly canonical: string
-			readonly facts: readonly OffendingFact<Rels>[]
-	  }
-	| {
-			readonly kind: "containment"
-			readonly statement?: Statement
-			readonly canonical: string
-			readonly direction: "sourceUnsatisfied" | "targetRequired"
-			readonly facts: readonly OffendingFact<Rels>[]
-	  }
-	| {
-			readonly kind: "containment"
-			readonly statement?: Statement
-			readonly canonical: string
-			readonly direction: "sourceUnsatisfied" | "targetRequired"
-			readonly orientation: "written" | "mirrored"
-			readonly facts: readonly OffendingFact<Rels>[]
-	  }
-	| {
-			readonly kind: "capacity"
-			readonly statement?: Statement
-			readonly canonical: string
-			readonly measure: bigint
-			readonly facts: readonly OffendingFact<Rels>[]
-	  }
+	| ImpliedKeyViolation<Rels>
+	| DeclaredKeyViolation<Rels>
+	| ContainmentViolation<Rels>
+	| MirrorViolation<Rels>
+	| CapacityViolation<Rels>
 
 /**
  * The abandoned arm of a write result (ruled 2026-07-23, R10): present in
@@ -265,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.
 	 */
-	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
+	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
 	/**
@@ -451,18 +539,28 @@ interface PrimaryKey {
 }
 
 /**
- * One materialized-statement slot as the SDK mirrors it: the form tag, the
- * SDK statement value that lowered to it (`undefined` for the
- * engine-materialized implied keys), and — for functionality forms — the
- * key's owner and projection (what keyed point reads resolve through).
+ * 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
+	readonly projection: readonly string[]
+}
+
+type DeclaredKeyEntry = {
+	readonly kind: "functionality"
+	readonly statement: Statement
+	readonly owner: string
+	readonly projection: readonly string[]
+}
+
 type StatementEntry =
-	| {
-			readonly kind: "functionality"
-			readonly statement?: Statement
-			readonly owner: string
-			readonly projection: readonly string[]
-	  }
+	| ImpliedKeyEntry
+	| DeclaredKeyEntry
 	| { readonly kind: "containment"; readonly statement: Statement }
 	| { readonly kind: "mirrors"; readonly statement: Statement; readonly orientation: "written" | "mirrored" }
 	| { readonly kind: "capacity"; readonly statement: Statement }
@@ -749,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
@@ -841,16 +901,24 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 			throw errors.new(`bumbledb violation cites unknown statement id ${wire.statementId}`)
 		}
 		const facts = Object.freeze(wire.facts.map(offendingFactOf))
-		const statement = entry.statement
 		const canonical = wire.canonical
 		if (entry.kind === "functionality") {
-			return Object.freeze({ kind: "functionality", statement, canonical, facts })
+			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, canonical, measure: wire.measure, facts })
+			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`)
@@ -858,14 +926,20 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 		if (entry.kind === "mirrors") {
 			return Object.freeze({
 				kind: "containment",
-				statement,
+				statement: entry.statement,
 				canonical,
 				direction: wire.direction,
 				orientation: entry.orientation,
 				facts
 			})
 		}
-		return Object.freeze({ kind: "containment", statement, canonical, direction: wire.direction, facts })
+		return Object.freeze({
+			kind: "containment",
+			statement: entry.statement,
+			canonical,
+			direction: wire.direction,
+			facts
+		})
 	}
 
 	/**
@@ -877,7 +951,7 @@ function openDb<Rels extends SchemaRelations>(handle: DbHandle, theory: Schema<R
 	 */
 	function declaredKeyOf(relation: AnyRelation, statement: Statement): PrimaryKey {
 		const statementId = tables.statements.findIndex(function byIdentity(candidate) {
-			return candidate.statement === statement
+			return "statement" in candidate && candidate.statement === statement
 		})
 		const entry = tables.statements[statementId]
 		if (entry === undefined) {
@@ -1159,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
 		})
@@ -1362,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
@@ -1399,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() {
@@ -1466,9 +1539,16 @@ const Db = Object.freeze({
 export type {
 	Abandon,
 	AbandonedArm,
+	CapacityViolation,
+	ContainmentViolation,
 	DeclaredKeyFact,
+	DeclaredKeyViolation,
 	DeltaBuild,
+	FreshRange,
+	ImpliedKeyViolation,
 	MemberRelation,
+	MirrorViolation,
+	MutationReport,
 	OffendingFact,
 	Prepared,
 	ReadScope,

package/src/index.ts

@@ -51,9 +51,16 @@ export { closed } from "#closed.ts"
 export type {
 	Abandon,
 	AbandonedArm,
+	CapacityViolation,
+	ContainmentViolation,
 	DeclaredKeyFact,
+	DeclaredKeyViolation,
 	DeltaBuild,
+	FreshRange,
+	ImpliedKeyViolation,
 	MemberRelation,
+	MirrorViolation,
+	MutationReport,
 	OffendingFact,
 	Prepared,
 	ReadScope,
@@ -109,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 {
@@ -164,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 }