@bjornpagen/bumbledb 1.1.0 → 1.2.1

package/src/capacity.ts

@@ -1,55 +1,15 @@
 import { AuthoringError } from "#errors.ts"
-/**
- * Capacity-law mints — the window, weight, and dependent-bound vocabulary
- * the one `capacity` statement constructor consumes
- * § the canonical-utterance law, restated
- * around the aggregate form). `within` is the ONE window spelling —
- * `within(n)` exact (`within(0n)` IS the exclusion's one spelling),
- * `within(lo, hi)` range (`within(0n, hi)` the canonical ceiling),
- * `within(lo, "*")` floor — `weigh` names the measure on the SOURCE row
- * (`weigh("watts")` a u64 field, `weigh(duration("booked"))` an interval's
- * measure), and `ref`/`duration` read a dependent bound from the
- * TARGET row (hi slot only — ruled 2026-07-24, C6). The ban table is
- * enforced REPRESENTATIONALLY in two tiers, split per-aggregate where
- * weight-sensitive (design § 6: a ban is canonical-utterance policing when
- * it is weight-independent, semantic deduplication when it is not):
- *
- * - **The type tier**: a banned spelling written as a LITERAL does not
- * compile — every negative bound, `within(n, n)`, `within(0n, 0n)`, and
- * `within(0n, "*")` are type errors naming the canonical form. The
- * weight-SENSITIVE row rides the `capacity` overloads themselves:
- * `within(1n, "*")` is banned on the unit overload only (`{1..*}` on the
- * count instance is the bare containment respelled —
- * `window_floor_containment`), and LEGAL on the weighted one ("positive
- * total" is not an existence claim over rows).
- * - **The construction tier**: a bound the type level cannot judge — a
- * COMPUTED `bigint`, or an inverted `within(lo, hi)` order — is judged at
- * construction with the same canonical-naming errors; and past both
- * tiers the engine's own spec validation remains the law for a hostile
- * FFI caller (the standing two-tier ban enforcement).
- *
- * The weight vocabulary is closed at the row (ruled 2026-07-24, ruling 6):
- * a path weight (`weigh("model.watts")`) is a typed refusal at BOTH tiers
- * whose diagnostic names the pinned-column idiom — the two-column
- * containment IS the join, stated as a law. Bounds are `bigint` (u64
- * crosses as bigint always, PRD-04's law); the witnessed measure comes
- * back as `bigint` too (u128-wide engine accumulator, C3).
- */
+/** Structural capacity measures and windows. Constructors and generated
+ * descriptions share the same checked representation. Bounds are u64;
+ * dependent bounds read the target row, measures read the source row. */
 
 import type { AnyFace, FaceFields, FaceSource, ProjectedShape } from "#face.ts"
 import type { CapacityBoundSpec, CapacityWindowSpec, WeightSpec } from "#spec.ts"
+import { integerValue, recordValue } from "#values.ts"
 
-const admitted: unique symbol = Symbol("bumbledb.capacity.admitted")
-
-interface CapacityWindow<S extends CapacityWindowSpec = CapacityWindowSpec> {
-	readonly window: S
-	readonly [admitted]: true
-}
+type CapacityWindow<S extends CapacityWindowSpec = CapacityWindowSpec> = S
 
-interface CapacityWeight<S extends WeightSpec = WeightSpec> {
-	readonly weight: S
-	readonly [admitted]: true
-}
+type CapacityWeight<S extends WeightSpec = WeightSpec> = S
 
 interface FieldRef<F extends string = string> {
 	readonly kind: "field"
@@ -61,14 +21,6 @@ interface DurationRef<F extends string = string> {
 	readonly field: F
 }
 
-function isCapacityWindow(value: unknown): value is CapacityWindow {
-	return typeof value === "object" && value !== null && admitted in value && "window" in value
-}
-
-function isCapacityWeight(value: unknown): value is CapacityWeight {
-	return typeof value === "object" && value !== null && admitted in value && "weight" in value
-}
-
 interface BannedWindow<Canonical extends string> {
 	readonly "banned window spelling — the canonical-utterance law names the one legal form": Canonical
 }
@@ -125,11 +77,12 @@ type RangeBan<Lo extends bigint, Hi extends bigint> = bigint extends Lo
  * The C18 dimension gate's ban row, unit instance (the engine's
  * `CapacityDimensionMixing` twin, ruled 2026-07-24): a unit (count)
  * window against a `duration` bound counts facts against a span of
