@tangle-network/agent-eval 0.150.2 → 0.161.1

package/dist/{llm-judge-BqqMS8t7.js → llm-judge-BhasIPFT.js}

@@ -1,17 +1,18 @@
 import { i as JudgeError, s as ValidationError, t as AgentEvalError } from "./errors-Dngq5h35.js";
+import { i as hashCanonical, r as canonicalString } from "./canonical-IL-Bu-14.js";
 import { s as weightedComposite, t as confidenceInterval } from "./descriptive-jDOuI6mz.js";
 import { r as pairedBootstrap } from "./paired-tests-BHIhYVdu.js";
-import { n as contentHash, t as canonicalJson } from "./verdict-cache-mZf5FEiY.js";
-import { a as campaignCellCostProvenance, o as campaignCellExecutionEvidence, t as detectRewardHacking, u as projectCampaignCellQuality } from "./reward-hacking-C0x0xihA.js";
+import { i as modelHasSnapshot } from "./run-record-BC0ebuRP.js";
+import { n as contentHash } from "./verdict-cache-CdVVTVmn.js";
+import { a as campaignCellCostProvenance, o as campaignCellExecutionEvidence, t as detectRewardHacking, u as projectCampaignCellQuality } from "./reward-hacking-t4lB1yt8.js";
 import { i as CostLedger, t as CostAccountingIncompleteError } from "./cost-ledger-B1qx30B4.js";
-import { u as mapConcurrent } from "./ledger-core-DTae9rv_.js";
-import { i as hashCanonical } from "./canonical-D-XsTQ6_.js";
-import { b as createRunCostLedger, h as isRecord, m as isExternalTextCandidate, x as fsCampaignStorage } from "./external-optimizer-subprocess-CKNb42oM.js";
+import { u as mapConcurrent } from "./ledger-core-BOzlRygb.js";
+import { b as createRunCostLedger, h as isRecord, m as isExternalTextCandidate, x as fsCampaignStorage } from "./external-optimizer-subprocess-BIWbHpgD.js";
 import { t as DEFAULT_REDACTION_RULES } from "./redact-7Aq1ukl-.js";
 import { a as heldoutSignificance, i as dimensionRegressions, o as pairHoldout } from "./power-preflight-DEw-uC7q.js";
 import { a as combineAbortSignals, n as clamp01, r as assertProposalFindings } from "./run-score-lDzV0X8j.js";
 import { c as deepFreezeCanonicalJson } from "./types-BI4fT3HN.js";
-import { f as maximumChargeForLlmRequest, l as costReceiptFromLlm, m as stripFencedJson, u as costReceiptFromLlmError } from "./llm-client-Bg32RW0j.js";
+import { d as stripFencedJson, o as costReceiptFromLlm, s as costReceiptFromLlmError, u as maximumChargeForLlmRequest } from "./llm-client-hgDieDNN.js";
 import { createHash } from "node:crypto";
 import { writeFileSync } from "node:fs";
 import { z } from "zod";
@@ -795,12 +796,13 @@ async function executeCell(args) {
 		durationMs: Date.now() - startMs,
 		seed: args.slot.cellSeed,
 		cached: false,
+		...args.attempt > 1 ? { retryAttempts: args.attempt - 1 } : {},
 		...failure ? { errorStage: failure.stage } : {},
 		...failure?.judge ? { errorJudge: failure.judge } : {},
 		error: errorMessage
 	};
+	let retry = false;
 	if (failure) {
-		const failurePath = join(cellDir, "failure-receipt.json");
 		const receipt = {
 			schemaVersion: 1,
 			runAttemptId: args.runAttemptId,
@@ -816,9 +818,12 @@ async function executeCell(args) {
 				tags: costTags
 			})
 		};
+		retry = args.cellRetry !== void 0 && args.attempt < args.cellRetry.attempts && !args.signal.aborted && fatalCellError === void 0 && args.cellRetry.retryable(receipt.failure);
+		const receiptName = retry ? `failure-receipt.attempt-${args.attempt}.json` : "failure-receipt.json";
+		const failurePath = join(cellDir, receiptName);
 		storage.write(failurePath, JSON.stringify(receipt, null, 2));
-		artifactsByPath[`${args.slot.cellId}/failure-receipt.json`] = failurePath;
-		args.onFailure?.(failure);
+		artifactsByPath[`${args.slot.cellId}/${receiptName}`] = failurePath;
+		if (!retry) args.onFailure?.(failure);
 	}
 	await trace.flush();
 	if (!errorMessage && args.resumable) storage.write(cachePath, JSON.stringify(cell));
