@tangle-network/agent-eval 0.150.2 → 0.161.1

package/dist/{skillopt-optimization-method-CPBlTcj5.js → skillopt-optimization-method-DbaekMcn.js}

@@ -1,10 +1,13 @@
-import { n as contentHash, t as canonicalJson } from "./verdict-cache-mZf5FEiY.js";
-import { C as optimizationTokenUsageFromSummary, G as assertGepaCandidatePopulationSummary, K as readGepaCandidatePopulationArtifact, S as costFromLedgerSummary, b as combineComparisonCosts, et as runCampaign, k as surfaceContentHash, t as llmJudge, z as campaignBreakdown } from "./llm-judge-BqqMS8t7.js";
-import { _ as resolveExternalOptimizerCallbackLimits, b as createRunCostLedger, d as assertJsonValue, f as assertNoCredentialValues, g as removeCredentialEnvironment, h as isRecord, i as startExternalOptimizerModelProxy, m as isExternalTextCandidate, n as closeExternalOptimizerResources, p as isCandidateText, r as runWithCleanup, t as runExternalOptimizerProcess, u as assertExternalOptimizerModelBudget, v as resolveExternalOptimizerProcessLimits, x as fsCampaignStorage, y as safePathComponent } from "./external-optimizer-subprocess-CKNb42oM.js";
+import { r as canonicalString } from "./canonical-IL-Bu-14.js";
+import { i as modelHasSnapshot } from "./run-record-BC0ebuRP.js";
+import { n as contentHash, t as canonicalJson } from "./verdict-cache-CdVVTVmn.js";
+import { D as costFromLedgerSummary, J as readGepaCandidatePopulationArtifact, N as surfaceContentHash, O as optimizationTokenUsageFromSummary, T as combineComparisonCosts, V as campaignBreakdown, nt as runCampaign, q as assertGepaCandidatePopulationSummary, t as llmJudge, y as recordCandidatePopulationSearch } from "./llm-judge-BhasIPFT.js";
+import { t as FileLedgerJournal } from "./ledger-core-BOzlRygb.js";
+import { C as SEARCH_LEDGER_FILE_CONTEXT, E as SearchLedgerIntegrityError, T as SearchLedgerError, _ as resolveExternalOptimizerCallbackLimits, b as createRunCostLedger, d as assertJsonValue, f as assertNoCredentialValues, g as removeCredentialEnvironment, h as isRecord, i as startExternalOptimizerModelProxy, m as isExternalTextCandidate, n as closeExternalOptimizerResources, p as isCandidateText, r as runWithCleanup, t as runExternalOptimizerProcess, u as assertExternalOptimizerModelBudget, v as resolveExternalOptimizerProcessLimits, w as SearchLedgerConflictError, x as fsCampaignStorage, y as safePathComponent } from "./external-optimizer-subprocess-BIWbHpgD.js";
 import { a as heldoutSignificance, o as pairHoldout } from "./power-preflight-DEw-uC7q.js";
 import { c as deepFreezeCanonicalJson } from "./types-BI4fT3HN.js";
-import { y as assertServedModelPolicy } from "./llm-client-Bg32RW0j.js";
-import { n as acquireSingleRunLock, t as startExternalOptimizerCallback } from "./external-optimizer-process-x9oEXKsU.js";
+import { g as assertServedModelPolicy } from "./llm-client-hgDieDNN.js";
+import { n as acquireSingleRunLock, t as startExternalOptimizerCallback } from "./external-optimizer-process-WosTBChy.js";
 import { createHash, randomBytes } from "node:crypto";
 import { z } from "zod";
 import { mkdir } from "node:fs/promises";
@@ -1408,6 +1411,746 @@ function isGepaCandidate(value, maxChars) {
 	return (typeof value === "string" ? value.length : JSON.stringify(value).length) <= maxChars;
 }
 //#endregion
