@bjornpagen/bumbledb 1.1.0 → 1.2.0

package/src/codec.ts

@@ -1,18 +1,20 @@
 import { Effect, Schema as EffectSchema, Result } from "effect"
+import { membersAgree } from "#closed.ts"
 import { schemaTables } from "#compile.ts"
 import { dbNative } from "#db-native.ts"
+import { AuthoringError } from "#errors.ts"
 import type { AnyField } from "#fields.ts"
-import { isFloatIntervalValue, isIntervalValue, rosterOf } from "#fields.ts"
 import { lower } from "#lower.ts"
-import type { AnyRelation, Fact } from "#relation.ts"
+import { type AnyRelation, type Fact, relationDescriptor, relationFields } from "#relation.ts"
 import type { CellValue } from "#rows.ts"
 import { factOfCells, flatRowsOf } from "#rows.ts"
 import { nativeOperationWith, runtimeHandle } from "#runtime.ts"
-import { DbError } from "#runtime-errors.ts"
+import { argumentError, DbError } from "#runtime-errors.ts"
 import type { AnySchema } from "#schema.ts"
+import { schemaDescriptor } from "#schema.ts"
 import type { Rel } from "#shape.ts"
 import { f64BitsHex } from "#spec.ts"
-import { Uuid } from "#uuid.ts"
+import { fieldValue, recordValue } from "#values.ts"
 
 /**
  * Boundary row codecs, derived from the core relation descriptors — never a
@@ -43,14 +45,27 @@ interface RowShape<R extends AnyRelation> {
 }
 
 function rowShape<S extends AnySchema, R extends Rel<S>>(schema: S, relation: R): RowShape<R> {
-	return Object.freeze({ schema, relation })
+	const ownedSchema = schemaDescriptor(schema)
+	const ownedRelation = relationDescriptor(relation)
+	return Object.freeze({ schema: ownedSchema, relation: ownedRelation })
+}
+
+function checkedRowShape<R extends AnyRelation>(operation: string, input: RowShape<R>) {
+	recordValue(`${operation} shape`, input, ["schema", "relation"])
+	const schema = schemaDescriptor(input.schema)
+	const relation = relationDescriptor(input.relation)
+	const relationId = schemaTables(schema).relationIds.get(relation.name)
+	if (relationId === undefined || !membersAgree(schema.relations[relation.name], relation)) {
+		throw new AuthoringError({ message: `${operation}: relation is not declared in the schema` })
+	}
+	return { relation, relationId, spec: lower(schema) }
 }
 
 function invalid(operation: string): DbError {
 	return new DbError({ operation, reason: { _tag: "InvalidArgument" } })
 }
 
-const DECIMAL = /^-?(?:0|[1-9][0-9]*)$/
+const DECIMAL = /^(?:0|-?[1-9][0-9]*)$/
 const HEX16 = /^[0-9a-f]{16}$/
 const LOWER_HEX = /^(?:[0-9a-f]{2})*$/
 
@@ -88,146 +103,71 @@ function f64OfHex(text: unknown): number | undefined {
 	return value
 }
 
-/** One host value to its schema-tagged JSON form (pure, bounded). */
-function encodeBoundaryValue(field: AnyField, value: unknown): unknown {
-	const roster = rosterOf(field)
-	if (roster !== undefined) {
-		if (typeof value !== "string" || !roster.handles.includes(value)) {
-			throw invalid("encodeBoundaryRows")
-		}
-		return value
-	}
+/** One host value to its canonical, field-directed JSON representation. */
+function encodeBoundaryValue(context: string, field: AnyField, input: unknown): unknown {
+	if ("closed" in field) return fieldValue(context, field, input)
 	switch (field.kind) {
-		case "bool": {
-			if (typeof value !== "boolean") {
-				throw invalid("encodeBoundaryRows")
-			}
-			return value
-		}
+		case "bool":
+		case "str":
+		case "uuid":
+			return fieldValue(context, field, input)
 		case "u64":
-		case "i64": {
-			if (typeof value !== "bigint") {
-				throw invalid("encodeBoundaryRows")
-			}
-			return value.toString(10)
-		}
-		case "f64": {
-			if (typeof value !== "number") {
-				throw invalid("encodeBoundaryRows")
-			}
-			return { $f64: f64BitsHex(value) }
-		}
-		case "uuid": {
-			if (!Uuid.isUuid(value)) {
-				throw invalid("encodeBoundaryRows")
-			}
-			return value
-		}
-		case "str": {
-			if (typeof value !== "string" || !value.isWellFormed()) {
-				throw invalid("encodeBoundaryRows")
-			}
-			return value
-		}
-		case "bytes": {
-			if (!(value instanceof Uint8Array) || value.byteLength !== field.width) {
-				throw invalid("encodeBoundaryRows")
-			}
-			return hexOfBytes(value)
-		}
+		case "i64":
+			return fieldValue(context, field, input).toString(10)
+		case "f64":
+			return { $f64: f64BitsHex(fieldValue(context, field, input)) }
+		case "bytes":
+			return hexOfBytes(fieldValue(context, field, input))
 		case "interval": {
 			if (field.element === "f64") {
-				if (!isFloatIntervalValue(value)) {
-					throw invalid("encodeBoundaryRows")
-				}
+				const value = fieldValue(context, { ...field, element: "f64" }, input)
 				return { start: { $f64: f64BitsHex(value.start) }, end: { $f64: f64BitsHex(value.end) } }
 			}
-			if (!isIntervalValue(value)) {
-				throw invalid("encodeBoundaryRows")
-			}
+			const value = fieldValue(context, { ...field, element: field.element }, input)
 			return { start: value.start.toString(10), end: value.end.toString(10) }
 		}
 	}
 }
 
-const U64_MAX = 0xffffffffffffffffn
-const I64_MIN = -0x8000000000000000n
-const I64_MAX = 0x7fffffffffffffffn
-
-function decodeInteger(kind: "u64" | "i64", value: unknown): bigint | undefined {
-	if (typeof value !== "string" || !DECIMAL.test(value)) {
-		return undefined
-	}
-	const parsed = BigInt(value)
-	if (kind === "u64" && (parsed < 0n || parsed > U64_MAX)) {
-		return undefined
-	}
-	if (kind === "i64" && (parsed < I64_MIN || parsed > I64_MAX)) {
-		return undefined
-	}
-	// Canonical decimal only (no leading zeros, no "-0") — DECIMAL enforces.
-	return parsed
+function decodeInteger(value: unknown): bigint | undefined {
+	// No accepted integer spelling is longer than 20 ASCII characters.
+	if (typeof value !== "string" || value.length > 20 || !DECIMAL.test(value)) return undefined
+	return BigInt(value)
 }
 
 function decodeTaggedF64(value: unknown): number | undefined {
-	if (typeof value !== "object" || value === null || !("$f64" in value)) {
-		return undefined
-	}
-	const keys = Object.keys(value)
-	if (keys.length !== 1) {
-		return undefined
-	}
-	return f64OfHex((value as { readonly $f64: unknown }).$f64)
+	const record = recordValue("binary64 image", value, ["$f64"])
+	return f64OfHex(record.$f64)
 }
 
-/** One schema-tagged JSON form back to the host value (strict, pure). */
-function decodeBoundaryValue(field: AnyField, value: unknown): unknown | undefined {
-	const roster = rosterOf(field)
-	if (roster !== undefined) {
-		return typeof value === "string" && roster.handles.includes(value) ? value : undefined
-	}
+/** Decode representation, then judge the value through the shared interpreter. */
+function decodeBoundaryValue(context: string, field: AnyField, input: unknown): unknown {
+	if ("closed" in field) return fieldValue(context, field, input)
+	let decoded: unknown = input
 	switch (field.kind) {
-		case "bool":
-			return typeof value === "boolean" ? value : undefined
 		case "u64":
 		case "i64":
-			return decodeInteger(field.kind, value)
+			decoded = decodeInteger(input)
+			break
 		case "f64":
-			return decodeTaggedF64(value)
-		case "uuid":
-			return Uuid.isUuid(value) ? value : undefined
-		case "str":
-			return typeof value === "string" && value.isWellFormed() ? value : undefined
-		case "bytes": {
-			if (typeof value !== "string" || value.length !== field.width * 2) {
-				return undefined
-			}
-			return bytesOfHex(value)
-		}
+			decoded = decodeTaggedF64(input)
+			break
+		case "bytes":
+			decoded = typeof input === "string" && input.length === field.width * 2 ? bytesOfHex(input) : undefined
+			break
 		case "interval": {
-			if (typeof value !== "object" || value === null || !("start" in value) || !("end" in value)) {
-				return undefined
-			}
-			const raw = value as { readonly start: unknown; readonly end: unknown }
-			if (field.element === "f64") {
-				const start = decodeTaggedF64(raw.start)
-				const end = decodeTaggedF64(raw.end)
-				if (start === undefined || end === undefined || Number.isNaN(start) || Number.isNaN(end) || !(start < end)) {
-					return undefined
-				}
-				return Object.freeze({ start, end })
-			}
-			const start = decodeInteger(field.element, raw.start)
-			const end = decodeInteger(field.element, raw.end)
-			if (start === undefined || end === undefined || start >= end) {
-				return undefined
-			}
-			return Object.freeze({ start, end })
+			const record = recordValue(context, input, ["start", "end"])
+			decoded =
+				field.element === "f64"
+					? { start: decodeTaggedF64(record.start), end: decodeTaggedF64(record.end) }
+					: { start: decodeInteger(record.start), end: decodeInteger(record.end) }
+			break
 		}
 	}
+	return fieldValue(context, field, decoded)
 }
 
-/** Pure schema-tagged JSON encoding of owned rows (bounded per call). */
+/** Pure schema-tagged JSON encoding of complete rows. */
 function encodeBoundaryRows<R extends AnyRelation>(
 	relation: R,
 	rows: Iterable<Fact<R>>
@@ -235,78 +175,68 @@ function encodeBoundaryRows<R extends AnyRelation>(
 	return Result.try({
 		try: () => {
 			const out: Array<Readonly<Record<string, unknown>>> = []
+			const fields = relationFields(relation)
+			const names = fields.map((declared) => declared.name)
 			for (const row of rows) {
-				const record: Record<string, unknown> = {}
-				for (const declared of relation.data.fields) {
-					record[declared.name] = encodeBoundaryValue(
-						declared.field,
-						(row as Readonly<Record<string, unknown>>)[declared.name]
+				const input = recordValue(`relation ${relation.name}`, row, names)
+				out.push(
+					Object.freeze(
+						Object.fromEntries(
+							fields.map((declared) => [
+								declared.name,
+								encodeBoundaryValue(`relation ${relation.name}.${declared.name}`, declared.field, input[declared.name])
+							])
+						)
 					)
-				}
-				out.push(Object.freeze(record))
+				)
 			}
 			return Object.freeze(out)
 		},
-		catch: (cause) => (cause instanceof DbError ? cause : invalid("encodeBoundaryRows"))
+		catch: (cause) => argumentError("encodeBoundaryRows", cause)
 	})
 }
 
-/** Pure strict decoding of schema-tagged JSON rows; any refusal is typed. */
+/** Pure strict decoding; malformed records, getters and values fail as data. */
 function decodeBoundaryRows<R extends AnyRelation>(
 	relation: R,
 	input: unknown
 ): Result.Result<ReadonlyArray<Fact<R>>, DbError> {
-	if (!Array.isArray(input)) {
-		return Result.fail(invalid("decodeBoundaryRows"))
-	}
-	const out: Array<Fact<R>> = []
-	for (const raw of input) {
-		if (typeof raw !== "object" || raw === null) {
-			return Result.fail(invalid("decodeBoundaryRows"))
-		}
-		const record: Record<string, unknown> = {}
-		for (const declared of relation.data.fields) {
-			const decoded = decodeBoundaryValue(declared.field, (raw as Readonly<Record<string, unknown>>)[declared.name])
-			if (decoded === undefined) {
-				return Result.fail(invalid("decodeBoundaryRows"))
-			}
-			record[declared.name] = decoded
-		}
-		// Unknown extra keys refuse: wrong-schema values never pass.
-		for (const key of Object.keys(raw)) {
-			if (!(key in record)) {
-				return Result.fail(invalid("decodeBoundaryRows"))
-			}
-		}
-		out.push(Object.freeze(record) as Fact<R>)
-	}
-	return Result.succeed(Object.freeze(out))
+	return Result.try({
+		try: () => {
+			if (!Array.isArray(input)) throw invalid("decodeBoundaryRows")
+			const fields = relationFields(relation)
+			const names = fields.map((declared) => declared.name)
+			return Object.freeze(
+				input.map((row) => {
+					const raw = recordValue(`relation ${relation.name}`, row, names)
+					return Object.freeze(
+						Object.fromEntries(
+							fields.map((declared) => [
+								declared.name,
+								decodeBoundaryValue(`relation ${relation.name}.${declared.name}`, declared.field, raw[declared.name])
+							])
+						)
+					) as Fact<R>
+				})
+			)
+		},
+		catch: (cause) => argumentError("decodeBoundaryRows", cause)
+	})
 }
 
-/**
- * An Effect Schema for one relation's typed row, DERIVED from the core
- * descriptors (a validation-only declaration; the canonical `$f64`/decimal
- * wire form stays this module's explicit codec — Effect Schema's generic
- * JSON number encoding is not Bumbledb's `$f64` codec).
- */
+/** An Effect Schema derived from the same complete-row value interpreter. */
 function rowSchema<R extends AnyRelation>(relation: R) {
+	const fields = relationFields(relation)
+	const names = fields.map((declared) => declared.name)
 	return EffectSchema.declare((value: unknown): value is Fact<R> => {
-		if (typeof value !== "object" || value === null) {
+		try {
+			const record = recordValue(`relation ${relation.name}`, value, names)
+			for (const declared of fields)
+				fieldValue(`relation ${relation.name}.${declared.name}`, declared.field, record[declared.name])
+			return true
+		} catch {
 			return false
 		}
-		const record = value as Readonly<Record<string, unknown>>
-		return relation.data.fields.every(function checkField(declared) {
-			const cell = record[declared.name]
-			if (cell === undefined) {
-				return false
-			}
-			return Result.isSuccess(
-				Result.try({
-					try: () => encodeBoundaryValue(declared.field, cell),
-					catch: () => invalid("rowSchema")
-				})
-			)
-		})
 	})
 }
 
@@ -322,16 +252,14 @@ const encodeRows = Effect.fn("encodeRows")(function* <R extends AnyRelation>(
 	rows: Iterable<Fact<R>>
 ) {
 	const runtime = yield* runtimeHandle()
-	const tables = schemaTables(shape.schema)
-	const relationId = tables.relationIds.get(shape.relation.name)
-	if (relationId === undefined || shape.schema.relations[shape.relation.name] !== shape.relation) {
-		return yield* Effect.fail(invalid("encodeRows"))
-	}
+	const { relation, relationId, spec } = yield* Effect.try({
+		try: () => checkedRowShape("encodeRows", shape),
+		catch: (cause) => argumentError("encodeRows", cause)
+	})
 	const flat = yield* Effect.try({
-		try: () => flatRowsOf(shape.relation.data, rows as Iterable<object>),
-		catch: (cause) => (cause instanceof DbError ? cause : invalid("encodeRows"))
+		try: () => flatRowsOf(relation, rows as Iterable<object>),
+		catch: (cause) => argumentError("encodeRows", cause)
 	})
-	const spec = lower(shape.schema)
 	return yield* nativeOperationWith(
 		"encodeRows",
 		(callback) => dbNative.runtimeEncodeRows(runtime, spec, relationId, flat.rows, flat.cells, callback),
@@ -342,20 +270,18 @@ const encodeRows = Effect.fn("encodeRows")(function* <R extends AnyRelation>(
 
 const decodeRows = Effect.fn("decodeRows")(function* <R extends AnyRelation>(shape: RowShape<R>, input: Uint8Array) {
 	const runtime = yield* runtimeHandle()
-	const tables = schemaTables(shape.schema)
-	const relationId = tables.relationIds.get(shape.relation.name)
-	if (relationId === undefined || shape.schema.relations[shape.relation.name] !== shape.relation) {
-		return yield* Effect.fail(invalid("decodeRows"))
-	}
+	const { relation, relationId, spec } = yield* Effect.try({
+		try: () => checkedRowShape("decodeRows", shape),
+		catch: (cause) => argumentError("decodeRows", cause)
+	})
 	if (!(input instanceof Uint8Array) || !(input.buffer instanceof ArrayBuffer)) {
 		return yield* Effect.fail(invalid("decodeRows"))
 	}
-	const spec = lower(shape.schema)
 	return yield* nativeOperationWith(
 		"decodeRows",
 		(callback) => dbNative.runtimeDecodeRows(runtime, spec, relationId, input, callback),
 		dbNative.runtimeRowsTake,
-		(rows) => Object.freeze(rows.map((row) => factOfCells(shape.relation, row as readonly CellValue[])))
+		(rows) => Object.freeze(rows.map((row) => factOfCells(relation, row as readonly CellValue[])))
 	)
 })
 

package/src/compile.ts

@@ -1,22 +1,24 @@
 import { Effect } from "effect"
-import { isClosedMember } from "#closed.ts"
+import { isClosedMember, membersAgree } from "#closed.ts"
 import { dbNative } from "#db-native.ts"
 import { SdkInvariantError } from "#errors.ts"
+import { isImmutable, snapshotData } from "#immutable.ts"
 import type { SchemaClasses } from "#law.ts"
 import { lower } from "#lower.ts"
 import type { SealedDescriptor } from "#native.ts"
+import type { AnyRelation } from "#relation.ts"
 import { nativeOperationWith, runtimeHandle } from "#runtime.ts"
+import { argumentError } from "#runtime-errors.ts"
 import type { AnySchema, Schema as SchemaDeclaration, SchemaRelations } from "#schema.ts"
-import type { Statement } from "#statements.ts"
+import { schemaDescriptor } from "#schema.ts"
+import { type KeyStatement, type Statement, statementDescriptor } from "#statements.ts"
 
 /**
  * `SchemaId` — the engine's canonical schema fingerprint as lowercase hex.
- * Independent of database identity; a branded string so arbitrary text does
- * not typecheck where a schema identity is required.
+ * Independent of database identity; ordinary structural text. Native
+ * boundaries verify the fingerprint wherever it grants admission.
  */
-declare const schemaIdBrand: unique symbol
-
-type SchemaId = string & { readonly [schemaIdBrand]: "bumbledb.SchemaId" }
+type SchemaId = string
 
 /**
  * `CompiledSchema<S>` — bounded detached immutable descriptor data plus the
@@ -36,44 +38,35 @@ interface CompiledSchema<S extends AnySchema> {
  * ids (declaration order = ids), materialized statement ids (closed
  * relations' auto-handle keys FIRST in relation-declaration order, then
  * declared statements in declaration order with `mirrors` occupying two
- * consecutive slots, source-first — the theory's `StatementId` law), and
- * each relation's primary key (a closed relation's synthetic `(id)`,
- * otherwise its FIRST declared `key` statement).
+ * consecutive slots, source-first — the theory's `StatementId` law).
+ * Every declared statement retains its own native identity; no key is
+ * privileged by its position in the declaration.
  */
-interface PrimaryKey {
-	readonly statementId: number
-	readonly projection: readonly string[]
-}
-
 interface SchemaTables {
 	readonly relationIds: ReadonlyMap<string, number>
-	readonly primaryKeys: ReadonlyMap<string, PrimaryKey>
+	readonly statementIds: ReadonlyMap<Statement, number>
 }
 
 function declaredWidth(statement: Statement): number {
-	return statement.data.kind === "mirrors" ? 2 : 1
+	return statement.kind === "mirrors" ? 2 : 1
 }
 
 function tablesOf(theory: AnySchema): SchemaTables {
 	const relationIds = new Map<string, number>()
-	const primaryKeys = new Map<string, PrimaryKey>()
+	const statementIds = new Map<Statement, number>()
 	let autoKeys = 0
 	Object.entries(theory.relations).forEach(function assignRelation([name, member], ordinal) {
 		relationIds.set(name, ordinal)
 		if (isClosedMember(member)) {
-			primaryKeys.set(name, Object.freeze({ statementId: autoKeys, projection: Object.freeze(["id"]) }))
 			autoKeys += 1
 		}
 	})
 	let offset = autoKeys
 	for (const statement of theory.statements) {
-		const data = statement.data
-		if (data.kind === "key" && !primaryKeys.has(data.owner.name)) {
-			primaryKeys.set(data.owner.name, Object.freeze({ statementId: offset, projection: data.projection }))
-		}
+		statementIds.set(statement, offset)
 		offset += declaredWidth(statement)
 	}
-	return Object.freeze({ relationIds, primaryKeys })
+	return Object.freeze({ relationIds, statementIds })
 }
 
 const compiledCache = new WeakMap<AnySchema, SchemaTables>()
@@ -85,15 +78,37 @@ function schemaTables(theory: AnySchema): SchemaTables {
 		return cached
 	}
 	const built = tablesOf(theory)
-	compiledCache.set(theory, built)
+	if (isImmutable(theory)) compiledCache.set(theory, built)
 	return built
 }
 
+/** Resolve a logical key declaration, never an opaque constructor token. */
+function declaredKey<R extends AnyRelation>(
+	theory: AnySchema,
+	input: KeyStatement<R>
+): { readonly key: KeyStatement<R>; readonly statementId: number } | undefined
+function declaredKey(
+	theory: AnySchema,
+	input: KeyStatement
+): { readonly key: KeyStatement; readonly statementId: number } | undefined {
+	const key = statementDescriptor(input)
+	for (const [candidate, statementId] of schemaTables(theory).statementIds) {
+		if (
+			candidate.kind === "key" &&
+			membersAgree(candidate.owner, key.owner) &&
+			candidate.projection.length === key.projection.length &&
+			candidate.projection.every((field) => key.projection.includes(field))
+		)
+			return { key: candidate, statementId }
+	}
+	return undefined
+}
+
 function admitSchemaId(fingerprint: string): SchemaId {
-	if (typeof fingerprint !== "string" || fingerprint.length === 0) {
+	if (typeof fingerprint !== "string" || !/^[0-9a-f]{64}$/.test(fingerprint)) {
 		throw new SdkInvariantError({ message: "Schema.compile: the engine returned no canonical fingerprint" })
 	}
-	return fingerprint as SchemaId
+	return fingerprint
 }
 
 /**
@@ -105,18 +120,27 @@ function admitSchemaId(fingerprint: string): SchemaId {
  * native finalizer is created.
  */
 const compile = Effect.fn("Schema.compile")(function* <S extends AnySchema>(schema: S) {
+	const owned = yield* Effect.try({
+		try: () => schemaDescriptor(schema),
+		catch: (cause) => argumentError("Schema.compile", cause)
+	})
+	const spec = yield* Effect.try({ try: () => lower(owned), catch: (cause) => argumentError("Schema.compile", cause) })
 	const handle = yield* runtimeHandle()
-	const spec = lower(schema)
 	const descriptor = yield* nativeOperationWith(
 		"Schema.compile",
 		(callback) => dbNative.runtimeSchemaCompile(handle, spec, callback),
 		dbNative.runtimeSchemaTake,
 		(value) => value
 	)
+	const ownedDescriptor = snapshotData(descriptor)
 	const compiled: CompiledSchema<S> = Object.freeze({
-		schema,
+		get schema() {
+			return snapshotData(owned)
+		},
 		schemaId: admitSchemaId(descriptor.fingerprint),
-		descriptor
+		get descriptor() {
+			return snapshotData(ownedDescriptor)
+		}
 	})
 	return compiled
 })
@@ -143,5 +167,5 @@ type Schema<Rels extends SchemaRelations, Classes extends SchemaClasses = Schema
  */
 const Schema = Object.freeze({ compile })
 
-export type { CompiledSchema, PrimaryKey, SchemaId, SchemaTables }
-export { Schema, schemaTables }
+export type { CompiledSchema, SchemaId, SchemaTables }
+export { declaredKey, Schema, schemaTables }

package/src/db-native.ts

@@ -6,6 +6,8 @@
  * and joins any of them. Close verbs report the real drain outcome through
  * `CloseWire`.
  */
+
+import type { ChangeCounts } from "#changes.ts"
 import type { DbHandle, ParsedQuery, QueryParam, SealedDescriptor, Violation } from "#native.ts"
 import { native } from "#native.ts"
 import type { CellValue } from "#rows.ts"
@@ -30,6 +32,9 @@ export interface DraftHandle {
 export interface ChangesHandle {
 	readonly __changes: unique symbol
 }
+export interface ChangesCursorHandle {
+	readonly __changesCursor: unique symbol
+}
 
 /** The core-local witness: catalog/store identity plus generation, never a StateStamp. */
 export interface WitnessWire {
@@ -47,6 +52,16 @@ export type ApplyOutcomeWire =
 	| { readonly tag: "invariant-rejected"; readonly violations: readonly Violation[] }
 	| { readonly tag: "moved"; readonly witnessed: WitnessWire; readonly current: WitnessWire }
 
+export type JudgeOutcomeWire =
+	| { readonly tag: "admitted"; readonly base: WitnessWire; readonly changes: ChangeCounts }
+	| {
+			readonly tag: "invariant-rejected"
+			readonly base: WitnessWire
+			readonly changes: ChangeCounts
+			readonly violations: readonly Violation[]
+	  }
+	| { readonly tag: "moved"; readonly witnessed: WitnessWire; readonly current: WitnessWire }
+
 /** Bounded database diagnostics: measurements, never retained row payloads. */
 export interface DbInspectionWire {
 	readonly generation: bigint
@@ -62,6 +77,14 @@ export interface SnapshotWire {
 export interface ChangesWire {
 	readonly changes: ChangesHandle
 	readonly fingerprint: string
+	readonly counts: ChangeCounts
+	readonly byteLength: bigint
+}
+
+export interface ChangeRecordWire {
+	readonly relation: number
+	readonly kind: "add" | "remove"
+	readonly values: readonly CellValue[]
 }
 
 export interface MutationReportWire {
@@ -158,10 +181,29 @@ interface DbBridge {
 	runtimeChangesTake(operation: OperationHandle): ChangesWire
 	runtimeDraftClose(draft: DraftHandle, callback: (report: CloseWire) => void): void
 	runtimeChangesClose(changes: ChangesHandle, callback: (report: CloseWire) => void): void
+	/** Owned immutable bytes; parsing checks canonical order and the supplied schema. */
+	runtimeChangesBytes(changes: ChangesHandle, callback: () => void): OperationHandle
+	runtimeChangesParse(
+		runtime: RuntimeHandle,
+		spec: SchemaSpec,
+		bytes: Uint8Array,
+		callback: () => void
+	): OperationHandle
+	/** One command's add-wins composition, not sequential application. */
+	runtimeChangesCompose(left: ChangesHandle, right: ChangesHandle, callback: () => void): OperationHandle
+	/** Independent bounded traversal; never spends the immutable source. */
+	runtimeChangesCursor(changes: ChangesHandle, callback: () => void): OperationHandle
+	runtimeChangesCursorTake(operation: OperationHandle): ChangesCursorHandle
+	runtimeChangesCursorNext(cursor: ChangesCursorHandle, callback: () => void): OperationHandle
+	runtimeChangePageTake(operation: OperationHandle): readonly ChangeRecordWire[] | null
+	runtimeChangesCursorClose(cursor: ChangesCursorHandle, callback: (report: CloseWire) => void): void
 
 	/** One immutable final-state admission/commit under the managed owner. */
 	runtimeDbApply(db: DbHandle, changes: ChangesHandle, expected: ExpectedWire, callback: () => void): OperationHandle
 	runtimeApplyTake(operation: OperationHandle): ApplyOutcomeWire
+	/** Same candidate admission as apply, aborted on its worker before returning. */
+	runtimeDbJudge(db: DbHandle, changes: ChangesHandle, expected: ExpectedWire, callback: () => void): OperationHandle
+	runtimeJudgeTake(operation: OperationHandle): JudgeOutcomeWire
 
 	runtimeDbInspect(db: DbHandle, callback: () => void): OperationHandle
 	runtimeDbClearCache(db: DbHandle, callback: () => void): OperationHandle