@tangle-network/agent-eval 0.137.0 → 0.138.0

package/dist/{default-registry-CLXbRt0f.js → default-registry-lp5R0lve.js}

@@ -1,10 +1,13 @@
-import { i as CostLedger } from "./cost-ledger-D-5_-dhi.js";
-import { f as maximumChargeForLlmRequest, l as costReceiptFromLlm, n as LlmClient, s as callLlm, u as costReceiptFromLlmError } from "./llm-client-DKB25jV8.js";
+import { i as CostLedger } from "./cost-ledger-CHDLA0Ss.js";
+import { f as maximumChargeForLlmRequest, l as costReceiptFromLlm, n as LlmClient, s as callLlm, u as costReceiptFromLlmError } from "./llm-client-Cj3c7PEm.js";
 import { LLM_CONTEXT_TOKENS, LLM_INPUT_TOKEN_ATTR_KEYS, LLM_OUTPUT_TOKEN_ATTR_KEYS, TOOL_NAME_ATTR_KEYS } from "./trace-attributes.js";
 import { t as executionTrackByLane } from "./execution-tracks-CpgFPpS5.js";
-import { O as spanEpochMillis, a as runTraceAnalysisLoop, r as buildTraceAnalystTools } from "./tools-DZk2Jn64.js";
-import { c as makeFinding, o as combineAbortSignals } from "./proposal-findings-DCawte-y.js";
+import { D as spanEpochMillis } from "./store-otlp-BenKynPE.js";
+import { f as validateUsageSettlementTimeout, l as assertValidAnalystUsageReceipt, m as makeFinding, u as settleUsageReceiptFromCostLedger } from "./single-run-lock-D_bS5xhj.js";
+import { _ as canonicalString, v as hashCanonical } from "./ledger-core-C0Yx1I14.js";
+import { a as runTraceAnalysisLoop, r as buildTraceAnalystTools } from "./tools-DZGdROtG.js";
 import { t as analyzeSupervisorRunIntegrity } from "./integrity-CCXTftiL.js";
+import { o as combineAbortSignals } from "./proposal-findings-2GIUo1et.js";
 import { ai } from "@ax-llm/ax";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