@@ -826,7 +831,8 @@ async function executeCell(args) {
 	return {
 		cell,
 		artifactsByPath,
-		...failure ? { failure } : {}
+		...failure ? { failure } : {},
+		...retry ? { retry } : {}
 	};
 }
 async function waitForFailedCellCostSettlement(input) {
@@ -1047,6 +1053,11 @@ async function runCampaign(opts) {
 	const dispatchShutdownTimeoutMs = opts.dispatchShutdownTimeoutMs ?? 5e3;
 	assertCampaignDesign(opts.scenarios, reps);
 	if (!Number.isSafeInteger(dispatchShutdownTimeoutMs) || dispatchShutdownTimeoutMs <= 0) throw new Error("runCampaign: dispatchShutdownTimeoutMs must be a positive safe integer");
+	const cellRetry = opts.cellRetry;
+	if (cellRetry !== void 0) {
+		if (!Number.isSafeInteger(cellRetry.attempts) || cellRetry.attempts < 1) throw new Error("runCampaign: cellRetry.attempts must be a positive safe integer (total attempts, including the first)");
+		if (typeof cellRetry.retryable !== "function") throw new Error("runCampaign: cellRetry.retryable must be a function");
+	}
 	if (typeof opts.runDir !== "string" || opts.runDir.trim().length === 0) throw new Error("runCampaign: runDir is required and must be a non-empty string");
 	opts.runDir = resolveRunDir(opts.runDir, opts.repo);
 	storage.ensureDir(opts.runDir);
@@ -1099,29 +1110,37 @@ async function runCampaign(opts) {
 				const myIdx = nextIdx++;
 				if (myIdx >= schedule.length) return;
 				const slot = schedule[myIdx];
-				const result = await executeCell({
-					slot,
-					opts,
-					manifestHash,
-					resumable,
-					now,
-					storage,
-					buildTraceWriter: opts.buildTraceWriter ?? defaultBuildTraceWriter(storage),
-					signal: campaignSignal,
-					dispatchTimeoutMs: opts.dispatchTimeoutMs,
-					dispatchShutdownTimeoutMs,
-					costLedger,
-					costPhase,
-					runAttemptId,
-					onFailure: opts.abortOnCellError ? (failure) => {
-						if (firstCellFailure === void 0) {
-							firstCellFailure = failure;
-							campaignAbort.abort(failure.cause);
-						}
-					} : void 0
-				});
+				let attempt = 1;
+				let result;
+				while (true) {
+					result = await executeCell({
+						slot,
+						opts,
+						manifestHash,
+						resumable,
+						now,
+						storage,
+						buildTraceWriter: opts.buildTraceWriter ?? defaultBuildTraceWriter(storage),
+						signal: campaignSignal,
+						dispatchTimeoutMs: opts.dispatchTimeoutMs,
+						dispatchShutdownTimeoutMs,
+						costLedger,
+						costPhase,
+						runAttemptId,
+						attempt,
+						cellRetry,
+						onFailure: opts.abortOnCellError ? (failure) => {
+							if (firstCellFailure === void 0) {
+								firstCellFailure = failure;
+								campaignAbort.abort(failure.cause);
+							}
+						} : void 0
+					});
+					Object.assign(artifactsByPath, result.artifactsByPath);
+					if (!result.retry) break;
+					attempt += 1;
+				}
 				cellsRef.push(result.cell);
-				Object.assign(artifactsByPath, result.artifactsByPath);
 				if (opts.labeledStore && opts.labeledStore !== "off" && !result.cell.error) await captureToStore({
 					store: opts.labeledStore,
 					cell: result.cell,
@@ -1641,11 +1660,12 @@ var Dataset = class Dataset {
 		this.scenarios.splice(idx, 1);
 	}
 	/**
-	* Stable JSON-Lines serialization — deterministic byte-for-byte.
-	* Write to disk for contamination-verifiable archives.
+	* Stable JSON-Lines serialization — one RFC 8785 canonical row per scenario,
+	* sorted by id, deterministic byte-for-byte. Write to disk for
+	* contamination-verifiable archives.
 	*/
 	toJsonl() {
-		return `${this.scenarios.slice().sort((a, b) => a.id.localeCompare(b.id)).map((s) => JSON.stringify(canonicalize(s))).join("\n")}\n`;
+		return `${this.scenarios.slice().sort((a, b) => a.id.localeCompare(b.id)).map((s) => canonicalString(s)).join("\n")}\n`;
 	}
 	static fromJsonl(jsonl, manifest) {
 		const scenarios = [];
@@ -1661,20 +1681,15 @@ var Dataset = class Dataset {
 		});
 	}
 };
+/**
+* Hex sha-256 over the RFC 8785 canonical JSON of the scenarios sorted by id,
+* so the digest is independent of insertion order. A scenario with no
+* canonical JSON form (an `undefined`-valued field, a non-finite number, a
+* class instance) is refused: the digest is the dataset's identity and a
+* coerced field would let two different datasets share one.
+*/
 async function hashScenarios(scenarios) {
-	const canonical = scenarios.slice().sort((a, b) => a.id.localeCompare(b.id)).map(canonicalize);
-	const text = JSON.stringify(canonical);
-	const bytes = new TextEncoder().encode(text);
-	const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
-	return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
-}
-function canonicalize(v) {
-	if (v === null || typeof v !== "object") return v;
-	if (Array.isArray(v)) return v.map(canonicalize);
-	const keys = Object.keys(v).sort();
-	const out = {};
-	for (const k of keys) out[k] = canonicalize(v[k]);
-	return out;
+	return hashCanonical(scenarios.slice().sort((a, b) => a.id.localeCompare(b.id))).slice(7);
 }
 /** Splitmix-ish deterministic shuffle — small, self-contained, no deps. */
 function seededShuffle(items, seed) {
@@ -2893,9 +2908,9 @@ function createSearchHistoryReceipt(input) {
 /** Verify the bounded receipt. Full ledger bytes are verified by SearchLedger. */
 function verifySearchHistoryReceipt(receipt) {
 	if (!receipt || typeof receipt !== "object") throw new TypeError("search history receipt is required");
-	if (receipt.schemaVersion !== "1.0.0") throw new Error(`unsupported search history schemaVersion '${receipt.schemaVersion}'`);
+	if (receipt.schemaVersion !== SEARCH_HISTORY_RECEIPT_SCHEMA_VERSION) throw new Error(`unsupported search history schemaVersion '${receipt.schemaVersion}'`);
 	if (receipt.kind !== "search-history-receipt") throw new Error(`search history kind must be 'search-history-receipt'`);
-	if (receipt.digestAlgorithm !== "rfc8785-sha256") throw new Error(`unsupported search history digestAlgorithm '${receipt.digestAlgorithm}'`);
+	if (receipt.digestAlgorithm !== SEARCH_HISTORY_RECEIPT_DIGEST_ALGORITHM) throw new Error(`unsupported search history digestAlgorithm '${receipt.digestAlgorithm}'`);
 	const producerId = nonEmpty(receipt.producerId, "search history producerId");
 	const runId = nonEmpty(receipt.runId, "search history runId");
 	const ledger = normalizeArtifactRef(receipt.ledger);
@@ -3833,6 +3848,845 @@ function paretoFrontier(candidates, objectives) {
 		}))
 	};
 }
+/**
+* NSGA-II crowding distance — secondary sort for ties on the frontier.
+*
+* When the Pareto front collapses to a single point (or many candidates tie
+* on dominance), naive selection picks arbitrarily and the population
+* degenerates over generations. NSGA-II preserves diversity by preferring
+* candidates with more empty space around them on the frontier.
+*
+* Returns an array of `{ candidate, distance }` in the SAME order as the
+* input. Higher distance = more isolated = should be preferred when
+* preserving diversity.
+*/
+function crowdingDistance(candidates, objectives) {
+	const distances = new Map(candidates.map((c) => [c, 0]));
+	for (const obj of objectives) {
+		const sorted = [...candidates].sort((a, b) => obj.value(a) - obj.value(b));
+		const min = obj.value(sorted[0]);
+		const range = obj.value(sorted[sorted.length - 1]) - min || 1;
+		distances.set(sorted[0], Infinity);
+		distances.set(sorted[sorted.length - 1], Infinity);
+		for (let i = 1; i < sorted.length - 1; i++) {
+			const prev = obj.value(sorted[i - 1]);
+			const next = obj.value(sorted[i + 1]);
+			const current = distances.get(sorted[i]);
+			if (current === Infinity) continue;
+			distances.set(sorted[i], current + (next - prev) / range);
+		}
+	}
+	return candidates.map((c) => ({
+		candidate: c,
+		distance: distances.get(c) ?? 0
+	}));
+}
+/**
+* Pareto frontier with tie-break by crowding distance — the canonical
+* NSGA-II selection step. Returns the frontier sorted by descending crowding
+* distance so callers can `.slice(0, k)` to pick K diverse winners.
+*/
+function paretoFrontierWithCrowding(candidates, objectives) {
+	const { frontier } = paretoFrontier(candidates, objectives);
+	if (frontier.length === 0) return [];
+	return crowdingDistance(frontier, objectives).sort((a, b) => b.distance - a.distance);
+}
+//#endregion
+//#region src/campaign/search-ledger-recording.ts
+const SEARCH_LEDGER_DIR = "search-ledger";
+/**
+* Recorder for one `runOptimization` run: `open()`, then `recordGeneration()`
+* and `recordResults()` per generation, then `finish()`.
+*
+* Every event id is derived from the run, and an id already durable is not
+* appended again, so a resumed run continues one ledger instead of conflicting
+* with its own history.
+*/
+var SearchRecorder = class SearchRecorder {
+	opts;
+	tasks;
+	registered = /* @__PURE__ */ new Map();
+	order = [];
+	coverage = /* @__PURE__ */ new Map();
+	openSlots = /* @__PURE__ */ new Set();
+	durableEventIds = /* @__PURE__ */ new Set();
+	lastStampMs = 0;
+	proposalReceiptCount = 0;
+	constructor(opts) {
+		this.opts = opts;
+		this.tasks = plannedTasks(opts.scenarios, opts.reps, opts.runDir, opts.splitDigest);
+	}
+	/** Open the recorder and append the plan. An existing ledger for the same
+	*  run is re-read first, so a resumed run keeps one plan and one lineage. */
+	static async open(opts) {
+		const recorder = new SearchRecorder(opts);
+		await recorder.hydrate();
+		await recorder.plan();
+		return recorder;
+	}
+	/**
+	* Record one generation's candidate-generation call and the candidates it
+	* produced. A proposal larger than the planned population extends the plan
+	* with the extra slots; a proposal that fills fewer closes the rest.
+	*/
+	async recordGeneration(input) {
+		const { generation, candidates } = input;
+		const planned = this.opts.populationSize;
+		if (candidates.length > planned) {
+			const extra = [];
+			for (let index = planned; index < candidates.length; index++) {
+				const slot = {
+					slotId: slotId(generation, index),
+					generationOperationId: generationOperationId(generation)
+				};
+				extra.push(slot);
+				this.openSlots.add(slot.slotId);
+			}
+			await this.append({
+				kind: "search-plan-extended",
+				eventId: `search:plan-extended:gen-${generation}`,
+				occurredAt: this.stamp(),
+				artifacts: [this.proposalArtifact(generation, candidates)],
+				extension: {
+					candidateSlots: extra,
+					operations: []
+				}
+			});
+		}
+		await this.recordGenerationOperation(generation, candidates, planned - candidates.length);
+		const parent = this.registered.get(input.parentSurfaceHash);
+		for (const [index, candidate] of candidates.entries()) {
+			const candidateId = candidate.surfaceHash;
+			const slot = slotId(generation, index);
+			const surfaceArtifact = this.writeArtifact("candidate-surface", `candidate-${candidateId}.json`, {
+				surfaceHash: candidateId,
+				surface: candidate.surface,
+				label: candidate.label ?? ""
+			});
+			const ledgerGeneration = parent ? parent.generation + 1 : 0;
+			await this.append({
+				kind: "candidate-registered",
+				eventId: `candidate:${candidateId}`,
+				occurredAt: this.stamp(),
+				artifacts: [surfaceArtifact],
+				slotId: slot,
+				generationOperationId: generationOperationId(generation),
+				candidateId,
+				lineage: {
+					lineageNodeId: candidateId,
+					parentCandidateIds: parent ? [parent.candidateId] : [],
+					generation: ledgerGeneration,
+					proposer: this.opts.proposerLabel,
+					proposerSource: this.opts.binding.identity.proposer.source
+				},
+				surfaces: candidateSurfaces(candidate.surface, surfaceArtifact)
+			});
+			this.remember({
+				candidateId,
+				slotId: slot,
+				generation: ledgerGeneration
+			});
+		}
+		for (let index = candidates.length; index < planned; index++) await this.closeSlot(slotId(generation, index), generationOperationId(generation), {
+			code: "proposal-short",
+			message: `generation ${generation} proposed ${candidates.length} of ${planned} planned candidates`
+		});
+	}
+	/** Append one task attempt per designed cell of each candidate campaign. */
+	async recordResults(candidates) {
+		for (const candidate of candidates) {
+			const registered = this.registered.get(candidate.surfaceHash);
+			if (!registered) throw new Error(`search ledger: candidate ${candidate.surfaceHash} produced results without a registration`);
+			this.coverage.set(registered.candidateId, candidate.coverageComplete);
+			const evidence = this.writeArtifact("candidate-cells", `cells-${registered.candidateId}.json`, {
+				surfaceHash: candidate.surfaceHash,
+				runDir: candidate.runDir,
+				cells: candidate.cells.map((cell) => ({
+					cellId: cell.cellId,
+					scenarioId: cell.scenarioId,
+					rep: cell.rep,
+					judgeScores: cell.judgeScores,
+					costUsd: cell.costUsd,
+					costProvenance: cell.costProvenance,
+					tokenUsage: cell.tokenUsage,
+					...cell.error === void 0 ? {} : {
+						error: cell.error,
+						errorStage: cell.errorStage
+					}
+				}))
+			});
+			const surfaceIds = candidateSurfaces(candidate.surface, evidence).map((surface) => surface.surfaceId);
+			for (const cell of candidate.cells) {
+				const taskId = taskIdFor(cell.scenarioId, cell.rep);
+				const task = this.tasks.find((planned) => planned.taskId === taskId);
+				if (!task) throw new Error(`search ledger: cell ${cell.cellId} is outside the planned task set`);
+				await this.append({
+					kind: "task-attempted",
+					eventId: `attempt:${registered.candidateId}:${taskId}`,
+					occurredAt: this.stamp(),
+					artifacts: [evidence],
+					candidateId: registered.candidateId,
+					runId: `${registered.candidateId}:${cell.cellId}`,
+					attemptIndex: 0,
+					task: {
+						taskId,
+						source: task.source
+					},
+					identity: {
+						model: this.cellModel(cell),
+						agent: this.opts.binding.identity.agent,
+						benchmark: task.benchmark
+					},
+					outcome: cellOutcome(cell),
+					accounting: cellAccounting(cell),
+					surfaceEvidence: surfaceIds.map((surfaceId) => surfaceEvidenceFor(surfaceId, evidence))
+				});
+			}
+		}
+	}
+	/**
+	* Close the search: unreached generations, the selection operation, one
+	* decision per candidate, then the terminal event.
+	*
+	* The terminal event is appended only when canonical replay accounts for the
+	* whole planned denominator. An interrupted or partly unscored search stays
+	* `in-progress` and its receipt reports the exact gap, instead of claiming a
+	* closed search.
+	*/
+	async finish(input) {
+		const stopped = {
+			code: "generation-not-reached",
+			message: `the search stopped after ${input.generationsRun} generation(s)`
+		};
+		for (let generation = input.generationsRun; generation < this.opts.maxGenerations; generation++) {
+			await this.recordGenerationOperation(generation, [], this.opts.populationSize, stopped);
+			for (let index = 0; index < this.opts.populationSize; index++) await this.closeSlot(slotId(generation, index), generationOperationId(generation), stopped);
+		}
+		const decisions = this.writeArtifact("search-decisions", "decisions.json", {
+			winnerSurfaceHash: input.winnerSurfaceHash,
+			candidates: this.order.map((entry) => entry.candidateId)
+		});
+		await this.append({
+			kind: "search-operation-recorded",
+			eventId: "operation:selection",
+			occurredAt: this.stamp(),
+			artifacts: [decisions],
+			operationId: "selection",
+			operationKind: "selection",
+			execution: {
+				kind: "deterministic",
+				source: this.opts.binding.identity.search
+			},
+			outcome: { status: "completed" },
+			accounting: {
+				tokens: {
+					status: "known",
+					inputTokens: 0,
+					outputTokens: 0,
+					cachedTokens: 0
+				},
+				cost: {
+					status: "known",
+					usd: 0,
+					source: "free"
+				}
+			}
+		});
+		const winner = this.registered.get(input.winnerSurfaceHash);
+		for (const entry of this.order) await this.append({
+			kind: "candidate-decided",
+			eventId: `decision:${entry.candidateId}`,
+			occurredAt: this.stamp(),
+			artifacts: [decisions],
+			candidateId: entry.candidateId,
+			decision: winner?.candidateId === entry.candidateId ? { status: "selected" } : {
+				status: "rejected",
+				reason: this.coverage.get(entry.candidateId) === false ? {
+					code: "coverage-incomplete",
+					message: "the candidate missed a designed cell and could not be ranked"
+				} : {
+					code: "not-promoted",
+					message: "the candidate did not beat the incumbent"
+				}
+			}
+		});
+		const replay = await this.opts.binding.ledger.replay();
+		const { missingCandidateSlots, missingTaskOutcomes, missingOperations } = replay.audit.expected;
+		if (missingCandidateSlots.length === 0 && missingTaskOutcomes.length === 0 && missingOperations.length === 0 && replay.audit.decisions.pending === 0) await this.append({
+			kind: "search-completed",
+			eventId: "search:completed",
+			occurredAt: this.stamp(),
+			artifacts: [decisions],
+			result: winner ? {
+				status: "selected",
+				candidateId: winner.candidateId
+			} : {
+				status: "all-rejected",
+				reason: {
+					code: "no-promoted-candidate",
+					message: "no candidate beat the incumbent on the designed denominator"
+				}
+			}
+		});
+		return this.receipt(input.runId);
+	}
+	/** Bounded receipt over the exact ledger bytes this run produced. */
+	async receipt(runId) {
+		const { ledger } = this.opts.binding;
+		const replay = await ledger.replay();
+		const bytes = replay.entries.map((entry) => `${canonicalString(entry)}\n`).join("");
+		return createSearchHistoryReceipt({
+			producerId: this.opts.proposerLabel,
+			runId,
+			ledger: {
+				role: "search-ledger",
+				uri: `file://${ledger.path}`,
+				sha256: hashCanonical(bytes),
+				byteLength: new TextEncoder().encode(bytes).byteLength
+			},
+			replay
+		});
+	}
+	/** Read an existing ledger for this run so a resume continues it. */
+	async hydrate() {
+		const replay = await this.opts.binding.ledger.replay();
+		for (const entry of replay.entries) {
+			this.durableEventIds.add(entry.event.eventId);
+			const stamped = Date.parse(entry.event.occurredAt);
+			if (stamped > this.lastStampMs) this.lastStampMs = stamped;
+		}
+		for (const slot of replay.plan?.plan.candidateSlots ?? []) this.openSlots.add(slot.slotId);
+		for (const extension of replay.planExtensions) for (const slot of extension.extension.candidateSlots) this.openSlots.add(slot.slotId);
+		for (const closed of replay.closedCandidateSlots) this.openSlots.delete(closed.slotId);
+		for (const candidate of replay.candidates) {
+			this.remember({
+				candidateId: candidate.candidateId,
+				slotId: candidate.slotId,
+				generation: candidate.lineage.generation
+			});
+			this.openSlots.delete(candidate.slotId);
+		}
+	}
+	async plan() {
+		const candidateSlots = [];
+		const operations = [{
+			operationId: "selection",
+			kind: "selection"
+		}];
+		for (let generation = 0; generation < this.opts.maxGenerations; generation++) {
+			operations.push({
+				operationId: generationOperationId(generation),
+				kind: "candidate-generation"
+			});
+			for (let index = 0; index < this.opts.populationSize; index++) {
+				const slot = {
+					slotId: slotId(generation, index),
+					generationOperationId: generationOperationId(generation)
+				};
+				candidateSlots.push(slot);
+				if (!this.registeredSlot(slot.slotId)) this.openSlots.add(slot.slotId);
+			}
+		}
+		await this.append({
+			kind: "search-planned",
+			eventId: "search:plan",
+			occurredAt: this.stamp(),
+			artifacts: [this.writeArtifact("search-plan", "plan.json", {
+				runDir: this.opts.runDir,
+				splitDigest: this.opts.splitDigest,
+				maxGenerations: this.opts.maxGenerations,
+				populationSize: this.opts.populationSize,
+				tasks: this.tasks
+			})],
+			plan: {
+				candidateSlots,
+				tasks: this.tasks,
+				operations
+			}
+		});
+	}
+	registeredSlot(slot) {
+		return this.order.some((entry) => entry.slotId === slot);
+	}
+	remember(entry) {
+		if (this.registered.has(entry.candidateId)) return;
+		this.registered.set(entry.candidateId, entry);
+		this.order.push(entry);
+	}
+	async recordGenerationOperation(generation, candidates, unfilled, failure) {
+		const shortfall = {
+			code: "proposal-short",
+			message: `generation ${generation} left ${unfilled} planned candidate slot(s) unfilled`
+		};
+		const outcome = failure ? {
+			status: "failed",
+			failure
+		} : unfilled <= 0 ? { status: "completed" } : candidates.length === 0 ? {
+			status: "failed",
+			failure: shortfall
+		} : {
+			status: "partial",
+			failure: shortfall
+		};
+		await this.append({
+			kind: "search-operation-recorded",
+			eventId: `operation:${generationOperationId(generation)}`,
+			occurredAt: this.stamp(),
+			artifacts: [this.proposalArtifact(generation, candidates)],
+			operationId: generationOperationId(generation),
+			operationKind: "candidate-generation",
+			execution: this.opts.binding.identity.proposer,
+			outcome,
+			accounting: this.proposalAccounting()
+		});
+	}
+	async closeSlot(slot, generationOperation, reason) {
+		if (!this.openSlots.has(slot)) return;
+		this.openSlots.delete(slot);
+		await this.append({
+			kind: "candidate-slot-closed",
+			eventId: `slot-closed:${slot}`,
+			occurredAt: this.stamp(),
+			artifacts: [this.writeArtifact("closed-slot", `slot-${slot}.json`, {
+				slot,
+				reason
+			})],
+			slotId: slot,
+			generationOperationId: generationOperation,
+			reason
+		});
+	}
+	/** Spend booked to candidate generation since the previous generation. */
+	proposalAccounting() {
+		const receipts = this.opts.costLedger.list({ phase: "search.proposal" });
+		const fresh = receipts.slice(this.proposalReceiptCount);
+		this.proposalReceiptCount = receipts.length;
+		return receiptAccounting(fresh);
+	}
+	cellModel(cell) {
+		const resolved = cell.resolvedModel;
+		if (resolved === void 0) return this.opts.binding.identity.model;
+		if (!modelHasSnapshot(resolved)) throw new Error(`search ledger: cell ${cell.cellId} ran model '${resolved}', which carries no immutable snapshot; the ledger cannot record a moving alias as execution identity`);
+		return {
+			provider: this.opts.binding.identity.model.provider,
+			snapshot: resolved
+		};
+	}
+	proposalArtifact(generation, candidates) {
+		return this.writeArtifact("candidate-proposal", `proposal-gen-${generation}.json`, {
+			generation,
+			candidates: candidates.map((candidate) => ({
+				surfaceHash: candidate.surfaceHash,
+				label: candidate.label ?? ""
+			}))
+		});
+	}
+	/** Write one canonical evidence document and return its content address. */
+	writeArtifact(role, name, body) {
+		const directory = `${this.opts.runDir}/${SEARCH_LEDGER_DIR}`;
+		const path = `${directory}/${name}`;
+		const contents = canonicalString(body);
+		this.opts.storage.ensureDir(directory);
+		this.opts.storage.write(path, contents);
+		return {
+			role,
+			uri: `file://${path}`,
+			sha256: hashCanonical(contents),
+			byteLength: new TextEncoder().encode(contents).byteLength
+		};
+	}
+	async append(event) {
+		if (this.durableEventIds.has(event.eventId)) return;
+		await this.opts.binding.ledger.append(event);
+		this.durableEventIds.add(event.eventId);
+	}
+	/** Non-decreasing ISO stamps; the ledger refuses an event that moves back. */
+	stamp() {
+		const now = Date.now();
+		this.lastStampMs = now > this.lastStampMs ? now : this.lastStampMs + 1;
+		return new Date(this.lastStampMs).toISOString();
+	}
+};
+/** One task per designed (scenario, replicate) cell. */
+function plannedTasks(scenarios, reps, runDir, splitDigest) {
+	const tasks = [];
+	for (const scenario of scenarios) for (let rep = 0; rep < reps; rep++) tasks.push({
+		taskId: taskIdFor(scenario.id, rep),
+		source: {
+			uri: `scenario://${scenario.id}`,
+			revision: hashCanonical(scenario)
+		},
+		benchmark: {
+			uri: `campaign://${runDir}`,
+			revision: splitDigest
+		},
+		maxAttempts: 1
+	});
+	return tasks;
+}
+function taskIdFor(scenarioId, rep) {
+	return `${scenarioId}#rep-${rep}`;
+}
+function slotId(generation, index) {
+	return `gen-${generation}-slot-${index}`;
+}
+function generationOperationId(generation) {
+	return `candidate-generation:gen-${generation}`;
+}
+/** Declared surfaces of one candidate. A component surface declares one
+*  surface per named component, so per-component evidence stays addressable. */
+function candidateSurfaces(surface, artifact) {
+	if (typeof surface === "string") return [{
+		surfaceId: "prompt",
+		kind: "prompt",
+		artifact
+	}];
+	if (surface.kind === "code") return [{
+		surfaceId: "code",
+		kind: "code",
+		artifact
+	}];
+	return Object.keys(surface.components).sort().map((name) => ({
+		surfaceId: `component:${name}`,
+		kind: "prompt",
+		artifact
+	}));
+}
+/** The campaign measures a candidate surface as a whole, so per-surface
+*  attribution stays unmeasured instead of inventing a per-component delta. */
+function surfaceEvidenceFor(surfaceId, evidence) {
+	return {
+		surfaceId,
+		fired: true,
+		firingCount: 1,
+		effect: {
+			status: "not-measured",
+			reason: "the campaign measures the candidate surface as a whole, not per surface"
+		},
+		evidence: [evidence]
+	};
+}
+function cellOutcome(cell) {
+	const scores = Object.entries(cell.judgeScores).filter(([, score]) => score.failed !== true && Number.isFinite(score.composite));
+	if (cell.error !== void 0 || scores.length === 0) return {
+		status: "errored",
+		metrics: {},
+		error: {
+			code: cell.errorStage ?? "unscored",
+			message: cell.error ?? "the cell produced no complete judge score",
+			retryable: false
+		}
+	};
+	const composite = scores.reduce((sum, [, score]) => sum + score.composite, 0) / scores.length;
+	const metrics = { composite };
+	for (const [judge, score] of scores) metrics[`judge.${judge}`] = score.composite;
+	return {
+		status: "passed",
+		score: composite,
+		metrics
+	};
+}
+function cellAccounting(cell) {
+	const usage = cell.tokenUsage;
+	return {
+		tokens: usage.tokensKnown === false ? {
+			status: "unknown",
+			reason: "a paid call in this cell reported no token usage"
+		} : {
+			status: "known",
+			inputTokens: usage.input,
+			outputTokens: usage.output,
+			cachedTokens: 0
+		},
+		cost: cell.costProvenance.kind === "uncaptured" ? {
+			status: "unknown",
+			knownLowerBoundUsd: cell.costUsd,
+			reason: "the cell recorded spend without a provider receipt"
+		} : {
+			status: "known",
+			usd: cell.costUsd,
+			source: cell.costProvenance.kind === "observed" ? "provider" : "pricing-table"
+		}
+	};
+}
+function receiptAccounting(receipts) {
+	let inputTokens = 0;
+	let outputTokens = 0;
+	let cachedTokens = 0;
+	let usd = 0;
+	let tokensKnown = true;
+	let costKnown = true;
+	for (const receipt of receipts) {
+		if (receipt.usageUnknown === true) tokensKnown = false;
+		inputTokens += receipt.inputTokens;
+		outputTokens += receipt.outputTokens;
+		cachedTokens += receipt.cachedTokens ?? 0;
+		if (receipt.costUnknown) costKnown = false;
+		else usd += receipt.costUsd;
+	}
+	return {
+		tokens: tokensKnown ? {
+			status: "known",
+			inputTokens,
+			outputTokens,
+			cachedTokens
+		} : {
+			status: "unknown",
+			reason: "a candidate-generation call reported no token usage"
+		},
+		cost: costKnown ? {
+			status: "known",
+			usd,
+			source: usd === 0 ? "free" : "provider"
+		} : {
+			status: "unknown",
+			knownLowerBoundUsd: usd,
+			reason: "a candidate-generation call recorded no provider cost"
+		}
+	};
+}
+/**
+* Record an optimizer's own candidate graph into the same ledger.
+*
+* A complete optimization method searches inside its own process and reports
+* one artifact when it finishes: the candidate population, with each
+* candidate's parents and its score per selection scenario. This turns that
+* artifact into the canonical event stream, so a first-party method returns
+* the same `SearchHistoryReceipt` the in-process loop returns, and
+* `compareOptimizationMethods({ searchHistoryPolicy: 'require-complete' })`
+* accepts it.
+*
+* A candidate the optimizer left unscored on a planned scenario leaves the
+* planned denominator open, so the receipt reports the gap instead of closing
+* the search.
+*/
+async function recordCandidatePopulationSearch(input) {
+	const { population, ledger, identity } = input;
+	const stamps = monotonicStamps();
+	const writeArtifact = artifactWriter(input.storage, input.runDir);
+	const populationArtifact = {
+		role: "candidate-population",
+		uri: `file://${population.summary.path}`,
+		sha256: population.summary.sha256,
+		byteLength: population.summary.bytes
+	};
+	const tasks = input.scenarios.filter((scenario) => population.summary.scenarioIds.includes(scenario.id)).map((scenario) => ({
+		taskId: taskIdFor(scenario.id, 0),
+		source: {
+			uri: `scenario://${scenario.id}`,
+			revision: hashCanonical(scenario)
+		},
+		benchmark: {
+			uri: `optimizer://${input.producerId}`,
+			revision: population.summary.sha256
+		},
+		maxAttempts: 1
+	}));
+	if (tasks.length !== population.summary.scenarioIds.length) throw new Error(`search ledger: the candidate population scored ${population.summary.scenarioIds.length} scenarios, but ${tasks.length} were supplied`);
+	const generationOperation = "candidate-generation:population";
+	await ledger.append({
+		kind: "search-planned",
+		eventId: "search:plan",
+		occurredAt: stamps(),
+		artifacts: [populationArtifact],
+		plan: {
+			candidateSlots: population.candidates.map((candidate) => ({
+				slotId: `candidate-${candidate.index}`,
+				generationOperationId: generationOperation
+			})),
+			tasks,
+			operations: [{
+				operationId: generationOperation,
+				kind: "candidate-generation"
+			}, {
+				operationId: "selection",
+				kind: "selection"
+			}]
+		}
+	});
+	await ledger.append({
+		kind: "search-operation-recorded",
+		eventId: `operation:${generationOperation}`,
+		occurredAt: stamps(),
+		artifacts: [populationArtifact],
+		operationId: generationOperation,
+		operationKind: "candidate-generation",
+		execution: identity.proposer,
+		outcome: { status: "completed" },
+		accounting: input.generationAccounting
+	});
+	const candidateIds = /* @__PURE__ */ new Map();
+	const depths = /* @__PURE__ */ new Map();
+	for (const candidate of population.candidates) {
+		const parents = candidate.parentIndices.filter((index) => index !== null);
+		const candidateId = candidate.candidateHash;
+		candidateIds.set(candidate.index, candidateId);
+		const depth = parents.length === 0 ? 0 : Math.max(...parents.map((index) => depths.get(index) ?? 0)) + 1;
+		depths.set(candidate.index, depth);
+		const surfaceArtifact = writeArtifact("candidate-surface", `candidate-${candidate.index}.json`, {
+			index: candidate.index,
+			candidateDigest: candidate.candidateDigest,
+			candidate: candidate.candidate
+		});
+		await ledger.append({
+			kind: "candidate-registered",
+			eventId: `candidate:${candidate.index}`,
+			occurredAt: stamps(),
+			artifacts: [surfaceArtifact],
+			slotId: `candidate-${candidate.index}`,
+			generationOperationId: generationOperation,
+			candidateId,
+			lineage: {
+				lineageNodeId: candidateId.slice(0, 16),
+				parentCandidateIds: parents.map((index) => {
+					const parentId = candidateIds.get(index);
+					if (!parentId) throw new Error(`search ledger: candidate ${candidate.index} names parent ${index}, which precedes no registered candidate`);
+					return parentId;
+				}),
+				generation: depth,
+				proposer: input.producerId,
+				proposerSource: identity.proposer.source
+			},
+			surfaces: candidateSurfaces(externalSurface(candidate.candidate), surfaceArtifact)
+		});
+		const surfaceIds = candidateSurfaces(externalSurface(candidate.candidate), surfaceArtifact).map((surface) => surface.surfaceId);
+		for (const score of candidate.selectionScores) {
+			const task = tasks.find((planned) => planned.taskId === taskIdFor(score.scenarioId, 0));
+			if (!task) throw new Error(`search ledger: candidate ${candidate.index} scored unplanned scenario ${score.scenarioId}`);
+			await ledger.append({
+				kind: "task-attempted",
+				eventId: `attempt:${candidate.index}:${task.taskId}`,
+				occurredAt: stamps(),
+				artifacts: [populationArtifact],
+				candidateId,
+				runId: `${input.runId}:${candidate.index}:${task.taskId}`,
+				attemptIndex: 0,
+				task: {
+					taskId: task.taskId,
+					source: task.source
+				},
+				identity: {
+					model: identity.model,
+					agent: identity.agent,
+					benchmark: task.benchmark
+				},
+				outcome: {
+					status: "passed",
+					score: score.score,
+					metrics: { composite: score.score }
+				},
+				accounting: {
+					tokens: {
+						status: "unknown",
+						reason: "the optimizer reports no token usage per candidate evaluation"
+					},
+					cost: {
+						status: "unknown",
+						knownLowerBoundUsd: 0,
+						reason: "the optimizer reports no cost per candidate evaluation"
+					}
+				},
+				surfaceEvidence: surfaceIds.map((surfaceId) => surfaceEvidenceFor(surfaceId, populationArtifact))
+			});
+		}
+	}
+	await ledger.append({
+		kind: "search-operation-recorded",
+		eventId: "operation:selection",
+		occurredAt: stamps(),
+		artifacts: [populationArtifact],
+		operationId: "selection",
+		operationKind: "selection",
+		execution: {
+			kind: "deterministic",
+			source: identity.search
+		},
+		outcome: { status: "completed" },
+		accounting: {
+			tokens: {
+				status: "known",
+				inputTokens: 0,
+				outputTokens: 0,
+				cachedTokens: 0
+			},
+			cost: {
+				status: "known",
+				usd: 0,
+				source: "free"
+			}
+		}
+	});
+	const winnerId = candidateIds.get(population.bestIndex);
+	for (const candidate of population.candidates) await ledger.append({
+		kind: "candidate-decided",
+		eventId: `decision:${candidate.index}`,
+		occurredAt: stamps(),
+		artifacts: [populationArtifact],
+		candidateId: candidateIds.get(candidate.index),
+		decision: candidate.index === population.bestIndex ? { status: "selected" } : {
+			status: "rejected",
+			reason: {
+				code: "not-selected",
+				message: "the optimizer selected another candidate"
+			}
+		}
+	});
+	const replay = await ledger.replay();
+	const { missingCandidateSlots, missingTaskOutcomes, missingOperations } = replay.audit.expected;
+	if (winnerId && missingCandidateSlots.length === 0 && missingTaskOutcomes.length === 0 && missingOperations.length === 0 && replay.audit.decisions.pending === 0) await ledger.append({
+		kind: "search-completed",
+		eventId: "search:completed",
+		occurredAt: stamps(),
+		artifacts: [populationArtifact],
+		result: {
+			status: "selected",
+			candidateId: winnerId
+		}
+	});
+	const final = await ledger.replay();
+	const bytes = final.entries.map((entry) => `${canonicalString(entry)}\n`).join("");
+	return createSearchHistoryReceipt({
+		producerId: input.producerId,
+		runId: input.runId,
+		ledger: {
+			role: "search-ledger",
+			uri: `file://${ledger.path}`,
+			sha256: hashCanonical(bytes),
+			byteLength: new TextEncoder().encode(bytes).byteLength
+		},
+		replay: final
+	});
+}
+/** An optimizer candidate as the canonical mutable surface it represents. */
+function externalSurface(candidate) {
+	return typeof candidate === "string" ? candidate : {
+		kind: "components",
+		components: candidate
+	};
+}
+function artifactWriter(storage, runDir) {
+	const directory = `${runDir}/${SEARCH_LEDGER_DIR}`;
+	return (role, name, body) => {
+		const contents = canonicalString(body);
+		storage.ensureDir(directory);
+		storage.write(`${directory}/${name}`, contents);
+		return {
+			role,
+			uri: `file://${directory}/${name}`,
+			sha256: hashCanonical(contents),
+			byteLength: new TextEncoder().encode(contents).byteLength
+		};
+	};
+}
+/** Non-decreasing ISO stamps; the ledger refuses an event that moves back. */
+function monotonicStamps() {
+	let last = 0;
+	return () => {
+		const now = Date.now();
+		last = now > last ? now : last + 1;
+		return new Date(last).toISOString();
+	};
+}
 //#endregion
 //#region src/campaign/types.ts
 /** Type guard: a proposal carrying its rationale vs a bare
@@ -3854,7 +4708,9 @@ function labelTrustRank(trust) {
 /**
 * `runOptimization` runs a caller-owned candidate generator for a bounded
 * number of rounds. Each candidate is measured on the same cases, and only a
-* candidate that beats the current best becomes the next parent.
+* candidate that beats the current best becomes the incumbent. By default the
+* incumbent is also the parent every generation mutates; a `selectParent`
+* policy draws the parent from the Pareto frontier instead.
 * The same loop accepts deterministic, model-backed, or agent-backed
 * proposers; they differ only in how `propose()` picks candidates.
 *
@@ -3862,7 +4718,7 @@ function labelTrustRank(trust) {
 * and optional pull request creation.
 */
 /**
-* Improvement loop body: N generations of propose → campaign → rank, maintaining a Pareto frontier and one global incumbent across generations.
+* Improvement loop body: N generations of propose → campaign → rank, maintaining a Pareto frontier and one global incumbent across generations. The parent each generation mutates is the incumbent unless `selectParent` draws it from the frontier.
 */
 async function runOptimization(opts) {
 	const { proposer } = opts;
@@ -3899,6 +4755,18 @@ async function runOptimization(opts) {
 		const label = opts.premeasuredBaseline ? "premeasured baseline" : "baseline";
 		throw new Error(`runOptimization: ${label} is incomplete (${baselineCoverage.scorableCellIds.length}/${baselineCoverage.expectedCellIds.length} designed cells scorable) — ${formatCoverageFailures(baselineCoverage)}. Refusing to optimize against an incomplete incumbent.`);
 	}
+	const recorder = opts.searchLedger ? await SearchRecorder.open({
+		binding: opts.searchLedger,
+		storage,
+		runDir: opts.runDir,
+		scenarios: opts.scenarios,
+		reps,
+		maxGenerations: opts.maxGenerations,
+		populationSize: opts.populationSize,
+		splitDigest: baselineCampaign.splitDigest,
+		proposerLabel: proposer.kind,
+		costLedger
+	}) : void 0;
 	const generations = [];
 	const history = [];
 	let currentFindings = initialFindings;
@@ -3914,6 +4782,10 @@ async function runOptimization(opts) {
 	let winnerLabel;
 	let winnerRationale;
 	const scored = [toParetoParent(baselineSurface, winnerSurfaceHash, baselineCampaign, -1)];
+	const measuredByHash = /* @__PURE__ */ new Map([[winnerSurfaceHash, {
+		parent: scored[0],
+		outcome: baselineOutcome
+	}]]);
 	if (opts.analyzeGeneration && opts.maxGenerations > 0 && baselineCampaign.cells.length > 0) {
 		const fresh = await opts.analyzeGeneration({
 			generation: -1,
@@ -3933,20 +4805,30 @@ async function runOptimization(opts) {
 	for (let gen = 0; gen < opts.maxGenerations; gen++) {
 		const proposalHistory = immutableProposalSnapshot(history, "history");
 		if (proposer.decide?.({ history: proposalHistory }).stop) break;
-		const paretoParents = computeParetoFrontier(scored);
-		const parentSurfaceHash = winnerSurfaceHash;
-		const parentComposite = winnerComposite;
+		const paretoParents = immutableProposalSnapshot(computeParetoFrontier(scored), "Pareto parents");
+		const incumbentOutcome = immutableProposalSnapshot(winnerOutcome, "incumbent outcome");
+		const selected = opts.selectParent ? resolveSelectedParent(opts.selectParent(Object.freeze({
+			frontier: paretoParents,
+			incumbent: incumbentOutcome,
+			history: proposalHistory,
+			generation: gen
+		})), measuredByHash, gen) : void 0;
+		const parentSurface = selected ? selected.parent.surface : winnerSurface;
+		const parentSurfaceHash = selected ? selected.parent.surfaceHash : winnerSurfaceHash;
+		const parentComposite = selected ? selected.outcome.composite : winnerComposite;
+		const parentOutcome = selected ? selected.outcome : winnerOutcome;
 		const proposalContext = Object.freeze({
-			currentSurface: immutableProposalSnapshot(winnerSurface, "current surface"),
+			currentSurface: immutableProposalSnapshot(parentSurface, "current surface"),
 			history: proposalHistory,
 			findings: immutableProposalSnapshot(assertProposalFindings(currentFindings, "runOptimization proposal findings"), "findings"),
 			populationSize: opts.populationSize,
 			generation: gen,
 			signal: opts.signal ?? new AbortController().signal,
 			baselineOutcome: immutableProposalSnapshot(baselineOutcome, "baseline outcome"),
-			incumbentOutcome: immutableProposalSnapshot(winnerOutcome, "incumbent outcome"),
+			incumbentOutcome,
+			parentOutcome: immutableProposalSnapshot(parentOutcome, "parent outcome"),
 			maxImprovementShots: opts.maxImprovementShots,
-			paretoParents: immutableProposalSnapshot(paretoParents, "Pareto parents"),
+			paretoParents,
 			costLedger,
 			costPhase: "search.proposal"
 		});
@@ -3966,6 +4848,15 @@ async function runOptimization(opts) {
 			generationHashes.add(hash);
 		}
 		for (const hash of generationHashes) admittedCandidateHashes.add(hash);
+		await recorder?.recordGeneration({
+			generation: gen,
+			parentSurfaceHash,
+			candidates: candidates.map(({ surface, label }) => ({
+				surface,
+				surfaceHash: surfaceHash(surface),
+				...label ? { label } : {}
+			}))
+		});
 		const surfaceResults = await mapConcurrent(candidates, candidateConcurrency, async ({ surface, label, rationale }, i, signal) => {
 			const hash = surfaceHash(surface);
 			const campaign = await runCampaign({
@@ -3993,8 +4884,22 @@ async function runOptimization(opts) {
 		}, opts.signal);
 		for (const result of surfaceResults) {
 			const { surface, surfaceHash: hash, campaign, coverage, label, rationale } = result;
-			if (coverage.complete) scored.push(toParetoParent(surface, hash, campaign, gen, label || void 0, rationale || void 0));
+			if (coverage.complete) {
+				const parent = toParetoParent(surface, hash, campaign, gen, label || void 0, rationale || void 0);
+				scored.push(parent);
+				measuredByHash.set(hash, {
+					parent,
+					outcome: toScoredSurfaceOutcome(hash, campaign, coverage, gen)
+				});
+			}
 		}
+		await recorder?.recordResults(surfaceResults.map((result) => ({
+			surface: result.surface,
+			surfaceHash: result.surfaceHash,
+			cells: result.campaign.cells,
+			runDir: result.campaign.runDir,
+			coverageComplete: result.coverage.complete
+		})));
 		surfaceResults.sort((a, b) => {
 			if (a.coverage.complete !== b.coverage.complete) return a.coverage.complete ? -1 : 1;
 			if (a.rankKey && b.rankKey) return compareRankKeys(b.rankKey, a.rankKey);
@@ -4064,6 +4969,11 @@ async function runOptimization(opts) {
 			currentFindings = immutableProposalSnapshot(assertProposalFindings(fresh, "runOptimization generation analysis findings"), "generation analysis findings");
 		}
 	}
+	const searchHistory = await recorder?.finish({
+		winnerSurfaceHash,
+		generationsRun: generations.length,
+		runId: opts.runDir
+	});
 	return {
 		generations,
 		baselineSurface,
@@ -4072,10 +4982,22 @@ async function runOptimization(opts) {
 		winnerLabel,
 		winnerRationale,
 		baselineCampaign,
+		...searchHistory ? { searchHistory } : {},
 		paretoFrontier: computeParetoFrontier(scored),
 		cost: costLedger.summary()
 	};
 }
+/** Resolve the parent a `selectParent` policy returned to the measured record
+*  this run holds for it. Refuses a surface the run never measured to
+*  completion, and a parent whose surface does not hash to its `surfaceHash`. */
+function resolveSelectedParent(returned, measuredByHash, generation) {
+	if (typeof returned !== "object" || returned === null || typeof returned.surfaceHash !== "string") throw new TypeError(`runOptimization: selectParent must return a ParetoParent (generation ${generation})`);
+	const parent = returned;
+	const measured = measuredByHash.get(parent.surfaceHash);
+	if (!measured) throw new Error(`runOptimization: selectParent returned surface "${parent.surfaceHash}" in generation ${generation}, which this run has not measured to completion; a parent must be a scored surface from the frontier`);
+	if (surfaceHash(parent.surface) !== parent.surfaceHash) throw new Error(`runOptimization: selectParent returned a parent whose surface does not match its surfaceHash "${parent.surfaceHash}" (generation ${generation})`);
+	return measured;
+}
 function immutableProposalSnapshot(value, label) {
 	try {
 		return deepFreeze(structuredClone(value));
@@ -4508,7 +5430,7 @@ function buildLoopProvenanceRecord(args) {
 		gate: {
 			decision: args.gate.decision,
 			reasons: args.gate.reasons,
-			delta: args.gate.delta,
+			...args.gate.delta === void 0 ? {} : { delta: args.gate.delta },
 			contributingGates: args.gate.contributingGates.map((g) => ({
 				name: g.name,
 				status: g.status,
@@ -4544,7 +5466,7 @@ function durableOptimizationMethod(value) {
 	if (!value.cost || !Number.isFinite(value.cost.totalCostUsd) || value.cost.totalCostUsd < 0 || typeof value.cost.accountingComplete !== "boolean" || !Array.isArray(value.cost.incompleteReasons) || value.cost.incompleteReasons.some((reason) => typeof reason !== "string" || !reason.trim()) || value.cost.accountingComplete !== (value.cost.incompleteReasons.length === 0)) throw new Error("buildLoopProvenanceRecord: optimization method cost is invalid");
 	if (value.durationMs !== void 0 && (!Number.isFinite(value.durationMs) || value.durationMs < 0)) throw new Error("buildLoopProvenanceRecord: optimization method duration is invalid");
 	try {
-		return JSON.parse(canonicalJson(value));
+		return JSON.parse(canonicalString(value));
 	} catch (cause) {
 		throw new Error("buildLoopProvenanceRecord: optimization method data must be canonical JSON", { cause });
 	}
@@ -4590,22 +5512,15 @@ function verifyLoopProvenanceRecord(record) {
 	assertGateContributions(record.gate?.contributingGates, "loop provenance");
 	return record;
 }
-/** Return the canonical SHA-256 digest of a JSON-serializable value. */
+/** SHA-256 over the RFC 8785 canonical JSON of `value`. Throws
+* `LedgerCanonicalizationError` for a value with no canonical form. */
 function canonicalDigest(value) {
-	const json = JSON.stringify(value, function strictJson(_key, item) {
-		if (typeof item === "number" && !Number.isFinite(item)) throw new Error("canonical digest cannot encode a non-finite number");
-		if (typeof item === "bigint" || typeof item === "function" || typeof item === "symbol") throw new Error(`canonical digest cannot encode ${typeof item}`);
-		if (item === void 0 && Array.isArray(this)) throw new Error("canonical digest cannot encode an undefined array item");
-		if (item instanceof Map || item instanceof Set) throw new Error(`canonical digest cannot encode ${item instanceof Map ? "Map" : "Set"}`);
-		return item;
-	});
-	if (json === void 0) throw new Error("canonical digest value is not serializable");
-	return `sha256:${contentHash(JSON.parse(json))}`;
+	return hashCanonical(value);
 }
 function durableGateDetail(detail) {
 	if (detail === void 0) return null;
 	try {
-		return JSON.parse(canonicalJson(detail));
+		return JSON.parse(canonicalString(detail));
 	} catch (cause) {
 		throw new Error("buildLoopProvenanceRecord: gate detail must be canonical JSON", { cause });
 	}
@@ -4890,6 +5805,33 @@ async function emitLoopProvenance(args) {
 	};
 }
 //#endregion
+//#region src/campaign/transient-failure.ts
+const BASE_TRANSIENT = /\b50[234]\b|no stream output|produced no stream|admission timed out|admission_rejected|queue_timeout|fetch failed|ECONNRESET|This operation was aborted/i;
+const TIMEOUT_PATTERN = /timeout after \d+ ?ms|cli-bridge timeout/i;
+/**
+* True when the error text describes an infrastructure hiccup that should be
+* retried rather than scored. Empty/undefined input is not transient.
+*/
+function isTransientTransportFailure(message, opts = {}) {
+	if (!message) return false;
+	if (BASE_TRANSIENT.test(message)) return true;
+	if ((opts.retryFullDurationTimeouts ?? false) && TIMEOUT_PATTERN.test(message)) return true;
+	for (const p of opts.extraPatterns ?? []) if (p.test(message)) return true;
+	return false;
+}
+/**
+* Ready-made `cellRetry.retryable` predicate: true for a dispatch-stage
+* failure whose error message `isTransientTransportFailure` classifies as an
+* infrastructure hiccup. A judge-stage failure is never retried here — the
+* dispatch already produced an artifact, so re-dispatching would score a
+* different sample. A per-cell dispatch deadline ("dispatch exceeded <N>ms")
+* is not transient by default; opt in via `extraPatterns` or
+* `retryFullDurationTimeouts` when queue starvation eats the clock.
+*/
+function transientDispatchFailure(opts = {}) {
+	return (failure) => failure.stage === "dispatch" && isTransientTransportFailure(failure.error.message, opts);
+}
+//#endregion
 //#region src/judges.ts
 /**
 * A judge's model response could not be parsed into scored dimensions.
@@ -4950,6 +5892,8 @@ function llmJudge(name, prompt, opts) {
 	const dimensions = normalizeDimensions(opts.dimensions, name);
 	const scale = opts.scale ?? "unit";
 	const divisor = scale === "ten" ? 10 : 1;
+	const scoring = opts.scoring ?? { method: "sampled" };
+	if (scoring.method === "expectation" && scale !== "ten") throw new Error(`llmJudge '${name}': expectation scoring requires scale 'ten' — a [0,1] score is not one token, so no single position carries its distribution`);
 	const renderUser = opts.renderUser ?? ((input) => JSON.stringify({
 		scenario: input.scenario,
 		artifact: input.artifact
@@ -4983,6 +5927,7 @@ function llmJudge(name, prompt, opts) {
 			maxTokens: opts.maxTokens ?? 800,
 			weights: opts.weights ?? null,
 			scale,
+			scoring,
 			jsonSchema: jsonSchema ?? null,
 			renderUser: opts.renderUser?.toString() ?? null
 		}),
@@ -5002,6 +5947,7 @@ function llmJudge(name, prompt, opts) {
 				}],
 				jsonMode: true,
 				jsonSchema,
+				...scoring.method === "expectation" ? { logprobs: { topLogprobs: EXPECTATION_TOP_LOGPROBS } } : {},
 				temperature: opts.temperature ?? .1,
 				maxTokens: opts.maxTokens ?? 800
 			};
@@ -5037,7 +5983,7 @@ function llmJudge(name, prompt, opts) {
 				cause: /* @__PURE__ */ new Error("response has no `dimensions` object"),
 				llmCall
 			});
-			const dims = {};
+			const sampled = {};
 			for (const { key } of dimensions) {
 				const raw = rawDims[key];
 				const value = Number(raw);
@@ -5045,8 +5991,26 @@ function llmJudge(name, prompt, opts) {
 					cause: /* @__PURE__ */ new Error(`dimension '${key}' missing or non-numeric (got ${JSON.stringify(raw)})`),
 					llmCall
 				});
-				dims[key] = clamp01(value / divisor);
+				sampled[key] = value;
+			}
+			let scoringMethod = "sampled";
+			let distribution;
+			const dims = {};
+			if (scoring.method === "expectation") {
+				const expectation = expectedDimensionScores({
+					tokens: response.logprobs ?? null,
+					sampled,
+					maxScore: divisor
+				});
+				if (expectation.kind === "unavailable") {
+					if (scoring.whenUnavailable === "fail") throw new Error(`llmJudge '${name}': expectation scoring is unavailable — ${expectation.reason}`);
+				} else {
+					scoringMethod = "expectation";
+					distribution = expectation.distribution;
+					for (const { key } of dimensions) dims[key] = clamp01(expectation.scores[key] / divisor);
+				}
 			}
+			if (scoringMethod === "sampled") for (const { key } of dimensions) dims[key] = clamp01(sampled[key] / divisor);
 			const { composite } = weightedComposite({
 				dims,
 				weights: opts.weights ?? Object.fromEntries(dimensions.map((d) => [d.key, 1 / dimensions.length]))
@@ -5055,11 +6019,105 @@ function llmJudge(name, prompt, opts) {
 				dimensions: dims,
 				composite,
 				notes: firstString(parsed.notes) ?? firstString(parsed.rationale) ?? `${name}: composite ${composite.toFixed(3)} over ${dimensions.length} dimension(s)`,
-				llmCall
+				llmCall,
+				...opts.scoring ? { scoringMethod } : {},
+				...distribution ? { distribution } : {}
 			};
 		}
 	};
 }
+/** Alternatives requested per score token. Twenty is the documented ceiling of
+*  the OpenAI-compatible `top_logprobs` field, and a grade scale has at most
+*  eleven integer candidates, so the window always covers the whole scale. */
+const EXPECTATION_TOP_LOGPROBS = 20;
+/**
+* Expected grade per dimension: locate the token that carried each dimension's
+* integer score, then average the integer grades the model considered at that
+* position, weighted by their probabilities.
+*
+* Unavailable — never silently approximated — when the provider returned no
+* log probabilities, when a dimension's grade is not in the token stream, or
+* when the grade did not land in exactly one token (a two-token `10`, a float).
+*/
+function expectedDimensionScores(input) {
+	const { tokens, sampled, maxScore } = input;
+	if (tokens === null) return {
+		kind: "unavailable",
+		reason: "the provider returned no logprobs"
+	};
+	if (tokens.length === 0) return {
+		kind: "unavailable",
+		reason: "the provider returned an empty logprob stream"
+	};
+	const offsets = [];
+	let text = "";
+	for (const token of tokens) {
+		offsets.push(text.length);
+		text += token.token;
+	}
+	const scores = {};
+	const distribution = {};
+	for (const [key, value] of Object.entries(sampled)) {
+		const match = new RegExp(`"${escapeRegExp(key)}"\\s*:\\s*`).exec(text);
+		if (!match) return {
+			kind: "unavailable",
+			reason: `dimension '${key}' is not in the token stream`
+		};
+		const scoreOffset = match.index + match[0].length;
+		let index = -1;
+		for (let position = 0; position < offsets.length; position++) if (offsets[position] <= scoreOffset) index = position;
+		else break;
+		const token = tokens[index];
+		if (!token) return {
+			kind: "unavailable",
+			reason: `dimension '${key}' has no token at its score position`
+		};
+		if (integerGrade(token.token, maxScore) !== value) return {
+			kind: "unavailable",
+			reason: `dimension '${key}' scored ${value}, which is not the whole of its token '${token.token}'`
+		};
+		const candidates = [];
+		let total = 0;
+		for (const alternative of token.top.length > 0 ? token.top : [token]) {
+			const grade = integerGrade(alternative.token, maxScore);
+			if (grade === null) continue;
+			const probability = Math.exp(alternative.logprob);
+			if (!Number.isFinite(probability) || probability <= 0) continue;
+			candidates.push({
+				score: grade,
+				probability
+			});
+			total += probability;
+		}
+		if (candidates.length === 0 || total <= 0) return {
+			kind: "unavailable",
+			reason: `dimension '${key}' has no integer grade in its probability window`
+		};
+		let expectation = 0;
+		for (const candidate of candidates) expectation += candidate.probability / total * candidate.score;
+		scores[key] = expectation;
+		distribution[key] = candidates.map((candidate) => ({
+			score: candidate.score,
+			probability: candidate.probability / total
+		})).sort((left, right) => left.score - right.score);
+	}
+	return {
+		kind: "expectation",
+		scores,
+		distribution
+	};
+}
+/** The token's integer grade on the judge's scale, or null when the token is
+*  not exactly one integer in range. */
+function integerGrade(token, maxScore) {
+	const trimmed = token.trim();
+	if (!/^\d+$/.test(trimmed)) return null;
+	const value = Number(trimmed);
+	return Number.isInteger(value) && value >= 0 && value <= maxScore ? value : null;
+}
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function normalizeDimensions(input, name) {
 	const raw = input && input.length > 0 ? input : ["quality"];
 	const out = [];
@@ -5115,6 +6173,6 @@ function firstString(value) {
 	return typeof value === "string" && value.trim() ? value : void 0;
 }
 //#endregion
-export { runEval as $, surfaceHash as A, campaignMeanComposite as B, optimizationTokenUsageFromSummary as C, componentSurfaceIdentityMaterial as D, codeSurfaceIdentityMaterial as E, assertSearchHistoryMatchesReplay as F, assertGepaCandidatePopulationSummary as G, buildReflectionPrompt as H, createSearchHistoryReceipt as I, DEFAULT_RED_TEAM_CORPUS as J, readGepaCandidatePopulationArtifact as K, searchHistoryCoverageRow as L, SEARCH_HISTORY_RECEIPT_SCHEMA_VERSION as M, SearchHistoryRequiredError as N, renderSurfaceDiff as O, assertCompleteSearchHistory as P, runCanaries as Q, verifySearchHistoryReceipt as R, costFromLedgerSummary as S, assertComponentSurface as T, parseReflectionResponse as U, compareRankKeys as V, recoverTruncatedJson as W, redTeamReport as X, redTeamDataset as Y, scoreRedTeamOutput as Z, paretoFrontier as _, canonicalDigest as a, assertRealBackend as at, combineComparisonCosts as b, loopProvenanceSpans as c, assertCampaignSplitIdentity as ct, verifyLoopProvenanceRecord as d, campaignSplitDigestFromIdentities as dt, runCampaign as et, runImprovementLoop as f, readCachedCell as ft, dominates as g, labelTrustRank as h, campaignMeasurementDigest as i, BackendIntegrityError as it, SEARCH_HISTORY_RECEIPT_DIGEST_ALGORITHM as j, surfaceContentHash as k, provenanceRecordPath as l, campaignScenarioIdentity as lt, isProposedCandidate as m, computeManifestHash as mt, JudgeParseError as n, resolveRunDir as nt, emitLoopProvenance as o, summarizeBackendIntegrity as ot, runOptimization as p, cellCachePath as pt, defaultProductionGate as q, buildLoopProvenanceRecord as r, tangleTracesRoot as rt, loopProvenanceArgsFromResult as s, assertCampaignDesign as st, llmJudge as t, planCampaignRun as tt, provenanceSpansPath as u, campaignSplitDigest as ut, openAutoPr as v, assertCodeSurfaceIdentity as w, compareOptimizationMethods as x, assertOptimizationResult as y, campaignBreakdown as z };
+export { scoreRedTeamOutput as $, codeSurfaceIdentityMaterial as A, verifySearchHistoryReceipt as B, openAutoPr as C, costFromLedgerSummary as D, compareOptimizationMethods as E, SearchHistoryRequiredError as F, parseReflectionResponse as G, campaignMeanComposite as H, assertCompleteSearchHistory as I, readGepaCandidatePopulationArtifact as J, recoverTruncatedJson as K, assertSearchHistoryMatchesReplay as L, renderSurfaceDiff as M, surfaceContentHash as N, optimizationTokenUsageFromSummary as O, surfaceHash as P, redTeamReport as Q, createSearchHistoryReceipt as R, paretoFrontierWithCrowding as S, combineComparisonCosts as T, compareRankKeys as U, campaignBreakdown as V, buildReflectionPrompt as W, DEFAULT_RED_TEAM_CORPUS as X, defaultProductionGate as Y, redTeamDataset as Z, labelTrustRank as _, buildLoopProvenanceRecord as a, tangleTracesRoot as at, dominates as b, emitLoopProvenance as c, summarizeBackendIntegrity as ct, provenanceRecordPath as d, campaignScenarioIdentity as dt, runCanaries as et, provenanceSpansPath as f, campaignSplitDigest as ft, isProposedCandidate as g, computeManifestHash as gt, runOptimization as h, cellCachePath as ht, transientDispatchFailure as i, resolveRunDir as it, componentSurfaceIdentityMaterial as j, assertCodeSurfaceIdentity as k, loopProvenanceArgsFromResult as l, assertCampaignDesign as lt, runImprovementLoop as m, readCachedCell as mt, JudgeParseError as n, runCampaign as nt, campaignMeasurementDigest as o, BackendIntegrityError as ot, verifyLoopProvenanceRecord as p, campaignSplitDigestFromIdentities as pt, assertGepaCandidatePopulationSummary as q, isTransientTransportFailure as r, planCampaignRun as rt, canonicalDigest as s, assertRealBackend as st, llmJudge as t, runEval as tt, loopProvenanceSpans as u, assertCampaignSplitIdentity as ut, SearchRecorder as v, assertOptimizationResult as w, paretoFrontier as x, recordCandidatePopulationSearch as y, searchHistoryCoverageRow as z };
 
-//# sourceMappingURL=llm-judge-BqqMS8t7.js.map
+//# sourceMappingURL=llm-judge-BhasIPFT.js.map