@tangle-network/agent-eval 0.131.1 → 0.132.0

package/dist/contract/index.js

@@ -1,9 +1,10 @@
 import { s as ValidationError } from "../errors-8YnH8WlF.js";
-import { L as createChatClient, t as buildDefaultAnalystRegistry } from "../default-registry-C-vFCSEc.js";
+import { L as createChatClient, t as buildDefaultAnalystRegistry } from "../default-registry-B1JcpnRv.js";
+import { i as CostLedger } from "../cost-ledger-ZAa_P4r0.js";
 import { LLM_MODEL_ATTR_KEYS, SPAN_KIND_ATTR_KEYS } from "../trace-attributes.js";
 import { b as classifyOtlpSpanRole, x as isOtlpModelCall } from "../tools-BmuN627J.js";
 import { r as mapConcurrentRange } from "../concurrency-MUjT7VjM.js";
-import { B as surfaceContentHash, Ct as llmJudge, M as compareOptimizationMethods, O as composeGate, Q as inMemoryCampaignStorage, S as defaultProductionGate, T as heldoutSignificance, V as surfaceHash, X as createRunCostLedger, Y as runCampaign, Z as fsCampaignStorage, _ as buildEvidenceVector, a as emitLoopProvenance, b as powerPreflight, ct as campaignSplitDigest, d as runImprovementLoop, dt as REFERENCE_EQUIVALENCE_INPUT_LIMITS, ft as REFERENCE_EQUIVALENCE_JUDGE_VERSION, g as gepaOptimizationMethod, j as assertOptimizationResult, k as externalTextOptimizationMethod, mt as runReferenceEquivalenceJudge, o as loopProvenanceArgsFromResult, p as runEval, pt as createReferenceEquivalenceJudge, rt as resolveRunDir, t as skillOptOptimizationMethod, v as paretoPolicy, x as heldOutGate, y as paretoSignificanceGate } from "../skillopt-optimization-method-eOJL2570.js";
+import { B as surfaceContentHash, Ct as llmJudge, M as compareOptimizationMethods, O as composeGate, Q as inMemoryCampaignStorage, S as defaultProductionGate, T as heldoutSignificance, V as surfaceHash, X as createRunCostLedger, Y as runCampaign, Z as fsCampaignStorage, _ as buildEvidenceVector, a as emitLoopProvenance, b as powerPreflight, ct as campaignSplitDigest, d as runImprovementLoop, dt as REFERENCE_EQUIVALENCE_INPUT_LIMITS, ft as REFERENCE_EQUIVALENCE_JUDGE_VERSION, g as gepaOptimizationMethod, j as assertOptimizationResult, k as externalTextOptimizationMethod, mt as runReferenceEquivalenceJudge, o as loopProvenanceArgsFromResult, p as runEval, pt as createReferenceEquivalenceJudge, rt as resolveRunDir, t as skillOptOptimizationMethod, v as paretoPolicy, x as heldOutGate, y as paretoSignificanceGate } from "../skillopt-optimization-method-CQlz8GQM.js";
 import { v as pairedBootstrap } from "../statistics-CnnxdpOg.js";
 import { i as parseRunRecordSafe, r as modelHasSnapshot } from "../run-record-CN8Zd21B.js";
 import { i as summarizeTraceErrors, n as recordAggregateMeasurements, r as summarizeExecutionMeasurements, t as readTaskFailureLabels } from "../task-failure-attributes-CQZlB3et.js";