@@ -551,6 +554,11 @@ function behavioralAnalyst(options = {}) {
 		inputKind: "trace-store",
 		cost: { kind: "deterministic" },
 		version: "2.0.0",
+		executionConfig: {
+			kind: "behavioral-efficiency",
+			max_traces: maxTraces,
+			max_evidence_refs_per_finding: maxEvidenceRefsPerFinding
+		},
 		async analyze(store, context) {
 			const analyzedTraceIds = await listTraceIds(store, maxTraces, context.signal);
 			const findingsById = /* @__PURE__ */ new Map();
@@ -692,6 +700,7 @@ function boundOutputTokens(request, limit) {
 	const maxTokens = requested === void 0 ? limit : Math.min(requested, limit);
 	return {
 		...request,
+		...request.functionCall === void 0 && !request.functions?.length ? { functionCall: "none" } : {},
 		modelConfig: {
 			...request.modelConfig,
 			maxTokens,
@@ -800,6 +809,221 @@ function assertPositiveInteger(value, field) {
 	if (!Number.isSafeInteger(value) || value <= 0) throw new RangeError(`meterAxChatService: ${field} must be a positive integer`);
 }
 //#endregion
+//#region src/ledger-core/deep-freeze.ts
+/** Freeze a detached canonical-JSON graph. Canonicalization has already ruled out cycles.
+*
+* Lives outside canonical.ts so the analyst-benchmark implementation digest,
+* which covers canonical.ts, stays bound to the published benchmark evidence. */
+function deepFreezeCanonicalJson(value) {
+	if (value && typeof value === "object" && !Object.isFrozen(value)) {
+		Object.freeze(value);
+		for (const nested of Object.values(value)) deepFreezeCanonicalJson(nested);
+	}
+	return value;
+}
+//#endregion
+//#region src/analyst/exact-types.ts
+/** Canonical identity for any live component admitted to an exact run. */
+function snapshotExactExecutionComponentIdentity(value, context) {
+	let detached;
+	try {
+		detached = JSON.parse(canonicalString(value));
+	} catch (cause) {
+		throw new TypeError(`${context} must have a canonical JSON representation`, { cause });
+	}
+	const parsed = componentIdentitySchema.safeParse(detached);
+	if (!parsed.success) throw new TypeError(`${context} requires non-empty id/version and object config`);
+	return deepFreezeCanonicalJson({
+		id: parsed.data.id,
+		version: parsed.data.version,
+		config_digest: hashCanonical(parsed.data.config)
+	});
+}
+const nonEmptyString = z.string().min(1);
+const digest = z.string().regex(/^sha256:[a-f0-9]{64}$/);
+const finiteNonnegative$1 = z.number().finite().nonnegative();
+const nonnegativeSafeInteger$1 = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+const positiveTimeout = z.number().int().positive().max(2147483647);
+const componentSnapshotSchema = z.strictObject({
+	id: nonEmptyString,
+	version: nonEmptyString,
+	config_digest: digest
+});
+const componentIdentitySchema = z.strictObject({
+	id: nonEmptyString,
+	version: nonEmptyString,
+	config: z.record(z.string(), z.unknown())
+});
+const deterministicCostSchema = z.strictObject({
+	kind: z.literal("deterministic"),
+	est_usd_per_run: finiteNonnegative$1.optional(),
+	models: z.array(nonEmptyString).optional()
+});
+const llmCostSchema = z.strictObject({
+	kind: z.literal("llm"),
+	est_usd_per_run: finiteNonnegative$1.optional(),
+	models: z.array(nonEmptyString).optional(),
+	settlement_timeout_ms: nonnegativeSafeInteger$1.optional()
+});
+const requirementsSchema = z.strictObject({
+	min_shots: nonnegativeSafeInteger$1.optional(),
+	capabilities: z.array(nonEmptyString).optional()
+}).nullable();
+const analystSnapshotSchema = z.strictObject({
+	id: nonEmptyString,
+	version: nonEmptyString,
+	input_kind: z.enum([
+		"trace-store",
+		"artifact-dir",
+		"run-record",
+		"judge-input",
+		"custom"
+	]),
+	cost: z.discriminatedUnion("kind", [deterministicCostSchema, llmCostSchema]),
+	requirements: requirementsSchema,
+	execution_config_digest: digest
+});
+const allocationsSchema = z.record(nonEmptyString, z.union([finiteNonnegative$1, z.null()]));
+const weightsSchema = z.record(nonEmptyString, finiteNonnegative$1);
+const budgetSnapshotSchema = z.discriminatedUnion("kind", [
+	z.strictObject({ kind: z.literal("none") }),
+	z.strictObject({
+		kind: z.literal("equal"),
+		total_usd: finiteNonnegative$1,
+		allocations_usd: allocationsSchema
+	}),
+	z.strictObject({
+		kind: z.literal("weighted"),
+		total_usd: finiteNonnegative$1,
+		weights: weightsSchema,
+		allocations_usd: allocationsSchema
+	})
+]);
+const priorFindingsSchema = z.discriminatedUnion("kind", [
+	z.strictObject({ kind: z.literal("none") }),
+	z.strictObject({
+		kind: z.literal("ordered"),
+		count: nonnegativeSafeInteger$1,
+		digest
+	}),
+	z.strictObject({
+		kind: z.literal("by_analyst"),
+		keys: z.array(nonEmptyString),
+		count: nonnegativeSafeInteger$1,
+		digest
+	})
+]);
+const exactRunPolicySchema = z.strictObject({
+	budget: budgetSnapshotSchema,
+	total_timeout_ms: positiveTimeout.nullable(),
+	signal_provided: z.boolean(),
+	cost_ledger: componentSnapshotSchema.nullable(),
+	cost_phase: nonEmptyString.nullable(),
+	tags: z.record(z.string(), z.string()).nullable(),
+	prior_findings: priorFindingsSchema,
+	chain_findings: z.boolean(),
+	missing_input_mode: z.enum(["skip", "abort"]),
+	registry_hooks: componentSnapshotSchema.nullable(),
+	registry_chat: componentSnapshotSchema.nullable()
+});
+const exactExecutionPlanSchema = z.strictObject({
+	schema_version: z.literal("1.0.0"),
+	analysts: z.array(analystSnapshotSchema).min(1),
+	policy: exactRunPolicySchema,
+	digest
+}).superRefine((plan, context) => {
+	const issue = (path, message) => context.addIssue({
+		code: "custom",
+		path,
+		message
+	});
+	const analystIds = plan.analysts.map((analyst) => analyst.id);
+	if (new Set(analystIds).size !== analystIds.length) issue(["analysts"], "analyst ids must be unique");
+	if (plan.policy.cost_ledger === null && plan.policy.cost_phase !== null) issue(["policy", "cost_phase"], "cost phase requires a cost ledger");
+	if (plan.policy.prior_findings.kind === "by_analyst" && plan.policy.prior_findings.keys.some((key, index, keys) => index > 0 && key <= keys[index - 1])) issue([
+		"policy",
+		"prior_findings",
+		"keys"
+	], "keys must be sorted and unique");
+	const budget = plan.policy.budget;
+	if (budget.kind === "none") return;
+	const allocationIds = Object.keys(budget.allocations_usd).sort();
+	const selectedIds = [...analystIds].sort();
+	if (allocationIds.length !== selectedIds.length || allocationIds.some((id, index) => id !== selectedIds[index])) {
+		issue([
+			"policy",
+			"budget",
+			"allocations_usd"
+		], "allocations must name every analyst and no others");
+		return;
+	}
+	const runnableIds = analystIds.filter((id) => budget.allocations_usd[id] !== null);
+	const epsilon = Math.max(1, budget.total_usd) * Number.EPSILON * 8;
+	if (runnableIds.length === 0) return;
+	if (budget.kind === "weighted") {
+		const weightIds = Object.keys(budget.weights).sort();
+		if (weightIds.length !== selectedIds.length || weightIds.some((id, index) => id !== selectedIds[index])) {
+			issue([
+				"policy",
+				"budget",
+				"weights"
+			], "weights must name every analyst and no others");
+			return;
+		}
+		const totalWeight = runnableIds.reduce((sum, id) => sum + (budget.weights[id] ?? 0), 0);
+		if (totalWeight === 0) {
+			issue([
+				"policy",
+				"budget",
+				"weights"
+			], "runnable analysts must have positive total weight");
+			return;
+		}
+		for (const id of runnableIds) {
+			const expected = budget.total_usd * (budget.weights[id] ?? 0) / totalWeight;
+			if (Math.abs((budget.allocations_usd[id] ?? 0) - expected) > epsilon) issue([
+				"policy",
+				"budget",
+				"allocations_usd",
+				id
+			], "allocation does not match the weighted policy");
+		}
+		return;
+	}
+	const expected = budget.total_usd / runnableIds.length;
+	for (const id of runnableIds) if (Math.abs((budget.allocations_usd[id] ?? 0) - expected) > epsilon) issue([
+		"policy",
+		"budget",
+		"allocations_usd",
+		id
+	], "allocation does not match the equal policy");
+});
+/**
+* Canonicalize and validate the one exact-plan representation shared by execution and archival.
+* Unknown fields fail at every level; the returned graph is detached and deeply frozen.
+*/
+function snapshotExactExecutionPlan(value, context = "exact analyst execution plan") {
+	let detached;
+	try {
+		detached = JSON.parse(canonicalString(value));
+	} catch (cause) {
+		throw new TypeError(`${context} must have a canonical JSON representation`, { cause });
+	}
+	const parsed = exactExecutionPlanSchema.safeParse(detached);
+	if (!parsed.success) {
+		const issue = parsed.error.issues[0];
+		const path = issue?.path.length ? ` ${issue.path.join(".")}` : "";
+		throw new TypeError(`${context}${path}: ${issue?.message ?? "is invalid"}`);
+	}
+	const expectedDigest = hashCanonical({
+		schema_version: parsed.data.schema_version,
+		analysts: parsed.data.analysts,
+		policy: parsed.data.policy
+	});
+	if (parsed.data.digest !== expectedDigest) throw new TypeError(`${context} digest does not match its content`);
+	return deepFreezeCanonicalJson(parsed.data);
+}
+//#endregion
 //#region src/analyst/finding-subject.ts
 /**
 * Typed `FindingSubject` — the canonical grammar every analyst kind emits.
@@ -1311,6 +1535,7 @@ function parseFindingWithSchema(schema, row, log) {
 }
 function evidenceKindFromUri(uri) {
 	if (uri.startsWith("span://")) return "span";
+	if (/^trace:\/\/[^/]+\/span\/[^/]+$/.test(uri)) return "span";
 	if (uri.startsWith("event://")) return "event";
 	if (uri.startsWith("finding://")) return "finding";
 	if (uri.startsWith("metric://")) return "metric";
@@ -1424,49 +1649,6 @@ async function structureFindings(opts) {
 		outcome: "extraction_failed"
 	};
 }
-/** Convert one ledger channel's complete call set into one analyst receipt. */
-function usageReceiptFromCostLedger(ledger, filter = "analyst") {
-	const resolvedFilter = typeof filter === "string" ? { channel: filter } : filter;
-	const summary = ledger.summary(resolvedFilter);
-	const receipts = ledger.list(resolvedFilter);
-	const hasReasoningUsage = receipts.some((receipt) => receipt.reasoningTokens !== void 0);
-	const hasCacheWriteUsage = receipts.some((receipt) => receipt.cacheWriteTokens !== void 0);
-	const cost = summary.costProvenance;
-	return {
-		calls: summary.totalCalls + summary.pendingCalls,
-		tokens: summary.usageComplete ? {
-			input: summary.inputTokens,
-			output: summary.outputTokens,
-			...hasReasoningUsage ? { reasoning: summary.reasoningTokens ?? 0 } : {},
-			...summary.cachedTokens > 0 ? { cached: summary.cachedTokens } : {},
-			...hasCacheWriteUsage ? { cacheWrite: summary.cacheWriteTokens ?? 0 } : {}
-		} : null,
-		cost,
-		...cost.kind === "uncaptured" ? { knownCostUsd: summary.totalCostUsd } : {}
-	};
-}
-/** Wait a bounded time for late provider receipts, then take one immutable snapshot. */
-async function settleUsageReceiptFromCostLedger(ledger, options = {}) {
-	const { timeoutMs: requestedTimeoutMs, ...requestedFilter } = options;
-	const filter = {
-		channel: requestedFilter.channel ?? "analyst",
-		...requestedFilter.phase === void 0 ? {} : { phase: requestedFilter.phase },
-		...requestedFilter.tags === void 0 ? {} : { tags: requestedFilter.tags }
-	};
-	const timeoutMs = validateUsageSettlementTimeout(requestedTimeoutMs);
-	const waitResult = ledger.summary(filter).pendingCalls === 0 ? true : ledger.waitForIdle ? await ledger.waitForIdle({ timeoutMs }) : false;
-	const pendingCalls = ledger.summary(filter).pendingCalls;
-	return {
-		settled: waitResult && pendingCalls === 0,
-		pendingCalls,
-		receipt: usageReceiptFromCostLedger(ledger, filter)
-	};
-}
-function validateUsageSettlementTimeout(timeoutMs) {
-	const resolved = timeoutMs ?? 5e3;
-	if (!Number.isSafeInteger(resolved) || resolved < 0 || resolved > 2147483647) throw new TypeError("settlementTimeoutMs must be a non-negative safe integer no greater than 2147483647");
-	return resolved;
-}
 //#endregion
 //#region src/analyst/kind-factory.ts
 /**
@@ -1484,6 +1666,8 @@ function createTraceAnalystKind(spec, opts) {
 	const minimumEvidenceCitations = spec.minimumEvidenceCitations ?? 1;
 	if (!Number.isInteger(minimumEvidenceCitations) || minimumEvidenceCitations < 1) throw new TypeError("minimumEvidenceCitations must be a positive integer");
 	const settlementTimeoutMs = validateUsageSettlementTimeout(opts.settlementTimeoutMs);
+	const maxOutputTokens = spec.maxOutputTokens ?? 4096;
+	const aiIdentity = opts.aiIdentity === void 0 ? null : snapshotExactExecutionComponentIdentity(opts.aiIdentity, "createTraceAnalystKind aiIdentity");
 	return {
 		id: spec.id,
 		description: spec.description,
@@ -1493,8 +1677,29 @@ function createTraceAnalystKind(spec, opts) {
 			settlement_timeout_ms: settlementTimeoutMs
 		},
 		version,
+		executionConfig: {
+			kind: "trace-analyst",
+			model,
+			ai_identity: aiIdentity,
+			actor_description_digest: hashCanonical(spec.actorDescription.trim()),
+			max_subqueries: spec.subqueries?.maxCalls ?? 0,
+			max_parallel_subqueries: spec.subqueries?.maxParallel ?? 2,
+			max_turns: spec.maxTurns ?? 12,
+			max_runtime_chars: spec.maxRuntimeChars ?? 6e3,
+			max_output_tokens: maxOutputTokens,
+			minimum_evidence_citations: minimumEvidenceCitations,
+			require_structured_findings: spec.requireStructuredFindings ?? false,
+			prepare_context: spec.prepareContext === void 0 ? "disabled" : "version-bound",
+			post_process: spec.postProcess === void 0 ? "disabled" : "version-bound",
+			recovery: opts.recovery === void 0 ? null : {
+				base_url: opts.recovery.baseUrl,
+				model: opts.recovery.model ?? model,
+				api_key_provided: opts.recovery.apiKey !== void 0,
+				fetch_implementation: opts.recovery.fetchImpl === void 0 ? "global" : "version-bound"
+			},
+			settlement_timeout_ms: settlementTimeoutMs
+		},
 		async analyze(store, ctx) {
-			const maxOutputTokens = spec.maxOutputTokens ?? 4096;
 			const costLedger = ctx.costLedger ?? new CostLedger(ctx.budgetUsd);
 			const costTags = {
 				...ctx.tags ?? {},
@@ -1511,7 +1716,10 @@ function createTraceAnalystKind(spec, opts) {
 				tags: costTags
 			});
 			try {
-				const tools = spec.buildTools(store);
+				const preparedContext = await spec.prepareContext?.(store, ctx);
+				if (preparedContext !== void 0 && typeof preparedContext !== "string") throw new TypeError(`Trace analyst '${spec.id}' prepareContext must return a string`);
+				const tools = preparedContext === void 0 ? spec.buildTools(store) : [];
+				const analysisMode = preparedContext === void 0 ? "tool-loop" : "prepared-context";
 				const maxSubqueries = spec.subqueries?.maxCalls ?? 0;
 				const maxParallel = spec.subqueries?.maxParallel ?? 2;
 				const priorContext = renderPriorFindings(ctx.priorFindings);
@@ -1520,9 +1728,11 @@ function createTraceAnalystKind(spec, opts) {
 				ctx.log?.(`analyst.kind ${spec.id} forward`, {
 					max_subqueries: maxSubqueries,
 					tool_count: tools.length,
+					analysis_mode: analysisMode,
+					prepared_context_chars: preparedContext?.length ?? 0,
 					tags: ctx.tags
 				});
-				const { report, findings: submittedFindings } = await runTraceAnalysisLoop({
+				const completed = await runTraceAnalysisLoop({
 					id: spec.id,
 					description: spec.description,
 					prompt: actorDescription,
@@ -1535,8 +1745,10 @@ function createTraceAnalystKind(spec, opts) {
 					maxParallelSubqueries: maxParallel,
 					maxTurns: spec.maxTurns ?? 12,
 					maxRuntimeChars: spec.maxRuntimeChars ?? 6e3,
+					...preparedContext !== void 0 ? { context: preparedContext } : {},
 					...ctx.signal ? { signal: ctx.signal } : {}
 				});
+				const { report, findings: submittedFindings } = completed;
 				const expectedSubjects = KIND_EXPECTED_SUBJECTS[spec.id];
 				const out = [];
 				const rawRows = submittedFindings;
@@ -1586,7 +1798,10 @@ function createTraceAnalystKind(spec, opts) {
 					if (!parsed) continue;
 					const postProcessed = processRow(parsed);
 					if (!postProcessed) continue;
-					out.push(toAnalystFinding(spec, version, postProcessed));
+					out.push(toAnalystFinding(spec, version, postProcessed, {
+						analysis_mode: analysisMode,
+						analysis_turn_count: completed.turnCount
+					}));
 				}
 				ctx.log?.(`analyst.kind ${spec.id} done`, {
 					emitted: rawRows.length,
@@ -1623,6 +1838,7 @@ function createTraceAnalystKind(spec, opts) {
 						});
 					}
 					if (out.length === 0) {
+						if (spec.requireStructuredFindings) throw new Error(`Trace analyst '${spec.id}' produced no valid structured findings after ${completed.turnCount} turns: ${truncateForContext(report, 600)}`);
 						const fallback = processRow({
 							claim: "Analyst produced a diagnosis but no structured findings — see report.",
 							rationale: report.slice(0, 1500),
@@ -1633,7 +1849,11 @@ function createTraceAnalystKind(spec, opts) {
 								excerpt: report.slice(0, 2e3)
 							}]
 						});
-						if (fallback) out.push(toAnalystFinding(spec, version, fallback, { outcome: "extraction_failed" }));
+						if (fallback) out.push(toAnalystFinding(spec, version, fallback, {
+							analysis_mode: analysisMode,
+							analysis_turn_count: completed.turnCount,
+							outcome: "extraction_failed"
+						}));
 						else throw new Error(`Trace analyst '${spec.id}' produced a substantive report, but no finding satisfied its acceptance rules`);
 					}
 				}
@@ -1792,6 +2012,10 @@ var ControlIntegrityAnalyst = class {
 		est_usd_per_run: 0
 	};
 	version = "2.0.0";
+	executionConfig = {
+		kind: "control-integrity",
+		produced_at_source: "tags.producedAt-or-system-clock"
+	};
 	async analyze(input, ctx) {
 		const findings = emitControlIntegrityFindings(input, ctx.tags?.producedAt ?? (/* @__PURE__ */ new Date()).toISOString());
 		ctx.log?.(`control-integrity: ${findings.length} finding(s)`, { input: "nodes" in input ? "SupervisorRunTree" : "SupervisorRunSources" });
@@ -1827,6 +2051,13 @@ const TOOL_NAMES_BY_GROUP = {
 		"queryTraces",
 		"viewSpans",
 		"searchSpan"
+	]),
+	singleTrace: /* @__PURE__ */ new Set([
+		"getDatasetOverview",
+		"viewTrace",
+		"viewSpans",
+		"searchTrace",
+		"searchSpan"
 	])
 };
 /**
@@ -2017,6 +2248,483 @@ const DEFAULT_TRACE_ANALYST_KINDS = [
 	IMPROVEMENT_KIND_SPEC
 ];
 //#endregion
+//#region src/feedback-trajectory-review.ts
+/** Bind an analyst finding's complete canonical JSON content to a stable digest. */
+function analystFindingDigest(finding) {
+	return hashCanonical(snapshotAnalystFinding(finding, "analyst finding"));
+}
+/** Bind the complete analyst result to one immutable review target. */
+function analystRunDigest(run) {
+	return hashCanonical(snapshotAnalystRun(run, "analyst run"));
+}
+function snapshotAnalystRun(value, context = "analyst run") {
+	const snapshot = snapshotAnalystRunRecord(value, context);
+	if (snapshot.execution_plan !== void 0) return sealExactAnalystRunReceipt(snapshot, context);
+	if (snapshot.completion !== void 0) throw new TypeError(`${context} completion is valid only for an exact run`);
+	return snapshot;
+}
+/** Canonicalize, validate, and deeply freeze one complete or failed exact-run receipt. */
+function snapshotExactAnalystRunReceipt(value, context = "exact analyst run receipt") {
+	return sealExactAnalystRunReceipt(snapshotAnalystRunRecord(value, context), context);
+}
+function snapshotAnalystRunRecord(value, context) {
+	let snapshot;
+	try {
+		snapshot = JSON.parse(canonicalString(value));
+	} catch (cause) {
+		throw new TypeError(`${context} must have a canonical JSON representation`, { cause });
+	}
+	if (!isRecord(snapshot)) throw new TypeError(`${context} must be an object`);
+	assertOnlyKeys(snapshot, [
+		"run_id",
+		"correlation_id",
+		"started_at",
+		"ended_at",
+		"findings",
+		"per_analyst",
+		"total_cost_usd",
+		"total_cost_provenance",
+		"execution_plan",
+		"completion"
+	], context);
+	requiredString(snapshot.run_id, `${context} run_id`);
+	requiredString(snapshot.correlation_id, `${context} correlation_id`);
+	canonicalTimestamp(snapshot.started_at, `${context} started_at`);
+	canonicalTimestamp(snapshot.ended_at, `${context} ended_at`);
+	snapshot.findings = snapshotAnalystFindings(snapshot.findings, `${context} findings`);
+	if (!Array.isArray(snapshot.per_analyst)) throw new TypeError(`${context} per_analyst must be an array`);
+	for (const [index, summary] of snapshot.per_analyst.entries()) assertAnalystRunSummary(summary, `${context} per_analyst ${index}`);
+	if (typeof snapshot.total_cost_usd !== "number" || !Number.isFinite(snapshot.total_cost_usd) || snapshot.total_cost_usd < 0) throw new TypeError(`${context} total_cost_usd must be a finite non-negative number`);
+	if (snapshot.total_cost_provenance !== void 0) assertCostProvenance(snapshot.total_cost_provenance, `${context} total_cost_provenance`);
+	return snapshot;
+}
+function assertAnalystRunSummary(value, context) {
+	if (!isRecord(value)) throw new TypeError(`${context} must be an object`);
+	assertOnlyKeys(value, [
+		"analyst_id",
+		"status",
+		"reason",
+		"findings_count",
+		"latency_ms",
+		"usage",
+		"allocated_budget_usd",
+		"error"
+	], context);
+	requiredString(value.analyst_id, `${context} analyst_id`);
+	if (value.status !== "ok" && value.status !== "skipped" && value.status !== "failed") throw new TypeError(`${context} status is invalid`);
+	if (value.reason !== void 0) requiredString(value.reason, `${context} reason`);
+	if (value.status === "skipped" && value.reason === void 0) throw new TypeError(`${context} skipped summary requires reason`);
+	nonnegativeSafeInteger(value.findings_count, `${context} findings_count`);
+	finiteNonnegative(value.latency_ms, `${context} latency_ms`);
+	assertAnalystUsageReceipt(value.usage, `${context} usage`);
+	if (value.allocated_budget_usd !== void 0 && value.allocated_budget_usd !== null) finiteNonnegative(value.allocated_budget_usd, `${context} allocated_budget_usd`);
+	if (value.error !== void 0) {
+		if (value.status !== "failed" || !isRecord(value.error)) throw new TypeError(`${context} error is valid only for failed summaries`);
+		assertOnlyKeys(value.error, ["class", "message"], `${context} error`);
+		requiredString(value.error.class, `${context} error class`);
+		requiredString(value.error.message, `${context} error message`);
+	} else if (value.status === "failed") throw new TypeError(`${context} failed summary requires error`);
+}
+function assertAnalystUsageReceipt(value, context) {
+	if (!isRecord(value)) throw new TypeError(`${context} must be an object`);
+	assertOnlyKeys(value, [
+		"calls",
+		"tokens",
+		"cost",
+		"knownCostUsd"
+	], context);
+	for (const field of [
+		"calls",
+		"tokens",
+		"cost"
+	]) if (!Object.hasOwn(value, field)) throw new TypeError(`${context} ${field} is required`);
+	if (value.tokens !== null) {
+		if (!isRecord(value.tokens)) throw new TypeError(`${context} tokens must be an object or null`);
+		assertOnlyKeys(value.tokens, [
+			"input",
+			"output",
+			"reasoning",
+			"cached",
+			"cacheWrite"
+		], `${context} tokens`);
+	}
+	assertCostProvenance(value.cost, `${context} cost`);
+	assertValidAnalystUsageReceipt(value, context);
+}
+function assertCostProvenance(value, context) {
+	if (!isRecord(value)) throw new TypeError(`${context} must be an object`);
+	assertOnlyKeys(value, ["kind", "usd"], context);
+	if (value.kind === "uncaptured") {
+		if (value.usd !== null) throw new TypeError(`${context} uncaptured usd must be null`);
+		return;
+	}
+	if (value.kind !== "observed" && value.kind !== "estimated") throw new TypeError(`${context} kind is invalid`);
+	finiteNonnegative(value.usd, `${context} usd`);
+}
+function sealExactAnalystRunReceipt(run, context) {
+	if (run.execution_plan === void 0) throw new TypeError(`${context} exact run requires execution_plan`);
+	const plan = snapshotExactExecutionPlan(run.execution_plan, `${context} execution_plan`);
+	const completion = snapshotExactRunCompletion(run.completion, `${context} completion`);
+	run.execution_plan = plan;
+	run.completion = completion;
+	const summaries = run.per_analyst;
+	const findings = run.findings;
+	const planned = plan.analysts.map((analyst) => analyst.id);
+	const completed = summaries.map((summary) => summary.analyst_id);
+	if (!completed.every((analystId, index) => analystId === planned[index]) || completion.status === "complete" && completed.length !== planned.length) throw new TypeError(completion.status === "complete" ? `${context} complete receipt must contain every execution_plan analyst in exact order` : `${context} failed receipt per_analyst must be an execution_plan prefix`);
+	const completedIds = new Set(completed);
+	for (const finding of findings) if (!completedIds.has(finding.analyst_id)) throw new TypeError(`${context} finding names an analyst absent from per_analyst`);
+	for (const summary of summaries) {
+		const actual = findings.filter((finding) => finding.analyst_id === summary.analyst_id).length;
+		if (summary.findings_count !== actual) throw new TypeError(`${context} findings_count does not match findings for "${summary.analyst_id}"`);
+		const hasAllocation = Object.hasOwn(summary, "allocated_budget_usd");
+		if (summary.status === "skipped") {
+			if (hasAllocation) throw new TypeError(`${context} skipped summary "${summary.analyst_id}" cannot report an allocated budget`);
+			continue;
+		}
+		const allocation = summary.allocated_budget_usd;
+		if (!(hasAllocation && (plan.policy.budget.kind === "none" ? allocation === null : typeof allocation === "number" && plan.policy.budget.allocations_usd[summary.analyst_id] !== null && plan.policy.budget.allocations_usd[summary.analyst_id] !== void 0 && allocation <= plan.policy.budget.allocations_usd[summary.analyst_id]))) throw new TypeError(`${context} summary "${summary.analyst_id}" allocation does not match its execution plan`);
+	}
+	let knownCost = 0;
+	for (const summary of summaries) {
+		const amount = summary.usage.cost.kind === "uncaptured" ? summary.usage.knownCostUsd ?? 0 : summary.usage.cost.usd ?? 0;
+		knownCost = finiteNonnegative(knownCost + amount, `${context} aggregate known cost`);
+	}
+	if (run.total_cost_usd !== knownCost) throw new TypeError(`${context} total_cost_usd does not match per_analyst usage`);
+	if (run.total_cost_provenance === void 0) throw new TypeError(`${context} exact run requires total_cost_provenance`);
+	const costs = summaries.map((summary) => summary.usage.cost);
+	const expectedProvenance = costs.some((cost) => cost.kind === "uncaptured") ? {
+		kind: "uncaptured",
+		usd: null
+	} : {
+		kind: costs.some((cost) => cost.kind === "estimated") ? "estimated" : "observed",
+		usd: costs.reduce((sum, cost) => finiteNonnegative(sum + (cost.usd ?? 0), `${context} aggregate captured cost`), 0)
+	};
+	if (hashCanonical(run.total_cost_provenance) !== hashCanonical(expectedProvenance)) throw new TypeError(`${context} total_cost_provenance does not match per_analyst usage`);
+	return deepFreezeCanonicalJson(run);
+}
+function snapshotExactRunCompletion(value, context) {
+	if (!isRecord(value)) throw new TypeError(`${context} must be an object`);
+	if (value.status === "complete") {
+		assertOnlyKeys(value, ["status"], context);
+		return value;
+	}
+	if (value.status !== "failed") throw new TypeError(`${context} status must be complete or failed`);
+	assertOnlyKeys(value, ["status", "error"], context);
+	if (!isRecord(value.error)) throw new TypeError(`${context} failed receipt requires error`);
+	assertOnlyKeys(value.error, ["class", "message"], `${context} error`);
+	requiredString(value.error.class, `${context} error class`);
+	requiredString(value.error.message, `${context} error message`);
+	return value;
+}
+function finiteNonnegative(value, context) {
+	if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new TypeError(`${context} must be a non-negative finite number`);
+	return value;
+}
+function nonnegativeSafeInteger(value, context) {
+	if (!Number.isSafeInteger(value) || value < 0) throw new TypeError(`${context} must be a non-negative safe integer`);
+	return value;
+}
+function snapshotAnalystFindings(value, context = "analyst run findings") {
+	if (!Array.isArray(value)) throw new TypeError(`${context} must be an array`);
+	const findings = value.map((finding, index) => snapshotAnalystFinding(finding, `${context} finding ${index}`));
+	assertUniqueFindingIds(findings.map((finding) => finding.finding_id));
+	return findings;
+}
+function readAnalystReview(trajectory) {
+	const analystAttempts = trajectory.attempts.filter((attempt) => isRecord(attempt.artifact) && attempt.artifact.type === "analyst-run");
+	const analysis = isRecord(trajectory.metadata?.analysis) ? trajectory.metadata.analysis : void 0;
+	if (analystAttempts.length === 0) {
+		if (analysis?.kind === "analyst-run") throw new TypeError(`feedbackTrajectoryToOptimizerRow: analyst trajectory "${trajectory.id}" is missing its archived run`);
+		return;
+	}
+	if (analystAttempts.length !== 1) throw new TypeError(`feedbackTrajectoryToOptimizerRow: analyst trajectory "${trajectory.id}" must contain exactly one archived run`);
+	if (analysis?.kind !== "analyst-run") throw new TypeError(`feedbackTrajectoryToOptimizerRow: analyst trajectory "${trajectory.id}" is missing review state`);
+	const artifact = analystAttempts[0].artifact;
+	if (!isRecord(artifact)) throw new TypeError(`feedbackTrajectoryToOptimizerRow: analyst trajectory "${trajectory.id}" has an invalid archived run`);
+	const runId = requiredString(artifact.analystRunId, `analyst trajectory "${trajectory.id}" run id`);
+	if (analysis.runId !== runId) throw new TypeError(`feedbackTrajectoryToOptimizerRow: analyst trajectory "${trajectory.id}" run identity does not match its review state`);
+	const artifactRunDigest = requiredDigest(artifact.runDigest, `analyst trajectory "${trajectory.id}" archived run digest`);
+	const storedRunDigest = requiredDigest(analysis.runDigest, `analyst trajectory "${trajectory.id}" review run digest`);
+	if (artifactRunDigest !== storedRunDigest) throw new TypeError(`feedbackTrajectoryToOptimizerRow: analyst trajectory "${trajectory.id}" run digest does not match its review state`);
+	const findings = snapshotAnalystFindings(artifact.findings, `analyst trajectory "${trajectory.id}"`);
+	const findingIds = findings.map((finding) => finding.finding_id);
+	const analystIds = stringArray(artifact.analystIds, `analyst trajectory "${trajectory.id}" analyst ids`);
+	const attemptMetadata = analystAttempts[0].metadata;
+	if (!isRecord(attemptMetadata)) throw new TypeError(`feedbackTrajectoryToOptimizerRow: analyst trajectory "${trajectory.id}" is missing archived run metadata`);
+	const archivedRun = snapshotAnalystRun({
+		run_id: runId,
+		correlation_id: artifact.correlationId,
+		started_at: analysis.startedAt,
+		ended_at: analysis.endedAt,
+		findings,
+		per_analyst: attemptMetadata.perAnalyst,
+		total_cost_usd: analysis.knownCostUsd,
+		...analysis.costProvenance === void 0 ? {} : { total_cost_provenance: analysis.costProvenance },
+		...artifact.executionPlan === void 0 ? {} : {
+			execution_plan: artifact.executionPlan,
+			completion: artifact.completion
+		}
+	}, `analyst trajectory "${trajectory.id}" archived run`);
+	const knownAnalystIds = new Set(analystIds);
+	for (const [index, finding] of findings.entries()) if (!knownAnalystIds.has(finding.analyst_id)) throw new TypeError(`feedbackTrajectoryToOptimizerRow: analyst trajectory "${trajectory.id}" omits generating analyst "${finding.analyst_id}" at finding ${index}`);
+	const reviewDecisions = validateAnalystReviewDecisions({
+		runId,
+		runDigest: storedRunDigest,
+		findings,
+		analystIds,
+		decisions: analysis.reviewDecisions,
+		requireComplete: true
+	});
+	const expectedRunDigest = analystRunDigest(archivedRun);
+	if (storedRunDigest !== expectedRunDigest) throw new TypeError(`feedbackTrajectoryToOptimizerRow: analyst trajectory "${trajectory.id}" archived run digest mismatch`);
+	return {
+		runId,
+		runDigest: expectedRunDigest,
+		findings,
+		findingIds,
+		analystIds,
+		reviewDecisions
+	};
+}
+function completedAnalystReviewQuality(review) {
+	const findingDecisions = review.reviewDecisions.filter((decision) => decision.verdict !== "completeness_assessed");
+	const completeness = review.reviewDecisions.filter((decision) => decision.verdict === "completeness_assessed");
+	if (completeness.length !== 1) throw new TypeError("feedbackTrajectoryToOptimizerRow: analyst run requires exactly one independent completeness_assessed decision");
+	const confirmed = findingDecisions.filter((decision) => decision.verdict === "confirmed").length;
+	const rejected = findingDecisions.length - confirmed;
+	const emitted = review.findingIds.length;
+	const missed = completeness[0].missedIssues.length;
+	const precision = emitted === 0 ? 1 : confirmed / emitted;
+	const recallDenominator = confirmed + missed;
+	const recall = recallDenominator === 0 ? 1 : confirmed / recallDenominator;
+	return {
+		precision,
+		recall,
+		f1: precision + recall === 0 ? 0 : 2 * precision * recall / (precision + recall),
+		counts: {
+			emitted,
+			confirmed,
+			rejected,
+			missed
+		}
+	};
+}
+function validateAnalystReviewDecisions(input) {
+	if (!Array.isArray(input.decisions)) throw new TypeError("analyst review decisions must be an array");
+	const findings = snapshotAnalystFindings(input.findings);
+	const expectedRunDigest = requiredDigest(input.runDigest, "analyst review run digest");
+	const findingsById = new Map(findings.map((finding) => [finding.finding_id, finding]));
+	const generatingAnalystIds = new Set(input.analystIds);
+	const seenFindingIds = /* @__PURE__ */ new Set();
+	let completenessCount = 0;
+	const decisions = input.decisions.map((value, index) => {
+		if (!isRecord(value)) throw new TypeError(`analyst review decision ${index} must be an object`);
+		const source = requiredString(value.source, `analyst review decision ${index} source`);
+		if (!isAnalystReviewSource(source)) throw new TypeError(`analyst review decision ${index} source must be user, judge, environment, metric, or policy`);
+		const reviewerId = requiredString(value.reviewerId, `analyst review decision ${index} reviewerId`);
+		if (generatingAnalystIds.has(reviewerId)) throw new TypeError(`analyst review decision ${index} reviewerId must differ from the generating analyst`);
+		const reviewId = requiredString(value.reviewId, `analyst review decision ${index} reviewId`);
+		if (reviewId === input.runId) throw new TypeError(`analyst review decision ${index} reviewId must identify an independent review`);
+		const reason = requiredString(value.reason, `analyst review decision ${index} reason`);
+		const decidedAt = canonicalTimestamp(value.decidedAt, `analyst review decision ${index} decidedAt`);
+		const runDigest = requiredDigest(value.runDigest, `analyst review decision ${index} runDigest`);
+		if (runDigest !== expectedRunDigest) throw new TypeError(`analyst review decision ${index} run digest mismatch`);
+		if (value.verdict === "completeness_assessed") {
+			assertOnlyKeys(value, [
+				"runDigest",
+				"verdict",
+				"missedIssues",
+				"source",
+				"reviewerId",
+				"reviewId",
+				"reason",
+				"decidedAt"
+			], `analyst review decision ${index}`);
+			completenessCount += 1;
+			if (completenessCount > 1) throw new TypeError("duplicate completeness_assessed analyst review decision");
+			return {
+				runDigest,
+				verdict: "completeness_assessed",
+				missedIssues: validateMissedIssues(value.missedIssues, findingsById, `analyst review decision ${index}`),
+				source,
+				reviewerId,
+				reviewId,
+				reason,
+				decidedAt
+			};
+		}
+		if (value.verdict !== "confirmed" && value.verdict !== "rejected") throw new TypeError(`analyst review decision ${index} verdict must be confirmed, rejected, or completeness_assessed`);
+		assertOnlyKeys(value, [
+			"runDigest",
+			"findingId",
+			"findingDigest",
+			"verdict",
+			"source",
+			"reviewerId",
+			"reviewId",
+			"reason",
+			"decidedAt"
+		], `analyst review decision ${index}`);
+		const findingId = requiredString(value.findingId, `analyst review decision ${index} findingId`);
+		const finding = findingsById.get(findingId);
+		if (!finding) throw new TypeError(`analyst review decision references unknown finding id "${findingId}"`);
+		if (seenFindingIds.has(findingId)) throw new TypeError(`duplicate analyst review decision for finding id "${findingId}"`);
+		seenFindingIds.add(findingId);
+		const findingDigest = requiredString(value.findingDigest, `analyst review decision ${index} findingDigest`);
+		const expectedDigest = analystFindingDigest(finding);
+		if (findingDigest !== expectedDigest) throw new TypeError(`analyst review decision ${index} digest mismatch for finding id "${findingId}"`);
+		return {
+			runDigest,
+			findingId,
+			findingDigest: expectedDigest,
+			verdict: value.verdict,
+			source,
+			reviewerId,
+			reviewId,
+			reason,
+			decidedAt
+		};
+	});
+	if (input.requireComplete) {
+		const missing = findings.map((finding) => finding.finding_id).filter((findingId) => !seenFindingIds.has(findingId));
+		if (missing.length > 0) throw new TypeError(`feedbackTrajectoryToOptimizerRow: missing independent decisions for finding ids: ${missing.join(", ")}`);
+		if (completenessCount !== 1) throw new TypeError("feedbackTrajectoryToOptimizerRow: analyst run requires exactly one independent completeness_assessed decision");
+	}
+	return decisions;
+}
+function assertUniqueFindingIds(findingIds) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const findingId of findingIds) {
+		if (findingId.trim().length === 0) throw new TypeError("analyst finding id must not be empty");
+		if (seen.has(findingId)) throw new TypeError(`analyst run contains duplicate finding id "${findingId}"`);
+		seen.add(findingId);
+	}
+}
+function snapshotAnalystFinding(value, context) {
+	let snapshot;
+	try {
+		snapshot = JSON.parse(canonicalString(value));
+	} catch (cause) {
+		throw new TypeError(`${context} must have a canonical JSON representation`, { cause });
+	}
+	assertAnalystFinding(snapshot, context);
+	return snapshot;
+}
+function assertAnalystFinding(value, context) {
+	if (!isRecord(value)) throw new TypeError(`${context} must be an object`);
+	assertOnlyKeys(value, [
+		"schema_version",
+		"finding_id",
+		"analyst_id",
+		"produced_at",
+		"severity",
+		"area",
+		"claim",
+		"rationale",
+		"evidence_refs",
+		"recommended_action",
+		"validation_plan",
+		"confidence",
+		"subject",
+		"derived_from_judge",
+		"metadata"
+	], context);
+	if (value.schema_version !== "1.0.0") throw new TypeError(`${context} schema_version must be "1.0.0"`);
+	requiredString(value.finding_id, `${context} finding_id`);
+	requiredString(value.analyst_id, `${context} analyst_id`);
+	canonicalTimestamp(value.produced_at, `${context} produced_at`);
+	if (value.severity !== "critical" && value.severity !== "high" && value.severity !== "medium" && value.severity !== "low" && value.severity !== "info") throw new TypeError(`${context} severity is invalid`);
+	requiredString(value.area, `${context} area`);
+	requiredString(value.claim, `${context} claim`);
+	optionalString(value.rationale, `${context} rationale`);
+	value.evidence_refs = validateEvidenceRefs(value.evidence_refs, `${context} evidence_refs`);
+	optionalString(value.recommended_action, `${context} recommended_action`);
+	optionalString(value.validation_plan, `${context} validation_plan`);
+	if (typeof value.confidence !== "number" || !Number.isFinite(value.confidence) || value.confidence < 0 || value.confidence > 1) throw new TypeError(`${context} confidence must be a finite number from 0 through 1`);
+	optionalString(value.subject, `${context} subject`);
+	if (value.derived_from_judge !== void 0 && typeof value.derived_from_judge !== "boolean") throw new TypeError(`${context} derived_from_judge must be a boolean`);
+	if (value.metadata !== void 0 && !isRecord(value.metadata)) throw new TypeError(`${context} metadata must be an object`);
+}
+function validateMissedIssues(value, findingsById, context) {
+	if (!Array.isArray(value)) throw new TypeError(`${context} missedIssues must be an array`);
+	const seen = /* @__PURE__ */ new Set();
+	return value.map((issue, index) => {
+		const issueContext = `${context} missedIssues ${index}`;
+		if (!isRecord(issue)) throw new TypeError(`${issueContext} must be an object`);
+		assertOnlyKeys(issue, [
+			"id",
+			"reason",
+			"evidence"
+		], issueContext);
+		const id = requiredString(issue.id, `${issueContext} id`);
+		if (findingsById.has(id)) throw new TypeError(`${issueContext} id "${id}" is already an emitted finding id`);
+		if (seen.has(id)) throw new TypeError(`duplicate missed issue id "${id}"`);
+		seen.add(id);
+		return {
+			id,
+			reason: requiredString(issue.reason, `${issueContext} reason`),
+			...issue.evidence === void 0 ? {} : { evidence: validateEvidenceRefs(issue.evidence, `${issueContext} evidence`) }
+		};
+	});
+}
+function validateEvidenceRefs(value, context) {
+	if (!Array.isArray(value)) throw new TypeError(`${context} must be an array`);
+	return value.map((evidence, index) => {
+		const evidenceContext = `${context} ${index}`;
+		if (!isRecord(evidence)) throw new TypeError(`${evidenceContext} must be an object`);
+		assertOnlyKeys(evidence, [
+			"kind",
+			"uri",
+			"excerpt"
+		], evidenceContext);
+		if (evidence.kind !== "span" && evidence.kind !== "event" && evidence.kind !== "artifact" && evidence.kind !== "finding" && evidence.kind !== "metric") throw new TypeError(`${evidenceContext} kind is invalid`);
+		const uri = requiredString(evidence.uri, `${evidenceContext} uri`);
+		const excerpt = evidence.excerpt;
+		optionalString(excerpt, `${evidenceContext} excerpt`);
+		return {
+			kind: evidence.kind,
+			uri,
+			...excerpt === void 0 ? {} : { excerpt }
+		};
+	});
+}
+function assertOnlyKeys(value, allowed, name) {
+	const allowedKeys = new Set(allowed);
+	const unexpected = Object.keys(value).filter((key) => !allowedKeys.has(key));
+	if (unexpected.length > 0) throw new TypeError(`${name} contains unknown fields: ${unexpected.sort().join(", ")}`);
+}
+function stringArray(value, name) {
+	if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) throw new TypeError(`${name} must be an array of strings`);
+	const strings = value.map((item) => requiredString(item, name));
+	if (new Set(strings).size !== strings.length) throw new TypeError(`${name} must contain unique values`);
+	return strings;
+}
+function requiredString(value, name) {
+	if (typeof value !== "string" || value.trim().length === 0) throw new TypeError(`${name} must be a non-empty string`);
+	return value;
+}
+function requiredDigest(value, name) {
+	const digest = requiredString(value, name);
+	if (!/^sha256:[a-f0-9]{64}$/.test(digest)) throw new TypeError(`${name} must be a sha256 digest`);
+	return digest;
+}
+function optionalString(value, name) {
+	if (value !== void 0 && typeof value !== "string") throw new TypeError(`${name} must be a string`);
+}
+function canonicalTimestamp(value, name) {
+	const timestamp = requiredString(value, name);
+	const parsed = new Date(timestamp);
+	if (Number.isNaN(parsed.valueOf()) || parsed.toISOString() !== timestamp) throw new TypeError(`${name} must be a canonical ISO 8601 UTC timestamp`);
+	return timestamp;
+}
+function isAnalystReviewSource(value) {
+	return value === "user" || value === "judge" || value === "environment" || value === "metric" || value === "policy";
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
 //#region src/analyst/registry.ts
 /**
 * AnalystRegistry — orchestrate N analysts against one run.
@@ -2035,6 +2743,17 @@ const DEFAULT_TRACE_ANALYST_KINDS = [
 * (equal split vs weighted vs custom) lives in `BudgetPolicy`. Both
 * have sensible defaults; consumers override only what they need.
 */
+/** A post-start exact-run failure; completed work remains attached for accounting and review. */
+var ExactAnalystRunExecutionError = class extends Error {
+	name = "ExactAnalystRunExecutionError";
+	result;
+	constructor(message, result, options) {
+		super(message, options);
+		const snapshot = snapshotExactAnalystRunReceipt(result, "ExactAnalystRunExecutionError result");
+		if (snapshot.completion.status !== "failed") throw new TypeError("ExactAnalystRunExecutionError result must be a failed receipt");
+		this.result = snapshot;
+	}
+};
 var AnalystRegistry = class {
 	analysts = /* @__PURE__ */ new Map();
 	options;
@@ -2042,12 +2761,15 @@ var AnalystRegistry = class {
 		this.options = options;
 	}
 	register(analyst) {
-		if (!analyst.id) throw new Error("AnalystRegistry.register: analyst.id is required");
-		if (this.analysts.has(analyst.id)) throw new Error(`AnalystRegistry.register: duplicate analyst id "${analyst.id}"`);
-		if (!analyst.version) throw new Error(`AnalystRegistry.register: analyst "${analyst.id}" must declare a version`);
-		if (analyst.cost.kind === "deterministic" && analyst.cost.settlement_timeout_ms !== void 0) throw new TypeError(`AnalystRegistry.register: deterministic analyst "${analyst.id}" cannot declare settlement_timeout_ms`);
-		if (analyst.cost.settlement_timeout_ms !== void 0) validateUsageSettlementTimeout(analyst.cost.settlement_timeout_ms);
-		this.analysts.set(analyst.id, analyst);
+		const id = analyst.id;
+		const version = analyst.version;
+		const cost = analyst.cost;
+		if (!id) throw new Error("AnalystRegistry.register: analyst.id is required");
+		if (this.analysts.has(id)) throw new Error(`AnalystRegistry.register: duplicate analyst id "${id}"`);
+		if (!version) throw new Error(`AnalystRegistry.register: analyst "${id}" must declare a version`);
+		if (cost.kind === "deterministic" && cost.settlement_timeout_ms !== void 0) throw new TypeError(`AnalystRegistry.register: deterministic analyst "${id}" cannot declare settlement_timeout_ms`);
+		if (cost.settlement_timeout_ms !== void 0) validateUsageSettlementTimeout(cost.settlement_timeout_ms);
+		this.analysts.set(id, analyst);
 	}
 	list() {
 		return Array.from(this.analysts.values()).map((a) => ({
@@ -2061,6 +2783,15 @@ var AnalystRegistry = class {
 		for await (const ev of this.runStream(runId, inputs, runOpts)) if (ev.type === "run-completed") return ev.result;
 		throw new Error("AnalystRegistry.run: stream completed without run-completed event");
 	}
+	/** Run exactly the ordered analysts and complete policy supplied by the caller. */
+	async runExact(runId, inputs, runOpts) {
+		for await (const ev of this.runExactStream(runId, inputs, runOpts)) if (ev.type === "run-completed") return ev.result;
+		throw new Error("AnalystRegistry.runExact: stream completed without run-completed event");
+	}
+	/** Streaming counterpart to {@link runExact}. */
+	async *runExactStream(runId, inputs, runOpts) {
+		for await (const event of this.executePlanStream(this.normalizeExactPlan(runId, inputs, runOpts))) yield event;
+	}
 	/**
 	* Streaming counterpart to `run()`. Emits `AnalystRunEvent` values
 	* in real time — `run-started`, then per-analyst `skipped` /
@@ -2073,50 +2804,124 @@ var AnalystRegistry = class {
 	* replacement.
 	*/
 	async *runStream(runId, inputs, runOpts = {}) {
+		yield* this.executePlanStream(this.normalizeLegacyPlan(runId, inputs, runOpts));
+	}
+	normalizeLegacyPlan(runId, inputs, runOpts) {
+		const timeoutMs = validateTimeout(runOpts.timeoutMs) ?? null;
+		const budget = runOpts.budget ?? this.options.defaultBudget;
+		validateBudgetPolicy(budget);
+		return {
+			runId,
+			prepared: this.selectAnalysts(runOpts).map((analyst) => ({
+				analyst,
+				input: this.routeInput(analyst, inputs)
+			})),
+			budget: budget ? {
+				kind: "dynamic",
+				policy: budget
+			} : { kind: "none" },
+			totalTimeoutMs: timeoutMs,
+			signal: runOpts.signal ?? null,
+			costLedger: runOpts.costLedger ?? null,
+			costPhase: runOpts.costPhase ?? null,
+			tags: runOpts.tags ?? null,
+			priorFindings: runOpts.priorFindings ?? null,
+			chainFindings: runOpts.chainFindings ?? false,
+			hooks: this.options.hooks ?? {},
+			chat: this.options.chat,
+			log: this.options.log ?? (() => {}),
+			executionSnapshot: void 0
+		};
+	}
+	normalizeExactPlan(runId, inputs, runOpts) {
+		const exactRunId = snapshotExactRunId(runId);
+		const exact = snapshotExactRegistryRunOpts(runOpts);
+		const selected = normalizeExactAnalysts(this.selectExactAnalysts(exact.analystIds));
+		const registryChat = this.options.chat;
+		const registryChatIdentity = this.options.chatIdentity;
+		const registryHooks = this.options.hooks;
+		const registryHooksIdentity = this.options.hooksIdentity;
+		if (exact.useRegistryChat && registryChat === void 0) throw new TypeError("ExactRegistryRunOpts.useRegistryChat is true but the registry has no chat client");
+		if (exact.applyRegistryHooks && !hasRegistryHooks(registryHooks)) throw new TypeError("ExactRegistryRunOpts.applyRegistryHooks is true but the registry has no lifecycle hooks");
+		const inputSnapshot = snapshotAnalystRunInputChannels(inputs);
+		const prepared = selected.map((analyst) => ({
+			analyst,
+			input: this.routeInput(analyst, inputSnapshot)
+		}));
+		if (exact.missingInputMode === "abort") {
+			const missing = prepared.find((candidate) => candidate.input.kind === "missing")?.analyst;
+			if (missing) throw new TypeError(`ExactRegistryRunOpts.missingInputMode abort preflight found no "${missing.inputKind}" input for "${missing.id}"`);
+		}
+		const hooksIdentity = exact.applyRegistryHooks && registryHooks ? requireExactComponentIdentity(registryHooksIdentity, "registry hooks") : null;
+		const chatIdentity = exact.useRegistryChat ? requireExactComponentIdentity(registryChatIdentity, "registry chat") : null;
+		const costLedgerIdentity = exact.costLedger === null ? null : requireExactComponentIdentity(exact.costLedgerIdentity ?? void 0, "cost ledger");
+		const executionSnapshot = exactExecutionSnapshot(selected, exact, exactFixedBudgets(exact.budget, prepared.filter((candidate) => candidate.input.kind === "present").map((candidate) => candidate.analyst), selected), costLedgerIdentity, hooksIdentity, chatIdentity);
+		return {
+			runId: exactRunId,
+			prepared,
+			budget: { kind: "none" },
+			totalTimeoutMs: exact.totalTimeoutMs,
+			signal: exact.signal,
+			costLedger: exact.costLedger,
+			costPhase: exact.costPhase,
+			tags: exact.tags,
+			priorFindings: exact.priorFindings,
+			chainFindings: exact.chainFindings,
+			hooks: exact.applyRegistryHooks && registryHooks ? snapshotHooks(registryHooks) : {},
+			chat: exact.useRegistryChat && registryChat ? snapshotChat(registryChat) : void 0,
+			log: () => {},
+			executionSnapshot
+		};
+	}
+	async *executePlanStream(plan) {
+		const exact = plan.executionSnapshot !== void 0;
+		if (exact && plan.signal?.aborted) throw abortReason(plan.signal);
 		const correlationId = `ar_${randomUUID().slice(0, 12)}`;
-		const log = this.options.log ?? (() => {});
-		const hooks = this.options.hooks ?? {};
+		const log = plan.log;
 		const startedAt = (/* @__PURE__ */ new Date()).toISOString();
 		const started = Date.now();
-		const timeoutMs = validateTimeout(runOpts.timeoutMs);
-		const deadlineMs = timeoutMs === void 0 ? void 0 : started + timeoutMs;
-		const timeoutSignal = timeoutMs === void 0 ? void 0 : AbortSignal.timeout(timeoutMs);
-		const runSignal = combineAbortSignals(runOpts.signal, timeoutSignal);
-		const selected = this.selectAnalysts(runOpts);
-		const budget = runOpts.budget ?? this.options.defaultBudget;
-		validateBudgetPolicy(budget);
-		yield {
+		const timeoutSignal = plan.totalTimeoutMs === null ? void 0 : AbortSignal.timeout(plan.totalTimeoutMs);
+		const runSignal = combineAbortSignals(plan.signal ?? void 0, timeoutSignal);
+		const deadlineMs = plan.totalTimeoutMs === null ? void 0 : started + plan.totalTimeoutMs;
+		const runnable = plan.prepared.filter((candidate) => candidate.input.kind === "present").map((candidate) => candidate.analyst);
+		let remainingUsd = plan.budget.kind === "dynamic" ? plan.budget.policy.totalUsd : void 0;
+		const weights = plan.budget.kind === "dynamic" ? plan.budget.policy.weights : void 0;
+		const totalWeight = weights && plan.budget.kind === "dynamic" && plan.budget.policy.totalUsd != null && !plan.budget.policy.allocate && runnable.length > 0 ? runnable.reduce((sum, analyst) => sum + analystWeight(weights, analyst.id), 0) : void 0;
+		if (totalWeight === 0) throw new Error("BudgetPolicy.weights must allocate positive weight to a runnable analyst");
+		const upstreamFindings = [];
+		yield snapshotExecutionEvent({
 			type: "run-started",
-			run_id: runId,
+			run_id: plan.runId,
 			correlation_id: correlationId,
 			started_at: startedAt,
-			analyst_ids: selected.map((a) => a.id)
-		};
-		const summaries = [];
-		const allFindings = [];
-		let totalCost = 0;
-		let remainingUsd = budget?.totalUsd;
-		const runnableAnalysts = selected.filter((a) => this.routeInput(a, inputs).kind !== "missing");
-		const runnableCount = runnableAnalysts.length;
-		const weights = budget?.weights;
-		const totalWeight = weights && budget?.totalUsd != null && !budget.allocate && runnableCount > 0 ? runnableAnalysts.reduce((sum, analyst) => sum + analystWeight(weights, analyst.id), 0) : void 0;
-		if (totalWeight === 0) throw new Error("BudgetPolicy.weights must allocate positive weight to a runnable analyst");
-		for (const analyst of selected) {
+			analyst_ids: plan.prepared.map(({ analyst }) => analyst.id),
+			...plan.executionSnapshot === void 0 ? {} : { execution_plan: plan.executionSnapshot }
+		}, exact);
+		const executions = [];
+		let executionFailure;
+		for (const { analyst, input } of plan.prepared) {
 			const t0 = Date.now();
 			if (runSignal?.aborted) {
 				const summary = abortedBeforeStartSummary(analyst, runSignal);
-				summaries.push(summary);
+				executions.push({
+					summary,
+					findings: [],
+					budgetDebitUsd: 0
+				});
 				log(`[analyst] skip ${analyst.id} — run aborted`, {
-					runId,
+					runId: plan.runId,
 					reason: summary.reason
 				});
-				yield {
+				yield snapshotExecutionEvent({
 					type: "analyst-skipped",
 					summary
-				};
+				}, exact);
+				if (exact) {
+					executionFailure = abortReason(runSignal);
+					break;
+				}
 				continue;
 			}
-			const input = this.routeInput(analyst, inputs);
 			if (input.kind === "missing") {
 				const summary = {
 					analyst_id: analyst.id,
@@ -2126,189 +2931,295 @@ var AnalystRegistry = class {
 					latency_ms: 0,
 					usage: zeroUsage()
 				};
-				summaries.push(summary);
+				const execution = {
+					summary,
+					findings: [],
+					budgetDebitUsd: 0
+				};
+				executions.push(execution);
 				log(`[analyst] skip ${analyst.id} — missing input`, {
-					runId,
+					runId: plan.runId,
 					kind: analyst.inputKind
 				});
-				await waitForHook(hooks.onAfterAnalyze ? () => hooks.onAfterAnalyze?.({
-					analyst,
-					summary,
-					findings: [],
-					runId
-				}) : void 0, runSignal);
-				yield {
+				const hookValues = snapshotAfterHookValues(summary, [], exact);
+				try {
+					await waitForHook(plan.hooks.onAfterAnalyze ? () => plan.hooks.onAfterAnalyze?.({
+						analyst,
+						summary: hookValues.summary,
+						findings: hookValues.findings,
+						runId: plan.runId
+					}) : void 0, runSignal);
+				} catch (error) {
+					if (!exact) throw error;
+					executionFailure = error;
+				}
+				yield snapshotExecutionEvent({
 					type: "analyst-skipped",
 					summary
-				};
+				}, exact);
+				if (executionFailure !== void 0) break;
 				continue;
 			}
-			const perBudget = allocateBudget(budget, {
+			const allocatedUsd = plan.executionSnapshot === void 0 ? allocateBudget(plan.budget.kind === "dynamic" ? plan.budget.policy : void 0, {
 				analyst,
 				remainingUsd,
-				runningCount: runnableCount,
+				runningCount: runnable.length,
 				totalWeight
-			});
+			}) : exactPlannedAllocation(plan.executionSnapshot, analyst.id);
+			const budgetCeilingUsd = plan.executionSnapshot === void 0 ? remainingUsd : allocatedUsd;
 			const usageReceipts = [];
+			const contextTags = plan.tags === null ? void 0 : { ...plan.tags };
+			const priorFindings = selectPriorFindings(plan.priorFindings ?? void 0, analyst.id);
+			const chainedFindings = plan.chainFindings && upstreamFindings.length > 0 ? [...upstreamFindings] : void 0;
 			const ctx = {
-				runId,
+				runId: plan.runId,
 				correlationId,
 				deadlineMs,
-				budgetUsd: perBudget,
-				costLedger: runOpts.costLedger,
-				costPhase: runOpts.costPhase,
-				chat: this.options.chat,
-				tags: runOpts.tags,
-				log: (msg, fields) => log(`[${analyst.id}] ${msg}`, {
-					runId,
+				budgetUsd: allocatedUsd,
+				costLedger: plan.costLedger ?? void 0,
+				costPhase: plan.costPhase ?? void 0,
+				chat: plan.chat,
+				tags: contextTags,
+				log: (message, fields) => log(`[${analyst.id}] ${message}`, {
+					runId: plan.runId,
 					correlationId,
 					...fields
 				}),
 				signal: runSignal,
-				priorFindings: selectPriorFindings(runOpts.priorFindings, analyst.id),
-				upstreamFindings: runOpts.chainFindings && allFindings.length > 0 ? [...allFindings] : void 0,
+				priorFindings,
+				upstreamFindings: chainedFindings,
 				recordUsage: (receipt) => {
-					assertValidUsageReceipt(receipt);
-					usageReceipts.push(receipt);
+					if (!exact) {
+						assertValidAnalystUsageReceipt(receipt);
+						usageReceipts.push(receipt);
+						return;
+					}
+					usageReceipts.push(snapshotUsageReceiptOnce(receipt, `AnalystRegistry.runExact analyst "${analyst.id}" usage`));
 				}
 			};
-			await waitForHook(hooks.onBeforeAnalyze ? () => hooks.onBeforeAnalyze?.({
-				analyst,
-				ctx,
-				runId
-			}) : void 0, runSignal);
+			if (exact) {
+				if (contextTags) deepFreezeCanonicalJson(contextTags);
+				if (priorFindings) deepFreezeCanonicalJson(priorFindings);
+				if (chainedFindings) deepFreezeCanonicalJson(chainedFindings);
+				Object.freeze(ctx);
+			}
+			try {
+				await waitForHook(plan.hooks.onBeforeAnalyze ? () => plan.hooks.onBeforeAnalyze?.({
+					analyst,
+					ctx,
+					runId: plan.runId
+				}) : void 0, runSignal);
+			} catch (error) {
+				if (!exact) throw error;
+				executionFailure = error;
+				break;
+			}
 			if (runSignal?.aborted) {
 				const summary = abortedBeforeStartSummary(analyst, runSignal, Date.now() - t0);
-				summaries.push(summary);
-				log(`[analyst] skip ${analyst.id} — run aborted`, {
-					runId,
-					reason: summary.reason
+				executions.push({
+					summary,
+					findings: [],
+					budgetDebitUsd: 0
 				});
-				yield {
+				yield snapshotExecutionEvent({
 					type: "analyst-skipped",
 					summary
-				};
+				}, exact);
+				if (exact) {
+					executionFailure = abortReason(runSignal);
+					break;
+				}
 				continue;
 			}
-			const effectiveBudget = validateEffectiveBudget(ctx.budgetUsd, remainingUsd, analyst.id);
-			yield {
+			let effectiveBudget;
+			try {
+				effectiveBudget = validateEffectiveBudget(ctx.budgetUsd, budgetCeilingUsd, analyst.id);
+			} catch (error) {
+				if (!exact) throw error;
+				executionFailure = error;
+				break;
+			}
+			const analystContext = exact ? ctx : { ...ctx };
+			const executionSignal = exact ? ctx.signal : runSignal;
+			yield snapshotExecutionEvent({
 				type: "analyst-started",
 				analyst_id: analyst.id,
 				started_at: new Date(t0).toISOString()
-			};
+			}, exact);
 			let findings;
 			let summary;
+			let lifecycleFailure;
+			let analysisFailure;
 			try {
 				if (runSignal?.aborted) throw abortReason(runSignal);
-				findings = await waitForOperation(analyst.analyze(input.value, ctx), runSignal, analystAbortGraceMs(analyst));
-				const latency = Date.now() - t0;
-				const usage = resolveUsage(analyst, usageReceipts);
-				const cost = knownCostUsd(usage);
-				totalCost += cost;
-				if (typeof remainingUsd === "number") remainingUsd = Math.max(0, remainingUsd - budgetDebit(usage, effectiveBudget));
-				allFindings.push(...findings);
+				findings = snapshotExecutionFindings(await waitForOperation(analyst.analyze(input.value, analystContext), executionSignal, analystAbortGraceMs(analyst)), exact, `AnalystRegistry.runExact analyst "${analyst.id}" findings`);
+			} catch (error) {
+				const cause = error instanceof Error ? error : new Error(String(error));
+				analysisFailure = cause;
+				let hookFindings = [];
+				if (!executionSignal?.aborted) try {
+					hookFindings = snapshotExecutionFindings(await waitForHook(plan.hooks.onError ? () => plan.hooks.onError?.({
+						analyst,
+						error: cause,
+						runId: plan.runId
+					}) : void 0, executionSignal) ?? [], exact, `AnalystRegistry.runExact analyst "${analyst.id}" onError findings`);
+				} catch (error) {
+					lifecycleFailure = error;
+				}
+				findings = hookFindings;
+			}
+			let usage;
+			try {
+				usage = resolveUsage(analyst, usageReceipts, exact);
+			} catch (error) {
+				if (!exact) throw error;
+				executionFailure = error;
+				break;
+			}
+			if (analysisFailure === void 0) {
 				summary = {
 					analyst_id: analyst.id,
 					status: "ok",
 					findings_count: findings.length,
-					latency_ms: latency,
-					usage
+					latency_ms: Date.now() - t0,
+					usage,
+					...exact ? { allocated_budget_usd: effectiveBudget ?? null } : {}
 				};
-				summaries.push(summary);
 				log(`[analyst] ok ${analyst.id}`, {
-					runId,
+					runId: plan.runId,
 					findings: findings.length,
-					latency_ms: latency,
-					cost_usd: cost,
+					latency_ms: summary.latency_ms,
+					cost_usd: knownCostUsd(usage),
 					cost_kind: usage.cost.kind,
 					input_tokens: usage.tokens?.input ?? null,
 					output_tokens: usage.tokens?.output ?? null
 				});
-				if (effectiveBudget !== void 0 && usage.cost.kind === "uncaptured") log(`[analyst] WARN ${analyst.id} — USD cost uncaptured; budget not reconciled`, {
-					runId,
-					budget_usd: effectiveBudget,
-					cost_captured: false
-				});
-			} catch (err) {
-				const latency = Date.now() - t0;
-				const e = err instanceof Error ? err : new Error(String(err));
-				const hookFindings = runSignal?.aborted ? [] : await hooks.onError?.({
-					analyst,
-					error: e,
-					runId
-				}) ?? [];
-				if (hookFindings.length) allFindings.push(...hookFindings);
-				const usage = resolveUsage(analyst, usageReceipts);
-				const cost = knownCostUsd(usage);
-				totalCost += cost;
-				if (typeof remainingUsd === "number") remainingUsd = Math.max(0, remainingUsd - budgetDebit(usage, effectiveBudget));
-				const summary = {
+			} else {
+				const errorClass = analysisFailure.constructor.name || "Error";
+				const errorMessage = exact && analysisFailure.message.length === 0 ? "Analyst failed without an error message" : analysisFailure.message;
+				summary = {
 					analyst_id: analyst.id,
 					status: "failed",
-					findings_count: hookFindings.length,
-					latency_ms: latency,
+					findings_count: findings.length,
+					latency_ms: Date.now() - t0,
 					usage,
+					...exact ? { allocated_budget_usd: effectiveBudget ?? null } : {},
 					error: {
-						class: e.constructor.name,
-						message: e.message
+						class: errorClass,
+						message: errorMessage
 					}
 				};
-				summaries.push(summary);
 				log(`[analyst] FAIL ${analyst.id}`, {
-					runId,
-					error_class: e.constructor.name,
-					error: e.message,
-					cost_usd: cost,
+					runId: plan.runId,
+					error_class: errorClass,
+					error: errorMessage,
+					cost_usd: knownCostUsd(usage),
 					cost_kind: usage.cost.kind
 				});
-				if (effectiveBudget !== void 0 && usage.cost.kind === "uncaptured") log(`[analyst] WARN ${analyst.id} — USD cost uncaptured; budget not reconciled`, {
-					runId,
-					budget_usd: effectiveBudget,
-					cost_captured: false
-				});
-				await waitForHook(hooks.onAfterAnalyze ? () => hooks.onAfterAnalyze?.({
-					analyst,
-					summary,
-					findings: hookFindings,
-					runId
-				}) : void 0, runSignal);
-				yield {
-					type: "analyst-completed",
-					summary,
-					findings: hookFindings
-				};
-				continue;
 			}
-			await waitForHook(hooks.onAfterAnalyze ? () => hooks.onAfterAnalyze?.({
+			logUncapturedBudgetWarning({
 				analyst,
+				runId: plan.runId,
+				budgetUsd: effectiveBudget,
+				usage,
+				log
+			});
+			const execution = {
 				summary,
 				findings,
-				runId
-			}) : void 0, runSignal);
-			yield {
+				budgetDebitUsd: budgetDebit(summary.usage, effectiveBudget)
+			};
+			if (exact) try {
+				executionCost([...executions, execution], true);
+			} catch (error) {
+				executionFailure = error;
+				break;
+			}
+			executions.push(execution);
+			if (plan.budget.kind === "dynamic" && remainingUsd !== void 0) remainingUsd = Math.max(0, remainingUsd - execution.budgetDebitUsd);
+			if (plan.chainFindings) upstreamFindings.push(...findings);
+			if (lifecycleFailure !== void 0) {
+				if (!exact) throw lifecycleFailure;
+				executionFailure = lifecycleFailure;
+				break;
+			}
+			const hookValues = snapshotAfterHookValues(summary, findings, exact);
+			try {
+				await waitForHook(plan.hooks.onAfterAnalyze ? () => plan.hooks.onAfterAnalyze?.({
+					analyst,
+					summary: hookValues.summary,
+					findings: hookValues.findings,
+					runId: plan.runId
+				}) : void 0, executionSignal);
+			} catch (error) {
+				if (!exact) throw error;
+				executionFailure = error;
+				break;
+			}
+			yield snapshotExecutionEvent({
 				type: "analyst-completed",
 				summary,
 				findings
-			};
+			}, exact);
+			if (exact && runSignal?.aborted) {
+				executionFailure = abortReason(runSignal);
+				break;
+			}
 		}
-		const result = {
-			run_id: runId,
+		const summaries = executions.map(({ summary }) => summary);
+		const findings = executions.flatMap((execution) => execution.findings);
+		const cost = executionCost(executions, exact);
+		const baseResult = {
+			run_id: plan.runId,
 			correlation_id: correlationId,
 			started_at: startedAt,
 			ended_at: (/* @__PURE__ */ new Date()).toISOString(),
-			findings: allFindings,
+			findings,
 			per_analyst: summaries,
-			total_cost_usd: totalCost,
-			total_cost_provenance: aggregateCostProvenance(summaries.map((summary) => summary.usage?.cost ?? {
-				kind: "uncaptured",
-				usd: null
-			}))
-		};
-		await waitForHook(hooks.onComplete ? () => hooks.onComplete?.({ result }) : void 0, runSignal);
-		yield {
-			type: "run-completed",
-			result
+			total_cost_usd: cost.known,
+			total_cost_provenance: cost.provenance
 		};
+		if (plan.executionSnapshot === void 0) {
+			await waitForHook(plan.hooks.onComplete ? () => plan.hooks.onComplete?.({ result: baseResult }) : void 0, runSignal);
+			yield {
+				type: "run-completed",
+				result: baseResult
+			};
+			return;
+		}
+		let completeResult;
+		if (executionFailure === void 0) try {
+			completeResult = snapshotExactAnalystRunReceipt({
+				...baseResult,
+				execution_plan: plan.executionSnapshot,
+				completion: { status: "complete" }
+			}, "AnalystRegistry.runExact result");
+			await waitForHook(plan.hooks.onComplete ? () => plan.hooks.onComplete?.({ result: completeResult }) : void 0, runSignal);
+		} catch (error) {
+			executionFailure = error;
+		}
+		if (runSignal?.aborted) executionFailure ??= abortReason(runSignal);
+		if (executionFailure === void 0 && completeResult) {
+			yield snapshotExecutionEvent({
+				type: "run-completed",
+				result: completeResult
+			}, true);
+			return;
+		}
+		const cause = executionFailure instanceof Error ? executionFailure : new Error(String(executionFailure));
+		const errorClass = cause.constructor.name || "Error";
+		const errorMessage = cause.message.trim().length === 0 ? "Exact analyst run failed without a message" : cause.message;
+		throw new ExactAnalystRunExecutionError(`exact analyst run failed after starting: ${errorMessage}; partial result is attached`, {
+			...baseResult,
+			execution_plan: plan.executionSnapshot,
+			completion: {
+				status: "failed",
+				error: {
+					class: errorClass,
+					message: errorMessage
+				}
+			}
+		}, { cause });
 	}
 	selectAnalysts(opts) {
 		let candidates = Array.from(this.analysts.values());
@@ -2322,34 +3233,377 @@ var AnalystRegistry = class {
 		}
 		return candidates;
 	}
+	selectExactAnalysts(ids) {
+		return ids.map((id) => {
+			const analyst = this.analysts.get(id);
+			if (!analyst) throw new Error(`ExactRegistryRunOpts.analystIds names unknown analyst "${id}"`);
+			return {
+				registeredId: id,
+				analyst
+			};
+		});
+	}
 	routeInput(analyst, inputs) {
 		switch (analyst.inputKind) {
-			case "trace-store": return inputs.traceStore ? {
-				kind: "present",
-				value: inputs.traceStore
-			} : { kind: "missing" };
-			case "artifact-dir": return inputs.artifactDir ? {
-				kind: "present",
-				value: inputs.artifactDir
-			} : { kind: "missing" };
-			case "run-record": return inputs.runRecord ? {
-				kind: "present",
-				value: inputs.runRecord
-			} : { kind: "missing" };
-			case "judge-input": return inputs.judgeInput ? {
-				kind: "present",
-				value: inputs.judgeInput
-			} : { kind: "missing" };
+			case "trace-store": {
+				const value = inputs.traceStore;
+				return value ? {
+					kind: "present",
+					value
+				} : { kind: "missing" };
+			}
+			case "artifact-dir": {
+				const value = inputs.artifactDir;
+				return value ? {
+					kind: "present",
+					value
+				} : { kind: "missing" };
+			}
+			case "run-record": {
+				const value = inputs.runRecord;
+				return value ? {
+					kind: "present",
+					value
+				} : { kind: "missing" };
+			}
+			case "judge-input": {
+				const value = inputs.judgeInput;
+				return value ? {
+					kind: "present",
+					value
+				} : { kind: "missing" };
+			}
 			case "custom": {
-				const v = inputs.custom?.[analyst.id];
-				return v !== void 0 ? {
+				const value = inputs.custom?.[analyst.id];
+				return value !== void 0 ? {
 					kind: "present",
-					value: v
+					value
 				} : { kind: "missing" };
 			}
 		}
 	}
 };
+const exactRunFields = [
+	"analystIds",
+	"budget",
+	"totalTimeoutMs",
+	"signal",
+	"costLedger",
+	"costLedgerIdentity",
+	"costPhase",
+	"tags",
+	"priorFindings",
+	"chainFindings",
+	"missingInputMode",
+	"applyRegistryHooks",
+	"useRegistryChat"
+];
+const exactNonEmptyString = z.string().min(1);
+const exactFiniteNonnegative = z.number().finite().nonnegative();
+const exactBudgetSchema = z.discriminatedUnion("kind", [z.strictObject({
+	kind: z.literal("equal"),
+	totalUsd: exactFiniteNonnegative
+}), z.strictObject({
+	kind: z.literal("weighted"),
+	totalUsd: exactFiniteNonnegative,
+	weights: z.record(exactNonEmptyString, exactFiniteNonnegative)
+})]);
+const exactRunDataSchema = z.strictObject({
+	analystIds: z.array(exactNonEmptyString).min(1),
+	budget: exactBudgetSchema.nullable(),
+	totalTimeoutMs: z.number().int().positive().max(2147483647).nullable(),
+	costLedgerIdentity: z.unknown().nullable(),
+	costPhase: exactNonEmptyString.nullable(),
+	tags: z.record(z.string(), z.string()).nullable(),
+	chainFindings: z.boolean(),
+	missingInputMode: z.enum(["skip", "abort"]),
+	applyRegistryHooks: z.boolean(),
+	useRegistryChat: z.boolean()
+}).superRefine((policy, context) => {
+	const issue = (path, message) => context.addIssue({
+		code: "custom",
+		path,
+		message
+	});
+	if (new Set(policy.analystIds).size !== policy.analystIds.length) issue(["analystIds"], "must not contain duplicates");
+	if (policy.budget?.kind === "weighted" && Object.values(policy.budget.weights).every((weight) => weight === 0)) issue(["budget", "weights"], "must allocate positive weight to at least one analyst");
+	if (policy.budget?.kind === "weighted") {
+		const selected = [...policy.analystIds].sort();
+		const weighted = Object.keys(policy.budget.weights).sort();
+		if (selected.length !== weighted.length || selected.some((id, index) => id !== weighted[index])) issue(["budget", "weights"], "must name every selected analyst and no others");
+	}
+});
+/** Validate the canonical exact-run policy before any analyst can start. */
+function assertExactRegistryRunOpts(value) {
+	snapshotExactRegistryRunOpts(value);
+}
+function snapshotExactRunId(value) {
+	if (typeof value !== "string" || value.length === 0) throw new TypeError("AnalystRegistry.runExact: runId must be a non-empty string");
+	return canonicalJsonSnapshot(value, "AnalystRegistry.runExact runId");
+}
+function snapshotAnalystRunInputChannels(inputs) {
+	if (!inputs || typeof inputs !== "object" || Array.isArray(inputs)) throw new TypeError("AnalystRegistry.runExact: inputs must be an object");
+	const traceStore = inputs.traceStore;
+	const artifactDir = inputs.artifactDir;
+	const runRecord = inputs.runRecord;
+	const judgeInput = inputs.judgeInput;
+	const custom = inputs.custom;
+	return Object.freeze({
+		traceStore,
+		artifactDir,
+		runRecord,
+		judgeInput,
+		custom
+	});
+}
+/**
+* Read the untrusted caller object once, then validate and execute only this frozen snapshot.
+* Functions and resource handles retain identity; all data fields are copied canonically.
+*/
+function snapshotExactRegistryRunOpts(value) {
+	const captured = readOwnFields(value, exactRunFields, "ExactRegistryRunOpts");
+	const missing = exactRunFields.find((field) => !Object.hasOwn(captured, field));
+	if (missing) throw new TypeError(`ExactRegistryRunOpts.${missing} must be supplied explicitly`);
+	const { signal, costLedger, priorFindings, ...rawData } = captured;
+	const data = canonicalJsonSnapshot(rawData, "ExactRegistryRunOpts");
+	const parsed = exactRunDataSchema.safeParse(data);
+	if (!parsed.success) {
+		const issue = parsed.error.issues[0];
+		if (issue?.code === "unrecognized_keys" && issue.path.join(".") === "budget") {
+			const required = isPlainRecord(data.budget) && data.budget.kind === "weighted" ? "kind, totalUsd, weights" : "kind, totalUsd";
+			throw new TypeError(`ExactRegistryRunOpts.budget must contain exactly ${required}`);
+		}
+		const path = issue?.path.length ? `.${issue.path.join(".")}` : "";
+		throw new TypeError(`ExactRegistryRunOpts${path}: ${issue?.message ?? "is invalid"}`);
+	}
+	if (signal !== null && (!signal || typeof signal !== "object" || typeof signal.addEventListener !== "function")) throw new TypeError("ExactRegistryRunOpts.signal must be an AbortSignal or null");
+	if (costLedger !== null && (!costLedger || typeof costLedger !== "object")) throw new TypeError("ExactRegistryRunOpts.costLedger must be a CostLedgerHandle or null");
+	if (costLedger === null && parsed.data.costLedgerIdentity !== null) throw new TypeError("ExactRegistryRunOpts.costLedgerIdentity must be null without costLedger");
+	if (costLedger !== null && parsed.data.costLedgerIdentity === null) throw new TypeError("ExactRegistryRunOpts.costLedgerIdentity is required with costLedger");
+	if (costLedger === null && parsed.data.costPhase !== null) throw new TypeError("ExactRegistryRunOpts.costPhase requires a non-null costLedger");
+	return Object.freeze({
+		...deepFreezeCanonicalJson(parsed.data),
+		signal,
+		costLedger,
+		priorFindings: snapshotExactPriorFindings(priorFindings)
+	});
+}
+function snapshotExactPriorFindings(value) {
+	if (value === null) return null;
+	if (Array.isArray(value)) return snapshotAnalystFindings(value, "ExactRegistryRunOpts.priorFindings");
+	if (!isPlainRecord(value)) throw new TypeError("ExactRegistryRunOpts.priorFindings must be an array, a findings record, or null");
+	const result = {};
+	for (const [key, findings] of Object.entries(value)) {
+		if (!Array.isArray(findings)) throw new TypeError(`ExactRegistryRunOpts.priorFindings.${key} must be an array`);
+		result[key] = snapshotAnalystFindings(findings, `ExactRegistryRunOpts.priorFindings.${key}`);
+	}
+	return deepFreezeCanonicalJson(result);
+}
+function normalizeExactAnalysts(selections) {
+	return selections.map(({ registeredId, analyst }) => {
+		const exactAnalyst = analyst;
+		const id = analyst.id;
+		const description = analyst.description;
+		const inputKind = analyst.inputKind;
+		const rawCostValue = analyst.cost;
+		const requiresValue = analyst.requires;
+		const version = analyst.version;
+		const executionConfigValue = exactAnalyst.executionConfig;
+		const analyzeValue = analyst.analyze;
+		if (id !== registeredId) throw new TypeError(`AnalystRegistry.runExact: registered analyst "${registeredId}" changed id to "${id}"`);
+		if (executionConfigValue === void 0) throw new TypeError(`AnalystRegistry.runExact: analyst "${id}" must declare executionConfig`);
+		const executionConfig = canonicalJsonSnapshot(executionConfigValue, `AnalystRegistry.runExact analyst "${id}" executionConfig`);
+		if (!isPlainRecord(executionConfig)) throw new TypeError(`AnalystRegistry.runExact analyst "${id}" executionConfig must be an object`);
+		const rawCost = canonicalJsonSnapshot(rawCostValue, `AnalystRegistry.runExact analyst "${id}" cost`);
+		const cost = rawCost.kind === "llm" ? Object.freeze({
+			...rawCost,
+			settlement_timeout_ms: validateUsageSettlementTimeout(rawCost.settlement_timeout_ms)
+		}) : rawCost;
+		const requires = requiresValue === void 0 ? void 0 : canonicalJsonSnapshot(requiresValue, `AnalystRegistry.runExact analyst "${id}" requirements`);
+		const analyze = analyzeValue.bind(analyst);
+		return Object.freeze({
+			id,
+			description,
+			inputKind,
+			cost,
+			...requires === void 0 ? {} : { requires },
+			version,
+			executionConfig,
+			analyze
+		});
+	});
+}
+function hasRegistryHooks(hooks) {
+	return Boolean(hooks && (hooks.onBeforeAnalyze || hooks.onAfterAnalyze || hooks.onError || hooks.onComplete));
+}
+function snapshotHooks(hooks) {
+	const onBeforeAnalyze = hooks.onBeforeAnalyze;
+	const onAfterAnalyze = hooks.onAfterAnalyze;
+	const onError = hooks.onError;
+	const onComplete = hooks.onComplete;
+	return Object.freeze({
+		...onBeforeAnalyze === void 0 ? {} : { onBeforeAnalyze: onBeforeAnalyze.bind(hooks) },
+		...onAfterAnalyze === void 0 ? {} : { onAfterAnalyze: onAfterAnalyze.bind(hooks) },
+		...onError === void 0 ? {} : { onError: onError.bind(hooks) },
+		...onComplete === void 0 ? {} : { onComplete: onComplete.bind(hooks) }
+	});
+}
+function snapshotChat(chat) {
+	const transport = chat.transport;
+	const defaultModel = chat.defaultModel;
+	const maximumAttempts = chat.maximumAttempts;
+	const call = chat.chat;
+	return Object.freeze({
+		transport,
+		...defaultModel === void 0 ? {} : { defaultModel },
+		...maximumAttempts === void 0 ? {} : { maximumAttempts },
+		chat: call.bind(chat)
+	});
+}
+function requireExactComponentIdentity(value, label) {
+	if (value === void 0) throw new TypeError(`AnalystRegistry.runExact: ${label} requires a versioned identity`);
+	return snapshotExactExecutionComponentIdentity(value, `AnalystRegistry.runExact ${label} identity`);
+}
+function exactExecutionSnapshot(analysts, opts, allocations, costLedger, hooks, chat) {
+	const priorFindings = exactPriorFindingsSnapshot(opts.priorFindings);
+	const budget = opts.budget === null ? { kind: "none" } : opts.budget.kind === "equal" ? {
+		kind: "equal",
+		total_usd: opts.budget.totalUsd,
+		allocations_usd: { ...allocations }
+	} : {
+		kind: "weighted",
+		total_usd: opts.budget.totalUsd,
+		weights: { ...opts.budget.weights },
+		allocations_usd: { ...allocations }
+	};
+	const material = {
+		schema_version: "1.0.0",
+		analysts: analysts.map((analyst) => ({
+			id: analyst.id,
+			version: analyst.version,
+			input_kind: analyst.inputKind,
+			cost: analyst.cost,
+			requirements: analyst.requires ?? null,
+			execution_config_digest: hashCanonical(analyst.executionConfig)
+		})),
+		policy: {
+			budget,
+			total_timeout_ms: opts.totalTimeoutMs,
+			signal_provided: opts.signal !== null,
+			cost_ledger: costLedger,
+			cost_phase: opts.costPhase,
+			tags: opts.tags === null ? null : { ...opts.tags },
+			prior_findings: priorFindings,
+			chain_findings: opts.chainFindings,
+			missing_input_mode: opts.missingInputMode,
+			registry_hooks: hooks,
+			registry_chat: chat
+		}
+	};
+	return snapshotExactExecutionPlan({
+		...material,
+		digest: hashCanonical(material)
+	}, "AnalystRegistry.runExact execution plan");
+}
+function exactPriorFindingsSnapshot(findings) {
+	if (findings === null) return { kind: "none" };
+	if (Array.isArray(findings)) return {
+		kind: "ordered",
+		count: findings.length,
+		digest: hashCanonical(findings)
+	};
+	const record = findings;
+	const keys = Object.keys(record).sort();
+	return {
+		kind: "by_analyst",
+		keys,
+		count: keys.reduce((sum, key) => sum + (record[key]?.length ?? 0), 0),
+		digest: hashCanonical(record)
+	};
+}
+function canonicalJsonSnapshot(value, label) {
+	let snapshot;
+	try {
+		snapshot = JSON.parse(canonicalString(value));
+	} catch (cause) {
+		throw new TypeError(`${label} must be canonical JSON`, { cause });
+	}
+	return deepFreezeCanonicalJson(snapshot);
+}
+function snapshotUsageReceiptOnce(receipt, context) {
+	const data = readOwnFields(receipt, [
+		"calls",
+		"tokens",
+		"cost",
+		"knownCostUsd"
+	], context);
+	data.tokens = data.tokens === null ? null : readOwnFields(data.tokens, [
+		"input",
+		"output",
+		"reasoning",
+		"cached",
+		"cacheWrite"
+	], `${context} tokens`);
+	data.cost = readOwnFields(data.cost, ["kind", "usd"], `${context} cost`);
+	const snapshot = canonicalJsonSnapshot(data, context);
+	assertValidAnalystUsageReceipt(snapshot, context);
+	return snapshot;
+}
+function readOwnFields(value, fields, context) {
+	if (!isPlainRecord(value)) throw new TypeError(`${context} must be a plain object`);
+	const unexpected = Object.keys(value).filter((key) => !fields.includes(key));
+	if (unexpected.length > 0) throw new TypeError(`${context} contains unknown fields: ${unexpected.sort().join(", ")}`);
+	return Object.fromEntries(fields.flatMap((field) => Object.hasOwn(value, field) ? [[field, value[field]]] : []));
+}
+function isPlainRecord(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function exactFixedBudgets(exact, runnable, selected) {
+	if (exact === null) return {};
+	const allocations = Object.fromEntries(selected.map((analyst) => [analyst.id, null]));
+	if (runnable.length === 0) return deepFreezeCanonicalJson(allocations);
+	if (exact.kind === "equal") {
+		const each = exact.totalUsd / runnable.length;
+		for (const analyst of runnable) allocations[analyst.id] = each;
+		return deepFreezeCanonicalJson(allocations);
+	}
+	const totalWeight = runnable.reduce((sum, analyst) => sum + exact.weights[analyst.id], 0);
+	if (totalWeight === 0) throw new Error("ExactRegistryRunOpts weighted budget must allocate positive weight to a runnable analyst");
+	for (const analyst of runnable) allocations[analyst.id] = exact.totalUsd * exact.weights[analyst.id] / totalWeight;
+	return deepFreezeCanonicalJson(allocations);
+}
+function snapshotExecutionFindings(findings, exact, context) {
+	return exact ? deepFreezeCanonicalJson(snapshotAnalystFindings(findings, context)) : findings;
+}
+function snapshotAfterHookValues(summary, findings, exact) {
+	if (!exact) return {
+		summary,
+		findings
+	};
+	return {
+		summary: canonicalJsonSnapshot(summary, "AnalystRegistry.runExact onAfterAnalyze summary"),
+		findings: deepFreezeCanonicalJson(snapshotAnalystFindings(findings, "AnalystRegistry.runExact onAfterAnalyze findings"))
+	};
+}
+function exactPlannedAllocation(plan, analystId) {
+	const budget = plan.policy.budget;
+	if (budget.kind === "none") return void 0;
+	const allocated = budget.allocations_usd[analystId];
+	return allocated === null ? void 0 : allocated;
+}
+function snapshotExecutionEvent(event, exact) {
+	return exact ? canonicalJsonSnapshot(event, "AnalystRegistry.runExact event") : event;
+}
+function logUncapturedBudgetWarning(args) {
+	if (args.budgetUsd === void 0 || args.usage.cost.kind !== "uncaptured") return;
+	args.log(`[analyst] WARN ${args.analyst.id} — USD cost uncaptured; budget not reconciled`, {
+		runId: args.runId,
+		budget_usd: args.budgetUsd,
+		cost_captured: false
+	});
+}
 function validateTimeout(timeoutMs) {
 	if (timeoutMs === void 0) return void 0;
 	if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2147483647) throw new TypeError("RegistryRunOpts.timeoutMs must be a positive safe integer no greater than 2147483647");
@@ -2479,8 +3733,8 @@ function zeroUsage() {
 		}
 	};
 }
-function resolveUsage(analyst, receipts) {
-	if (receipts.length > 0) return mergeUsageReceipts(receipts);
+function resolveUsage(analyst, receipts, exact = false) {
+	if (receipts.length > 0) return mergeUsageReceipts(receipts, exact);
 	if (analyst.cost.kind === "deterministic") return zeroUsage();
 	return {
 		calls: null,
@@ -2491,24 +3745,21 @@ function resolveUsage(analyst, receipts) {
 		}
 	};
 }
-function mergeUsageReceipts(receipts) {
-	const calls = receipts.every((receipt) => receipt.calls !== null) ? receipts.reduce((sum, receipt) => sum + (receipt.calls ?? 0), 0) : null;
-	const tokens = receipts.every((receipt) => receipt.tokens !== null) ? receipts.reduce((sum, receipt) => ({
-		input: sum.input + (receipt.tokens?.input ?? 0),
-		output: sum.output + (receipt.tokens?.output ?? 0),
-		...sum.reasoning !== void 0 || receipt.tokens?.reasoning !== void 0 ? { reasoning: (sum.reasoning ?? 0) + (receipt.tokens?.reasoning ?? 0) } : {},
-		...sum.cached !== void 0 || receipt.tokens?.cached !== void 0 ? { cached: (sum.cached ?? 0) + (receipt.tokens?.cached ?? 0) } : {},
-		...sum.cacheWrite !== void 0 || receipt.tokens?.cacheWrite !== void 0 ? { cacheWrite: (sum.cacheWrite ?? 0) + (receipt.tokens?.cacheWrite ?? 0) } : {}
-	}), {
-		input: 0,
-		output: 0
-	}) : null;
-	const cost = aggregateCostProvenance(receipts.map((receipt) => receipt.cost));
+function mergeUsageReceipts(receipts, exact = false) {
+	const calls = receipts.every((receipt) => receipt.calls !== null) ? usageSum(receipts.map((receipt) => receipt.calls ?? 0), exact, "calls", true) : null;
+	const tokens = receipts.every((receipt) => receipt.tokens !== null) ? Object.fromEntries([
+		"input",
+		"output",
+		"reasoning",
+		"cached",
+		"cacheWrite"
+	].flatMap((field) => field === "input" || field === "output" || receipts.some((receipt) => receipt.tokens?.[field] !== void 0) ? [[field, usageSum(receipts.map((receipt) => receipt.tokens?.[field] ?? 0), exact, `tokens.${field}`, true)]] : [])) : null;
+	const cost = aggregateCostProvenance(receipts.map((receipt) => receipt.cost), exact);
 	return {
 		calls,
 		tokens,
 		cost,
-		...cost.kind === "uncaptured" ? { knownCostUsd: receipts.reduce((sum, receipt) => sum + knownCostUsd(receipt), 0) } : {}
+		...cost.kind === "uncaptured" ? { knownCostUsd: usageSum(receipts.map(knownCostUsd), exact, "known cost") } : {}
 	};
 }
 function knownCostUsd(receipt) {
@@ -2518,12 +3769,12 @@ function budgetDebit(receipt, allocatedUsd) {
 	const known = knownCostUsd(receipt);
 	return receipt.cost.kind === "uncaptured" && allocatedUsd !== void 0 ? Math.max(known, allocatedUsd) : known;
 }
-function aggregateCostProvenance(costs) {
+function aggregateCostProvenance(costs, exact = false) {
 	if (costs.some((cost) => cost.kind === "uncaptured")) return {
 		kind: "uncaptured",
 		usd: null
 	};
-	const usd = costs.reduce((sum, cost) => sum + (cost.usd ?? 0), 0);
+	const usd = usageSum(costs.map((cost) => cost.usd ?? 0), exact, "captured cost");
 	return costs.some((cost) => cost.kind === "estimated") ? {
 		kind: "estimated",
 		usd
@@ -2532,24 +3783,17 @@ function aggregateCostProvenance(costs) {
 		usd
 	};
 }
-function assertValidUsageReceipt(receipt) {
-	if (receipt.calls !== null && (!Number.isInteger(receipt.calls) || receipt.calls < 0)) throw new Error("AnalystContext.recordUsage: calls must be a non-negative integer or null");
-	if (receipt.tokens) {
-		assertNonNegativeFinite(receipt.tokens.input, "tokens.input");
-		assertNonNegativeFinite(receipt.tokens.output, "tokens.output");
-		if (receipt.tokens.reasoning !== void 0) {
-			assertNonNegativeFinite(receipt.tokens.reasoning, "tokens.reasoning");
-			if (receipt.tokens.reasoning > receipt.tokens.output) throw new Error("AnalystContext.recordUsage: tokens.reasoning must not exceed tokens.output");
-		}
-		if (receipt.tokens.cached !== void 0) assertNonNegativeFinite(receipt.tokens.cached, "tokens.cached");
-		if (receipt.tokens.cacheWrite !== void 0) assertNonNegativeFinite(receipt.tokens.cacheWrite, "tokens.cacheWrite");
-	}
-	if (receipt.cost.kind !== "uncaptured") assertNonNegativeFinite(receipt.cost.usd, "cost.usd");
-	else if (receipt.cost.usd !== null) throw new Error("AnalystContext.recordUsage: uncaptured cost.usd must be null");
-	if (receipt.knownCostUsd !== void 0) assertNonNegativeFinite(receipt.knownCostUsd, "knownCostUsd");
+function executionCost(executions, exact) {
+	const usages = executions.map((execution) => execution.summary.usage);
+	return {
+		known: usageSum(usages.map(knownCostUsd), exact, "run known cost"),
+		provenance: aggregateCostProvenance(usages.map((usage) => usage.cost), exact)
+	};
 }
-function assertNonNegativeFinite(value, field) {
-	if (!Number.isFinite(value) || value < 0) throw new Error(`AnalystContext.recordUsage: ${field} must be a non-negative finite number`);
+function usageSum(values, exact, field, integer = false) {
+	const sum = values.reduce((total, value) => total + value, 0);
+	if (exact && (integer ? !Number.isSafeInteger(sum) : !Number.isFinite(sum))) throw new RangeError(`exact analyst usage ${field} aggregate ${integer ? "exceeds a safe integer" : "is not finite"}`);
+	return sum;
 }
 /**
 * Resolve the `priorFindings` slice an analyst sees.
@@ -2583,12 +3827,13 @@ function buildDefaultAnalystRegistry(opts = {}) {
 		const kinds = opts.kinds ?? DEFAULT_TRACE_ANALYST_KINDS;
 		for (const spec of kinds) registry.register(createTraceAnalystKind(spec, {
 			ai: opts.ai,
-			model: opts.model
+			model: opts.model,
+			aiIdentity: opts.aiIdentity
 		}));
 	}
 	return registry;
 }
 //#endregion
-export { FindingSubjectStringSchema as A, parseRawFinding as C, FINDING_SUBJECT_GRAMMAR_PROMPT as D, stripCodeFences as E, behavioralAnalyst as F, deriveEfficiencyFindings as I, computeTraceMetrics as L, findingSubjectGrammarPromptFor as M, parseFindingSubject as N, FINDING_SUBJECT_KINDS as O, renderFindingSubject as P, createChatClient as R, evidenceRefsFromRawFinding as S, coerceToFindingRows as T, structureFindings as _, KNOWLEDGE_GAP_KIND_SPEC as a, RawAnalystEvidenceSchema as b, buildTraceToolsForGroup as c, emitControlIntegrityFindings as d, createTraceAnalystKind as f, validateUsageSettlementTimeout as g, settleUsageReceiptFromCostLedger as h, KNOWLEDGE_POISONING_KIND_SPEC as i, KIND_EXPECTED_SUBJECTS as j, FINDING_SUBJECT_SYNTAX as k, CONTROL_INTEGRITY_ANALYST as l, renderUpstreamFindings as m, AnalystRegistry as n, IMPROVEMENT_KIND_SPEC as o, renderPriorFindings as p, DEFAULT_TRACE_ANALYST_KINDS as r, FAILURE_MODE_KIND_SPEC as s, buildDefaultAnalystRegistry as t, ControlIntegrityAnalyst as u, ANALYST_SEVERITIES as v, coerceJson as w, RawAnalystFindingSchema as x, RAW_FINDING_SCHEMA_PROMPT as y, createAnalystAi as z };
+export { parseRawFinding as A, parseFindingSubject as B, renderUpstreamFindings as C, RawAnalystEvidenceSchema as D, RAW_FINDING_SCHEMA_PROMPT as E, FINDING_SUBJECT_KINDS as F, createChatClient as G, behavioralAnalyst as H, FINDING_SUBJECT_SYNTAX as I, createAnalystAi as K, FindingSubjectStringSchema as L, coerceToFindingRows as M, stripCodeFences as N, RawAnalystFindingSchema as O, FINDING_SUBJECT_GRAMMAR_PROMPT as P, KIND_EXPECTED_SUBJECTS as R, renderPriorFindings as S, ANALYST_SEVERITIES as T, deriveEfficiencyFindings as U, renderFindingSubject as V, computeTraceMetrics as W, buildTraceToolsForGroup as _, analystFindingDigest as a, emitControlIntegrityFindings as b, completedAnalystReviewQuality as c, validateAnalystReviewDecisions as d, DEFAULT_TRACE_ANALYST_KINDS as f, FAILURE_MODE_KIND_SPEC as g, IMPROVEMENT_KIND_SPEC as h, assertExactRegistryRunOpts as i, coerceJson as j, evidenceRefsFromRawFinding as k, readAnalystReview as l, KNOWLEDGE_GAP_KIND_SPEC as m, AnalystRegistry as n, analystRunDigest as o, KNOWLEDGE_POISONING_KIND_SPEC as p, ExactAnalystRunExecutionError as r, assertUniqueFindingIds as s, buildDefaultAnalystRegistry as t, snapshotAnalystRun as u, CONTROL_INTEGRITY_ANALYST as v, structureFindings as w, createTraceAnalystKind as x, ControlIntegrityAnalyst as y, findingSubjectGrammarPromptFor as z };
 
-//# sourceMappingURL=default-registry-CLXbRt0f.js.map
+//# sourceMappingURL=default-registry-lp5R0lve.js.map