+//#region src/campaign/search-ledger.ts
+/**
+* Durable append-only audit log for improvement searches.
+*
+* Existing campaign artifacts keep their own rich records: `RunRecord` owns a
+* measured run and `CostLedger` owns per-call accounting. This ledger does not
+* copy those structures. It binds their immutable ids and receipts into one replayable event stream so a
+* search can answer, after a crash, exactly which candidates and task attempts
+* existed, which surfaces actually fired, what they cost, and why they were
+* selected or rejected.
+*
+* 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; the implementation never skips a bad row.
+*
+* The journal machinery itself (hash chain, locking, fsync, idempotent append)
+* is the generic `ledger-core` journal; this module supplies the campaign
+* codec: event schemas, canonical event ordering, and the search state machine.
+*/
+const SEARCH_LEDGER_SCHEMA = "tangle.search-ledger.v1";
+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 LINEAGE_NODE_ID = z.string().regex(/^[a-f0-9]{16}$/);
+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 FINITE_NUMBER = z.number().finite();
+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 FailureReasonSchema = z.object({
+	code: NON_EMPTY,
+	message: NON_EMPTY
+}).strict();
+const EventBaseShape = {
+	eventId: NON_EMPTY,
+	occurredAt: ISO_TIMESTAMP,
+	artifacts: z.array(ArtifactRefSchema).min(1)
+};
+const OperationKindSchema = z.enum([
+	"candidate-generation",
+	"analysis",
+	"selection",
+	"judge",
+	"other"
+]);
+const CandidateSlotSchema = z.object({
+	slotId: NON_EMPTY,
+	generationOperationId: NON_EMPTY
+}).strict();
+const PlannedOperationSchema = z.object({
+	operationId: NON_EMPTY,
+	kind: OperationKindSchema
+}).strict();
+const SearchPlanExtendedSchema = z.object({
+	...EventBaseShape,
+	kind: z.literal("search-plan-extended"),
+	extension: z.object({
+		candidateSlots: z.array(CandidateSlotSchema),
+		operations: z.array(PlannedOperationSchema)
+	}).strict().superRefine((extension, ctx) => {
+		if (extension.candidateSlots.length === 0 && extension.operations.length === 0) ctx.addIssue({
+			code: "custom",
+			message: "a plan extension must add slots or operations"
+		});
+	})
+}).strict();
+const SearchPlannedSchema = z.object({
+	...EventBaseShape,
+	kind: z.literal("search-planned"),
+	plan: z.object({
+		candidateSlots: z.array(CandidateSlotSchema).min(1),
+		tasks: z.array(z.object({
+			taskId: NON_EMPTY,
+			source: SourceRefSchema,
+			benchmark: SourceRefSchema,
+			maxAttempts: z.number().int().positive().safe()
+		}).strict()).min(1),
+		operations: z.array(PlannedOperationSchema).min(1)
+	}).strict()
+}).strict();
+const CandidateRegisteredSchema = z.object({
+	...EventBaseShape,
+	kind: z.literal("candidate-registered"),
+	slotId: NON_EMPTY,
+	generationOperationId: NON_EMPTY,
+	candidateId: NON_EMPTY,
+	lineage: z.object({
+		lineageNodeId: LINEAGE_NODE_ID,
+		parentCandidateIds: z.array(NON_EMPTY),
+		generation: NON_NEGATIVE_INT,
+		proposer: NON_EMPTY,
+		proposerSource: SourceRefSchema
+	}).strict(),
+	surfaces: z.array(z.object({
+		surfaceId: NON_EMPTY,
+		kind: z.enum([
+			"prompt",
+			"tool-contract",
+			"runtime-config",
+			"memory",
+			"knowledge",
+			"agent-profile",
+			"code",
+			"deployment"
+		]),
+		artifact: ArtifactRefSchema
+	}).strict()).min(1)
+}).strict();
+const CandidateSlotClosedSchema = z.object({
+	...EventBaseShape,
+	kind: z.literal("candidate-slot-closed"),
+	slotId: NON_EMPTY,
+	generationOperationId: NON_EMPTY,
+	reason: FailureReasonSchema
+}).strict();
+const KnownTokensSchema = z.object({
+	status: z.literal("known"),
+	inputTokens: NON_NEGATIVE_INT,
+	outputTokens: NON_NEGATIVE_INT,
+	cachedTokens: NON_NEGATIVE_INT
+}).strict();
+const UnknownSchema = z.object({
+	status: z.literal("unknown"),
+	reason: NON_EMPTY
+}).strict();
+const KnownCostSchema = z.object({
+	status: z.literal("known"),
+	usd: z.number().finite().nonnegative(),
+	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: z.number().finite().nonnegative(),
+	reason: NON_EMPTY
+}).strict();
+const AccountingSchema = z.object({
+	tokens: z.discriminatedUnion("status", [KnownTokensSchema, UnknownSchema]),
+	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: "a fired surface must have firingCount >= 1"
+	});
+	if (!evidence.fired && evidence.firingCount !== 0) ctx.addIssue({
+		code: "custom",
+		message: "a surface that did not fire must have firingCount 0"
+	});
+	if (!evidence.fired && evidence.effect.status === "measured" && evidence.effect.delta !== 0) ctx.addIssue({
+		code: "custom",
+		message: "a surface that did not fire cannot claim non-zero effect"
+	});
+});
+const TaskAttemptedSchema = z.object({
+	...EventBaseShape,
+	kind: z.literal("task-attempted"),
+	candidateId: NON_EMPTY,
+	runId: NON_EMPTY,
+	attemptIndex: NON_NEGATIVE_INT,
+	task: z.object({
+		taskId: NON_EMPTY,
+		source: SourceRefSchema
+	}).strict(),
+	identity: z.object({
+		model: z.object({
+			provider: NON_EMPTY,
+			snapshot: NON_EMPTY.refine(modelHasSnapshot, "model must include an immutable snapshot")
+		}).strict(),
+		agent: SourceRefSchema,
+		benchmark: SourceRefSchema
+	}).strict(),
+	outcome: OutcomeSchema,
+	accounting: AccountingSchema,
+	surfaceEvidence: z.array(SurfaceEvidenceSchema).min(1)
+}).strict();
+const SearchOperationRecordedSchema = z.object({
+	...EventBaseShape,
+	kind: z.literal("search-operation-recorded"),
+	operationId: NON_EMPTY,
+	operationKind: OperationKindSchema,
+	execution: z.discriminatedUnion("kind", [z.object({
+		kind: z.literal("model"),
+		model: z.object({
+			provider: NON_EMPTY,
+			snapshot: NON_EMPTY.refine(modelHasSnapshot, "model must include an immutable snapshot")
+		}).strict(),
+		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 CandidateDecidedSchema = z.object({
+	...EventBaseShape,
+	kind: z.literal("candidate-decided"),
+	candidateId: NON_EMPTY,
+	decision: z.discriminatedUnion("status", [z.object({ status: z.literal("selected") }).strict(), z.object({
+		status: z.literal("rejected"),
+		reason: FailureReasonSchema
+	}).strict()])
+}).strict();
+const SearchCompletedSchema = z.object({
+	...EventBaseShape,
+	kind: z.literal("search-completed"),
+	result: z.discriminatedUnion("status", [z.object({
+		status: z.literal("selected"),
+		candidateId: NON_EMPTY
+	}).strict(), z.object({
+		status: z.literal("all-rejected"),
+		reason: FailureReasonSchema
+	}).strict()])
+}).strict();
+const EventSchema = z.discriminatedUnion("kind", [
+	SearchPlannedSchema,
+	SearchPlanExtendedSchema,
+	CandidateRegisteredSchema,
+	CandidateSlotClosedSchema,
+	TaskAttemptedSchema,
+	SearchOperationRecordedSchema,
+	CandidateDecidedSchema,
+	SearchCompletedSchema
+]);
+const EntrySchema = z.object({
+	schema: z.literal(SEARCH_LEDGER_SCHEMA),
+	campaignId: 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 is not semantic are
+* sorted so retries from different processes produce byte-identical events. */
+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 `replay` validates the complete existing file. */
+function openSearchLedger(options) {
+	if (options.path.trim().length === 0) throw new SearchLedgerError("ledger path is empty");
+	return new FileSearchLedger(options.path, options.campaignId, options.trustedHead);
+}
+function searchLedgerCodec(campaignId) {
+	return {
+		...SEARCH_LEDGER_FILE_CONTEXT,
+		header: {
+			schema: SEARCH_LEDGER_SCHEMA,
+			campaignId
+		},
+		conflictError: (message) => new SearchLedgerConflictError(message),
+		parseEntry: parseSearchLedgerEntry,
+		checkEntryHeader: (entry, index) => {
+			if (entry.campaignId !== campaignId) throw new SearchLedgerIntegrityError(`entry ${index} belongs to campaign ${entry.campaignId}, expected ${campaignId}`);
+		},
+		createProjector: () => createSearchLedgerProjector(campaignId)
+	};
+}
+/** Append-only file-backed search ledger with idempotent writes and replay. */
+var FileSearchLedger = class {
+	path;
+	campaignId;
+	trustedHeadPath;
+	trustedHeadMode;
+	journal;
+	constructor(path, campaignId, trustedHead = "pin") {
+		if (path.trim().length === 0) throw new SearchLedgerError("ledger path is empty");
+		if (campaignId.length === 0) throw new SearchLedgerError("campaignId is empty");
+		if (campaignId.trim() !== campaignId) throw new SearchLedgerError("campaignId must not contain surrounding whitespace");
+		this.campaignId = campaignId;
+		this.trustedHeadMode = trustedHead;
+		this.journal = new FileLedgerJournal(path, searchLedgerCodec(campaignId), { requireTrustedHead: trustedHead === "require" });
+		this.path = this.journal.path;
+		this.trustedHeadPath = this.journal.trustedHeadPath;
+	}
+	async replay() {
+		return (await this.journal.replay()).projection;
+	}
+	async append(input) {
+		const event = validateSearchLedgerEvent(input);
+		const { entry, appended, projection } = await this.journal.append(event, { pinHead: this.trustedHeadMode !== "off" });
+		return {
+			entry,
+			appended,
+			replay: projection
+		};
+	}
+	async trustedHead() {
+		return this.journal.trustedHead();
+	}
+	async pinTrustedHead() {
+		return this.journal.pinTrustedHead();
+	}
+	async clearTrustedHead() {
+		return this.journal.clearTrustedHead();
+	}
+};
+function parseSearchLedgerEntry(raw, context) {
+	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;
+}
+/** Replay the campaign search state machine over chain-verified entries. The
+* generic journal owns sequence, hash, and eventId-uniqueness checks; this
+* projector owns every campaign invariant and builds the replay projection. */
+function createSearchLedgerProjector(campaignId) {
+	const candidates = /* @__PURE__ */ new Map();
+	const plannedSlots = /* @__PURE__ */ new Map();
+	const plannedOperations = /* @__PURE__ */ new Map();
+	const planExtensions = [];
+	const candidateBySlot = /* @__PURE__ */ new Map();
+	const closedSlots = /* @__PURE__ */ new Map();
+	const lineageNodes = /* @__PURE__ */ new Map();
+	const runIds = /* @__PURE__ */ new Set();
+	const attemptKeys = /* @__PURE__ */ new Set();
+	const candidateEvents = [];
+	const closedSlotEvents = [];
+	const attempts = [];
+	const operationEvents = [];
+	const operationsById = /* @__PURE__ */ new Map();
+	const decisions = [];
+	let planEvent = null;
+	let completion = null;
+	let previousOccurredAt = Number.NEGATIVE_INFINITY;
+	const apply = (entry, index) => {
+		const event = entry.event;
+		if (completion) throw new SearchLedgerIntegrityError(`event ${event.eventId} appears after terminal event ${completion.eventId}`);
+		const occurredAt = Date.parse(event.occurredAt);
+		if (occurredAt < previousOccurredAt) throw new SearchLedgerIntegrityError(`event ${event.eventId} occurred before the preceding durable event`);
+		previousOccurredAt = occurredAt;
+		assertUnique(event.artifacts.map(artifactKey), "artifact receipt", event.eventId);
+		if (event.kind === "search-planned") {
+			if (index !== 0 || planEvent) throw new SearchLedgerIntegrityError("search plan must be the first and only plan event");
+			assertUnique(event.plan.candidateSlots.map((slot) => slot.slotId), "candidate slot", event.eventId);
+			assertUnique(event.plan.tasks.map((task) => task.taskId), "planned taskId", event.eventId);
+			assertUnique(event.plan.operations.map((operation) => operation.operationId), "planned operationId", event.eventId);
+			for (const operation of event.plan.operations) plannedOperations.set(operation.operationId, operation);
+			for (const slot of event.plan.candidateSlots) {
+				assertSlotGenerationOperation(slot, plannedOperations);
+				plannedSlots.set(slot.slotId, slot);
+			}
+			planEvent = event;
+			return;
+		}
+		if (!planEvent) throw new SearchLedgerIntegrityError(`event ${event.eventId} appears before the required search plan`);
+		if (event.kind === "search-plan-extended") {
+			assertUnique(event.extension.candidateSlots.map((slot) => slot.slotId), "candidate slot", event.eventId);
+			assertUnique(event.extension.operations.map((operation) => operation.operationId), "planned operationId", event.eventId);
+			for (const operation of event.extension.operations) {
+				if (plannedOperations.has(operation.operationId)) throw new SearchLedgerIntegrityError(`plan extension ${event.eventId} re-plans operation ${operation.operationId}`);
+				plannedOperations.set(operation.operationId, operation);
+			}
+			for (const slot of event.extension.candidateSlots) {
+				if (plannedSlots.has(slot.slotId)) throw new SearchLedgerIntegrityError(`plan extension ${event.eventId} re-plans candidate slot ${slot.slotId}`);
+				assertSlotGenerationOperation(slot, plannedOperations);
+				plannedSlots.set(slot.slotId, slot);
+			}
+			planExtensions.push(event);
+			return;
+		}
+		if (event.kind === "candidate-registered") {
+			if (candidates.has(event.candidateId)) throw new SearchLedgerIntegrityError(`candidate ${event.candidateId} was registered twice`);
+			const plannedSlot = plannedSlots.get(event.slotId);
+			if (!plannedSlot) throw new SearchLedgerIntegrityError(`candidate ${event.candidateId} binds unknown slot ${event.slotId}`);
+			if (candidateBySlot.has(event.slotId)) throw new SearchLedgerIntegrityError(`candidate slot ${event.slotId} was bound twice`);
+			if (closedSlots.has(event.slotId)) throw new SearchLedgerIntegrityError(`candidate slot ${event.slotId} was already closed`);
+			if (event.generationOperationId !== plannedSlot.generationOperationId) throw new SearchLedgerIntegrityError(`candidate ${event.candidateId} generation operation ${event.generationOperationId} does not match slot ${event.slotId} plan ${plannedSlot.generationOperationId}`);
+			const generationOperation = operationsById.get(event.generationOperationId);
+			if (!generationOperation) throw new SearchLedgerIntegrityError(`candidate ${event.candidateId} precedes generation operation ${event.generationOperationId}`);
+			if (generationOperation.outcome.status === "failed") throw new SearchLedgerIntegrityError(`candidate ${event.candidateId} cannot bind failed generation operation ${event.generationOperationId}`);
+			const previousCandidate = lineageNodes.get(event.lineage.lineageNodeId);
+			if (previousCandidate) throw new SearchLedgerIntegrityError(`lineage node ${event.lineage.lineageNodeId} is already bound to ${previousCandidate}`);
+			assertUnique(event.lineage.parentCandidateIds, "parentCandidateId", event.eventId);
+			const parents = event.lineage.parentCandidateIds.map((id) => {
+				const parent = candidates.get(id);
+				if (!parent) throw new SearchLedgerIntegrityError(`candidate ${event.candidateId} references unknown parent ${id}`);
+				return parent;
+			});
+			const expectedGeneration = parents.length === 0 ? 0 : Math.max(...parents.map((parent) => parent.registered.lineage.generation)) + 1;
+			if (event.lineage.generation !== expectedGeneration) throw new SearchLedgerIntegrityError(`candidate ${event.candidateId} generation ${event.lineage.generation} does not follow its parents (expected ${expectedGeneration})`);
+			assertUnique(event.surfaces.map((surface) => surface.surfaceId), "surfaceId", event.eventId);
+			candidates.set(event.candidateId, {
+				registered: event,
+				attempts: [],
+				decision: null
+			});
+			candidateBySlot.set(event.slotId, event.candidateId);
+			lineageNodes.set(event.lineage.lineageNodeId, event.candidateId);
+			candidateEvents.push(event);
+			return;
+		}
+		if (event.kind === "task-attempted") {
+			const candidate = candidates.get(event.candidateId);
+			if (!candidate) throw new SearchLedgerIntegrityError(`attempt ${event.eventId} references unknown candidate ${event.candidateId}`);
+			if (candidate.decision) throw new SearchLedgerIntegrityError(`attempt ${event.eventId} appears after candidate ${event.candidateId} was decided`);
+			const plannedTask = planEvent.plan.tasks.find((task) => task.taskId === event.task.taskId);
+			if (!plannedTask) throw new SearchLedgerIntegrityError(`attempt ${event.eventId} references unplanned task ${event.task.taskId}`);
+			if (canonicalString(plannedTask.source) !== canonicalString(event.task.source) || canonicalString(plannedTask.benchmark) !== canonicalString(event.identity.benchmark)) throw new SearchLedgerIntegrityError(`task ${event.task.taskId} does not match its planned source identity`);
+			if (event.attemptIndex >= plannedTask.maxAttempts) throw new SearchLedgerIntegrityError(`task ${event.task.taskId} attempt ${event.attemptIndex} exceeds planned maxAttempts ${plannedTask.maxAttempts}`);
+			if (runIds.has(event.runId)) throw new SearchLedgerIntegrityError(`runId ${event.runId} was recorded twice`);
+			runIds.add(event.runId);
+			const attemptKey = canonicalString([
+				event.candidateId,
+				event.task.taskId,
+				event.attemptIndex
+			]);
+			if (attemptKeys.has(attemptKey)) throw new SearchLedgerIntegrityError(`candidate ${event.candidateId} task ${event.task.taskId} attempt ${event.attemptIndex} was recorded twice`);
+			const expectedAttemptIndex = candidate.attempts.filter((attempt) => attempt.task.taskId === event.task.taskId).length;
+			if (event.attemptIndex !== expectedAttemptIndex) throw new SearchLedgerIntegrityError(`candidate ${event.candidateId} task ${event.task.taskId} attempt index ${event.attemptIndex} is not contiguous (expected ${expectedAttemptIndex})`);
+			const previousAttempt = candidate.attempts.find((attempt) => attempt.task.taskId === event.task.taskId);
+			if (previousAttempt?.outcome.status !== void 0 && previousAttempt.outcome.status !== "errored") throw new SearchLedgerIntegrityError(`task ${event.task.taskId} was retried after a measured outcome`);
+			if (previousAttempt && canonicalString({
+				task: previousAttempt.task,
+				identity: previousAttempt.identity
+			}) !== canonicalString({
+				task: event.task,
+				identity: event.identity
+			})) throw new SearchLedgerIntegrityError(`candidate ${event.candidateId} task ${event.task.taskId} changed immutable execution identity between attempts`);
+			attemptKeys.add(attemptKey);
+			const declared = candidate.registered.surfaces.map((surface) => surface.surfaceId).sort();
+			const observed = event.surfaceEvidence.map((surface) => surface.surfaceId).sort();
+			assertUnique(observed, "surface evidence", event.eventId);
+			for (const evidence of event.surfaceEvidence) assertUnique(evidence.evidence.map(artifactKey), "surface evidence receipt", event.eventId);
+			if (canonicalString(declared) !== canonicalString(observed)) throw new SearchLedgerIntegrityError(`attempt ${event.eventId} surface evidence does not exactly cover candidate ${event.candidateId}`);
+			candidate.attempts.push(event);
+			attempts.push(event);
+			return;
+		}
+		if (event.kind === "search-operation-recorded") {
+			const plannedOperation = plannedOperations.get(event.operationId);
+			if (!plannedOperation) throw new SearchLedgerIntegrityError(`operation ${event.operationId} was not declared in the search plan`);
+			if (plannedOperation.kind !== event.operationKind) throw new SearchLedgerIntegrityError(`operation ${event.operationId} kind ${event.operationKind} does not match planned ${plannedOperation.kind}`);
+			if (operationsById.has(event.operationId)) throw new SearchLedgerIntegrityError(`operation ${event.operationId} was recorded twice`);
+			operationsById.set(event.operationId, event);
+			operationEvents.push(event);
+			return;
+		}
+		if (event.kind === "candidate-slot-closed") {
+			const plannedSlot = plannedSlots.get(event.slotId);
+			if (!plannedSlot) throw new SearchLedgerIntegrityError(`candidate slot closure ${event.eventId} references unknown slot ${event.slotId}`);
+			if (event.generationOperationId !== plannedSlot.generationOperationId) throw new SearchLedgerIntegrityError(`candidate slot closure ${event.eventId} generation operation ${event.generationOperationId} does not match slot ${event.slotId} plan ${plannedSlot.generationOperationId}`);
+			if (candidateBySlot.has(event.slotId)) throw new SearchLedgerIntegrityError(`candidate slot ${event.slotId} was already bound to a candidate`);
+			if (closedSlots.has(event.slotId)) throw new SearchLedgerIntegrityError(`candidate slot ${event.slotId} was closed twice`);
+			const operation = operationsById.get(event.generationOperationId);
+			if (!operation) throw new SearchLedgerIntegrityError(`candidate slot closure ${event.eventId} precedes operation ${event.generationOperationId}`);
+			if (operation.outcome.status === "completed") throw new SearchLedgerIntegrityError(`candidate slot ${event.slotId} cannot close from completed operation ${event.generationOperationId}`);
+			closedSlots.set(event.slotId, event);
+			closedSlotEvents.push(event);
+			return;
+		}
+		if (event.kind === "candidate-decided") {
+			const candidate = candidates.get(event.candidateId);
+			if (!candidate) throw new SearchLedgerIntegrityError(`decision ${event.eventId} references unknown candidate ${event.candidateId}`);
+			if (candidate.decision) throw new SearchLedgerIntegrityError(`candidate ${event.candidateId} was decided twice`);
+			if (event.decision.status === "selected") {
+				if (!candidate.attempts.some((attempt) => attempt.outcome.status !== "errored")) throw new SearchLedgerIntegrityError(`candidate ${event.candidateId} cannot be selected without a measured task outcome`);
+				if (decisions.some((decision) => decision.decision.status === "selected")) throw new SearchLedgerIntegrityError("more than one candidate was selected");
+			}
+			candidate.decision = event;
+			decisions.push(event);
+			return;
+		}
+		const missingCandidateSlots = [...plannedSlots.values()].filter((slot) => !candidateBySlot.has(slot.slotId) && !closedSlots.has(slot.slotId)).map((slot) => slot.slotId);
+		if (missingCandidateSlots.length > 0) throw new SearchLedgerIntegrityError(`search completed with missing candidate slots: ${missingCandidateSlots.join(", ")}`);
+		const missingTaskOutcomes = plannedTaskOutcomeKeys(planEvent, candidates);
+		if (missingTaskOutcomes.length > 0) throw new SearchLedgerIntegrityError(`search completed with missing task outcomes: ${missingTaskOutcomes.join(", ")}`);
+		const missingOperations = [...plannedOperations.values()].filter((operation) => !operationsById.has(operation.operationId)).map((operation) => operation.operationId);
+		if (missingOperations.length > 0) throw new SearchLedgerIntegrityError(`search completed with missing search operations: ${missingOperations.join(", ")}`);
+		for (const operation of plannedOperations.values()) {
+			if (operation.kind !== "candidate-generation") continue;
+			const generationOutcome = operationsById.get(operation.operationId).outcome.status;
+			const slots = [...plannedSlots.values()].filter((slot) => slot.generationOperationId === operation.operationId);
+			if (slots.length === 0) continue;
+			const registeredCount = slots.filter((slot) => candidateBySlot.has(slot.slotId)).length;
+			const closedCount = slots.filter((slot) => closedSlots.has(slot.slotId)).length;
+			if (generationOutcome === "completed" && closedCount > 0) throw new SearchLedgerIntegrityError(`completed generation operation ${operation.operationId} contains ${closedCount} closed slot(s)`);
+			if (generationOutcome === "failed" && registeredCount > 0) throw new SearchLedgerIntegrityError(`failed generation operation ${operation.operationId} contains ${registeredCount} registered candidate(s)`);
+			if (generationOutcome === "partial" && (registeredCount === 0 || closedCount === 0)) throw new SearchLedgerIntegrityError(`partial generation operation ${operation.operationId} must contain both a registered candidate and a closed slot`);
+		}
+		const pending = [...candidates.values()].filter((candidate) => candidate.decision === null);
+		if (pending.length > 0) throw new SearchLedgerIntegrityError(`search completed with ${pending.length} candidate decision(s) missing`);
+		const selected = decisions.filter((decision) => decision.decision.status === "selected");
+		if (event.result.status === "selected") {
+			if (selected.length !== 1 || selected[0].candidateId !== event.result.candidateId) throw new SearchLedgerIntegrityError(`search completion winner ${event.result.candidateId} does not match candidate decisions`);
+		} else if (selected.length !== 0) throw new SearchLedgerIntegrityError("all-rejected completion contains a selected candidate");
+		completion = event;
+	};
+	const finish = (entries) => {
+		const selectedDecisions = decisions.filter((decision) => decision.decision.status === "selected");
+		const rejectedDecisions = decisions.filter((decision) => decision.decision.status === "rejected");
+		const outcomeCounts = {
+			passed: 0,
+			failed: 0,
+			errored: 0
+		};
+		const operationOutcomeCounts = {
+			completed: 0,
+			partial: 0,
+			failed: 0
+		};
+		let inputTokens = 0;
+		let outputTokens = 0;
+		let cachedTokens = 0;
+		let costUsd = 0;
+		const unknownTokenEventIds = [];
+		const unknownCostEventIds = [];
+		for (const attempt of attempts) outcomeCounts[attempt.outcome.status] += 1;
+		for (const operation of operationEvents) operationOutcomeCounts[operation.outcome.status] += 1;
+		for (const costedEvent of [...attempts, ...operationEvents]) {
+			if (costedEvent.accounting.tokens.status === "known") {
+				inputTokens += costedEvent.accounting.tokens.inputTokens;
+				outputTokens += costedEvent.accounting.tokens.outputTokens;
+				cachedTokens += costedEvent.accounting.tokens.cachedTokens;
+			} else unknownTokenEventIds.push(costedEvent.eventId);
+			if (costedEvent.accounting.cost.status === "known") costUsd += costedEvent.accounting.cost.usd;
+			else {
+				costUsd += costedEvent.accounting.cost.knownLowerBoundUsd;
+				unknownCostEventIds.push(costedEvent.eventId);
+			}
+		}
+		const accounting = unknownTokenEventIds.length === 0 && unknownCostEventIds.length === 0 ? {
+			status: "known",
+			inputTokens,
+			outputTokens,
+			cachedTokens,
+			costUsd
+		} : {
+			status: "partial",
+			knownInputTokens: inputTokens,
+			knownOutputTokens: outputTokens,
+			knownCachedTokens: cachedTokens,
+			knownCostUsd: costUsd,
+			unknownTokenEventIds,
+			unknownCostEventIds
+		};
+		const selectedCandidateId = completion?.result.status === "selected" ? completion.result.candidateId : null;
+		const status = completion?.result.status === "selected" ? "selected" : completion?.result.status === "all-rejected" ? "all-rejected" : "in-progress";
+		const missingCandidateSlots = [...plannedSlots.values()].filter((slot) => !candidateBySlot.has(slot.slotId) && !closedSlots.has(slot.slotId)).map((slot) => slot.slotId);
+		const missingTaskOutcomes = planEvent ? plannedTaskOutcomeKeys(planEvent, candidates) : [];
+		const missingOperations = [...plannedOperations.values()].filter((operation) => !operationsById.has(operation.operationId)).map((operation) => operation.operationId);
+		return {
+			entries: [...entries],
+			plan: planEvent,
+			planExtensions,
+			candidates: candidateEvents,
+			closedCandidateSlots: closedSlotEvents,
+			attempts,
+			operations: operationEvents,
+			decisions,
+			completion,
+			audit: {
+				campaignId,
+				eventCount: entries.length,
+				candidateCount: candidates.size,
+				closedCandidateSlotCount: closedSlots.size,
+				attemptCount: attempts.length,
+				operationCount: operationEvents.length,
+				outcomes: outcomeCounts,
+				operationOutcomes: operationOutcomeCounts,
+				decisions: {
+					selected: selectedDecisions.length,
+					rejected: rejectedDecisions.length,
+					pending: candidates.size - decisions.length
+				},
+				expected: {
+					candidateSlots: plannedSlots.size,
+					taskOutcomes: candidates.size * (planEvent?.plan.tasks.length ?? 0),
+					operations: plannedOperations.size,
+					missingCandidateSlots,
+					missingTaskOutcomes,
+					missingOperations
+				},
+				status,
+				selectedCandidateId,
+				accounting,
+				headHash: entries.at(-1)?.entryHash ?? null
+			}
+		};
+	};
+	return {
+		apply,
+		finish
+	};
+}
+/** Every candidate slot must name a planned candidate-generation operation,
+* whether it arrives with the plan or with a later extension. */
+function assertSlotGenerationOperation(slot, plannedOperations) {
+	if (plannedOperations.get(slot.generationOperationId)?.kind !== "candidate-generation") throw new SearchLedgerIntegrityError(`candidate slot ${slot.slotId} references unplanned candidate-generation operation ${slot.generationOperationId}`);
+}
+function plannedTaskOutcomeKeys(planEvent, candidates) {
+	const missing = [];
+	const registeredCandidates = [...candidates.values()].sort((a, b) => compareStrings(a.registered.slotId, b.registered.slotId));
+	for (const candidate of registeredCandidates) {
+		const slotId = candidate.registered.slotId;
+		for (const task of planEvent.plan.tasks) if (!candidate.attempts.some((attempt) => attempt.task.taskId === task.taskId && attempt.outcome.status !== "errored")) missing.push(`${slotId}/${task.taskId}`);
+	}
+	return missing;
+}
+function normalizeEvent(event) {
+	const artifacts = sortArtifacts(event.artifacts);
+	if (event.kind === "search-planned") return {
+		...event,
+		artifacts,
+		plan: {
+			candidateSlots: [...event.plan.candidateSlots].sort((a, b) => compareStrings(a.slotId, b.slotId)),
+			tasks: [...event.plan.tasks].sort((a, b) => compareStrings(a.taskId, b.taskId)),
+			operations: [...event.plan.operations].sort((a, b) => compareStrings(a.operationId, b.operationId))
+		}
+	};
+	if (event.kind === "search-plan-extended") return {
+		...event,
+		artifacts,
+		extension: {
+			candidateSlots: [...event.extension.candidateSlots].sort((a, b) => compareStrings(a.slotId, b.slotId)),
+			operations: [...event.extension.operations].sort((a, b) => compareStrings(a.operationId, b.operationId))
+		}
+	};
+	if (event.kind === "candidate-registered") return {
+		...event,
+		artifacts,
+		lineage: {
+			...event.lineage,
+			parentCandidateIds: sortedStrings(event.lineage.parentCandidateIds)
+		},
+		surfaces: [...event.surfaces].map((surface) => ({
+			...surface,
+			artifact: { ...surface.artifact }
+		})).sort((a, b) => compareStrings(a.surfaceId, b.surfaceId))
+	};
+	if (event.kind === "task-attempted") return {
+		...event,
+		artifacts,
+		surfaceEvidence: [...event.surfaceEvidence].map((evidence) => ({
+			...evidence,
+			evidence: sortArtifacts(evidence.evidence)
+		})).sort((a, b) => compareStrings(a.surfaceId, b.surfaceId))
+	};
+	return {
+		...event,
+		artifacts
+	};
+}
+function sortArtifacts(artifacts) {
+	return [...artifacts].map((artifact) => ({ ...artifact })).sort((a, b) => compareStrings(artifactKey(a), artifactKey(b)));
+}
+function artifactKey(artifact) {
+	return canonicalString(artifact);
+}
+function compareStrings(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+function sortedStrings(values) {
+	return [...values].sort();
+}
+function assertUnique(values, label, eventId) {
+	if (new Set(values).size !== values.length) throw new SearchLedgerIntegrityError(`event ${eventId} contains duplicate ${label} values`);
+}
+function formatZodError(error) {
+	return error.issues.map((issue) => `${issue.path.length > 0 ? issue.path.join(".") : "<root>"}: ${issue.message}`).join("; ");
+}
+//#endregion
 //#region src/campaign/gepa-optimization-method.ts
 /**
 * Turn an optional GEPA installation into an `OptimizationMethod`.
@@ -1662,14 +2405,32 @@ function gepaOptimizationMethod(config) {
 				resumed: result.resumed
 			});
 			if (callback.evaluations() !== result.totalEvaluations) throw new Error(`${name}: GEPA reported ${result.totalEvaluations} evaluations but the callback received ${callback.evaluations()}`);
+			let searchHistory;
 			if (result.candidatePopulation) {
-				const population = readGepaCandidatePopulationArtifact({ summary: result.candidatePopulation });
+				const population = readGepaCandidatePopulationArtifact({
+					summary: result.candidatePopulation,
+					storage
+				});
 				const selected = population.candidates[population.bestIndex];
 				const selectedHash = contentHash({
 					kind: "external-text-candidate",
 					candidate: result.bestCandidate
 				});
 				if (selected?.candidateHash !== selectedHash) throw new Error(`${name}: GEPA candidate population identifies a different winner`);
+				if (config.searchLedger) searchHistory = await recordCandidatePopulationSearch({
+					ledger: openSearchLedger({
+						path: config.searchLedger.path ?? `${runDir}/search-ledger.jsonl`,
+						campaignId: runId
+					}),
+					storage,
+					runDir,
+					identity: config.searchLedger.identity,
+					population,
+					scenarios: input.selectionScenarios,
+					generationAccounting: optimizerAccounting(result.tokenUsage, result.proposerCostUsd),
+					producerId: name,
+					runId
+				});
 			}
 			const evaluationCost = costFromLedgerSummary(costLedger.summary({
 				phase: "gepa.external-evaluation",
@@ -1712,6 +2473,7 @@ function gepaOptimizationMethod(config) {
 			const externalTotalCostUsd = evaluationCost.totalCostUsd + reportedProposerCost;
 			return {
 				winnerSurface: decodeExternalTextCandidate(result.bestCandidate),
+				...searchHistory ? { searchHistory } : {},
 				cost: modelProxy ? meteredCost : {
 					totalCostUsd: externalTotalCostUsd,
 					costProvenance: result.proposerCostAccounting === "reported" && evaluationCost.costProvenance.kind !== "uncaptured" ? {
@@ -1752,6 +2514,30 @@ function gepaOptimizationMethod(config) {
 		}
 	};
 }
+/** Spend the optimizer booked to its own candidate generation. Unknown stays
+*  unknown: the bridge reports proposer cost only when the engine measured it. */
+function optimizerAccounting(tokenUsage, proposerCostUsd) {
+	return {
+		tokens: tokenUsage?.inputTokens === void 0 || tokenUsage.outputTokens === void 0 ? {
+			status: "unknown",
+			reason: "the optimizer bridge reported no token usage"
+		} : {
+			status: "known",
+			inputTokens: tokenUsage.inputTokens,
+			outputTokens: tokenUsage.outputTokens,
+			cachedTokens: 0
+		},
+		cost: proposerCostUsd === void 0 ? {
+			status: "unknown",
+			knownLowerBoundUsd: 0,
+			reason: "the optimizer bridge reported no proposer cost"
+		} : {
+			status: "known",
+			usd: proposerCostUsd,
+			source: "provider"
+		}
+	};
+}
 const MAX_TIMER_DELAY_MS = 2147483647;
 function snapshotSkillOptOptimizationConfig(config) {
 	const runner = snapshotExternalOptimizerRunner(config.runner);
@@ -2095,6 +2881,6 @@ function skillOptOptimizationMethod(config) {
 	};
 }
 //#endregion
-export { externalTextOptimizationMethod as a, REFERENCE_EQUIVALENCE_INPUT_LIMITS as c, runReferenceEquivalenceJudge as d, composeGate as i, REFERENCE_EQUIVALENCE_JUDGE_VERSION as l, gepaOptimizationMethod as n, decodeExternalTextCandidate as o, heldOutGate as r, readExternalOptimizerObservationArtifact as s, skillOptOptimizationMethod as t, createReferenceEquivalenceJudge as u };
+export { validateSearchLedgerEvent as a, externalTextOptimizationMethod as c, REFERENCE_EQUIVALENCE_INPUT_LIMITS as d, REFERENCE_EQUIVALENCE_JUDGE_VERSION as f, openSearchLedger as i, decodeExternalTextCandidate as l, runReferenceEquivalenceJudge as m, gepaOptimizationMethod as n, heldOutGate as o, createReferenceEquivalenceJudge as p, FileSearchLedger as r, composeGate as s, skillOptOptimizationMethod as t, readExternalOptimizerObservationArtifact as u };
 
-//# sourceMappingURL=skillopt-optimization-method-CPBlTcj5.js.map
+//# sourceMappingURL=skillopt-optimization-method-DbaekMcn.js.map