- * time — a dimension error. Judged on the `capacity` UNIT overload
- * only: Duration weights pair with Duration-capable bounds, so the
- * weighted overload takes the same window freely.
+ * interval coordinates — a dimension error. Judged on the `capacity`
+ * UNIT overload only. Explicit scalar and Duration measures may use
+ * either scalar or Duration bounds; the application supplies their
+ * common unit (for example, cents or calendar days).
  */
-type UnitDimensionBan<W extends CapacityWindow> = W["window"] extends {
+type UnitDimensionBan<W extends CapacityWindow> = W extends {
 	readonly hi: { readonly kind: "durationField" }
 }
 	? BannedWindow<"a count of facts bounded by a span of time mixes dimensions (C18) — weigh the source with weigh(duration(field)), or bound by a u64 field or literal">
@@ -154,17 +107,17 @@ interface BoundKindMismatch<K, Want> {
 
 type BoundOnTarget<K extends string, Want extends "u64" | "interval", B extends AnyFace> = string extends K
 	? unknown
-	: K extends FaceFields<B["source"]>
-		? KindAt<B["source"], K> extends Want
+	: K extends FaceFields<B["owner"]>
+		? KindAt<B["owner"], K> extends Want
 			? unknown
 			: BoundKindMismatch<K, Want>
-		: BoundOffTargetRoster<K, FaceFields<B["source"]>>
+		: BoundOffTargetRoster<K, FaceFields<B["owner"]>>
 
-type BoundsOnTarget<W extends CapacityWindow, B extends AnyFace> = W["window"] extends {
+type BoundsOnTarget<W extends CapacityWindow, B extends AnyFace> = W extends {
 	readonly hi: FieldRef<infer K>
 }
 	? BoundOnTarget<K, "u64", B>
-	: W["window"] extends { readonly hi: DurationRef<infer K> }
+	: W extends { readonly hi: DurationRef<infer K> }
 		? BoundOnTarget<K, "interval", B>
 		: unknown
 
@@ -189,30 +142,32 @@ interface WeightKindMismatch<K, Want> {
  * position. Checked at the `capacity` call where the source face is
  * inferred — the proven constrain-after-inference pattern.
  */
-type WeightOnSource<M extends CapacityWeight, A extends AnyFace> = M["weight"] extends {
+type WeightOnSource<M extends CapacityWeight, A extends AnyFace> = M extends {
 	readonly kind: "field"
 	readonly field: infer K extends string
 }
 	? string extends K
 		? unknown
-		: K extends FaceFields<A["source"]>
-			? KindAt<A["source"], K> extends "u64"
+		: K extends FaceFields<A["owner"]>
+			? KindAt<A["owner"], K> extends "u64"
 				? unknown
 				: WeightKindMismatch<K, "u64">
-			: WeightOffSourceRoster<K, FaceFields<A["source"]>>
-	: M["weight"] extends { readonly kind: "durationField"; readonly field: infer K extends string }
+			: WeightOffSourceRoster<K, FaceFields<A["owner"]>>
+	: M extends { readonly kind: "durationField"; readonly field: infer K extends string }
 		? string extends K
 			? unknown
-			: K extends FaceFields<A["source"]>
-				? KindAt<A["source"], K> extends "interval"
+			: K extends FaceFields<A["owner"]>
+				? KindAt<A["owner"], K> extends "interval"
 					? unknown
 					: WeightKindMismatch<K, "interval">
-				: WeightOffSourceRoster<K, FaceFields<A["source"]>>
+				: WeightOffSourceRoster<K, FaceFields<A["owner"]>>
 		: unknown
 
 const unitWeight: WeightSpec = Object.freeze({ kind: "unit" })
 
-function assertRowLocal(field: string, role: string): string {
+function assertRowLocal<F extends string>(field: F, role: string): F {
+	if (typeof field !== "string" || !field.isWellFormed())
+		throw new AuthoringError({ message: `${role}: expected a well-formed field name` })
 	if (field.includes(".")) {
 		throw new AuthoringError({
 			message: `${role} \`${field}\` walks a reference — the vocabulary is closed at the row (ruling 6): pin the column with a two-column containment (Source(ref, f) <= Catalog(id, f)) and name the local field`
@@ -222,8 +177,8 @@ function assertRowLocal(field: string, role: string): string {
 }
 
 function admitWindow<S extends CapacityWindowSpec>(window: S): CapacityWindow<S> {
-	const value: CapacityWindow<S> = { window, [admitted]: true }
-	return Object.freeze(value)
+	capacityWindow(window)
+	return Object.freeze(window)
 }
 
 function lit(value: bigint): CapacityBoundSpec {
@@ -265,6 +220,8 @@ function within<const Lo extends bigint, const Hi extends bigint>(
 	| { readonly kind: "exact"; readonly n: { readonly kind: "lit"; readonly value: Lo } }
 >
 function within(lo: bigint, hi?: bigint | "*" | FieldRef | DurationRef): CapacityWindow {
+	integerValue("capacity lower bound", "u64", lo)
+	if (typeof hi === "bigint") integerValue("capacity upper bound", "u64", hi)
 	if (lo < 0n) {
 		throw new AuthoringError({
 			message: `capacity bounds are u64: within(${lo}${hi === undefined ? "" : ", …"}) is out of domain`
@@ -302,8 +259,8 @@ function within(lo: bigint, hi?: bigint | "*" | FieldRef | DurationRef): Capacit
 }
 
 function admitWeight<S extends WeightSpec>(weight: S): CapacityWeight<S> {
-	const value: CapacityWeight<S> = { weight, [admitted]: true }
-	return Object.freeze(value)
+	capacityWeight(weight)
+	return Object.freeze(weight)
 }
 
 /**
@@ -326,18 +283,74 @@ function weigh(measure: string | DurationRef): CapacityWeight {
 }
 
 function ref<const F extends string>(field: F & PathBan<F>): FieldRef<F> {
-	return Object.freeze({ kind: "field", field: assertRowLocal(field, "dependent bound") }) as FieldRef<F>
+	return Object.freeze({ kind: "field", field: assertRowLocal(field, "dependent bound") })
 }
 
 /**
  * `Duration(field)` — the interval-measure spelling, one mint for both
  * slots: handed to `weigh` it is the SOURCE row's interval measure;
  * in `within`'s hi slot it is the TARGET row's interval-measure bound
- * (Duration weights pair with Duration-capable bounds — C18).
+ * in the interval element's unit, not necessarily a clock unit.
+ * Explicit u64 measures/bounds may carry that same unit; an unweighted
+ * row count cannot be bounded by an interval measure (C18).
  */
 function duration<const F extends string>(field: F & PathBan<F>): DurationRef<F> {
-	return Object.freeze({ kind: "durationField", field: assertRowLocal(field, "Duration measure") }) as DurationRef<F>
+	return Object.freeze({ kind: "durationField", field: assertRowLocal(field, "Duration measure") })
 }
 
 export type { BoundsOnTarget, CapacityWeight, CapacityWindow, DurationRef, FieldRef, UnitDimensionBan, WeightOnSource }
-export { duration, isCapacityWeight, isCapacityWindow, ref, unitWeight, weigh, within }
+
+/** Read a checked bound without retaining a caller-owned record. */
+function capacityBound(input: unknown): CapacityBoundSpec {
+	const kind = typeof input === "object" && input !== null && "kind" in input ? input.kind : undefined
+	if (kind === "lit") {
+		const bound = recordValue("capacity bound", input, ["kind", "value"])
+		return Object.freeze({ kind, value: integerValue("capacity bound", "u64", bound.value) })
+	}
+	if (kind === "field" || kind === "durationField") {
+		const bound = recordValue("capacity bound", input, ["kind", "field"])
+		if (typeof bound.field !== "string") throw new AuthoringError({ message: "capacity bound: expected a field name" })
+		return Object.freeze({ kind, field: assertRowLocal(bound.field, "dependent bound") })
+	}
+	throw new AuthoringError({ message: "capacity bound: unknown kind" })
+}
+
+function literalBound(input: unknown): CapacityBoundSpec & { readonly kind: "lit" } {
+	const bound = capacityBound(input)
+	if (bound.kind !== "lit")
+		throw new AuthoringError({ message: "dependent bounds are allowed only at a range's upper bound" })
+	return bound
+}
+
+function capacityWindow(input: unknown): CapacityWindow {
+	const kind = typeof input === "object" && input !== null && "kind" in input ? input.kind : undefined
+	if (kind === "exact") {
+		const window = recordValue("capacity window", input, ["kind", "n"])
+		return Object.freeze({ kind, n: literalBound(window.n) })
+	}
+	if (kind === "floor") {
+		const window = recordValue("capacity window", input, ["kind", "lo"])
+		return Object.freeze({ kind, lo: literalBound(window.lo) })
+	}
+	if (kind === "range") {
+		const window = recordValue("capacity window", input, ["kind", "lo", "hi"])
+		const lo = literalBound(window.lo)
+		const hi = capacityBound(window.hi)
+		if (hi.kind === "lit" && hi.value < lo.value) throw new AuthoringError({ message: "capacity window is inverted" })
+		return Object.freeze({ kind, lo, hi })
+	}
+	throw new AuthoringError({ message: "capacity window: unknown kind" })
+}
+
+function capacityWeight(input: unknown): CapacityWeight {
+	const kind = typeof input === "object" && input !== null && "kind" in input ? input.kind : undefined
+	if (kind === "unit") {
+		recordValue("capacity weight", input, ["kind"])
+		return unitWeight
+	}
+	const weight = capacityBound(input)
+	if (weight.kind === "lit") throw new AuthoringError({ message: "capacity weight: expected unit or a source field" })
+	return weight
+}
+
+export { capacityWeight, capacityWindow, duration, ref, unitWeight, weigh, within }

package/src/changes.ts

@@ -1,19 +1,22 @@
 import type { Scope } from "effect"
-import { Effect, Exit } from "effect"
+import { Effect, Exit, Option, Stream } from "effect"
 import { drainClose, releaseOwner } from "#close.ts"
+import { isClosedMember, membersAgree } from "#closed.ts"
 import type { SchemaId } from "#compile.ts"
 import { Schema as CoreSchema, schemaTables } from "#compile.ts"
-import type { ChangesHandle, DraftHandle } from "#db-native.ts"
+import type { ChangeRecordWire, ChangesHandle, ChangesWire, DraftHandle } from "#db-native.ts"
 import { dbNative } from "#db-native.ts"
+import { SdkInvariantError } from "#errors.ts"
 import { lower } from "#lower.ts"
-import type { AnyRelation, Fact } from "#relation.ts"
+import { type AnyRelation, type Fact, relationFields } from "#relation.ts"
 import type { CellValue } from "#rows.ts"
-import { cellOf, hostCellCharge, recordOf } from "#rows.ts"
+import { factCellsOf, factOfCells, hostCellCharge } from "#rows.ts"
 import { nativeOperationWith, runtimeHandle } from "#runtime.ts"
 import type { CloseReport } from "#runtime-errors.ts"
-import { DbError } from "#runtime-errors.ts"
-import type { AnySchema } from "#schema.ts"
+import { argumentError, DbError } from "#runtime-errors.ts"
+import type { AnySchema, SchemaRelation } from "#schema.ts"
 import type { Rel } from "#shape.ts"
+import { bytesValue, recordValue } from "#values.ts"
 
 /**
  * `ChangeSet` — the engine's checked immutable delta:
@@ -22,10 +25,32 @@ import type { Rel } from "#shape.ts"
  * add-wins. Immutable and reusable while open; sealing/submitting it later
  * retains the SAME native value — no second JS row walk ever happens.
  */
+/** Counts of distinct fact additions and removals, never input events. */
+interface ChangeCounts {
+	readonly added: bigint
+	readonly removed: bigint
+}
+
+/** A relation-name-discriminated union of plain, fully typed facts. */
+type ChangeRecord<S extends AnySchema> = {
+	[N in keyof S["relations"]]: S["relations"][N] extends AnyRelation
+		? { readonly relation: N; readonly kind: "add" | "remove"; readonly fact: Fact<S["relations"][N]> }
+		: never
+}[keyof S["relations"]]
+
 interface ChangeSet<S extends AnySchema> {
 	readonly schemaId: SchemaId
+	/** Distinct requested actions; use judge for effective counts against a store. */
+	readonly counts: ChangeCounts
+	readonly byteLength: bigint
 	/** Phantom schema brand: a ChangeSet is only ever applied to its own S. */
 	readonly schema?: S
+	/** Independent scoped traversal, delivered in bounded native batches. Reusable. */
+	records(): Stream.Stream<ChangeRecord<S>, DbError>
+	/** Explicit full byte materialization. Mutating returned bytes cannot alter this value. */
+	toBytes(): Effect.Effect<Uint8Array, DbError>
+	/** Commutative add-wins composition into one command, not sequential replay. */
+	compose(other: ChangeSet<S>): Effect.Effect<ChangeSet<S>, DbError, Scope.Scope>
 	close(): Effect.Effect<CloseReport>
 }
 
@@ -97,31 +122,15 @@ function eventLoopTurn(): Effect.Effect<void> {
 }
 
 function hostFactCharge(relation: AnyRelation, record: Readonly<Record<string, unknown>>): bigint {
-	const data = relation.data
+	const fields = relationFields(relation)
 	let bytes = 0n
-	for (const declared of data.fields) {
+	for (const declared of fields) {
 		const value = record[declared.name]
-		if (value === undefined) {
-			throw refusal("ChangeDraft.ingest", "InvalidArgument")
-		}
 		bytes += hostCellCharge(value)
 	}
 	return bytes
 }
 
-function projectFact(relation: AnyRelation, record: Readonly<Record<string, unknown>>): readonly CellValue[] {
-	const data = relation.data
-	const cells: CellValue[] = []
-	for (const declared of data.fields) {
-		const value = record[declared.name]
-		if (value === undefined) {
-			throw refusal("ChangeDraft.ingest", "InvalidArgument")
-		}
-		cells.push(cellOf(`relation ${data.name} field ${declared.name}`, declared.field, value))
-	}
-	return cells
-}
-
 /**
  * Pulls one bounded chunk off the caller's iterator. Host length is judged
  * before any string scan or byte copy. A leftover fact that does not fit
@@ -141,13 +150,17 @@ function pullChunk(relation: AnyRelation, iterator: Iterator<object>, pending: o
 			}
 			current = next.value
 		}
-		const record = recordOf(current)
+		const record = recordValue(
+			`relation ${relation.name}`,
+			current,
+			relationFields(relation).map((field) => field.name)
+		)
 		const charge = hostFactCharge(relation, record)
 		if (rows > 0n && bytes + charge > CHUNK_BYTES) {
 			leftover = current
 			break
 		}
-		for (const cell of projectFact(relation, record)) cells.push(cell)
+		for (const cell of factCellsOf(relation, record)) cells.push(cell)
 		bytes += charge
 		rows += 1n
 		current = undefined
@@ -185,7 +198,7 @@ function ingest(
 			yield* spendAndDrain(state, operation)
 			return yield* Effect.fail(refusal(operation, "SpentHandle"))
 		}
-		if (state.theory.relations[relation.name] !== relation) {
+		if (!membersAgree(state.theory.relations[relation.name], relation)) {
 			return yield* Effect.fail(refusal(operation, "InvalidArgument"))
 		}
 		const tables = schemaTables(state.theory)
@@ -197,7 +210,7 @@ function ingest(
 		const body = Effect.gen(function* () {
 			const iterator = yield* Effect.try({
 				try: () => rows[Symbol.iterator](),
-				catch: () => refusal(operation, "InvalidArgument")
+				catch: (cause) => argumentError(operation, cause)
 			})
 			let leftover: object | undefined
 			let done = false
@@ -205,7 +218,7 @@ function ingest(
 				while (!done) {
 					const chunk = yield* Effect.try({
 						try: () => pullChunk(relation, iterator, leftover),
-						catch: (cause) => (cause instanceof DbError ? cause : refusal(operation, "InvalidArgument"))
+						catch: (cause) => argumentError(operation, cause)
 					}).pipe(Effect.catch((error) => spendAndDrain(state, operation).pipe(Effect.andThen(Effect.fail(error)))))
 					leftover = chunk.leftover
 					done = chunk.done && leftover === undefined
@@ -244,19 +257,126 @@ function ingest(
 	})
 }
 
-function makeChangeSet<S extends AnySchema>(handle: ChangesHandle, schemaId: SchemaId): ChangeSet<S> {
+function decodeChangeRecord<S extends AnySchema>(
+	relations: readonly SchemaRelation[],
+	record: ChangeRecordWire
+): ChangeRecord<S> {
+	const relation = relations[record.relation]
+	if (relation === undefined || isClosedMember(relation) || (record.kind !== "add" && record.kind !== "remove")) {
+		throw new SdkInvariantError({ message: "ChangeSet.records: invalid native record descriptor" })
+	}
+	// Relation id resolves through this schema's own ordered roster. The
+	// shared projector validates all field values before this union seam.
+	return Object.freeze({
+		relation: relation.name,
+		kind: record.kind,
+		fact: factOfCells(relation, record.values)
+	}) as ChangeRecord<S>
+}
+
+function changeRecords<S extends AnySchema>(
+	handle: ChangesHandle,
+	relations: readonly SchemaRelation[]
+): Stream.Stream<ChangeRecord<S>, DbError> {
+	return Stream.unwrap(
+		Effect.gen(function* () {
+			const cursor = yield* Effect.acquireRelease(
+				nativeOperationWith(
+					"ChangeSet.records",
+					(callback) => dbNative.runtimeChangesCursor(handle, callback),
+					dbNative.runtimeChangesCursorTake,
+					(value) => value
+				),
+				(value) =>
+					releaseOwner("ChangeCursor.close", (callback) => dbNative.runtimeChangesCursorClose(value, callback)),
+				{ interruptible: true }
+			)
+			return Stream.paginate(undefined, () =>
+				nativeOperationWith(
+					"ChangeSet.records",
+					(callback) => dbNative.runtimeChangesCursorNext(cursor, callback),
+					dbNative.runtimeChangePageTake,
+					(page) => page
+				).pipe(
+					Effect.map((page) =>
+						page === null
+							? ([[], Option.none<undefined>()] as const)
+							: ([page.map((record) => decodeChangeRecord<S>(relations, record)), Option.some(undefined)] as const)
+					)
+				)
+			)
+		})
+	)
+}
+
+function acquireChanges<S extends AnySchema>(
+	theory: S,
+	schemaId: SchemaId,
+	acquire: Effect.Effect<ChangesWire, DbError>
+): Effect.Effect<ChangeSet<S>, DbError, Scope.Scope> {
+	return Effect.acquireRelease(
+		acquire.pipe(Effect.map((wire) => makeChangeSet(theory, wire, schemaId))),
+		(changes) =>
+			Effect.suspend(() => {
+				const internal = changesInternals.get(changes)
+				if (internal === undefined) return Effect.void
+				internal.closed = true
+				return releaseOwner("ChangeSet.close", (callback) => dbNative.runtimeChangesClose(internal.handle, callback))
+			}),
+		{ interruptible: true }
+	)
+}
+
+function makeChangeSet<S extends AnySchema>(theory: S, wire: ChangesWire, schemaId: SchemaId): ChangeSet<S> {
+	const handle = wire.changes
+	const relations = Object.values(theory.relations)
+	const internal: ChangesInternal = { handle, schemaId, closed: false }
 	const value: ChangeSet<S> = {
 		schemaId,
+		counts: Object.freeze({ ...wire.counts }),
+		byteLength: wire.byteLength,
+		records() {
+			return changeRecords<S>(handle, relations)
+		},
+		toBytes() {
+			return nativeOperationWith(
+				"ChangeSet.toBytes",
+				(callback) => dbNative.runtimeChangesBytes(handle, callback),
+				dbNative.runtimeBytesTake,
+				(bytes) => bytes
+			)
+		},
+		compose(other) {
+			return Effect.suspend(() => {
+				const right = internalChanges(other)
+				if (right === undefined || right.schemaId !== schemaId)
+					return Effect.fail(refusal("ChangeSet.compose", "InvalidArgument"))
+				if (internal.closed || right.closed) return Effect.fail(refusal("ChangeSet.compose", "ClosedHandle"))
+				return acquireChanges(
+					theory,
+					schemaId,
+					nativeOperationWith(
+						"ChangeSet.compose",
+						(callback) => dbNative.runtimeChangesCompose(handle, right.handle, callback),
+						dbNative.runtimeChangesTake,
+						(result) => result
+					)
+				)
+			})
+		},
 		close() {
-			return drainClose("ChangeSet.close", (callback) => dbNative.runtimeChangesClose(handle, callback))
+			return Effect.suspend(() => {
+				internal.closed = true
+				return drainClose("ChangeSet.close", (callback) => dbNative.runtimeChangesClose(handle, callback))
+			})
 		}
 	}
 	Object.freeze(value)
-	changesInternals.set(value, { handle, schemaId, closed: false })
+	changesInternals.set(value, internal)
 	return value
 }
 
-function makeDraft<S extends AnySchema>(state: DraftState, schemaId: SchemaId): ChangeDraft<S> {
+function makeDraft<S extends AnySchema>(theory: S, state: DraftState, schemaId: SchemaId): ChangeDraft<S> {
 	const draft: ChangeDraft<S> = {
 		insert(relation, rows) {
 			return ingest(state, "ChangeDraft.insert", relation, rows)
@@ -265,7 +385,9 @@ function makeDraft<S extends AnySchema>(state: DraftState, schemaId: SchemaId):
 			return ingest(state, "ChangeDraft.delete", relation, rows)
 		},
 		finish() {
-			return Effect.acquireRelease(
+			return acquireChanges(
+				theory,
+				schemaId,
 				Effect.gen(function* () {
 					if (state.spent) {
 						return yield* Effect.fail(refusal("ChangeDraft.finish", "SpentHandle"))
@@ -276,26 +398,13 @@ function makeDraft<S extends AnySchema>(state: DraftState, schemaId: SchemaId):
 					}
 					// Finish CONSUMES the draft, success or failure.
 					state.spent = true
-					const wire = yield* nativeOperationWith(
+					return yield* nativeOperationWith(
 						"ChangeDraft.finish",
 						(callback) => dbNative.runtimeDraftFinish(state.handle, callback),
 						dbNative.runtimeChangesTake,
 						(value) => value
 					)
-					return makeChangeSet<S>(wire.changes, schemaId)
-				}),
-				(changes) =>
-					Effect.suspend(() => {
-						const internal = changesInternals.get(changes)
-						if (internal === undefined || internal.closed) {
-							return Effect.void
-						}
-						internal.closed = true
-						return releaseOwner("ChangeSet.close", (callback) =>
-							dbNative.runtimeChangesClose(internal.handle, callback)
-						)
-					}),
-				{ interruptible: true }
+				})
 			)
 		},
 		close() {
@@ -318,7 +427,7 @@ function makeDraft<S extends AnySchema>(state: DraftState, schemaId: SchemaId):
 const builder = Effect.fn("ChangeSet.builder")(function* <S extends AnySchema>(schema: S) {
 	const handle = yield* runtimeHandle()
 	const compiled = yield* CoreSchema.compile(schema)
-	const spec = lower(schema)
+	const spec = lower(compiled.schema)
 	return yield* Effect.acquireRelease(
 		Effect.gen(function* () {
 			const draftHandle = yield* nativeOperationWith(
@@ -329,11 +438,11 @@ const builder = Effect.fn("ChangeSet.builder")(function* <S extends AnySchema>(s
 			)
 			const state: DraftState = {
 				handle: draftHandle,
-				theory: schema,
+				theory: compiled.schema,
 				spent: false,
 				inFlight: false
 			}
-			const draft = makeDraft<S>(state, compiled.schemaId)
+			const draft = makeDraft(compiled.schema, state, compiled.schemaId)
 			draftStates.set(draft, state)
 			return draft
 		}),
@@ -357,7 +466,27 @@ const builder = Effect.fn("ChangeSet.builder")(function* <S extends AnySchema>(s
 // native handle without exposing it on the public capability.
 const draftStates = new WeakMap<object, DraftState>()
 
-const ChangeSet = Object.freeze({ builder })
+/** Parse canonical native bytes, owning the input when the Effect starts. */
+const fromBytes = Effect.fn("ChangeSet.fromBytes")(function* <S extends AnySchema>(schema: S, bytes: Uint8Array) {
+	const ownedBytes = yield* Effect.try({
+		try: () => bytesValue("ChangeSet.fromBytes", bytes),
+		catch: (cause) => argumentError("ChangeSet.fromBytes", cause)
+	})
+	const handle = yield* runtimeHandle()
+	const compiled = yield* CoreSchema.compile(schema)
+	return yield* acquireChanges(
+		compiled.schema,
+		compiled.schemaId,
+		nativeOperationWith(
+			"ChangeSet.fromBytes",
+			(callback) => dbNative.runtimeChangesParse(handle, lower(compiled.schema), ownedBytes, callback),
+			dbNative.runtimeChangesTake,
+			(wire) => wire
+		)
+	)
+})
+
+const ChangeSet = Object.freeze({ builder, fromBytes })
 
-export type { ChangeDraft }
+export type { ChangeCounts, ChangeDraft, ChangeRecord }
 export { ChangeSet, internalChanges }