@tangle-network/agent-eval 0.190.1 → 0.192.0

package/dist/search-ledger-Ck7tok0h.js

@@ -0,0 +1,1517 @@
+import { a as hashCanonical, i as compareCodeUnits, r as canonicalString } from "./canonical-BsZVgBhW.js";
+import { i as modelHasSnapshot, l as searchCellRunId } from "./run-record-BRlM99rX.js";
+import { n as MemoryLedgerJournal, r as replayLedgerText, t as FileLedgerJournal } from "./journal-DvKCvjty.js";
+import "./ledger-core/index.js";
+import { a as SearchLedgerError, i as SearchLedgerConflictError, o as SearchLedgerIntegrityError, t as SEARCH_LEDGER_FILE_CONTEXT } from "./search-ledger-file-DY0AXX3W.js";
+import { n as evaluationClaimSchema } from "./claim-V9Zqbq0J.js";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+//#region src/campaign/search-ledger-ordering.ts
+function artifactKey(artifact) {
+	return canonicalString(artifact);
+}
+function compareStrings(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+//#endregion
+//#region src/campaign/search-state.ts
+/**
+* `SearchState`: the one projection of a search ledger.
+*
+* The same code checks every invariant for the producer's journal, the kernel,
+* and the Intelligence verifier, and builds the read model they share. It keeps
+* compact indexes (nodes, edges, cells, per-unit score sums, running audit
+* totals), not the raw event list, and applies each entry in time proportional
+* to that entry, so a search of any length appends at a constant cost.
+*
+* The journal asks for a snapshot after every append. A snapshot is a
+* `SearchStateView` that reads the live indexes, so taking one costs nothing.
+* The view is valid until the state applies its next entry; a read after that
+* throws rather than returning numbers from a later ledger position. Read the
+* ledger's state again to see newer entries. The audit, header, head and claim
+* on a view are plain values and stay readable.
+*/
+/** Deterministic node id: identical content in one search is one node. */
+function searchNodeId(searchId, artifactDigest) {
+	return `node_${shortDigest([searchId, artifactDigest])}`;
+}
+/** Deterministic cell id: one node on one task in one split at one repeat. */
+function searchCellId(searchId, nodeId, taskId, split, rep) {
+	return `cell_${shortDigest([
+		searchId,
+		nodeId,
+		taskId,
+		split,
+		rep
+	])}`;
+}
+/** Digest a split's task list in taskId order. */
+function searchTaskSetDigest(tasks) {
+	return hashCanonical([...tasks].sort((left, right) => compareCodeUnits(left.taskId, right.taskId)));
+}
+/** 128 bits of SHA-256 over the canonical encoding: collision-safe and short
+* enough for directory names. */
+function shortDigest(value) {
+	return createHash("sha256").update(canonicalString(value)).digest("hex").slice(0, 32);
+}
+const MAX_LABEL_CHARS = 200;
+const USD_TOLERANCE = 1e-9;
+const SPLITS = [
+	"train",
+	"selection",
+	"test"
+];
+/**
+* Per-unit means of scored cells, in unitId order. Each unit sums its cells in
+* cellId order, so the result depends on the set of cells alone, never on the
+* order they settled in: a verifier that reads the same cells from a database
+* gets the same bits.
+*/
+function searchUnitScores(cells) {
+	const byUnit = /* @__PURE__ */ new Map();
+	for (const cell of cells) {
+		const unit = byUnit.get(cell.unitId);
+		if (unit) unit.push(cell);
+		else byUnit.set(cell.unitId, [cell]);
+	}
+	return [...byUnit.entries()].sort(([left], [right]) => compareCodeUnits(left, right)).map(([unitId, unitCells]) => {
+		let sum = 0;
+		for (const cell of unitCells.sort((left, right) => compareCodeUnits(left.cellId, right.cellId))) sum += cell.score;
+		return {
+			unitId,
+			sum,
+			count: unitCells.length,
+			mean: sum / unitCells.length
+		};
+	});
+}
+/**
+* The pure, incremental projection of one search ledger. `apply` refuses any
+* entry that breaks an invariant; the journal then discards this instance and
+* replays into a new one, so a refused entry leaves no partial state behind.
+*/
+var SearchState = class {
+	searchId;
+	version = 0;
+	header = null;
+	closed = null;
+	head = null;
+	lastOccurredAt = Number.NEGATIVE_INFINITY;
+	lastOccurredAtText = null;
+	tasks = /* @__PURE__ */ new Map();
+	nodes = /* @__PURE__ */ new Map();
+	nodeOrder = [];
+	nodeByDigest = /* @__PURE__ */ new Map();
+	edges = /* @__PURE__ */ new Map();
+	edgeOrder = [];
+	cells = /* @__PURE__ */ new Map();
+	operations = /* @__PURE__ */ new Map();
+	selectedNodeId = null;
+	claimUsedUsd = 0;
+	audit;
+	constructor(searchId) {
+		this.searchId = searchId;
+		this.audit = {
+			searchId,
+			eventCount: 0,
+			headHash: null,
+			status: "open",
+			closeReason: null,
+			nodes: 0,
+			nodesWithoutEdge: 0,
+			undecidedNodes: 0,
+			selectedNodeId: null,
+			edges: {
+				explicit: 0,
+				correlated: 0,
+				unknown: 0,
+				reproposals: 0
+			},
+			cells: {
+				allocated: 0,
+				settled: 0,
+				cancelled: 0,
+				open: 0
+			},
+			attempts: 0,
+			outcomes: {
+				passed: 0,
+				failed: 0,
+				errored: 0
+			},
+			operations: {
+				started: 0,
+				recorded: 0,
+				open: 0
+			},
+			spend: {
+				knownUsd: 0,
+				floorUsd: 0,
+				unknownCostCells: 0,
+				unknownCostOperations: 0,
+				committedUsd: 0,
+				openReservationUsd: 0,
+				overspendUsd: 0,
+				unreservedCells: 0,
+				boxMinutes: 0
+			},
+			tokens: {
+				inputTokens: 0,
+				outputTokens: 0,
+				cachedTokens: 0,
+				unknownTokenAttempts: 0
+			}
+		};
+	}
+	apply(entry, index) {
+		const event = entry.event;
+		if (this.closed) throw integrity(`event ${event.eventId} follows search-closed ${this.closed.eventId}`);
+		const occurredAt = Date.parse(event.occurredAt);
+		if (occurredAt < this.lastOccurredAt) throw integrity(`event ${event.eventId} occurred before the preceding event`);
+		assertUnique(event.artifacts.map(artifactKey), "artifact receipt", event.eventId);
+		if (event.kind === "search-opened") {
+			if (index !== 0 || this.header) throw integrity("search-opened must be the first and only opening event");
+			this.open(event);
+		} else {
+			if (!this.header) throw integrity(`event ${event.eventId} appears before search-opened`);
+			this.applyEvent(event, index);
+		}
+		this.lastOccurredAt = occurredAt;
+		this.lastOccurredAtText = event.occurredAt;
+		this.head = {
+			sequence: index,
+			entryHash: entry.entryHash
+		};
+		this.audit.eventCount = index + 1;
+		this.audit.headHash = entry.entryHash;
+		this.version += 1;
+	}
+	snapshot() {
+		return new SearchStateView(this, this.version);
+	}
+	/** @internal Views check this before every read of the live indexes. */
+	isAt(version) {
+		return this.version === version;
+	}
+	applyEvent(event, index) {
+		switch (event.kind) {
+			case "operation-started":
+				this.startOperation(event);
+				return;
+			case "operation-recorded":
+				this.recordOperation(event);
+				return;
+			case "node-registered":
+				this.registerNode(event, index);
+				return;
+			case "edge-recorded":
+				this.recordEdge(event, index);
+				return;
+			case "cell-allocated":
+				this.allocateCell(event, index);
+				return;
+			case "cell-settled":
+				this.settleCell(event, index);
+				return;
+			case "cell-cancelled":
+				this.cancelCell(event, index);
+				return;
+			case "node-decided":
+				this.decideNode(event, index);
+				return;
+			case "search-closed":
+				this.close(event);
+				return;
+		}
+	}
+	open(event) {
+		if (event.containment?.searchId === this.searchId) throw integrity("a search cannot contain itself");
+		if (event.derivedFrom?.searchId === this.searchId) throw integrity("a search cannot derive from itself");
+		const units = {
+			train: /* @__PURE__ */ new Set(),
+			selection: /* @__PURE__ */ new Set(),
+			test: /* @__PURE__ */ new Set()
+		};
+		for (const split of SPLITS) {
+			const { tasks, taskSetDigest } = event.splits[split];
+			if (searchTaskSetDigest(tasks) !== taskSetDigest) throw integrity(`the ${split} split's taskSetDigest does not match its tasks`);
+			for (const task of tasks) {
+				const owner = this.tasks.get(task.taskId);
+				if (owner) throw integrity(`task ${task.taskId} is in both the ${owner.split} and ${split} splits`);
+				this.tasks.set(task.taskId, {
+					split,
+					unitId: task.unitId
+				});
+				units[split].add(task.unitId);
+			}
+		}
+		if (event.splits.heldOutUnits) {
+			const seen = [...units.test].filter((unit) => units.train.has(unit) || units.selection.has(unit));
+			if (seen.length > 0) throw integrity(`test units ${seen.join(", ")} also appear in train or selection, but the splits declare heldOutUnits`);
+		}
+		const { budget } = event;
+		if (budget.maxUsd !== null && budget.reservedClaimUsd > budget.maxUsd + USD_TOLERANCE) throw integrity(`the claim reserve $${budget.reservedClaimUsd} exceeds the search cap $${budget.maxUsd}`);
+		this.header = event;
+	}
+	startOperation(event) {
+		if (this.operations.has(event.operationId)) throw integrity(`operation ${event.operationId} was started twice`);
+		this.admit(event.reservation, false, `operation ${event.operationId}`);
+		this.operations.set(event.operationId, {
+			operationId: event.operationId,
+			operationKind: event.operationKind,
+			reservation: event.reservation,
+			recorded: false,
+			outcome: null,
+			artifacts: [],
+			spentUsd: 0
+		});
+		this.audit.operations.started += 1;
+		this.audit.operations.open += 1;
+		this.audit.spend.openReservationUsd += event.reservation?.usd ?? 0;
+	}
+	recordOperation(event) {
+		const operation = this.operations.get(event.operationId);
+		if (!operation) throw integrity(`operation ${event.operationId} was recorded before it started`);
+		if (operation.recorded) throw integrity(`operation ${event.operationId} was recorded twice`);
+		if (operation.operationKind !== event.operationKind) throw integrity(`operation ${event.operationId} started as ${operation.operationKind} but recorded as ${event.operationKind}`);
+		const cost = this.book(event.accounting);
+		if (cost.unknown) this.audit.spend.unknownCostOperations += 1;
+		const reserved = operation.reservation?.usd ?? 0;
+		this.audit.spend.openReservationUsd -= reserved;
+		if (operation.reservation) this.audit.spend.overspendUsd += Math.max(0, cost.usd - reserved);
+		operation.recorded = true;
+		operation.outcome = event.outcome.status;
+		operation.artifacts = event.artifacts;
+		operation.spentUsd = cost.usd;
+		this.audit.operations.recorded += 1;
+		this.audit.operations.open -= 1;
+	}
+	registerNode(event, index) {
+		const expected = searchNodeId(this.searchId, event.artifactDigest);
+		if (event.nodeId !== expected) throw integrity(`node ${event.nodeId} does not match its artifact digest (expected ${expected})`);
+		if (this.nodes.has(event.nodeId)) throw integrity(`node ${event.nodeId} was registered twice; a re-proposal is a second edge into it`);
+		assertUnique(event.surfaces.map((surface) => surface.surfaceId), "surfaceId", event.eventId);
+		const maxNodes = this.header.budget.maxNodes;
+		if (maxNodes !== null && this.nodes.size + 1 > maxNodes) throw integrity(`node ${event.nodeId} exceeds the search's maxNodes ${maxNodes}`);
+		this.nodes.set(event.nodeId, {
+			event,
+			ordinal: this.nodeOrder.length,
+			registeredSequence: index,
+			updatedSequence: index,
+			edgeIds: [],
+			parents: [],
+			parentKeys: /* @__PURE__ */ new Set(),
+			primaryParentId: null,
+			depth: null,
+			children: [],
+			decisions: [],
+			finalist: false,
+			cellIds: [],
+			scoredCells: 0,
+			spend: {
+				knownUsd: 0,
+				floorUsd: 0,
+				unknownCostCells: 0,
+				boxMinutes: 0
+			}
+		});
+		this.nodeOrder.push(event.nodeId);
+		this.nodeByDigest.set(event.artifactDigest, event.nodeId);
+		this.audit.nodes += 1;
+		this.audit.nodesWithoutEdge += 1;
+		this.audit.undecidedNodes += 1;
+	}
+	recordEdge(event, index) {
+		if (this.edges.has(event.edgeId)) throw integrity(`edge ${event.edgeId} was recorded twice`);
+		const child = this.nodes.get(event.childNodeId);
+		if (!child) throw integrity(`edge ${event.edgeId} names unregistered child ${event.childNodeId}`);
+		if (event.label.length > MAX_LABEL_CHARS) throw integrity(`edge ${event.edgeId} label exceeds ${MAX_LABEL_CHARS} characters`);
+		if (event.diffs.length !== event.parents.length) throw integrity(`edge ${event.edgeId} needs one diff per parent`);
+		assertUnique(event.parents.map((parent) => canonicalString(parent)), "parent", event.eventId);
+		const { operator, attribution, parents } = event;
+		if (operator === "seed" !== (event.proposer === null)) throw integrity(`edge ${event.edgeId}: exactly the seed edge has no proposer`);
+		if (operator === "seed" && (parents.length > 0 || attribution === "unknown")) throw integrity(`seed edge ${event.edgeId} must have no parents and a known attribution`);
+		if (attribution === "unknown" && parents.length > 0) throw integrity(`edge ${event.edgeId} has unknown attribution but names parents`);
+		if (operator !== "seed" && attribution !== "unknown" && parents.length === 0) throw integrity(`${operator} edge ${event.edgeId} names no parent`);
+		if (operator === "merge" && attribution !== "unknown" && parents.length < 2) throw integrity(`merge edge ${event.edgeId} needs at least two parents`);
+		const operationId = event.proposer?.operationId ?? null;
+		if (operationId !== null && !this.operations.has(operationId)) throw integrity(`edge ${event.edgeId} names operation ${operationId}, which never started`);
+		const inSearch = [];
+		for (const parent of parents) {
+			if (parent.searchId !== this.searchId) {
+				const from = this.header.derivedFrom;
+				if (operator !== "derive" || parents.length !== 1 || !from || from.searchId !== parent.searchId || from.nodeId !== parent.nodeId) throw integrity(`edge ${event.edgeId} names a parent in search ${parent.searchId}; only a derive edge matching derivedFrom may`);
+				continue;
+			}
+			if (operator === "derive") throw integrity(`derive edge ${event.edgeId} must name the parent in derivedFrom`);
+			const record = this.nodes.get(parent.nodeId);
+			if (!record) throw integrity(`edge ${event.edgeId} names unregistered parent ${parent.nodeId}`);
+			if (record.ordinal >= child.ordinal) throw integrity(`edge ${event.edgeId}: parent ${parent.nodeId} registered after child ${child.event.nodeId}`);
+			if (record.edgeIds.length === 0) throw integrity(`edge ${event.edgeId}: parent ${parent.nodeId} has no edge of its own yet`);
+			inSearch.push(record);
+		}
+		if (child.edgeIds.length === 0) {
+			const primary = inSearch[0];
+			child.primaryParentId = primary?.event.nodeId ?? null;
+			child.depth = operator === "seed" || operator === "derive" ? 0 : primary && primary.depth !== null ? primary.depth + 1 : null;
+			this.audit.nodesWithoutEdge -= 1;
+		} else this.audit.edges.reproposals += 1;
+		child.edgeIds.push(event.edgeId);
+		for (const parent of parents) {
+			const key = canonicalString(parent);
+			if (child.parentKeys.has(key)) continue;
+			child.parentKeys.add(key);
+			child.parents.push(parent);
+		}
+		for (const parent of inSearch) if (!parent.children.includes(child.event.nodeId)) parent.children.push(child.event.nodeId);
+		child.updatedSequence = index;
+		this.edges.set(event.edgeId, event);
+		this.edgeOrder.push(event.edgeId);
+		this.audit.edges[attribution] += 1;
+	}
+	allocateCell(event, index) {
+		const expected = searchCellId(this.searchId, event.nodeId, event.taskId, event.split, event.rep);
+		if (event.cellId !== expected) throw integrity(`cell ${event.cellId} does not match its coordinates (expected ${expected})`);
+		if (this.cells.has(event.cellId)) throw integrity(`cell ${event.cellId} was allocated twice`);
+		const node = this.nodes.get(event.nodeId);
+		if (!node) throw integrity(`cell ${event.cellId} names unregistered node ${event.nodeId}`);
+		if (node.edgeIds.length === 0) throw integrity(`cell ${event.cellId}: node ${event.nodeId} has no edge yet`);
+		const task = this.tasks.get(event.taskId);
+		if (!task || task.split !== event.split) throw integrity(`cell ${event.cellId}: task ${event.taskId} is not in the ${event.split} split`);
+		if (task.unitId !== event.unitId) throw integrity(`cell ${event.cellId}: task ${event.taskId} samples unit ${task.unitId}`);
+		assertStageSplit(event.cellId, event.stage, event.split, node.ordinal === 0);
+		if (event.split === "test" && node.ordinal !== 0 && !node.finalist) throw integrity(`cell ${event.cellId}: the test split is sealed; only the root and finalists run on it`);
+		const maxCells = this.header.budget.maxCells;
+		if (maxCells !== null && this.audit.cells.allocated + 1 > maxCells) throw integrity(`cell ${event.cellId} exceeds the search's maxCells ${maxCells}`);
+		this.admit(event.reservation, event.stage === "claim", `cell ${event.cellId}`);
+		this.cells.set(event.cellId, {
+			cellId: event.cellId,
+			nodeId: event.nodeId,
+			taskId: event.taskId,
+			unitId: event.unitId,
+			split: event.split,
+			rep: event.rep,
+			stage: event.stage,
+			lane: event.lane,
+			reservation: event.reservation,
+			attempts: 0,
+			lastRunId: null,
+			outcome: null,
+			score: null,
+			final: false,
+			cancelled: null,
+			spentUsd: 0,
+			costKnown: true,
+			traceId: null,
+			allocatedSequence: index,
+			updatedSequence: index
+		});
+		node.cellIds.push(event.cellId);
+		node.updatedSequence = index;
+		this.audit.cells.allocated += 1;
+		this.audit.cells.open += 1;
+		this.audit.spend.openReservationUsd += event.reservation?.usd ?? 0;
+		if (event.stage === "claim") this.claimUsedUsd += event.reservation?.usd ?? 0;
+	}
+	settleCell(event, index) {
+		const cell = this.cells.get(event.cellId);
+		if (!cell) throw integrity(`attempt ${event.eventId} names unallocated cell ${event.cellId}`);
+		if (cell.cancelled) throw integrity(`cell ${event.cellId} was settled after it was cancelled`);
+		if (cell.final) throw integrity(`cell ${event.cellId} was attempted again after a final ${cell.outcome} outcome; only a retryable error admits another attempt`);
+		if (event.attempt !== cell.attempts + 1) throw integrity(`cell ${event.cellId} attempt ${event.attempt} is not contiguous (expected ${cell.attempts + 1})`);
+		const runId = searchCellRunId({
+			cellId: event.cellId,
+			attempt: event.attempt
+		});
+		if (event.runId !== runId) throw integrity(`cell ${event.cellId} attempt ${event.attempt} must have runId ${runId}`);
+		const node = this.nodes.get(cell.nodeId);
+		const declared = new Set(node.event.surfaces.map((surface) => surface.surfaceId));
+		assertUnique(event.surfaceEvidence.map((evidence) => evidence.surfaceId), "surface evidence", event.eventId);
+		for (const evidence of event.surfaceEvidence) if (!declared.has(evidence.surfaceId)) throw integrity(`attempt ${event.eventId} reports surface ${evidence.surfaceId}, which node ${cell.nodeId} does not declare`);
+		if (event.artifacts.filter((artifact) => artifact.role === "run-record").length > 1) throw integrity(`attempt ${event.eventId} binds more than one RunRecord`);
+		const before = this.reservationParts(cell);
+		const cost = this.book(event.accounting);
+		if (cell.attempts === 0) {
+			this.audit.cells.settled += 1;
+			this.audit.cells.open -= 1;
+			if (cell.reservation === null) this.audit.spend.unreservedCells += 1;
+		}
+		if (cost.unknown && cell.costKnown) {
+			cell.costKnown = false;
+			this.audit.spend.unknownCostCells += 1;
+			node.spend.unknownCostCells += 1;
+		}
+		cell.attempts = event.attempt;
+		cell.lastRunId = runId;
+		cell.outcome = event.outcome.status;
+		cell.spentUsd += cost.usd;
+		cell.updatedSequence = index;
+		if ("traceId" in event.traceRef) cell.traceId = event.traceRef.traceId;
+		if (event.outcome.status === "errored") cell.final = !event.outcome.error.retryable;
+		else {
+			cell.final = true;
+			cell.score = event.outcome.score;
+			node.scoredCells += 1;
+		}
+		const after = this.reservationParts(cell);
+		this.audit.spend.openReservationUsd += after.open - before.open;
+		this.audit.spend.overspendUsd += after.over - before.over;
+		if (cell.stage === "claim") this.claimUsedUsd += after.used - before.used;
+		if (cost.unknown) node.spend.floorUsd += cost.usd;
+		else node.spend.knownUsd += cost.usd;
+		const boxMinutes = event.boxMinutes ?? 0;
+		node.spend.boxMinutes += boxMinutes;
+		this.audit.spend.boxMinutes += boxMinutes;
+		node.updatedSequence = index;
+		this.audit.attempts += 1;
+		this.audit.outcomes[event.outcome.status] += 1;
+	}
+	cancelCell(event, index) {
+		const cell = this.cells.get(event.cellId);
+		if (!cell) throw integrity(`cancellation ${event.eventId} names unallocated cell ${event.cellId}`);
+		if (cell.cancelled) throw integrity(`cell ${event.cellId} was cancelled twice`);
+		if (cell.final) throw integrity(`cell ${event.cellId} was cancelled after a final outcome`);
+		const before = this.reservationParts(cell);
+		cell.cancelled = event.reason;
+		cell.updatedSequence = index;
+		const after = this.reservationParts(cell);
+		this.audit.spend.openReservationUsd += after.open - before.open;
+		this.audit.spend.overspendUsd += after.over - before.over;
+		if (cell.stage === "claim") this.claimUsedUsd += after.used - before.used;
+		if (cell.attempts === 0) {
+			this.audit.cells.cancelled += 1;
+			this.audit.cells.open -= 1;
+		}
+		this.nodes.get(cell.nodeId).updatedSequence = index;
+	}
+	decideNode(event, index) {
+		const node = this.nodes.get(event.nodeId);
+		if (!node) throw integrity(`decision ${event.eventId} names unregistered node ${event.nodeId}`);
+		if (node.edgeIds.length === 0) throw integrity(`decision ${event.eventId}: node ${event.nodeId} has no edge yet`);
+		const status = event.decision.status;
+		if (status === "selected") {
+			if (this.selectedNodeId !== null && this.selectedNodeId !== event.nodeId) throw integrity(`node ${event.nodeId} was selected while ${this.selectedNodeId} is still selected`);
+			if (node.scoredCells === 0) throw integrity(`node ${event.nodeId} cannot be selected without a scored cell`);
+		}
+		const previous = node.decisions.at(-1)?.decision.status ?? null;
+		const wasUndecided = previous === null || previous === "advanced";
+		const isUndecided = status === "advanced";
+		this.audit.undecidedNodes += (isUndecided ? 1 : 0) - (wasUndecided ? 1 : 0);
+		if (previous === "selected" && status !== "selected") this.selectedNodeId = null;
+		if (status === "selected") this.selectedNodeId = event.nodeId;
+		if (status === "finalist") node.finalist = true;
+		node.decisions.push({
+			sequence: index,
+			decision: event.decision,
+			basis: event.basis,
+			rule: event.rule,
+			reason: event.reason
+		});
+		node.updatedSequence = index;
+		this.audit.selectedNodeId = this.selectedNodeId;
+	}
+	close(event) {
+		const reasons = this.incompleteReasons();
+		if (reasons.length > 0) throw integrity(`search-closed while incomplete: ${reasons.join("; ")}`);
+		if (event.claim) this.checkClaim(event.claim);
+		this.closed = event;
+		this.audit.status = "closed";
+		this.audit.closeReason = event.reason;
+		this.audit.spend.openReservationUsd = 0;
+	}
+	checkClaim(claim) {
+		if (claim.finalists.length > 3) throw integrity(`the claim names ${claim.finalists.length} finalists; at most 3 are allowed`);
+		assertUnique(claim.finalists.map((finalist) => finalist.nodeId), "claim finalist", "search-closed");
+		for (const finalist of claim.finalists) if (!this.nodes.get(finalist.nodeId)?.finalist) throw integrity(`claim finalist ${finalist.nodeId} was never decided finalist`);
+		if (claim.selected !== this.selectedNodeId) throw integrity(`the claim selects ${claim.selected ?? "nothing"} but the selected node is ${this.selectedNodeId ?? "none"}`);
+		const root = this.nodeOrder[0] ?? null;
+		if (claim.decision === "ship") {
+			const shipped = claim.finalists.find((finalist) => finalist.nodeId === claim.selected);
+			if (claim.selected === null || claim.selected === root || !shipped?.promote) throw integrity("a ship claim must select a finalist that the paired test promoted");
+			if (!this.header.splits.heldOutUnits) throw integrity("a ship claim needs test units held out from train and selection");
+		} else if (claim.selected !== null && claim.selected !== root) throw integrity(`a ${claim.decision} claim keeps the root; it cannot select another node`);
+		if (claim.decision === "test-cannot-resolve") {
+			for (const cell of this.cells.values()) if (cell.split === "test" && cell.attempts > 0) throw integrity("a test-cannot-resolve claim spends nothing on test cells");
+		}
+	}
+	/** @internal */
+	incompleteReasons() {
+		const reasons = [];
+		if (!this.header) reasons.push("search-opened is missing");
+		if (this.audit.cells.open > 0) reasons.push(count(this.audit.cells.open, "cell", "has no outcome"));
+		if (this.audit.operations.open > 0) reasons.push(count(this.audit.operations.open, "operation", "is unrecorded"));
+		if (this.audit.nodesWithoutEdge > 0) reasons.push(count(this.audit.nodesWithoutEdge, "node", "has no edge"));
+		if (this.audit.undecidedNodes > 0) reasons.push(count(this.audit.undecidedNodes, "node", "has no terminal decision"));
+		return reasons;
+	}
+	/** Book an attempt's or operation's accounting into the running totals. An
+	* unknown cost counts as its proven floor. */
+	book(accounting) {
+		const { tokens, cost } = accounting;
+		if (tokens.status === "known") {
+			this.audit.tokens.inputTokens += tokens.inputTokens;
+			this.audit.tokens.outputTokens += tokens.outputTokens;
+			this.audit.tokens.cachedTokens += tokens.cachedTokens;
+		} else this.audit.tokens.unknownTokenAttempts += 1;
+		const usd = cost.status === "known" ? cost.usd : cost.knownLowerBoundUsd;
+		if (cost.status === "known") this.audit.spend.knownUsd += usd;
+		else this.audit.spend.floorUsd += usd;
+		this.audit.spend.committedUsd += usd;
+		return {
+			usd,
+			unknown: cost.status === "unknown"
+		};
+	}
+	/** A cell's share of the open reservations, its overspend, and what it draws
+	* from the claim reserve: the larger of its hold and its spend. */
+	reservationParts(cell) {
+		const reserved = cell.reservation?.usd ?? 0;
+		const holding = !cell.final && cell.cancelled === null;
+		return {
+			open: holding ? Math.max(0, reserved - cell.spentUsd) : 0,
+			over: cell.reservation ? Math.max(0, cell.spentUsd - reserved) : 0,
+			used: holding ? Math.max(reserved, cell.spentUsd) : cell.spentUsd
+		};
+	}
+	/** The admission rule: committed spend, open holds, the unspent claim
+	* reserve and the new hold stay within the cap. A claim cell draws on the
+	* claim reserve instead of adding to it. */
+	admit(reservation, claim, subject) {
+		const { maxUsd, reservedClaimUsd } = this.header.budget;
+		if (maxUsd === null) return;
+		const hold = reservation?.usd ?? 0;
+		const remainingClaim = Math.max(0, reservedClaimUsd - this.claimUsedUsd);
+		if (this.audit.spend.committedUsd + this.audit.spend.openReservationUsd + (claim ? Math.max(0, remainingClaim - hold) : remainingClaim) + hold > maxUsd + USD_TOLERANCE) throw integrity(`${subject} is not admissible: committed $${round(this.audit.spend.committedUsd)} + open $${round(this.audit.spend.openReservationUsd)} + claim reserve $${round(remainingClaim)} + hold $${round(hold)} exceeds the cap $${maxUsd}`);
+	}
+	/** @internal The largest hold a new non-claim cell or operation may take,
+	* and the claim reserve still unspent. */
+	readBudget() {
+		const { maxUsd, reservedClaimUsd } = this.header?.budget ?? {
+			maxUsd: null,
+			reservedClaimUsd: 0
+		};
+		const claimReserveUsd = Math.max(0, reservedClaimUsd - this.claimUsedUsd);
+		if (maxUsd === null) return {
+			headroomUsd: null,
+			claimReserveUsd
+		};
+		const used = this.audit.spend.committedUsd + this.audit.spend.openReservationUsd + claimReserveUsd;
+		return {
+			headroomUsd: Math.max(0, maxUsd - used),
+			claimReserveUsd
+		};
+	}
+	/** @internal */
+	readHeader() {
+		return this.header;
+	}
+	/** @internal */
+	readClosed() {
+		return this.closed;
+	}
+	/** @internal */
+	readHead() {
+		return this.head;
+	}
+	/** @internal */
+	readLastOccurredAt() {
+		return this.lastOccurredAtText;
+	}
+	/** @internal */
+	readAudit() {
+		const audit = this.audit;
+		return {
+			...audit,
+			edges: { ...audit.edges },
+			cells: { ...audit.cells },
+			outcomes: { ...audit.outcomes },
+			operations: { ...audit.operations },
+			spend: { ...audit.spend },
+			tokens: { ...audit.tokens }
+		};
+	}
+	/** @internal */
+	readNode(nodeId) {
+		const record = this.nodes.get(nodeId);
+		return record ? nodeView(record) : void 0;
+	}
+	/** @internal */
+	readNodeIds() {
+		return this.nodeOrder;
+	}
+	/** @internal */
+	readHasNode(nodeId) {
+		return this.nodes.has(nodeId);
+	}
+	/** @internal */
+	readNodeIdForDigest(artifactDigest) {
+		return this.nodeByDigest.get(artifactDigest);
+	}
+	/** @internal */
+	readEdge(edgeId) {
+		return this.edges.get(edgeId);
+	}
+	/** @internal */
+	readEdgeIds() {
+		return this.edgeOrder;
+	}
+	/** @internal */
+	readCell(cellId) {
+		const cell = this.cells.get(cellId);
+		return cell ? { ...cell } : void 0;
+	}
+	/** @internal */
+	readCellIds(nodeId) {
+		if (nodeId === void 0) return [...this.cells.keys()];
+		return this.nodes.get(nodeId)?.cellIds ?? [];
+	}
+	/** @internal */
+	readOperation(operationId) {
+		const operation = this.operations.get(operationId);
+		return operation ? { ...operation } : void 0;
+	}
+	/** @internal */
+	readScoredCells(nodeId, split) {
+		const scored = [];
+		for (const cellId of this.nodes.get(nodeId)?.cellIds ?? []) {
+			const cell = this.cells.get(cellId);
+			if (cell.split === split && cell.score !== null) scored.push({
+				cellId,
+				unitId: cell.unitId,
+				attempt: cell.attempts,
+				score: cell.score
+			});
+		}
+		return scored;
+	}
+};
+/**
+* A read of `SearchState` at one ledger position. Header, head, audit and
+* claim are values. Node, edge, cell and score reads go to the live indexes and
+* throw once the state has applied a later entry.
+*/
+var SearchStateView = class {
+	searchId;
+	header;
+	closed;
+	head;
+	/** `occurredAt` of the head entry; a writer stamps later events at or after it. */
+	lastOccurredAt;
+	audit;
+	completion;
+	/**
+	* The admission rule's room: `headroomUsd` is the largest reservation a new
+	* non-claim cell or operation may hold (committed spend, open holds and the
+	* unspent claim reserve all count against the cap), or null when the search
+	* declares no cap. `claimReserveUsd` is what claim cells may still draw.
+	*/
+	budget;
+	state;
+	version;
+	constructor(state, version) {
+		this.state = state;
+		this.version = version;
+		this.searchId = state.searchId;
+		this.header = state.readHeader();
+		this.closed = state.readClosed();
+		this.head = state.readHead();
+		this.lastOccurredAt = state.readLastOccurredAt();
+		this.audit = state.readAudit();
+		this.budget = state.readBudget();
+		const reasons = state.incompleteReasons();
+		if (!this.closed) reasons.unshift("search is open");
+		this.completion = {
+			complete: this.closed !== null,
+			reasons
+		};
+	}
+	/** The node the search started from: the first registered. */
+	get rootNodeId() {
+		return this.live().readNodeIds()[0] ?? null;
+	}
+	node(nodeId) {
+		return this.live().readNode(nodeId);
+	}
+	hasNode(nodeId) {
+		return this.live().readHasNode(nodeId);
+	}
+	/** Node ids in registration order. */
+	nodeIds() {
+		return [...this.live().readNodeIds()];
+	}
+	/** Nodes in registration order. */
+	nodes() {
+		const state = this.live();
+		return state.readNodeIds().map((nodeId) => state.readNode(nodeId));
+	}
+	nodeIdForDigest(artifactDigest) {
+		return this.live().readNodeIdForDigest(artifactDigest);
+	}
+	edge(edgeId) {
+		return this.live().readEdge(edgeId);
+	}
+	/** Edges in ledger order. */
+	edges() {
+		const state = this.live();
+		return state.readEdgeIds().map((edgeId) => state.readEdge(edgeId));
+	}
+	cell(cellId) {
+		return this.live().readCell(cellId);
+	}
+	/** Cells in allocation order, optionally of one node. */
+	cells(filter = {}) {
+		const state = this.live();
+		return state.readCellIds(filter.nodeId).map((cellId) => state.readCell(cellId));
+	}
+	operation(operationId) {
+		return this.live().readOperation(operationId);
+	}
+	/** A node's scored cells on one split, in allocation order. Unscored cells
+	* (errored, cancelled or in flight) are absent, never zero. */
+	scoredCells(nodeId, split) {
+		return this.live().readScoredCells(nodeId, split);
+	}
+	/** Per-unit score means of a node on one split, in unitId order. */
+	unitScores(nodeId, split) {
+		return searchUnitScores(this.scoredCells(nodeId, split));
+	}
+	/** The lineage a RunRecord mint needs for one cell attempt. */
+	lineage(coordinates) {
+		const state = this.live();
+		if (coordinates.searchId !== this.searchId) throw new SearchLedgerError(`coordinates name search ${coordinates.searchId}, not ${this.searchId}`);
+		const cell = state.readCell(coordinates.cellId);
+		if (!cell || cell.nodeId !== coordinates.nodeId) throw new SearchLedgerError(`cell ${coordinates.cellId} of node ${coordinates.nodeId} is not in search ${this.searchId}`);
+		if (coordinates.attempt < 1 || coordinates.attempt > cell.attempts) throw new SearchLedgerError(`cell ${coordinates.cellId} has ${cell.attempts} settled attempt(s), not attempt ${coordinates.attempt}`);
+		const node = state.readNode(cell.nodeId);
+		if (node.depth === null) throw new SearchLedgerError(`node ${node.nodeId} has unknown lineage, so its depth is unknown`);
+		const containment = this.header?.containment ?? null;
+		return {
+			depth: node.depth,
+			ordinal: node.ordinal,
+			rep: cell.rep,
+			containingRunId: containment ? searchCellRunId({
+				cellId: containment.cellId,
+				attempt: containment.attempt
+			}) : null
+		};
+	}
+	live() {
+		if (!this.state.isAt(this.version)) throw new SearchLedgerError(`this SearchStateView is from sequence ${this.head?.sequence ?? -1}, and the ledger has moved on; read the ledger's state again`);
+		return this.state;
+	}
+};
+function nodeView(record) {
+	const latest = record.decisions.at(-1)?.decision ?? null;
+	return {
+		nodeId: record.event.nodeId,
+		ordinal: record.ordinal,
+		artifactDigest: record.event.artifactDigest,
+		artifact: record.event.artifact,
+		surfaces: record.event.surfaces,
+		primaryParentId: record.primaryParentId,
+		depth: record.depth,
+		parents: [...record.parents],
+		children: [...record.children],
+		edgeIds: [...record.edgeIds],
+		status: latest?.status ?? null,
+		rung: latest?.status === "advanced" ? latest.rung : null,
+		finalist: record.finalist,
+		decisions: [...record.decisions],
+		cellCount: record.cellIds.length,
+		spend: { ...record.spend },
+		registeredSequence: record.registeredSequence,
+		updatedSequence: record.updatedSequence
+	};
+}
+function assertStageSplit(cellId, stage, split, isRoot) {
+	if (!{
+		root: ["train", "selection"],
+		train: ["train"],
+		screen: ["selection"],
+		rung: ["selection"],
+		claim: ["test"],
+		external: ["train", "selection"]
+	}[stage].includes(split)) throw integrity(`cell ${cellId}: a ${stage} cell cannot run on the ${split} split`);
+	if (stage === "root" && !isRoot) throw integrity(`cell ${cellId}: only the root node runs root cells`);
+}
+function assertUnique(values, label, eventId) {
+	if (new Set(values).size !== values.length) throw integrity(`event ${eventId} contains duplicate ${label} values`);
+}
+function count(value, noun, predicate) {
+	const verb = predicate.replace(/^(has|is) /, (word) => value === 1 ? word : word === "has " ? "have " : "are ");
+	return `${value} ${value === 1 ? noun : `${noun}s`} ${verb}`;
+}
+function round(usd) {
+	return Math.round(usd * 1e6) / 1e6;
+}
+function integrity(message) {
+	return new SearchLedgerIntegrityError(message);
+}
+//#endregion
+//#region src/campaign/search-ledger-types.ts
+/**
+* Schema tag every search-ledger entry carries. A ledger written under another
+* tag, such as the retired `tangle.search-ledger.v1` candidate-slot format, is
+* refused with its tag named; it is never translated.
+*/
+const SEARCH_LEDGER_SCHEMA = "tangle.search-ledger.2026-09";
+//#endregion
+//#region src/campaign/search-ledger.ts
+/**
+* Durable, append-only event log of one search: nodes (content-addressed
+* artifacts), edges (the proposals that derived them), cells (one run of one
+* node on one task), operations, decisions, and the claim.
+*
+* The ledger is the search's only lineage record and its only resume
+* checkpoint. A RunRecord owns one measured run and `CostLedger` owns per-call
+* accounting; this ledger binds them by digest instead of copying them.
+*
+* The file format is canonical JSONL with a SHA-256 hash chain. Every append is
+* serialized across processes, fsynced before acknowledgement, and idempotent
+* by `eventId`. A malformed, non-canonical, truncated, reordered, or conflicting
+* log fails loudly; a bad row is never skipped. A ledger written under another
+* schema tag is refused with that tag named, never translated.
+*
+* The journal machinery is the generic `ledger-core` journal. This module is
+* the search codec: event schemas and canonical ordering. `SearchState` is the
+* state machine and read model.
+*/
+const NON_EMPTY = z.string().min(1).refine((value) => value.trim() === value, "must not contain surrounding whitespace");
+const HASH = z.string().regex(/^sha256:[a-f0-9]{64}$/);
+const IMMUTABLE_REVISION = z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64}|sha256:[a-f0-9]{64}|sha512:[A-Za-z0-9+/=]+)$/);
+const ISO_TIMESTAMP = z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/).refine((value) => Number.isFinite(Date.parse(value)), "invalid timestamp");
+const NON_NEGATIVE_INT = z.number().int().nonnegative().safe();
+const POSITIVE_INT = z.number().int().positive().safe();
+const FINITE_NUMBER = z.number().finite();
+const USD = z.number().finite().nonnegative();
+const NODE_ID = z.string().regex(/^node_[a-f0-9]{32}$/);
+const CELL_ID = z.string().regex(/^cell_[a-f0-9]{32}$/);
+const ArtifactRefSchema = z.object({
+	role: NON_EMPTY,
+	uri: NON_EMPTY,
+	sha256: HASH,
+	byteLength: NON_NEGATIVE_INT
+}).strict();
+const SourceRefSchema = z.object({
+	uri: NON_EMPTY,
+	revision: IMMUTABLE_REVISION
+}).strict();
+const UnknownRefSchema = z.object({ unknown: NON_EMPTY }).strict();
+const FailureReasonSchema = z.object({
+	code: NON_EMPTY,
+	message: NON_EMPTY
+}).strict();
+const ModelIdentitySchema = z.union([z.object({
+	provider: NON_EMPTY,
+	snapshot: NON_EMPTY.refine(modelHasSnapshot, "model must include an immutable snapshot")
+}).strict(), z.object({
+	provider: NON_EMPTY,
+	alias: NON_EMPTY,
+	unknown: NON_EMPTY
+}).strict()]);
+const ExecutionIdentitySchema = z.object({
+	model: ModelIdentitySchema,
+	agent: SourceRefSchema,
+	benchmark: SourceRefSchema
+}).strict();
+const SURFACE_KINDS = [
+	"prompt",
+	"tool-contract",
+	"runtime-config",
+	"memory",
+	"knowledge",
+	"agent-profile",
+	"code",
+	"deployment"
+];
+const SPLIT = z.enum([
+	"train",
+	"selection",
+	"test"
+]);
+const ReservationSchema = z.object({
+	kind: z.enum(["hard", "estimate"]),
+	usd: USD
+}).strict();
+const EventBaseShape = {
+	eventId: NON_EMPTY,
+	occurredAt: ISO_TIMESTAMP,
+	artifacts: z.array(ArtifactRefSchema)
+};
+const OperationKindSchema = z.enum([
+	"candidate-generation",
+	"analysis",
+	"selection",
+	"judge",
+	"other"
+]);
+const KnownTokensSchema = z.object({
+	status: z.literal("known"),
+	inputTokens: NON_NEGATIVE_INT,
+	outputTokens: NON_NEGATIVE_INT,
+	cachedTokens: NON_NEGATIVE_INT
+}).strict();
+const UnknownTokensSchema = z.object({
+	status: z.literal("unknown"),
+	reason: NON_EMPTY
+}).strict();
+const KnownCostSchema = z.object({
+	status: z.literal("known"),
+	usd: USD,
+	source: z.enum([
+		"provider",
+		"pricing-table",
+		"free"
+	])
+}).strict().superRefine((cost, ctx) => {
+	if (cost.source === "free" && cost.usd !== 0) ctx.addIssue({
+		code: "custom",
+		message: "free cost source must have usd 0"
+	});
+});
+const UnknownCostSchema = z.object({
+	status: z.literal("unknown"),
+	knownLowerBoundUsd: USD,
+	reason: NON_EMPTY
+}).strict();
+const AccountingSchema = z.object({
+	tokens: z.discriminatedUnion("status", [KnownTokensSchema, UnknownTokensSchema]),
+	cost: z.discriminatedUnion("status", [KnownCostSchema, UnknownCostSchema])
+}).strict();
+const MetricsSchema = z.record(NON_EMPTY, FINITE_NUMBER).superRefine((metrics, ctx) => {
+	for (const key of Object.keys(metrics)) if (key === "__proto__" || key === "constructor" || key === "prototype") ctx.addIssue({
+		code: "custom",
+		message: `unsafe metric key ${key}`
+	});
+});
+const OutcomeSchema = z.discriminatedUnion("status", [
+	z.object({
+		status: z.literal("passed"),
+		score: FINITE_NUMBER,
+		metrics: MetricsSchema
+	}).strict(),
+	z.object({
+		status: z.literal("failed"),
+		score: FINITE_NUMBER,
+		metrics: MetricsSchema,
+		failure: FailureReasonSchema
+	}).strict(),
+	z.object({
+		status: z.literal("errored"),
+		metrics: MetricsSchema,
+		error: FailureReasonSchema.extend({ retryable: z.boolean() }).strict()
+	}).strict()
+]);
+const EffectSchema = z.discriminatedUnion("status", [z.object({
+	status: z.literal("measured"),
+	metric: NON_EMPTY,
+	baselineValue: FINITE_NUMBER,
+	candidateValue: FINITE_NUMBER,
+	delta: FINITE_NUMBER
+}).strict().superRefine((effect, ctx) => {
+	const expected = effect.candidateValue - effect.baselineValue;
+	const tolerance = Number.EPSILON * Math.max(1, Math.abs(expected), Math.abs(effect.delta)) * 8;
+	if (Math.abs(effect.delta - expected) > tolerance) ctx.addIssue({
+		code: "custom",
+		message: "delta must equal candidateValue - baselineValue"
+	});
+}), z.object({
+	status: z.literal("not-measured"),
+	reason: NON_EMPTY
+}).strict()]);
+const SurfaceEvidenceSchema = z.object({
+	surfaceId: NON_EMPTY,
+	fired: z.boolean(),
+	firingCount: NON_NEGATIVE_INT,
+	effect: EffectSchema,
+	evidence: z.array(ArtifactRefSchema).min(1)
+}).strict().superRefine((evidence, ctx) => {
+	if (evidence.fired !== evidence.firingCount > 0) ctx.addIssue({
+		code: "custom",
+		message: "fired must equal firingCount > 0"
+	});
+	if (!evidence.fired && evidence.effect.status === "measured" && evidence.effect.delta !== 0) ctx.addIssue({
+		code: "custom",
+		message: "a surface that did not fire has no effect"
+	});
+});
+const TaskSchema = z.object({
+	taskId: NON_EMPTY,
+	unitId: NON_EMPTY,
+	source: SourceRefSchema
+}).strict();
+const SplitTasksSchema = z.object({
+	taskSetDigest: HASH,
+	tasks: z.array(TaskSchema)
+}).strict();
+const SearchOpenedSchema = z.object({
+	...EventBaseShape,
+	kind: z.literal("search-opened"),
+	subject: NON_EMPTY,
+	process: z.object({
+		name: NON_EMPTY,
+		executionRef: SourceRefSchema
+	}).strict(),
+	artifactKind: z.enum([...SURFACE_KINDS, "output"]),
+	objective: z.object({
+		metric: NON_EMPTY,
+		direction: z.enum(["maximize", "minimize"]),
+		judge: z.union([SourceRefSchema, UnknownRefSchema]),
+		claim: evaluationClaimSchema
+	}).strict(),
+	splits: z.object({
+		train: SplitTasksSchema,
+		selection: SplitTasksSchema,
+		test: SplitTasksSchema,
+		heldOutUnits: z.boolean()
+	}).strict(),
+	policy: z.object({
+		expansion: NON_EMPTY,
+		allocation: NON_EMPTY,
+		seed: z.number().int().safe()
+	}).strict(),
+	budget: z.object({
+		maxUsd: USD.nullable(),
+		maxCells: POSITIVE_INT.nullable(),
+		maxNodes: POSITIVE_INT.nullable(),
+		deadline: ISO_TIMESTAMP.nullable(),
+		maxConcurrency: POSITIVE_INT.nullable(),
+		reservedClaimUsd: USD
+	}).strict(),
+	containment: z.object({
+		searchId: NON_EMPTY,
+		cellId: CELL_ID,
+		attempt: POSITIVE_INT
+	}).strict().nullable(),
+	derivedFrom: z.object({
+		searchId: NON_EMPTY,
+		nodeId: NODE_ID,
+		headHash: HASH
+	}).strict().nullable(),
+	identity: ExecutionIdentitySchema
+}).strict();
+const OperationStartedSchema = z.object({
+	...EventBaseShape,
+	kind: z.literal("operation-started"),
+	operationId: NON_EMPTY,
+	operationKind: OperationKindSchema,
+	reservation: ReservationSchema.nullable()
+}).strict();
+const OperationRecordedSchema = z.object({
+	...EventBaseShape,
+	kind: z.literal("operation-recorded"),
+	operationId: NON_EMPTY,
+	operationKind: OperationKindSchema,
+	execution: z.discriminatedUnion("kind", [z.object({
+		kind: z.literal("model"),
+		model: ModelIdentitySchema,
+		source: SourceRefSchema
+	}).strict(), z.object({
+		kind: z.literal("deterministic"),
+		source: SourceRefSchema
+	}).strict()]),
+	outcome: z.discriminatedUnion("status", [
+		z.object({ status: z.literal("completed") }).strict(),
+		z.object({
+			status: z.literal("partial"),
+			failure: FailureReasonSchema
+		}).strict(),
+		z.object({
+			status: z.literal("failed"),
+			failure: FailureReasonSchema
+		}).strict()
+	]),
+	accounting: AccountingSchema
+}).strict();
+const NodeRegisteredSchema = z.object({
+	...EventBaseShape,
+	kind: z.literal("node-registered"),
+	nodeId: NODE_ID,
+	artifactDigest: HASH,
+	artifact: ArtifactRefSchema,
+	surfaces: z.array(z.object({
+		surfaceId: NON_EMPTY,
+		kind: z.enum(SURFACE_KINDS),
+		artifact: ArtifactRefSchema
+	}).strict())
+}).strict();
+const NodeRefSchema = z.object({
+	searchId: NON_EMPTY,
+	nodeId: NODE_ID
+}).strict();
+const ArtifactOrUnknownSchema = z.union([ArtifactRefSchema, UnknownRefSchema]);
+const EdgeRecordedSchema = z.object({
+	...EventBaseShape,
+	kind: z.literal("edge-recorded"),
+	edgeId: z.string().regex(/^edge_[a-f0-9]{32}$/),
+	childNodeId: NODE_ID,
+	parents: z.array(NodeRefSchema),
+	operator: z.enum([
+		"seed",
+		"draft",
+		"improve",
+		"debug",
+		"merge",
+		"derive"
+	]),
+	attribution: z.enum([
+		"explicit",
+		"correlated",
+		"unknown"
+	]),
+	proposer: z.object({
+		kind: z.enum([
+			"trace",
+			"frontier-author",
+			"human",
+			"optimizer",
+			"compound"
+		]),
+		name: NON_EMPTY,
+		operationId: NON_EMPTY.nullable(),
+		source: SourceRefSchema
+	}).strict().nullable(),
+	selection: z.object({
+		rule: NON_EMPTY,
+		evidence: z.record(NON_EMPTY, FINITE_NUMBER)
+	}).strict().nullable(),
+	rationale: ArtifactOrUnknownSchema,
+	diffs: z.array(ArtifactOrUnknownSchema),
+	label: z.string()
+}).strict();
+const CellAllocatedSchema = z.object({
+	...EventBaseShape,
+	kind: z.literal("cell-allocated"),
+	cellId: CELL_ID,
+	nodeId: NODE_ID,
+	taskId: NON_EMPTY,
+	unitId: NON_EMPTY,
+	split: SPLIT,
+	rep: NON_NEGATIVE_INT,
+	stage: z.enum([
+		"root",
+		"train",
+		"screen",
+		"rung",
+		"claim",
+		"external"
+	]),
+	lane: NON_EMPTY.nullable(),
+	reservation: ReservationSchema.nullable()
+}).strict();
+const TraceRefSchema = z.union([z.object({
+	traceId: NON_EMPTY,
+	execRunId: NON_EMPTY.nullable(),
+	spansWritten: NON_NEGATIVE_INT.nullable(),
+	spansDropped: NON_NEGATIVE_INT.nullable()
+}).strict(), UnknownRefSchema]);
+const NON_NEGATIVE = z.number().finite().nonnegative();
+const CellSettledSchema = z.object({
+	...EventBaseShape,
+	kind: z.literal("cell-settled"),
+	cellId: CELL_ID,
+	attempt: POSITIVE_INT,
+	runId: NON_EMPTY,
+	outcome: OutcomeSchema,
+	accounting: AccountingSchema,
+	boxMinutes: NON_NEGATIVE.nullable(),
+	wallMs: NON_NEGATIVE.nullable(),
+	queueMs: NON_NEGATIVE.nullable(),
+	placement: z.object({
+		lane: NON_EMPTY,
+		boxId: NON_EMPTY.nullable()
+	}).strict().nullable(),
+	identity: ExecutionIdentitySchema,
+	surfaceEvidence: z.array(SurfaceEvidenceSchema),
+	traceRef: TraceRefSchema
+}).strict();
+const CellCancelledSchema = z.object({
+	...EventBaseShape,
+	kind: z.literal("cell-cancelled"),
+	cellId: CELL_ID,
+	reason: z.enum([
+		"pruned",
+		"budget",
+		"deadline",
+		"aborted"
+	])
+}).strict();
+const NodeEstimateSchema = z.object({
+	against: NODE_ID,
+	split: SPLIT,
+	units: NON_NEGATIVE_INT,
+	pairs: NON_NEGATIVE_INT,
+	delta: FINITE_NUMBER.nullable(),
+	interval: z.tuple([FINITE_NUMBER, FINITE_NUMBER]).nullable(),
+	method: z.enum([
+		"none",
+		"insufficient",
+		"descriptive",
+		"bootstrap"
+	]),
+	exactSignP: z.number().min(0).max(1).nullable(),
+	indeterminate: z.boolean(),
+	cellSetDigest: HASH,
+	estimator: SourceRefSchema
+}).strict();
+const NodeDecidedSchema = z.object({
+	...EventBaseShape,
+	kind: z.literal("node-decided"),
+	nodeId: NODE_ID,
+	decision: z.discriminatedUnion("status", [
+		z.object({
+			status: z.literal("advanced"),
+			rung: NON_NEGATIVE_INT
+		}).strict(),
+		z.object({ status: z.literal("pruned") }).strict(),
+		z.object({ status: z.literal("invalid") }).strict(),
+		z.object({ status: z.literal("finalist") }).strict(),
+		z.object({ status: z.literal("selected") }).strict(),
+		z.object({ status: z.literal("rejected") }).strict()
+	]),
+	basis: NodeEstimateSchema.nullable(),
+	rule: NON_EMPTY,
+	reason: NON_EMPTY
+}).strict();
+const SearchClosedSchema = z.object({
+	...EventBaseShape,
+	kind: z.literal("search-closed"),
+	reason: z.enum([
+		"budget",
+		"deadline",
+		"max-nodes",
+		"patience",
+		"converged",
+		"aborted"
+	]),
+	claim: z.object({
+		power: z.union([z.object({
+			adequate: z.boolean(),
+			minimumEffect: z.number().finite().positive(),
+			powerAtMinimumEffect: z.number().min(0).max(1),
+			units: NON_NEGATIVE_INT
+		}).strict(), UnknownRefSchema]),
+		finalists: z.array(z.object({
+			nodeId: NODE_ID,
+			estimate: NodeEstimateSchema.nullable(),
+			promote: z.boolean()
+		}).strict()),
+		selected: NODE_ID.nullable(),
+		decision: z.enum([
+			"ship",
+			"hold",
+			"test-cannot-resolve"
+		])
+	}).strict().nullable()
+}).strict();
+const EventSchema = z.discriminatedUnion("kind", [
+	SearchOpenedSchema,
+	OperationStartedSchema,
+	OperationRecordedSchema,
+	NodeRegisteredSchema,
+	EdgeRecordedSchema,
+	CellAllocatedSchema,
+	CellSettledSchema,
+	CellCancelledSchema,
+	NodeDecidedSchema,
+	SearchClosedSchema
+]);
+const EntrySchema = z.object({
+	schema: z.literal(SEARCH_LEDGER_SCHEMA),
+	searchId: NON_EMPTY,
+	sequence: NON_NEGATIVE_INT,
+	previousHash: z.union([HASH, z.null()]),
+	event: EventSchema,
+	entryHash: HASH
+}).strict();
+/** Validate and return a canonical copy. Arrays whose order carries no meaning
+* are sorted, so retries from different processes produce identical bytes. */
+function validateSearchLedgerEvent(input) {
+	const parsed = EventSchema.safeParse(input);
+	if (!parsed.success) throw new SearchLedgerError(`invalid search ledger event: ${formatZodError(parsed.error)}`);
+	return normalizeEvent(parsed.data);
+}
+/** Open a durable filesystem search ledger. Construction performs no I/O; the
+* first `append` or `state` verifies the whole existing file. */
+function openSearchLedger(options) {
+	if (options.store) return new MemorySearchLedger(options.path, options.searchId, options.store);
+	return new FileSearchLedger(options.path, options.searchId, options.trustedHead);
+}
+/** Verify and project immutable search-ledger JSONL through the same codec as
+* `FileSearchLedger`. */
+function replaySearchLedgerText(text, searchId, source) {
+	return replayLedgerText(text, source, searchLedgerCodec(searchId));
+}
+/**
+* Verify one stored ledger line in isolation: the schema tag, the entry and
+* event schemas, canonical bytes, the entry's own hash, and its search. The
+* chain (sequence and previous hash) and the state machine are the caller's,
+* because they need the lines before this one. An ingest server runs this on
+* every received line, so it hashes exactly the bytes the producer hashed.
+*/
+function parseSearchLedgerLine(line, searchId, context) {
+	let raw;
+	try {
+		raw = JSON.parse(line);
+	} catch (error) {
+		throw new SearchLedgerIntegrityError(`search ledger ${context.path} has invalid JSON at line ${context.line}`, { cause: error });
+	}
+	const entry = parseSearchLedgerEntry(raw, context);
+	if (entry.searchId !== searchId) throw new SearchLedgerIntegrityError(`search ledger ${context.path} line ${context.line} belongs to search ${entry.searchId}, expected ${searchId}`);
+	if (canonicalString(entry) !== line) throw new SearchLedgerIntegrityError(`search ledger ${context.path} has non-canonical bytes at line ${context.line}`);
+	const { entryHash, ...material } = entry;
+	const expected = hashCanonical(material);
+	if (entryHash !== expected) throw new SearchLedgerIntegrityError(`search ledger ${context.path} line ${context.line} hash mismatch: expected ${expected}, got ${entryHash}`);
+	return entry;
+}
+function searchLedgerCodec(searchId) {
+	return {
+		...SEARCH_LEDGER_FILE_CONTEXT,
+		header: {
+			schema: SEARCH_LEDGER_SCHEMA,
+			searchId
+		},
+		conflictError: (message) => new SearchLedgerConflictError(message),
+		parseEntry: parseSearchLedgerEntry,
+		checkEntryHeader: (entry, index) => {
+			if (entry.searchId !== searchId) throw new SearchLedgerIntegrityError(`entry ${index} belongs to search ${entry.searchId}, expected ${searchId}`);
+		},
+		createProjector: () => new SearchState(searchId)
+	};
+}
+/** Append-only file-backed search ledger with idempotent writes. */
+var FileSearchLedger = class {
+	path;
+	searchId;
+	trustedHeadPath;
+	trustedHeadMode;
+	journal;
+	constructor(path, searchId, trustedHead = "pin") {
+		if (path.trim().length === 0) throw new SearchLedgerError("ledger path is empty");
+		if (searchId.length === 0 || searchId.trim() !== searchId) throw new SearchLedgerError("searchId must be non-empty without surrounding whitespace");
+		this.searchId = searchId;
+		this.trustedHeadMode = trustedHead;
+		this.journal = new FileLedgerJournal(path, searchLedgerCodec(searchId), { requireTrustedHead: trustedHead === "require" });
+		this.path = this.journal.path;
+		this.trustedHeadPath = this.journal.trustedHeadPath;
+	}
+	async state() {
+		return this.journal.replay();
+	}
+	async append(input) {
+		const event = validateSearchLedgerEvent(input);
+		const { entry, appended, projection } = await this.journal.append(event, { pinHead: this.trustedHeadMode !== "off" });
+		return {
+			entry,
+			appended,
+			state: projection
+		};
+	}
+	async trustedHead() {
+		return this.journal.trustedHead();
+	}
+	async pinTrustedHead() {
+		return this.journal.pinTrustedHead();
+	}
+	async clearTrustedHead() {
+		return this.journal.clearTrustedHead();
+	}
+};
+/** A search ledger held in an in-process text store. */
+var MemorySearchLedger = class {
+	path;
+	searchId;
+	trustedHeadPath;
+	journal;
+	constructor(path, searchId, store) {
+		if (path.trim().length === 0) throw new SearchLedgerError("ledger path is empty");
+		if (searchId.length === 0 || searchId.trim() !== searchId) throw new SearchLedgerError("searchId must be non-empty without surrounding whitespace");
+		this.path = path;
+		this.searchId = searchId;
+		this.trustedHeadPath = `${path}.head`;
+		this.journal = new MemoryLedgerJournal(path, searchLedgerCodec(searchId), store);
+	}
+	async state() {
+		return this.journal.replay();
+	}
+	async append(input) {
+		const { entry, appended, projection } = await this.journal.append(validateSearchLedgerEvent(input));
+		return {
+			entry,
+			appended,
+			state: projection
+		};
+	}
+	async trustedHead() {
+		return null;
+	}
+	async pinTrustedHead() {
+		throw new SearchLedgerError(`search ledger ${this.path} is held in memory; a trusted head protects only a file`);
+	}
+	async clearTrustedHead() {
+		return { removed: false };
+	}
+};
+function parseSearchLedgerEntry(raw, context) {
+	const schema = raw?.schema;
+	if (schema !== "tangle.search-ledger.2026-09") throw new SearchLedgerIntegrityError(`search ledger ${context.path} line ${context.line} was written under schema ${JSON.stringify(schema)}; this version reads only ${SEARCH_LEDGER_SCHEMA} and does not translate other formats`);
+	const parsed = EntrySchema.safeParse(raw);
+	if (!parsed.success) throw new SearchLedgerIntegrityError(`search ledger ${context.path} has a malformed entry at line ${context.line}: ${formatZodError(parsed.error)}`);
+	const entry = parsed.data;
+	if (canonicalString(validateSearchLedgerEvent(entry.event)) !== canonicalString(entry.event)) throw new SearchLedgerIntegrityError(`search ledger ${context.path} has non-canonical event ordering at line ${context.line}`);
+	return entry;
+}
+function normalizeEvent(event) {
+	const artifacts = sortArtifacts(event.artifacts);
+	switch (event.kind) {
+		case "search-opened": return {
+			...event,
+			artifacts,
+			splits: {
+				...event.splits,
+				train: {
+					...event.splits.train,
+					tasks: sortTasks(event.splits.train.tasks)
+				},
+				selection: {
+					...event.splits.selection,
+					tasks: sortTasks(event.splits.selection.tasks)
+				},
+				test: {
+					...event.splits.test,
+					tasks: sortTasks(event.splits.test.tasks)
+				}
+			}
+		};
+		case "node-registered": return {
+			...event,
+			artifacts,
+			surfaces: [...event.surfaces].sort((a, b) => compareStrings(a.surfaceId, b.surfaceId))
+		};
+		case "cell-settled": return {
+			...event,
+			artifacts,
+			surfaceEvidence: [...event.surfaceEvidence].map((evidence) => ({
+				...evidence,
+				evidence: sortArtifacts(evidence.evidence)
+			})).sort((a, b) => compareStrings(a.surfaceId, b.surfaceId))
+		};
+		default: return {
+			...event,
+			artifacts
+		};
+	}
+}
+function sortTasks(tasks) {
+	return [...tasks].sort((a, b) => compareStrings(a.taskId, b.taskId));
+}
+function sortArtifacts(artifacts) {
+	return [...artifacts].sort((a, b) => compareStrings(artifactKey(a), artifactKey(b)));
+}
+function formatZodError(error) {
+	return error.issues.map((issue) => `${issue.path.length > 0 ? issue.path.join(".") : "<root>"}: ${issue.message}`).join("; ");
+}
+//#endregion
+export { validateSearchLedgerEvent as a, SearchStateView as c, searchTaskSetDigest as d, searchUnitScores as f, replaySearchLedgerText as i, searchCellId as l, openSearchLedger as n, SEARCH_LEDGER_SCHEMA as o, parseSearchLedgerLine as r, SearchState as s, FileSearchLedger as t, searchNodeId as u };
+
+//# sourceMappingURL=search-ledger-Ck7tok0h.js.map