@@ -14,7 +15,7 @@ import { a as fromPiSession, c as observeCodeAgentSession, i as fromOpenCodeSess
 import { t as createHostedClient } from "../client-CYzbdJOZ.js";
 import { dirname, join } from "node:path";
 import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
-import { agentCandidateBenchmarkSuiteSchema, agentCandidateBenchmarkTaskSchema, agentCandidateBundleSchema, agentCandidateEvaluationPolicySchema, agentCandidateExperimentSchema, agentImprovementMeasuredComparisonSchema, agentProfileImprovementExperimentSchema, agentProfileImprovementMeasuredComparisonSchema, agentProfileImprovementRunCellSchema, agentProfileImprovementRunReceiptSchema, agentProfileImprovementSuiteInputsSchema, agentProfileImprovementSuiteSchema, agentProfileImprovementTaskSchema, candidateExecutionEvidenceSchema, canonicalCandidateDigest, canonicalCandidateJson, omitTopLevelDigest } from "@tangle-network/agent-interface";
+import { agentCandidateBenchmarkSuiteSchema, agentCandidateBenchmarkTaskSchema, agentCandidateBundleSchema, agentCandidateEvaluationPolicySchema, agentCandidateExperimentSchema, agentImprovementMeasuredComparisonSchema, agentProfileImprovementExperimentSchema, agentProfileImprovementMeasuredComparisonSchema, agentProfileImprovementRunCellSchema, agentProfileImprovementRunReceiptSchema, agentProfileImprovementSuiteInputsSchema, agentProfileImprovementSuiteSchema, agentProfileImprovementTaskSchema, candidateExecutionEvidenceSchema, canonicalCandidateDigest, canonicalCandidateJson, numbersApproximatelyEqual, omitTopLevelDigest } from "@tangle-network/agent-interface";
 //#region src/contract/self-improve.ts
 /**
 * Run one complete improvement job.
@@ -546,6 +547,19 @@ function requirePositiveInteger(value, field) {
 	return value;
 }
 //#endregion
+//#region src/contract/fixed-spend.ts
+function addFixedSpend(left, right) {
+	return {
+		inputTokens: left.inputTokens + right.inputTokens,
+		outputTokens: left.outputTokens + right.outputTokens,
+		cachedInputTokens: left.cachedInputTokens + right.cachedInputTokens,
+		reasoningTokens: left.reasoningTokens + right.reasoningTokens,
+		modelCalls: left.modelCalls + right.modelCalls,
+		costUsdNanos: left.costUsdNanos + right.costUsdNanos,
+		costProvenance: left.costProvenance === "observed" && right.costProvenance === "observed" ? "observed" : "estimated"
+	};
+}
+//#endregion
 //#region src/contract/concurrent-map.ts
 /** Map both arms while bounding the actual executions, not the number of pairs. */
 async function mapPairedConcurrent(options) {
@@ -568,6 +582,62 @@ async function mapPairedConcurrent(options) {
 	}));
 }
 //#endregion
