@bjornpagen/bumbledb-log 0.17.0 → 0.19.0

package/src/descriptor.ts

@@ -1,11 +1,8 @@
 /**
- * The parsed protocol descriptor: the SDK's lowered `SchemaSpec` resolved
- * once — names to dense ids, handles to row ids, statements materialized
- * in the engine's own order (fresh auto-keys first, closed auto-keys,
- * then declared statements with `==` split into two containments) — so
- * every pure function downstream reads ids, never names. Braid
- * derivation and the schema fingerprint mirror live on the same parse:
- * one boundary, parsed in full, cached per theory value.
+ * The parsed protocol descriptor: one thin parse of the engine's sealed
+ * truth — relation ids, sealed field order, resolved closed rows,
+ * materialized statements, and the real fingerprint — plus the braid
+ * map the protocol derives from that truth. Cached per theory value.
  */
 
 import type {
@@ -13,20 +10,22 @@ import type {
 	LiteralSetSpec,
 	LiteralSpec,
 	SchemaSpec,
+	SealedDescriptor,
+	SealedSide,
+	SealedStatement,
 	SideSpec,
 	StatementSpec,
-	ValueSpec,
-	ValueTypeSpec
+	ValueSpec
 } from "@bjornpagen/bumbledb"
-import { internalBlake3, lower } from "@bjornpagen/bumbledb"
+import { internalDescriptor, lower } from "@bjornpagen/bumbledb"
 import * as errors from "@superbuilders/errors"
-import { ByteWriter, fromHex, toHex, utf8Encoder } from "#bytes.ts"
-import type { LogValue } from "#value.ts"
-import { writeCanonicalLiteral } from "#value.ts"
+import { regex } from "arkregex"
+import { fromHex } from "#bytes.ts"
+import type { Value } from "#value.ts"
 
 interface FieldInfo {
 	readonly name: string
-	readonly type: ValueTypeSpec
+	readonly type: SchemaSpec["relations"][number]["fields"][number]["valueType"]
 	readonly fresh: boolean
 	/** Set when the field's newtype names a closed relation's id class. */
 	readonly closedRef: string | undefined
@@ -40,13 +39,13 @@ interface RelationInfo {
 	/** Sealed order: a closed relation's synthetic u64 `id` at ordinal 0. */
 	readonly fields: readonly FieldInfo[]
 	/** Closed ground axioms in sealed order (id first), resolved values. */
-	readonly rows: ReadonlyArray<readonly LogValue[]>
+	readonly rows: ReadonlyArray<readonly Value[]>
 }
 
 interface SideInfo {
 	readonly relation: number
 	readonly projection: readonly number[]
-	readonly selection: ReadonlyArray<{ readonly field: number; readonly values: readonly LogValue[] }>
+	readonly selection: ReadonlyArray<{ readonly field: number; readonly values: readonly Value[] }>
 }
 
 type WeightInfo =
@@ -78,38 +77,125 @@ type StatementInfo =
 			readonly source: SideInfo
 	  }
 
+declare const braidBrand: unique symbol
+type Braid = string & { readonly [braidBrand]: typeof braidBrand }
+
+const BRAID_ID = regex("^c[0-9a-f]{8}$")
+const ID_CLASS = regex("^(.*)\\.id$")
+
+function braid(raw: string): Braid {
+	if (!BRAID_ID.test(raw)) {
+		throw errors.new(`not a braid id: ${raw}`)
+	}
+	return raw as Braid
+}
+
+function refuseShape(why: string): never {
+	throw errors.new(`theory: ${why}`)
+}
+
+/** `{name}.id` — the closed relation's generator class. */
+function idClassOwner(newtype: string): string | undefined {
+	const match = ID_CLASS.exec(newtype)
+	const owner = match?.[1]
+	if (owner === undefined || owner.length === 0) {
+		return undefined
+	}
+	return owner
+}
+
+function indexRelations(relations: readonly RelationInfo[]): Map<number, RelationInfo> {
+	const byId = new Map<number, RelationInfo>()
+	for (const relation of relations) {
+		if (byId.has(relation.id)) {
+			refuseShape(`duplicate relation id ${relation.id}`)
+		}
+		byId.set(relation.id, relation)
+	}
+	return byId
+}
+
+function relationOfId(byId: ReadonlyMap<number, RelationInfo>, id: number): RelationInfo {
+	const relation = byId.get(id)
+	if (relation === undefined) {
+		refuseShape(`unknown relation id ${id}`)
+	}
+	return relation
+}
+
+function fieldNamed(relation: RelationInfo, name: string): { readonly ordinal: number; readonly field: FieldInfo } {
+	let ordinal = 0
+	for (const field of relation.fields) {
+		if (field.name === name) {
+			return { ordinal, field }
+		}
+		ordinal += 1
+	}
+	refuseShape(`relation ${relation.name} has no field ${name}`)
+}
+
 interface SerialStatement {
 	readonly statement: number
-	readonly braid: string
+	readonly braid: Braid
 }
 
-interface LogDescriptor {
+function serialAtOf(
+	byId: ReadonlyMap<number, RelationInfo>,
+	statements: readonly StatementInfo[],
+	braidOfRelation: ReadonlyMap<number, Braid>
+): SerialStatement[] {
+	const serialAt: SerialStatement[] = []
+	for (const statement of statements) {
+		if (statement.kind === "functionality" && statement.projection.length === 0) {
+			const relation = relationOfId(byId, statement.relation)
+			if (relation.fields.length > 0) {
+				const braid = braidOfRelation.get(statement.relation)
+				if (braid !== undefined) {
+					serialAt.push({ statement: statement.id, braid })
+				}
+			}
+		}
+		if (statement.kind === "capacity" && statement.target.projection.length === 0) {
+			const targetRelation = relationOfId(byId, statement.target.relation)
+			if (!targetRelation.closed) {
+				const braid = braidOfRelation.get(statement.target.relation)
+				if (braid === undefined) {
+					refuseShape(`capacity ${statement.id} target ${targetRelation.name} is not in the derived braid set`)
+				}
+				serialAt.push({ statement: statement.id, braid })
+			}
+		}
+	}
+	return serialAt
+}
+
+interface Descriptor {
 	readonly relations: readonly RelationInfo[]
 	readonly relationByName: ReadonlyMap<string, RelationInfo>
 	readonly statements: readonly StatementInfo[]
-	/** Ordinary relation id → braid id string (`c{smallest:08x}`). */
-	readonly braidOfRelation: ReadonlyMap<number, string>
-	/** Braid id string → member relation ids, ascending. */
-	readonly braidMembers: ReadonlyMap<string, readonly number[]>
+	/** Ordinary relation id → braid id (`c{smallest:08x}`). */
+	readonly braidOfRelation: ReadonlyMap<number, Braid>
+	/** Braid id → member relation ids, ascending. */
+	readonly braidMembers: ReadonlyMap<Braid, readonly number[]>
 	readonly serialAtStatements: readonly SerialStatement[]
 	readonly fingerprint: string
 	readonly fingerprintBytes: Uint8Array
 }
 
 /** The pure trio's input: the theory value, its lowered spec, or an already-parsed descriptor. */
-type LogTheory = AnySchema | SchemaSpec | LogDescriptor
+type Theory = AnySchema | SchemaSpec | Descriptor
 
-function isDescriptor(theory: LogTheory): theory is LogDescriptor {
+function isDescriptor(theory: Theory): theory is Descriptor {
 	return "braidMembers" in theory
 }
 
-function isSpec(theory: LogTheory): theory is SchemaSpec {
+function isSpec(theory: Theory): theory is SchemaSpec {
 	return Array.isArray((theory as SchemaSpec).relations)
 }
 
-const cache = new WeakMap<object, LogDescriptor>()
+const cache = new WeakMap<object, Descriptor>()
 
-function descriptorOf(theory: LogTheory): LogDescriptor {
+function descriptorOf(theory: Theory): Descriptor {
 	if (isDescriptor(theory)) {
 		return theory
 	}
@@ -118,17 +204,192 @@ function descriptorOf(theory: LogTheory): LogDescriptor {
 		return hit
 	}
 	const spec = isSpec(theory) ? theory : lower(theory)
-	const parsed = spec === theory ? parseSpec(spec) : (cache.get(spec) ?? parseSpec(spec))
+	const parsed = spec === theory ? fromSealed(spec) : (cache.get(spec) ?? fromSealed(spec))
 	cache.set(theory, parsed)
 	cache.set(spec, parsed)
 	return parsed
 }
 
-function braidHex(relationId: number): string {
-	return `c${relationId.toString(16).padStart(8, "0")}`
+function braidHex(relationId: number): Braid {
+	return braid(`c${relationId.toString(16).padStart(8, "0")}`)
+}
+
+function asValue(raw: unknown): Value {
+	if (typeof raw === "boolean" || typeof raw === "bigint" || typeof raw === "string" || raw instanceof Uint8Array) {
+		return raw
+	}
+	if (typeof raw === "object" && raw !== null && "start" in raw && "end" in raw) {
+		const interval = raw as { start: unknown; end: unknown }
+		if (typeof interval.start === "bigint" && typeof interval.end === "bigint") {
+			return { start: interval.start, end: interval.end }
+		}
+	}
+	refuseShape("sealed value is not a raw fact value")
+}
+
+function sideOf(side: SealedSide): SideInfo {
+	return {
+		relation: side.relation,
+		projection: side.projection,
+		selection: side.selection.map(function valuesOf(binding) {
+			return { field: binding.field, values: binding.values.map(asValue) }
+		})
+	}
+}
+
+function statementOf(statement: SealedStatement): StatementInfo {
+	switch (statement.kind) {
+		case "functionality":
+			return statement
+		case "containment":
+			return {
+				id: statement.id,
+				kind: "containment",
+				source: sideOf(statement.source),
+				target: sideOf(statement.target)
+			}
+		case "capacity":
+			return {
+				id: statement.id,
+				kind: "capacity",
+				target: sideOf(statement.target),
+				weight: statement.weight,
+				lo: statement.lo,
+				hi: statement.hi,
+				source: sideOf(statement.source)
+			}
+	}
+}
+
+function fromSealed(spec: SchemaSpec): Descriptor {
+	const sealed: SealedDescriptor = internalDescriptor(spec)
+	const specByName = new Map<string, SchemaSpec["relations"][number]>()
+	for (const relation of spec.relations) {
+		if (specByName.has(relation.name)) {
+			refuseShape(`duplicate relation ${relation.name}`)
+		}
+		specByName.set(relation.name, relation)
+	}
+	const closedOwners = new Set(
+		spec.relations
+			.filter(function closedOf(relation) {
+				return relation.closed !== undefined
+			})
+			.map(function nameOf(relation) {
+				return relation.name
+			})
+	)
+
+	const relations: RelationInfo[] = sealed.relations.map(function relationOf(relation) {
+		const declared = specByName.get(relation.name)
+		if (declared === undefined) {
+			refuseShape(`sealed relation ${relation.name} is not in the spec`)
+		}
+		const closed = relation.extension !== undefined
+		const fields: FieldInfo[] = relation.fields.map(function fieldOf(field) {
+			if (field.name === "id" && closed) {
+				return { name: field.name, type: field.valueType, fresh: false, closedRef: relation.name }
+			}
+			const specField = declared.fields.find(function named(candidate) {
+				return candidate.name === field.name
+			})
+			let closedRef: string | undefined
+			const owner = specField?.newtype === undefined ? undefined : idClassOwner(specField.newtype)
+			if (owner !== undefined && closedOwners.has(owner)) {
+				closedRef = owner
+			}
+			return {
+				name: field.name,
+				type: field.valueType,
+				fresh: specField?.fresh === true,
+				closedRef
+			}
+		})
+		const extension = relation.extension ?? []
+		const named = new Map(
+			relation.fields.map(function indexOf(field) {
+				return [field.name, field]
+			})
+		)
+		const rows = extension.map(function rowOf(row) {
+			const cells = new Map(
+				row.values.map(function cellOf(cell) {
+					return [cell.name, asValue(cell.value)]
+				})
+			)
+			return relation.fields.map(function cellValue(field) {
+				const hit = cells.get(field.name)
+				if (hit !== undefined) {
+					return hit
+				}
+				if (field.name === "id" && named.has("id")) {
+					return row.id
+				}
+				return refuseShape(`closed relation ${relation.name}: sealed row ${row.handle} missing field ${field.name}`)
+			})
+		})
+		return {
+			id: relation.id,
+			name: relation.name,
+			closed,
+			handles: extension.map(function handleOf(row) {
+				return row.handle
+			}),
+			fields,
+			rows
+		}
+	})
+
+	const byName = new Map<string, RelationInfo>()
+	for (const relation of relations) {
+		if (byName.has(relation.name)) {
+			refuseShape(`duplicate relation ${relation.name}`)
+		}
+		byName.set(relation.name, relation)
+	}
+
+	const statements = sealed.statements.map(statementOf)
+	const byId = indexRelations(relations)
+	const { braidOfRelation, braidMembers } = deriveBraids(byId, statements)
+	const serialAtStatements = serialAtOf(byId, statements, braidOfRelation)
+
+	const fingerprint = sealed.fingerprint
+	return {
+		relations,
+		relationByName: byName,
+		statements,
+		braidOfRelation,
+		braidMembers,
+		serialAtStatements,
+		fingerprint,
+		fingerprintBytes: fromHex(fingerprint)
+	}
+}
+
+/**
+ * The same descriptor under a pinned fingerprint — for stores whose
+ * identity is carried (a manifest, a conformance sidecar) rather than
+ * recomputed.
+ */
+function withFingerprint(descriptor: Descriptor, fingerprint: string): Descriptor {
+	return {
+		relations: descriptor.relations,
+		relationByName: descriptor.relationByName,
+		statements: descriptor.statements,
+		braidOfRelation: descriptor.braidOfRelation,
+		braidMembers: descriptor.braidMembers,
+		serialAtStatements: descriptor.serialAtStatements,
+		fingerprint,
+		fingerprintBytes: fromHex(fingerprint)
+	}
 }
 
-function logValueOf(value: ValueSpec): LogValue {
+/**
+ * Assemble a descriptor from a SchemaSpec that is not a theory — the
+ * conformance corpus pins the codec and the braid map on shapes the
+ * engine seal refuses. Theories enter through descriptorOf.
+ */
+function rawValue(value: ValueSpec): Value {
 	switch (value.kind) {
 		case "bool":
 			return value.value
@@ -147,8 +408,39 @@ function logValueOf(value: ValueSpec): LogValue {
 
 interface SpecTables {
 	readonly spec: SchemaSpec
-	readonly relations: RelationInfo[]
 	readonly byName: Map<string, RelationInfo>
+	readonly byId: Map<number, RelationInfo>
+}
+
+function zipClosedPayload(
+	relation: RelationInfo,
+	handle: string,
+	literals: readonly LiteralSpec[]
+): Array<readonly [FieldInfo, LiteralSpec]> {
+	const pairs: Array<readonly [FieldInfo, LiteralSpec]> = []
+	const pending = literals[Symbol.iterator]()
+	let seenId = false
+	for (const field of relation.fields) {
+		if (!seenId) {
+			if (field.name !== "id") {
+				refuseShape(`closed relation ${relation.name} has no sealed id field`)
+			}
+			seenId = true
+			continue
+		}
+		const next = pending.next()
+		if (next.done) {
+			refuseShape(`closed row ${handle} of ${relation.name}: fewer cells than payload fields`)
+		}
+		pairs.push([field, next.value])
+	}
+	if (!seenId) {
+		refuseShape(`closed relation ${relation.name} has no sealed id field`)
+	}
+	if (!pending.next().done) {
+		refuseShape(`closed row ${handle} of ${relation.name}: more cells than payload fields`)
+	}
+	return pairs
 }
 
 function fieldsOf(
@@ -166,8 +458,8 @@ function fieldsOf(
 	}
 	for (const field of relation.fields) {
 		let closedRef: string | undefined
-		if (field.newtype?.endsWith(".id")) {
-			const owner = field.newtype.slice(0, -3)
+		const owner = field.newtype === undefined ? undefined : idClassOwner(field.newtype)
+		if (owner !== undefined) {
 			const target = tables.get(owner)
 			if (target?.closed === true) {
 				closedRef = owner
@@ -178,27 +470,25 @@ function fieldsOf(
 	return fields
 }
 
-function resolveLiteral(tables: SpecTables, relation: RelationInfo, field: FieldInfo, literal: LiteralSpec): LogValue {
+function resolveLiteral(tables: SpecTables, relation: RelationInfo, field: FieldInfo, literal: LiteralSpec): Value {
 	if (literal.kind === "value") {
-		return logValueOf(literal.value)
+		return rawValue(literal.value)
 	}
 	if (field.closedRef === undefined) {
-		throw errors.new(
-			`handle literal ${literal.handle} on ${relation.name}.${field.name}, which references no closed roster`
-		)
+		refuseShape(`handle literal ${literal.handle} on ${relation.name}.${field.name}, which references no closed roster`)
 	}
 	const target = tables.byName.get(field.closedRef)
 	if (target === undefined) {
-		throw errors.new(`handle literal ${literal.handle}: unknown closed relation ${field.closedRef}`)
+		refuseShape(`handle literal ${literal.handle}: unknown closed relation ${field.closedRef}`)
 	}
 	const id = target.handles.indexOf(literal.handle)
 	if (id === -1) {
-		throw errors.new(`handle literal ${literal.handle} is not in the ${target.name} roster`)
+		refuseShape(`handle literal ${literal.handle} is not in the ${target.name} roster`)
 	}
 	return BigInt(id)
 }
 
-function literalSetOf(tables: SpecTables, relation: RelationInfo, field: FieldInfo, set: LiteralSetSpec): LogValue[] {
+function literalSetOf(tables: SpecTables, relation: RelationInfo, field: FieldInfo, set: LiteralSetSpec): Value[] {
 	if (set.kind === "one") {
 		return [resolveLiteral(tables, relation, field, set.literal)]
 	}
@@ -208,29 +498,19 @@ function literalSetOf(tables: SpecTables, relation: RelationInfo, field: FieldIn
 }
 
 function fieldOrdinal(relation: RelationInfo, name: string): number {
-	const ordinal = relation.fields.findIndex(function byName(field) {
-		return field.name === name
-	})
-	if (ordinal === -1) {
-		throw errors.new(`relation ${relation.name} has no field ${name}`)
-	}
-	return ordinal
+	return fieldNamed(relation, name).ordinal
 }
 
-function sideOf(tables: SpecTables, side: SideSpec): SideInfo {
+function specSideOf(tables: SpecTables, side: SideSpec): SideInfo {
 	const relation = tables.byName.get(side.relation)
 	if (relation === undefined) {
-		throw errors.new(`statement cites unknown relation ${side.relation}`)
+		refuseShape(`statement cites unknown relation ${side.relation}`)
 	}
 	const projection = side.projection.map(function ordinalOf(name) {
 		return fieldOrdinal(relation, name)
 	})
 	const selection = side.selection.map(function bindingOf(binding) {
-		const ordinal = fieldOrdinal(relation, binding[0])
-		const field = relation.fields[ordinal]
-		if (field === undefined) {
-			throw errors.new(`relation ${relation.name} has no field ordinal ${ordinal}`)
-		}
+		const { ordinal, field } = fieldNamed(relation, binding[0])
 		return { field: ordinal, values: literalSetOf(tables, relation, field, binding[1]) }
 	})
 	return { relation: relation.id, projection, selection }
@@ -238,7 +518,7 @@ function sideOf(tables: SpecTables, side: SideSpec): SideInfo {
 
 function boundValue(context: string, bound: { readonly kind: string }): bigint {
 	if (bound.kind !== "lit") {
-		throw errors.new(`${context}: dependent floors are refused by the schema grammar`)
+		refuseShape(`${context}: dependent floors are refused by the schema grammar`)
 	}
 	return (bound as { readonly kind: "lit"; readonly value: bigint }).value
 }
@@ -248,12 +528,12 @@ function capacityOf(
 	id: number,
 	statement: Extract<StatementSpec, { kind: "capacity" }>
 ): StatementInfo {
-	const target = sideOf(tables, statement.target)
-	const source = sideOf(tables, statement.source)
+	const target = specSideOf(tables, statement.target)
+	const source = specSideOf(tables, statement.source)
 	const sourceRelation = tables.byName.get(statement.source.relation)
 	const targetRelation = tables.byName.get(statement.target.relation)
 	if (sourceRelation === undefined || targetRelation === undefined) {
-		throw errors.new("capacity statement cites unknown relations")
+		refuseShape("capacity statement cites unknown relations")
 	}
 	let weight: WeightInfo
 	switch (statement.weight.kind) {
@@ -306,56 +586,62 @@ function capacityOf(
 	return { id, kind: "capacity", target, weight, lo, hi, source }
 }
 
-/** The `exact {n}` window: lo = hi = n; a non-literal n is grammar-refused upstream. */
-
-function parseSpec(spec: SchemaSpec): LogDescriptor {
+function assembleFromSpec(spec: SchemaSpec): Descriptor {
 	const prepass = new Map<string, { closed: boolean; handles: readonly string[] }>()
 	for (const relation of spec.relations) {
+		if (prepass.has(relation.name)) {
+			refuseShape(`duplicate relation ${relation.name}`)
+		}
 		prepass.set(relation.name, {
 			closed: relation.closed !== undefined,
 			handles: relation.closed === undefined ? [] : relation.closed.rows.map((row) => row.handle)
 		})
 	}
 
-	const relations: RelationInfo[] = []
 	const byName = new Map<string, RelationInfo>()
-	spec.relations.forEach(function buildRelation(relation, id) {
-		const fields = fieldsOf(prepass, relation)
+	const byId = new Map<number, RelationInfo>()
+	let nextId = 0
+	for (const relation of spec.relations) {
+		const table = prepass.get(relation.name)
+		if (table === undefined) {
+			refuseShape(`relation ${relation.name} missing from the closedness table`)
+		}
 		const info: RelationInfo = {
-			id,
+			id: nextId,
 			name: relation.name,
-			closed: relation.closed !== undefined,
-			handles: prepass.get(relation.name)?.handles ?? [],
-			fields,
+			closed: table.closed,
+			handles: table.handles,
+			fields: fieldsOf(prepass, relation),
 			rows: []
 		}
-		relations.push(info)
+		nextId += 1
 		byName.set(relation.name, info)
-	})
-	const tables: SpecTables = { spec, relations, byName }
+		byId.set(info.id, info)
+	}
 
-	spec.relations.forEach(function resolveRows(relation, id) {
+	const tables: SpecTables = { spec, byName, byId }
+
+	for (const relation of spec.relations) {
 		if (relation.closed === undefined) {
-			return
+			continue
 		}
-		const info = relations[id]
+		const info = byName.get(relation.name)
 		if (info === undefined) {
-			throw errors.new(`relation ordinal ${id} missing`)
+			refuseShape(`closed relation ${relation.name} missing`)
 		}
 		const rows = relation.closed.rows.map(function resolveRow(row, rowId) {
-			const values: LogValue[] = [BigInt(rowId)]
-			row.values.forEach(function resolveCell(literal, column) {
-				const field = info.fields[column + 1]
-				if (field === undefined) {
-					throw errors.new(`closed row ${row.handle} of ${relation.name}: no field at column ${column}`)
-				}
+			const values: Value[] = [BigInt(rowId)]
+			for (const [field, literal] of zipClosedPayload(info, row.handle, row.values)) {
 				values.push(resolveLiteral(tables, info, field, literal))
-			})
+			}
 			return values
 		})
-		relations[id] = { ...info, rows }
-		byName.set(relation.name, relations[id])
-	})
+		const updated = { ...info, rows }
+		byName.set(relation.name, updated)
+		byId.set(info.id, updated)
+	}
+
+	const relations = [...byId.values()]
 
 	const statements: StatementInfo[] = []
 	relations.forEach(function freshKeys(relation) {
@@ -375,7 +661,7 @@ function parseSpec(spec: SchemaSpec): LogDescriptor {
 			case "fd": {
 				const relation = byName.get(statement.relation)
 				if (relation === undefined) {
-					throw errors.new(`key statement cites unknown relation ${statement.relation}`)
+					refuseShape(`key statement cites unknown relation ${statement.relation}`)
 				}
 				statements.push({
 					id: statements.length,
@@ -388,8 +674,8 @@ function parseSpec(spec: SchemaSpec): LogDescriptor {
 				break
 			}
 			case "containment": {
-				const source = sideOf(tables, statement.source)
-				const target = sideOf(tables, statement.target)
+				const source = specSideOf(tables, statement.source)
+				const target = specSideOf(tables, statement.target)
 				statements.push({ id: statements.length, kind: "containment", source, target })
 				if (statement.bidirectional) {
 					statements.push({ id: statements.length, kind: "containment", source: target, target: source })
@@ -403,78 +689,28 @@ function parseSpec(spec: SchemaSpec): LogDescriptor {
 		}
 	}
 
-	const { braidOfRelation, braidMembers } = deriveBraids(relations, statements)
-
-	const serialAtStatements: SerialStatement[] = []
-	for (const statement of statements) {
-		if (statement.kind === "functionality" && statement.projection.length === 0) {
-			const braid = braidOfRelation.get(statement.relation)
-			if (braid !== undefined) {
-				serialAtStatements.push({ statement: statement.id, braid })
-			}
-		}
-		if (statement.kind === "capacity" && statement.target.projection.length === 0) {
-			const targetRelation = relations[statement.target.relation]
-			if (targetRelation !== undefined && !targetRelation.closed) {
-				const braid = braidOfRelation.get(statement.target.relation)
-				if (braid !== undefined) {
-					serialAtStatements.push({ statement: statement.id, braid })
-				}
-			}
-		}
-	}
-
-	let hashed: { readonly hex: string; readonly bytes: Uint8Array } | undefined
-	function fingerprintLazily(): { readonly hex: string; readonly bytes: Uint8Array } {
-		if (hashed === undefined) {
-			const bytes = fingerprintOf(relations, statements)
-			hashed = { hex: toHex(bytes), bytes }
-		}
-		return hashed
-	}
+	const { braidOfRelation, braidMembers } = deriveBraids(byId, statements)
+	const serialAtStatements = serialAtOf(byId, statements, braidOfRelation)
 
-	const descriptor: LogDescriptor = {
+	const fingerprint = "00".repeat(32)
+	return {
 		relations,
 		relationByName: byName,
 		statements,
 		braidOfRelation,
 		braidMembers,
 		serialAtStatements,
-		get fingerprint() {
-			return fingerprintLazily().hex
-		},
-		get fingerprintBytes() {
-			return fingerprintLazily().bytes
-		}
-	}
-	return descriptor
-}
-
-/**
- * The same descriptor under a pinned fingerprint — for stores whose
- * identity is carried (a manifest, a conformance sidecar) rather than
- * recomputed, e.g. when the mirror cannot hash a closed relation's
- * interned string axioms.
- */
-function withFingerprint(descriptor: LogDescriptor, fingerprint: string): LogDescriptor {
-	return {
-		relations: descriptor.relations,
-		relationByName: descriptor.relationByName,
-		statements: descriptor.statements,
-		braidOfRelation: descriptor.braidOfRelation,
-		braidMembers: descriptor.braidMembers,
-		serialAtStatements: descriptor.serialAtStatements,
 		fingerprint,
 		fingerprintBytes: fromHex(fingerprint)
 	}
 }
 
 function deriveBraids(
-	relations: readonly RelationInfo[],
+	byId: ReadonlyMap<number, RelationInfo>,
 	statements: readonly StatementInfo[]
-): { braidOfRelation: Map<number, string>; braidMembers: Map<string, readonly number[]> } {
+): { braidOfRelation: Map<number, Braid>; braidMembers: Map<Braid, readonly number[]> } {
 	const parent = new Map<number, number>()
-	for (const relation of relations) {
+	for (const relation of byId.values()) {
 		if (!relation.closed) {
 			parent.set(relation.id, relation.id)
 		}
@@ -500,9 +736,9 @@ function deriveBraids(
 		if (statement.kind === "functionality") {
 			continue
 		}
-		const source = relations[statement.source.relation]
-		const target = relations[statement.target.relation]
-		if (source === undefined || target === undefined || source.closed || target.closed) {
+		const source = relationOfId(byId, statement.source.relation)
+		const target = relationOfId(byId, statement.target.relation)
+		if (source.closed || target.closed) {
 			continue
 		}
 		union(source.id, target.id)
@@ -517,8 +753,8 @@ function deriveBraids(
 			list.push(id)
 		}
 	}
-	const braidOfRelation = new Map<number, string>()
-	const braidMembers = new Map<string, readonly number[]>()
+	const braidOfRelation = new Map<number, Braid>()
+	const braidMembers = new Map<Braid, readonly number[]>()
 	for (const [root, ids] of [...members.entries()].sort(function byRoot(a, b) {
 		return a[0] - b[0]
 	})) {
@@ -534,208 +770,16 @@ function deriveBraids(
 	return { braidOfRelation, braidMembers }
 }
 
-/** `bumbledb-schema-v5` canonical bytes, mirrored from the engine's own encoder. */
-const FORMAT_VERSION_LABEL = "bumbledb-schema-v5"
-
-const VALUE_TYPE_TAG = { bool: 0, u64: 2, i64: 3, string: 4, fixedBytes: 5, interval: 6, fixedInterval: 7 } as const
-
-function putLen(out: ByteWriter, len: number): void {
-	out.u32le(len)
-}
-
-function putBytes(out: ByteWriter, raw: Uint8Array): void {
-	putLen(out, raw.length)
-	out.bytes(raw)
-}
-
-function putString(out: ByteWriter, text: string): void {
-	putBytes(out, utf8Encoder.encode(text))
-}
-
-function putValueType(out: ByteWriter, type: ValueTypeSpec): void {
-	switch (type.kind) {
-		case "bool": {
-			out.u8(VALUE_TYPE_TAG.bool)
-			return
-		}
-		case "u64": {
-			out.u8(VALUE_TYPE_TAG.u64)
-			return
-		}
-		case "i64": {
-			out.u8(VALUE_TYPE_TAG.i64)
-			return
-		}
-		case "string": {
-			out.u8(VALUE_TYPE_TAG.string)
-			return
-		}
-		case "fixedBytes": {
-			out.u8(VALUE_TYPE_TAG.fixedBytes)
-			out.u16le(type.len)
-			return
-		}
-		case "interval": {
-			if (type.width === undefined) {
-				out.u8(VALUE_TYPE_TAG.interval)
-				out.u8(type.element === "u64" ? 0 : 1)
-				return
-			}
-			out.u8(VALUE_TYPE_TAG.fixedInterval)
-			out.u8(type.element === "u64" ? 0 : 1)
-			out.u64le(type.width)
-			return
-		}
-	}
-}
-
-function putSide(out: ByteWriter, relations: readonly RelationInfo[], side: SideInfo): void {
-	out.u32le(side.relation)
-	putLen(out, side.projection.length)
-	for (const field of side.projection) {
-		out.u16le(field)
-	}
-	putLen(out, side.selection.length)
-	const relation = relations[side.relation]
-	if (relation === undefined) {
-		throw errors.new(`side cites unknown relation id ${side.relation}`)
-	}
-	for (const binding of side.selection) {
-		out.u16le(binding.field)
-		const field = relation.fields[binding.field]
-		if (field === undefined) {
-			throw errors.new(`selection cites unknown field ordinal ${binding.field}`)
-		}
-		putLen(out, binding.values.length)
-		for (const value of binding.values) {
-			if (typeof value === "string") {
-				putString(out, value)
-			} else {
-				writeCanonicalLiteral(out, field.type, value)
-			}
-		}
-	}
-}
-
-function fingerprintOf(relations: readonly RelationInfo[], statements: readonly StatementInfo[]): Uint8Array {
-	const out = new ByteWriter(1024)
-	putString(out, FORMAT_VERSION_LABEL)
-	putLen(out, relations.length)
-	for (const relation of relations) {
-		putString(out, relation.name)
-		putLen(out, relation.fields.length)
-		for (const field of relation.fields) {
-			putString(out, field.name)
-			putValueType(out, field.type)
-			out.u8(field.fresh ? 1 : 0)
-		}
-		if (!relation.closed) {
-			out.u8(0)
-		} else {
-			out.u8(1)
-			putLen(out, relation.rows.length)
-			relation.rows.forEach(function putRow(row, rowId) {
-				const handle = relation.handles[rowId]
-				if (handle === undefined) {
-					throw errors.new(`closed relation ${relation.name}: no handle for row ${rowId}`)
-				}
-				putString(out, handle)
-				const fact = new ByteWriter(64)
-				row.forEach(function putCell(value, ordinal) {
-					const field = relation.fields[ordinal]
-					if (field === undefined) {
-						throw errors.new(`closed relation ${relation.name}: no field at ordinal ${ordinal}`)
-					}
-					if (field.type.kind === "string") {
-						throw errors.new(
-							`closed relation ${relation.name} has a string ground axiom — the fingerprint mirror does not carry interned axiom columns`
-						)
-					}
-					writeCanonicalLiteral(fact, field.type, value)
-				})
-				putBytes(out, fact.finish())
-			})
-		}
-	}
-	putLen(out, statements.length)
-	for (const statement of statements) {
-		switch (statement.kind) {
-			case "functionality": {
-				out.u8(0)
-				out.u32le(statement.relation)
-				putLen(out, statement.projection.length)
-				for (const field of statement.projection) {
-					out.u16le(field)
-				}
-				break
-			}
-			case "containment": {
-				out.u8(1)
-				putSide(out, relations, statement.source)
-				putSide(out, relations, statement.target)
-				break
-			}
-			case "capacity": {
-				out.u8(4)
-				putSide(out, relations, statement.target)
-				switch (statement.weight.kind) {
-					case "unit": {
-						out.u8(0)
-						break
-					}
-					case "field": {
-						out.u8(1)
-						out.u16le(statement.weight.field)
-						break
-					}
-					case "duration": {
-						out.u8(2)
-						out.u16le(statement.weight.field)
-						break
-					}
-				}
-				out.u64le(statement.lo)
-				switch (statement.hi.kind) {
-					case "unbounded": {
-						out.u8(0)
-						break
-					}
-					case "lit": {
-						out.u8(1)
-						out.u8(0)
-						out.u64le(statement.hi.value)
-						break
-					}
-					case "targetField": {
-						out.u8(1)
-						out.u8(1)
-						out.u16le(statement.hi.field)
-						break
-					}
-					case "targetDuration": {
-						out.u8(1)
-						out.u8(2)
-						out.u16le(statement.hi.field)
-						break
-					}
-				}
-				putSide(out, relations, statement.source)
-				break
-			}
-		}
-	}
-	return new Uint8Array(internalBlake3(out.finish()))
-}
-
 export type {
+	Braid,
+	Descriptor,
 	FieldInfo,
 	HiInfo,
-	LogDescriptor,
-	LogTheory,
 	RelationInfo,
 	SerialStatement,
 	SideInfo,
 	StatementInfo,
+	Theory,
 	WeightInfo
 }
-export { braidHex, descriptorOf, withFingerprint }
+export { assembleFromSpec, braid, braidHex, descriptorOf, withFingerprint }