+//#region src/contract/paid-paired-measurement.ts
+/**
+* Reserve the complete signed suite before its first cell starts.
+*
+* The host executor receives each task's signed cap through `execute`; this
+* batch reservation prevents a complete comparison from turning into a partial
+* one after earlier analysis or search has used the remaining budget.
+*/
+async function runPaidPairedMeasurement(options) {
+	assertNonNegativeFinite(options.maximumCostUsd, "maximumCostUsd");
+	const costLedger = resolveCostLedger(options);
+	const startedAt = performance.now();
+	const paid = await costLedger.runPaidCall({
+		callId: options.call.callId,
+		channel: options.call.channel,
+		phase: options.call.phase,
+		actor: options.call.actor,
+		model: options.call.model,
+		maximumCharge: { externallyEnforcedMaximumUsd: options.maximumCostUsd },
+		...options.call.tags ? { tags: options.call.tags } : {},
+		...options.signal ? { signal: options.signal } : {},
+		execute: async (signal) => await mapPairedConcurrent({
+			count: options.count,
+			maxConcurrency: options.maxConcurrency,
+			label: options.label,
+			signal,
+			map: options.execute
+		}),
+		receipt: options.receipt
+	});
+	const wallDurationMs = performance.now() - startedAt;
+	if (!paid.succeeded) throw paid.error;
+	if (paid.receipt.costUnknown) throw new Error(`${options.label} did not capture the complete measurement cost`);
+	return {
+		measurements: paid.value,
+		wallDurationMs,
+		cost: paid.receipt.actualCostUsd === void 0 ? {
+			kind: "estimated",
+			usd: paid.receipt.costUsd
+		} : {
+			kind: "observed",
+			usd: paid.receipt.costUsd
+		}
+	};
+}
+function resolveCostLedger(options) {
+	if (options.budgetUsd === void 0) return options.costLedger ?? new CostLedger();
+	assertNonNegativeFinite(options.budgetUsd, "budgetUsd");
+	if (!options.costLedger) throw new Error(`${options.label} with a policy budget requires one shared CostLedger`);
+	if (options.costLedger.costCeilingUsd !== options.budgetUsd) throw new Error(`${options.label} CostLedger ceiling must equal the frozen policy budget`);
+	return options.costLedger;
+}
+function assertNonNegativeFinite(value, label) {
+	if (!Number.isFinite(value) || value < 0) throw new Error(`${label} must be a non-negative finite number`);
+}
+//#endregion
 //#region src/contract/measured-comparison.ts
 /** Content-address one task before any measured execution can see it. */
 function sealCandidateBenchmarkTask(material) {
@@ -614,12 +684,23 @@ function verifyCandidateExperiment(input) {
 async function runCandidateExperiment(options) {
 	const experiment = verifyCandidateExperiment(options.experiment);
 	const { suite, tasks } = experiment.benchmark;
-	return (await mapPairedConcurrent({
+	const run = await runPaidPairedMeasurement({
 		count: suite.taskDigests.length * suite.reps,
 		maxConcurrency: options.maxConcurrency ?? 2,
 		label: "candidate experiment",
+		budgetUsd: experiment.policy.budgetUsd,
+		...options.costLedger ? { costLedger: options.costLedger } : {},
+		maximumCostUsd: candidateMeasurementMaximumCostUsd(experiment),
+		call: {
+			callId: `candidate-measurement:${experiment.digest}`,
+			channel: "measurement",
+			phase: "heldout",
+			actor: experiment.digest,
+			model: candidateMeasurementModel(experiment),
+			tags: { experimentDigest: experiment.digest }
+		},
 		...options.signal ? { signal: options.signal } : {},
-		async map(index, arm, signal) {
+		async execute(index, arm, signal) {
 			const taskIndex = Math.floor(index / suite.reps);
 			const repetition = index % suite.reps;
 			const task = tasks[taskIndex];
@@ -630,7 +711,7 @@ async function runCandidateExperiment(options) {
 				taskIndex,
 				repetition
 			};
-			return options.execute({
+			return verifyExecutionEvidence(await options.execute({
 				experiment,
 				arm,
 				bundle: experiment[arm],
@@ -638,9 +719,22 @@ async function runCandidateExperiment(options) {
 				benchmarkCell,
 				seed,
 				signal
-			});
+			}));
+		},
+		receipt(measurements) {
+			return candidateMeasurementCostReceipt(measurements, candidateMeasurementModel(experiment));
+		}
+	});
+	return {
+		measurements: run.measurements.map((measurement, index) => verifyMeasurement(experiment, measurement, index)),
+		measurement: {
+			wallDurationMs: run.wallDurationMs,
+			cost: {
+				usd: run.cost.usd,
+				provenance: run.cost.kind
+			}
 		}
-	})).map((measurement, index) => verifyMeasurement(experiment, measurement, index));
+	};
 }
 /**
 * Calculate the shared paired decision from any complete receipt shape.
@@ -651,8 +745,11 @@ async function runCandidateExperiment(options) {
 */
 function evaluatePairedMeasurements(options) {
 	if (options.measurements.length === 0) throw new Error("paired measurement evaluation requires at least one paired cell");
-	const additionalCostUsd = options.additionalCostUsd ?? 0;
-	if (!Number.isFinite(additionalCostUsd) || additionalCostUsd < 0) throw new Error("paired measurement evaluation additionalCostUsd must be a non-negative number");
+	const preparationCost = options.preparationCost ?? {
+		usd: 0,
+		provenance: "observed"
+	};
+	if (!Number.isFinite(preparationCost.usd) || preparationCost.usd < 0) throw new Error("paired measurement evaluation preparation cost must be a non-negative number");
 	if (typeof options.sharedScorerChannel !== "boolean") throw new Error("paired measurement evaluation sharedScorerChannel must be a boolean");
 	const policy = agentCandidateEvaluationPolicySchema.parse(options.policy);
 	const measurements = options.measurements.map((measurement, index) => projectPairedMeasurement(measurement, index, options.adapter));
@@ -738,12 +835,22 @@ function evaluatePairedMeasurements(options) {
 	const guardedDimensions = new Set(criticalDimensions);
 	const missingCriticalDimensions = criticalDimensions.filter((dimension) => !dimensions.includes(dimension));
 	const regressions = objectives.filter((objective) => objective.kind === "dimension" && guardedDimensions.has(objective.name) && objective.availability === "measured" && objective.confidenceInterval.lower < -regressionTolerance);
-	const executionCostUsd = measurements.reduce((sum, measurement) => sum + measurement.baseline.costUsd + measurement.candidate.costUsd, 0);
-	const executionDurationMs = measurements.reduce((sum, measurement) => sum + measurement.baseline.latencyMs + measurement.candidate.latencyMs, 0);
+	const measurementCostUsd = measurements.reduce((sum, measurement) => sum + measurement.baseline.costUsd + measurement.candidate.costUsd, 0);
+	const measurementWorkDurationMs = measurements.reduce((sum, measurement) => sum + measurement.baseline.latencyMs + measurement.candidate.latencyMs, 0);
 	const incompleteRuns = measurements.flatMap((measurement) => [measurement.baseline, measurement.candidate]).filter((run) => !run.completed);
 	const failedCandidateResults = measurements.filter((measurement) => !measurement.candidate.passed);
-	const totalCostUsd = executionCostUsd + additionalCostUsd;
-	const budgetPassed = budgetUsd === void 0 || totalCostUsd <= budgetUsd;
+	const derivedMeasurementCost = {
+		usd: measurementCostUsd,
+		provenance: measurements.every((measurement) => measurement.baseline.costProvenance === "observed" && measurement.candidate.costProvenance === "observed") ? "observed" : "estimated"
+	};
+	const measurementCost = options.measurementCost ?? derivedMeasurementCost;
+	assertKnownCost(measurementCost, "paired measurement cost");
+	if (options.measurementCost !== void 0 && (measurementCost.provenance !== derivedMeasurementCost.provenance || !numbersApproximatelyEqual(measurementCost.usd, derivedMeasurementCost.usd))) throw new Error("paired measurement cost does not match its signed receipts");
+	const totalCost = {
+		usd: preparationCost.usd + measurementCost.usd,
+		provenance: preparationCost.provenance === "observed" && measurementCost.provenance === "observed" ? "observed" : "estimated"
+	};
+	const budgetPassed = budgetUsd === void 0 || totalCost.usd < budgetUsd || numbersApproximatelyEqual(totalCost.usd, budgetUsd);
 	const checks = [
 		{
 			name: "paired-significance",
@@ -778,7 +885,7 @@ function evaluatePairedMeasurements(options) {
 		...missingCriticalDimensions.length === 0 ? [] : [`critical dimensions missing: ${missingCriticalDimensions.join(", ")}`],
 		...incompleteRuns.length === 0 ? [] : [`${incompleteRuns.length} benchmark executions did not exit successfully`],
 		...failedCandidateResults.length === 0 ? [] : [`candidate failed ${failedCandidateResults.length} benchmark tasks`],
-		...budgetPassed ? [] : [`total cost ${totalCostUsd} exceeded budget ${budgetUsd}`]
+		...budgetPassed ? [] : [`total cost ${totalCost.usd} exceeded budget ${budgetUsd}`]
 	];
 	return {
 		overall: {
@@ -802,9 +909,9 @@ function evaluatePairedMeasurements(options) {
 			sharedScorerChannel: options.sharedScorerChannel,
 			reason: power.reason
 		},
-		executionCostUsd,
-		totalCostUsd,
-		executionDurationMs
+		measurementCost,
+		totalCost,
+		measurementWorkDurationMs
 	};
 }
 /** Build the only publishable comparison: paired statistics over Runtime receipts. */
@@ -815,7 +922,8 @@ function measuredComparisonFromCandidateExperiment(options) {
 	if (measurements.length !== expectedN) throw new Error(`candidate experiment is incomplete (${measurements.length}/${expectedN} paired cells)`);
 	verifyStableProfileMaterialization(measurements);
 	if (!options.runId.trim()) throw new Error("candidate experiment runId is required");
-	const searchCostUsd = options.searchCostUsd ?? 0;
+	assertPhaseAccounting(options.preparation, "candidate preparation");
+	assertPhaseAccounting(options.measurement, "candidate measurement");
 	const evaluation = evaluatePairedMeasurements({
 		measurements: measurements.map((measurement, index) => ({
 			cellId: cellIds(experiment)[index],
@@ -824,12 +932,10 @@ function measuredComparisonFromCandidateExperiment(options) {
 		policy: experiment.policy,
 		adapter: candidateExecutionEvidenceAdapter,
 		sharedScorerChannel: true,
-		additionalCostUsd: searchCostUsd
+		preparationCost: options.preparation.cost,
+		measurementCost: options.measurement.cost
 	});
 	const diff = deriveCandidateBundleDiff(experiment);
-	const searchDurationMs = options.searchDurationMs ?? 0;
-	const totalCostUsd = evaluation.totalCostUsd;
-	const durationMs = evaluation.executionDurationMs + searchDurationMs;
 	const provisional = agentImprovementMeasuredComparisonSchema.parse({
 		kind: "agent-improvement-measured-comparison",
 		experiment,
@@ -850,12 +956,16 @@ function measuredComparisonFromCandidateExperiment(options) {
 		diff,
 		evaluation: {
 			generationsExplored: options.generationsExplored ?? 0,
-			searchDurationMs,
-			executionDurationMs: evaluation.executionDurationMs,
-			durationMs,
-			searchCostUsd,
-			executionCostUsd: evaluation.executionCostUsd,
-			totalCostUsd
+			preparation: options.preparation,
+			measurement: {
+				wallDurationMs: options.measurement.wallDurationMs,
+				workDurationMs: evaluation.measurementWorkDurationMs,
+				cost: evaluation.measurementCost
+			},
+			total: {
+				wallDurationMs: options.preparation.wallDurationMs + options.measurement.wallDurationMs,
+				cost: evaluation.totalCost
+			}
 		},
 		...options.metadata ? { metadata: options.metadata } : {}
 	});
@@ -880,12 +990,52 @@ function verifyCandidateExperimentComparison(input) {
 		runId: comparison.provenance.runId,
 		...comparison.candidate ? { candidate: comparison.candidate } : {},
 		generationsExplored: comparison.evaluation.generationsExplored,
-		searchDurationMs: comparison.evaluation.searchDurationMs,
-		searchCostUsd: comparison.evaluation.searchCostUsd,
+		preparation: comparison.evaluation.preparation,
+		measurement: {
+			wallDurationMs: comparison.evaluation.measurement.wallDurationMs,
+			cost: comparison.evaluation.measurement.cost
+		},
 		...comparison.metadata ? { metadata: comparison.metadata } : {}
 	})) !== canonicalCandidateDigest(comparison)) throw new Error("candidate experiment comparison does not match its Runtime receipts");
 	return comparison;
 }
+function candidateMeasurementMaximumCostUsd(experiment) {
+	const maximum = experiment.benchmark.tasks.reduce((sum, task) => sum + task.limits.maxCostUsd * experiment.benchmark.suite.reps * 2, 0);
+	if (!Number.isFinite(maximum) || maximum < 0) throw new Error("candidate measurement maximum cost is invalid");
+	return maximum;
+}
+function candidateMeasurementModel(experiment) {
+	const models = [...new Set(experiment.benchmark.tasks.map((task) => task.model.model))];
+	return models.length === 1 ? models[0] : "multiple-models";
+}
+function candidateMeasurementCostReceipt(measurements, model) {
+	const usage = measurements.reduce((sum, measurement) => addFixedSpend(addFixedSpend(sum, combinedUsage(measurement.baseline)), combinedUsage(measurement.candidate)), {
+		inputTokens: 0,
+		outputTokens: 0,
+		cachedInputTokens: 0,
+		reasoningTokens: 0,
+		modelCalls: 0,
+		costUsdNanos: 0,
+		costProvenance: "observed"
+	});
+	const costUsd = usage.costUsdNanos / 1e9;
+	return {
+		model,
+		inputTokens: usage.inputTokens,
+		outputTokens: usage.outputTokens,
+		cachedTokens: usage.cachedInputTokens,
+		reasoningTokens: usage.reasoningTokens,
+		...usage.costProvenance === "observed" ? { actualCostUsd: costUsd } : { estimatedCostUsd: costUsd }
+	};
+}
+function assertPhaseAccounting(accounting, label) {
+	if (!Number.isFinite(accounting.wallDurationMs) || accounting.wallDurationMs < 0) throw new Error(`${label} wall duration must be a non-negative number`);
+	assertKnownCost(accounting.cost, `${label} cost`);
+}
+function assertKnownCost(cost, label) {
+	if (!Number.isFinite(cost.usd) || cost.usd < 0) throw new Error(`${label} must be a non-negative number`);
+	if (cost.provenance !== "observed" && cost.provenance !== "estimated") throw new Error(`${label} provenance must be observed or estimated`);
+}
 function deriveCandidateBundleDiff(experiment) {
 	const changed = [
 		"profile",
@@ -1061,10 +1211,13 @@ function projectRun(run, adapter, label) {
 	const completed = adapter.completed(run);
 	const passed = adapter.passed(run);
 	if (typeof completed !== "boolean" || typeof passed !== "boolean") throw new Error(`${label} completion and pass values must be booleans`);
+	const costProvenance = adapter.costProvenance(run);
+	if (costProvenance !== "observed" && costProvenance !== "estimated") throw new Error(`${label} cost provenance must be observed or estimated`);
 	return {
 		score: finiteMeasurement(adapter.score(run), `${label} score`),
 		dimensions,
 		costUsd: nonNegativeMeasurement(adapter.costUsd(run), `${label} cost`),
+		costProvenance,
 		latencyMs: nonNegativeMeasurement(adapter.latencyMs(run), `${label} latency`),
 		completed,
 		passed
@@ -1149,6 +1302,7 @@ const candidateExecutionEvidenceAdapter = {
 	score: (evidence) => evidence.receipt.benchmarkResult.material.score,
 	dimensions: (evidence) => evidence.receipt.benchmarkResult.material.dimensions,
 	costUsd: costFromEvidence,
+	costProvenance: (evidence) => combinedUsage(evidence).costProvenance,
 	latencyMs: latencyFromEvidence,
 	completed: completedSuccessfully,
 	passed: (evidence) => evidence.receipt.benchmarkResult.material.passed
@@ -1162,14 +1316,7 @@ function latencyFromEvidence(evidence) {
 function combinedUsage(evidence) {
 	const candidate = evidence.receipt.modelSettlement.material.usage;
 	const grader = evidence.receipt.benchmarkResult.material.grading.usage;
-	return {
-		inputTokens: candidate.inputTokens + grader.inputTokens,
-		outputTokens: candidate.outputTokens + grader.outputTokens,
-		cachedInputTokens: candidate.cachedInputTokens + grader.cachedInputTokens,
-		reasoningTokens: candidate.reasoningTokens + grader.reasoningTokens,
-		modelCalls: candidate.modelCalls + grader.modelCalls,
-		costUsdNanos: candidate.costUsdNanos + grader.costUsdNanos
-	};
+	return addFixedSpend(candidate, grader);
 }
 function cellIds(experiment) {
 	const { suite, tasks } = experiment.benchmark;
@@ -1235,15 +1382,45 @@ function verifyAgentProfileImprovementExperiment(input) {
 */
 async function runAgentProfileImprovementExperiment(options) {
 	const experiment = verifyAgentProfileImprovementExperiment(options.experiment);
-	return (await mapPairedConcurrent({
+	const run = await runPaidPairedMeasurement({
 		count: experiment.benchmark.suite.taskDigests.length * experiment.benchmark.suite.reps,
 		maxConcurrency: options.maxConcurrency ?? 2,
 		label: "profile improvement experiment",
+		budgetUsd: experiment.policy.budgetUsd,
+		...options.costLedger ? { costLedger: options.costLedger } : {},
+		maximumCostUsd: profileMeasurementMaximumCostUsd(experiment),
+		call: {
+			callId: `profile-improvement-measurement:${experiment.digest}`,
+			channel: "measurement",
+			phase: "heldout",
+			actor: experiment.executionRef.identity,
+			model: profileMeasurementModel(experiment),
+			tags: {
+				experimentDigest: experiment.digest,
+				executorDigest: experiment.executionRef.digest
+			}
+		},
 		...options.signal ? { signal: options.signal } : {},
-		map(index, arm, signal) {
-			return options.execute(profileExecutionInput(experiment, arm, index, signal));
+		async execute(index, arm, signal) {
+			const expected = profileExecutionInput(experiment, arm, index, signal);
+			const receipt = agentProfileImprovementRunReceiptSchema.parse(await options.execute(expected));
+			verifyProfileReceiptContract(receipt, expected, index);
+			return receipt;
+		},
+		receipt(measurements) {
+			return profileMeasurementCostReceipt(measurements, profileMeasurementModel(experiment));
 		}
-	})).map((measurement, index) => verifyProfileMeasurement(experiment, measurement, index));
+	});
+	return {
+		measurements: run.measurements.map((measurement, index) => verifyProfileMeasurement(experiment, measurement, index)),
+		measurement: {
+			wallDurationMs: run.wallDurationMs,
+			cost: {
+				usd: run.cost.usd,
+				provenance: run.cost.kind
+			}
+		}
+	};
 }
 /** Build the only publishable profile comparison from complete host receipts. */
 function measuredComparisonFromAgentProfileImprovementExperiment(options) {
@@ -1252,8 +1429,6 @@ function measuredComparisonFromAgentProfileImprovementExperiment(options) {
 	const expectedCount = experiment.benchmark.suite.taskDigests.length * experiment.benchmark.suite.reps;
 	if (measurements.length !== expectedCount) throw new Error(`profile improvement experiment is incomplete (${measurements.length}/${expectedCount} paired cells)`);
 	if (!options.runId.trim()) throw new Error("profile improvement experiment runId is required");
-	const searchCostUsd = nonNegative(options.searchCostUsd ?? 0, "searchCostUsd");
-	const searchDurationMs = nonNegative(options.searchDurationMs ?? 0, "searchDurationMs");
 	const evaluation = evaluatePairedMeasurements({
 		measurements: measurements.map((measurement, index) => ({
 			cellId: profileCellId(experiment, index),
@@ -1262,7 +1437,8 @@ function measuredComparisonFromAgentProfileImprovementExperiment(options) {
 		policy: experiment.policy,
 		adapter: profileReceiptAdapter,
 		sharedScorerChannel: true,
-		additionalCostUsd: searchCostUsd
+		preparationCost: options.preparation.cost,
+		measurementCost: options.measurement.cost
 	});
 	const provisional = agentProfileImprovementMeasuredComparisonSchema.parse({
 		kind: "agent-profile-improvement-measured-comparison",
@@ -1284,12 +1460,16 @@ function measuredComparisonFromAgentProfileImprovementExperiment(options) {
 		diff: canonicalCandidateJson(experiment.change),
 		evaluation: {
 			generationsExplored: options.generationsExplored ?? 0,
-			searchDurationMs,
-			executionDurationMs: evaluation.executionDurationMs,
-			durationMs: evaluation.executionDurationMs + searchDurationMs,
-			searchCostUsd,
-			executionCostUsd: evaluation.executionCostUsd,
-			totalCostUsd: evaluation.totalCostUsd
+			preparation: options.preparation,
+			measurement: {
+				wallDurationMs: options.measurement.wallDurationMs,
+				workDurationMs: evaluation.measurementWorkDurationMs,
+				cost: evaluation.measurementCost
+			},
+			total: {
+				wallDurationMs: options.preparation.wallDurationMs + options.measurement.wallDurationMs,
+				cost: evaluation.totalCost
+			}
 		},
 		...options.metadata ? { metadata: options.metadata } : {}
 	});
@@ -1314,12 +1494,48 @@ function verifyAgentProfileImprovementExperimentComparison(input) {
 		runId: comparison.provenance.runId,
 		...comparison.candidate ? { candidate: comparison.candidate } : {},
 		generationsExplored: comparison.evaluation.generationsExplored,
-		searchDurationMs: comparison.evaluation.searchDurationMs,
-		searchCostUsd: comparison.evaluation.searchCostUsd,
+		preparation: comparison.evaluation.preparation,
+		measurement: {
+			wallDurationMs: comparison.evaluation.measurement.wallDurationMs,
+			cost: comparison.evaluation.measurement.cost
+		},
 		...comparison.metadata ? { metadata: comparison.metadata } : {}
 	})) !== canonicalCandidateDigest(comparison)) throw new Error("profile improvement comparison does not match its Runtime receipts");
 	return comparison;
 }
+function profileMeasurementMaximumCostUsd(experiment) {
+	const pairs = experiment.benchmark.suite.reps;
+	const maximum = experiment.benchmark.tasks.reduce((sum, task) => sum + task.limits.maxCostUsd * pairs * 2, 0);
+	if (!Number.isFinite(maximum) || maximum < 0) throw new Error("profile improvement measurement maximum cost is invalid");
+	return maximum;
+}
+function profileMeasurementModel(experiment) {
+	const models = [...new Set(experiment.benchmark.tasks.map((task) => task.model.model))];
+	return models.length === 1 ? models[0] : "multiple-models";
+}
+function profileMeasurementCostReceipt(measurements, model) {
+	const usage = measurements.reduce((sum, measurement) => addFixedSpend(addFixedSpend(sum, combinedProfileUsage(measurement.baseline)), combinedProfileUsage(measurement.candidate)), {
+		inputTokens: 0,
+		outputTokens: 0,
+		cachedInputTokens: 0,
+		reasoningTokens: 0,
+		modelCalls: 0,
+		costUsdNanos: 0,
+		costProvenance: "observed"
+	});
+	const costUsd = usage.costUsdNanos / 1e9;
+	return {
+		model,
+		inputTokens: usage.inputTokens,
+		outputTokens: usage.outputTokens,
+		cachedTokens: usage.cachedInputTokens,
+		reasoningTokens: usage.reasoningTokens,
+		...usage.costProvenance === "observed" ? { actualCostUsd: costUsd } : { estimatedCostUsd: costUsd }
+	};
+}
+function combinedProfileUsage(receipt) {
+	return addFixedSpend(receipt.usage, receipt.grading.usage);
+}
 function profileExecutionInput(experiment, arm, index, signal) {
 	const { task, taskIndex, repetition, seed } = profileCell(experiment, index);
 	const stateDigest = experiment[arm].stateDigest;
@@ -1356,17 +1572,18 @@ function verifyProfileMeasurement(experiment, input, index) {
 	const baseline = agentProfileImprovementRunReceiptSchema.parse(material.baseline);
 	const candidate = agentProfileImprovementRunReceiptSchema.parse(material.candidate);
 	if (baseline.runCell.digest !== expectedBaseline.runCell.digest || candidate.runCell.digest !== expectedCandidate.runCell.digest) throw new Error(`profile improvement measurement ${index} substituted a measured arm`);
-	verifyProfileReceiptTaskContract(baseline, expectedBaseline, index);
-	verifyProfileReceiptTaskContract(candidate, expectedCandidate, index);
+	verifyProfileReceiptContract(baseline, expectedBaseline, index);
+	verifyProfileReceiptContract(candidate, expectedCandidate, index);
 	if (baseline.executionId === candidate.executionId || baseline.digest === candidate.digest) throw new Error(`profile improvement measurement ${index} reused one execution across arms`);
 	return {
 		baseline,
 		candidate
 	};
 }
-function verifyProfileReceiptTaskContract(receipt, expected, index) {
+function verifyProfileReceiptContract(receipt, expected, index) {
 	const task = expected.task;
 	if (canonicalCandidateDigest(receipt.resolvedModel) !== canonicalCandidateDigest(task.model) || canonicalCandidateDigest(receipt.limits) !== canonicalCandidateDigest(task.limits) || canonicalCandidateDigest(receipt.grading.grader) !== canonicalCandidateDigest(task.grader)) throw new Error(`profile improvement measurement ${index} substituted its ${expected.arm} task contract`);
+	if (canonicalCandidateDigest(receipt.executionRef) !== canonicalCandidateDigest(expected.experiment.executionRef)) throw new Error(`profile improvement measurement ${index} substituted its ${expected.arm} executor`);
 }
 function profileCell(experiment, index) {
 	const { suite, tasks } = experiment.benchmark;
@@ -1389,14 +1606,11 @@ const profileReceiptAdapter = {
 	score: (receipt) => receipt.grading.score,
 	dimensions: (receipt) => receipt.grading.dimensions,
 	costUsd: (receipt) => (receipt.usage.costUsdNanos + receipt.grading.usage.costUsdNanos) / 1e9,
+	costProvenance: (receipt) => receipt.usage.costProvenance === "observed" && receipt.grading.usage.costProvenance === "observed" ? "observed" : "estimated",
 	latencyMs: (receipt) => receipt.timing.durationMs + receipt.grading.timing.durationMs,
 	completed: (receipt) => receipt.outcome.status === "succeeded",
 	passed: (receipt) => receipt.grading.passed
 };
-function nonNegative(value, label) {
-	if (!Number.isFinite(value) || value < 0) throw new Error(`${label} must be a non-negative number`);
-	return value;
-}
 //#endregion
 //#region src/contract/intake/run-record-dir.ts
 /**