@tangle-network/agent-eval 0.215.0 → 0.216.0

package/dist/{default-registry-BhYGMVbV.js → default-registry-Cn1LQ2Ve.js}

@@ -1,11 +1,11 @@
 import { a as hashCanonical, r as canonicalString } from "./canonical-BsZVgBhW.js";
 import { t as deepFreezeCanonicalJson } from "./deep-freeze-CurcOQg3.js";
-import { C as combineAbortSignals } from "./llm-client-C_o62yG1.js";
-import { A as spanEpochMillis, H as findingSubjectGrammarPromptFor, J as snapshotExactExecutionPlan, q as snapshotExactExecutionComponentIdentity, t as createTraceAnalyst } from "./kind-factory-CMlOx08-.js";
+import { a as makeFinding } from "./types-IXD2HJzu.js";
+import { C as combineAbortSignals } from "./llm-client-DQveoxSM.js";
+import { A as spanEpochMillis, H as findingSubjectGrammarPromptFor, J as snapshotExactExecutionPlan, q as snapshotExactExecutionComponentIdentity, t as createTraceAnalyst } from "./kind-factory-CbZ-6tvu.js";
 import { i as validateUsageSettlementTimeout, t as assertValidAnalystUsageReceipt } from "./usage-receipt-Cx3xNeyB.js";
 import { LLM_CONTEXT_TOKENS, LLM_INPUT_TOKEN_ATTR_KEYS, LLM_OUTPUT_TOKEN_ATTR_KEYS, TOOL_NAME_ATTR_KEYS } from "./trace-attributes.js";
 import "./otlp-attributes-D9ptWaIJ.js";
-import { r as makeFinding } from "./types-CW5b90JH.js";
 import { t as executionTrackByLane } from "./execution-tracks-CpgFPpS5.js";
 import { t as analyzeSupervisorRunIntegrity } from "./integrity-BV1ZDf42.js";
 import { randomUUID } from "node:crypto";
@@ -1265,564 +1265,336 @@ const DEFAULT_TRACE_ANALYST_KINDS = [
 	IMPROVEMENT_KIND_SPEC
 ];
 //#endregion
-//#region src/analyst/registry.ts
+//#region src/analyst/registry-accounting.ts
+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 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
+	});
+}
 /**
-* AnalystRegistry — orchestrate N analysts against one run.
-*
-* Owns three responsibilities and only three:
-*   1. Registration — ids must be unique; bad registrations fail loudly
-*      at register-time, not run-time.
-*   2. Routing — each analyst declares its `inputKind`; the registry
-*      picks the matching field from AnalystRunInputs and skips the
-*      analyst with a logged reason if it's missing.
-*   3. Isolation — one analyst's exception MUST NOT stop other analysts.
-*      Failed analysts produce zero findings + a 'failed' summary row.
-*
-* Cross-cutting concerns (telemetry, error → finding conversion, cost
-* ingestion, storage rotation) live in `AnalystHooks`. Budget shaping
-* (equal split vs weighted vs custom) lives in `BudgetPolicy`. Both
-* have sensible defaults; consumers override only what they need.
+* Custom allocation takes priority, then weights, then equal shares.
+* Each allocation stays within the unspent overall budget.
 */
-/** 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;
-	constructor(options = {}) {
-		this.options = options;
-	}
-	register(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) => ({
-			id: a.id,
-			description: a.description,
-			version: a.version,
-			cost: a.cost
-		}));
-	}
-	async run(runId, inputs, runOpts = {}) {
-		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` /
-	* `started` / `completed`, then a terminal `run-completed` whose
-	* payload is the full `AnalystRunResult`. UIs use this to render
-	* progress; persistence consumers use `run()` and read the result.
-	*
-	* Hooks (`onBeforeAnalyze` / `onAfterAnalyze` / `onError` /
-	* `onComplete`) fire as before — streaming is additive, not a hook
-	* 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}"`);
+function allocateBudget(policy, args) {
+	if (!policy) return void 0;
+	if (policy.allocate) {
+		const allocated = policy.allocate({
+			analyst: args.analyst,
+			totalUsd: policy.totalUsd,
+			remainingUsd: args.remainingUsd,
+			runningCount: args.runningCount
+		});
+		if (allocated === void 0) {
+			if (policy.totalUsd !== void 0) throw new Error(`BudgetPolicy.allocate('${args.analyst.id}') cannot return undefined when totalUsd is set`);
+			return;
 		}
-		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
-		};
+		assertBudgetAmount(allocated, `BudgetPolicy.allocate('${args.analyst.id}')`);
+		return args.remainingUsd === void 0 ? allocated : Math.min(allocated, args.remainingUsd);
 	}
-	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 = plan.log;
-		const startedAt = (/* @__PURE__ */ new Date()).toISOString();
-		const started = Date.now();
-		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: plan.runId,
-			correlation_id: correlationId,
-			started_at: startedAt,
-			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);
-				executions.push({
-					summary,
-					findings: [],
-					budgetDebitUsd: 0
-				});
-				log(`[analyst] skip ${analyst.id} — run aborted`, {
-					runId: plan.runId,
-					reason: summary.reason
-				});
-				yield snapshotExecutionEvent({
-					type: "analyst-skipped",
-					summary
-				}, exact);
-				if (exact) {
-					executionFailure = abortReason(runSignal);
-					break;
-				}
-				continue;
-			}
-			if (input.kind === "missing") {
-				const summary = {
-					analyst_id: analyst.id,
-					status: "skipped",
-					reason: `missing input of kind '${analyst.inputKind}'`,
-					findings_count: 0,
-					latency_ms: 0,
-					usage: zeroUsage()
-				};
-				const execution = {
-					summary,
-					findings: [],
-					budgetDebitUsd: 0
-				};
-				executions.push(execution);
-				log(`[analyst] skip ${analyst.id} — missing input`, {
-					runId: plan.runId,
-					kind: analyst.inputKind
-				});
-				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 allocatedUsd = plan.executionSnapshot === void 0 ? allocateBudget(plan.budget.kind === "dynamic" ? plan.budget.policy : void 0, {
-				analyst,
-				remainingUsd,
-				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: plan.runId,
-				correlationId,
-				deadlineMs,
-				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,
-				upstreamFindings: chainedFindings,
-				recordUsage: (receipt) => {
-					if (!exact) {
-						assertValidAnalystUsageReceipt(receipt);
-						usageReceipts.push(receipt);
-						return;
-					}
-					usageReceipts.push(snapshotUsageReceiptOnce(receipt, `AnalystRegistry.runExact analyst "${analyst.id}" usage`));
-				}
-			};
-			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);
-				executions.push({
-					summary,
-					findings: [],
-					budgetDebitUsd: 0
-				});
-				yield snapshotExecutionEvent({
-					type: "analyst-skipped",
-					summary
-				}, exact);
-				if (exact) {
-					executionFailure = abortReason(runSignal);
-					break;
-				}
-				continue;
-			}
-			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 = 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: Date.now() - t0,
-					usage,
-					...exact ? { allocated_budget_usd: effectiveBudget ?? null } : {}
-				};
-				log(`[analyst] ok ${analyst.id}`, {
-					runId: plan.runId,
-					findings: findings.length,
-					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
-				});
-			} 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: findings.length,
-					latency_ms: Date.now() - t0,
-					usage,
-					...exact ? { allocated_budget_usd: effectiveBudget ?? null } : {},
-					error: {
-						class: errorClass,
-						message: errorMessage
-					}
-				};
-				log(`[analyst] FAIL ${analyst.id}`, {
-					runId: plan.runId,
-					error_class: errorClass,
-					error: errorMessage,
-					cost_usd: knownCostUsd(usage),
-					cost_kind: usage.cost.kind
-				});
-			}
-			logUncapturedBudgetWarning({
-				analyst,
-				runId: plan.runId,
-				budgetUsd: effectiveBudget,
-				usage,
-				log
-			});
-			const execution = {
-				summary,
-				findings,
-				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;
-			}
+	if (policy.totalUsd == null) return void 0;
+	const allocated = policy.weights ? policy.totalUsd * analystWeight(policy.weights, args.analyst.id) / args.totalWeight : policy.totalUsd / Math.max(1, args.runningCount);
+	return args.remainingUsd === void 0 ? allocated : Math.min(allocated, args.remainingUsd);
+}
+function validateBudgetPolicy(policy) {
+	if (!policy) return;
+	if (policy.totalUsd !== void 0) assertBudgetAmount(policy.totalUsd, "BudgetPolicy.totalUsd");
+	for (const [analystId, weight] of Object.entries(policy.weights ?? {})) assertBudgetAmount(weight, `BudgetPolicy.weights['${analystId}']`);
+}
+function assertBudgetAmount(value, field) {
+	if (!Number.isFinite(value) || value < 0) throw new Error(`${field} must be a non-negative finite number`);
+}
+function validateEffectiveBudget(budgetUsd, remainingUsd, analystId) {
+	if (budgetUsd !== void 0) assertBudgetAmount(budgetUsd, `AnalystContext.budgetUsd for '${analystId}'`);
+	if (remainingUsd === void 0) return budgetUsd;
+	if (budgetUsd === void 0) throw new Error(`AnalystContext.budgetUsd for '${analystId}' cannot be removed while an overall budget remains`);
+	if (budgetUsd > remainingUsd) throw new Error(`AnalystContext.budgetUsd for '${analystId}' (${budgetUsd}) exceeds the remaining overall budget (${remainingUsd})`);
+	return budgetUsd;
+}
+function analystWeight(weights, analystId) {
+	const weight = weights[analystId] ?? 1;
+	assertBudgetAmount(weight, `BudgetPolicy.weights['${analystId}']`);
+	return weight;
+}
+function zeroUsage() {
+	return {
+		calls: 0,
+		tokens: {
+			input: 0,
+			output: 0
+		},
+		cost: {
+			kind: "observed",
+			usd: 0
 		}
-		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,
-			per_analyst: summaries,
-			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;
+	};
+}
+function resolveUsage(analyst, receipts, exact = false) {
+	if (receipts.length > 0) return mergeUsageReceipts(receipts, exact);
+	if (analyst.cost.kind === "deterministic") return zeroUsage();
+	return {
+		calls: null,
+		tokens: null,
+		cost: {
+			kind: "uncaptured",
+			usd: null
+		}
+	};
+}
+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: usageSum(receipts.map(knownCostUsd), exact, "known cost") } : {}
+	};
+}
+function knownCostUsd(receipt) {
+	return receipt.cost.kind === "uncaptured" ? receipt.knownCostUsd ?? 0 : receipt.cost.usd;
+}
+function budgetDebit(receipt, allocatedUsd) {
+	const known = knownCostUsd(receipt);
+	return receipt.cost.kind === "uncaptured" && allocatedUsd !== void 0 ? Math.max(known, allocatedUsd) : known;
+}
+function aggregateCostProvenance(costs, exact = false) {
+	if (costs.some((cost) => cost.kind === "uncaptured")) return {
+		kind: "uncaptured",
+		usd: null
+	};
+	const usd = usageSum(costs.map((cost) => cost.usd ?? 0), exact, "captured cost");
+	return costs.some((cost) => cost.kind === "estimated") ? {
+		kind: "estimated",
+		usd
+	} : {
+		kind: "observed",
+		usd
+	};
+}
+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 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;
+}
+//#endregion
+//#region src/analyst/registry-plan.ts
+function normalizeLegacyPlan(runId, inputs, runOpts, analysts, options) {
+	const timeoutMs = validateTimeout(runOpts.timeoutMs) ?? null;
+	const budget = runOpts.budget ?? options.defaultBudget;
+	validateBudgetPolicy(budget);
+	return {
+		runId,
+		prepared: selectAnalysts(analysts, runOpts).map((analyst) => ({
+			analyst,
+			input: 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: options.hooks ?? {},
+		chat: options.chat,
+		log: options.log ?? (() => {}),
+		executionSnapshot: void 0
+	};
+}
+function routeInput(analyst, inputs) {
+	switch (analyst.inputKind) {
+		case "trace-store": {
+			const value = inputs.traceStore;
+			return value ? {
+				kind: "present",
+				value
+			} : { kind: "missing" };
 		}
-		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;
+		case "artifact-dir": {
+			const value = inputs.artifactDir;
+			return value ? {
+				kind: "present",
+				value
+			} : { kind: "missing" };
 		}
-		if (runSignal?.aborted) executionFailure ??= abortReason(runSignal);
-		if (executionFailure === void 0 && completeResult) {
-			yield snapshotExecutionEvent({
-				type: "run-completed",
-				result: completeResult
-			}, true);
-			return;
+		case "run-record": {
+			const value = inputs.runRecord;
+			return value ? {
+				kind: "present",
+				value
+			} : { kind: "missing" };
 		}
-		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());
-		if (opts.only?.length) {
-			const only = new Set(opts.only);
-			candidates = candidates.filter((a) => only.has(a.id));
+		case "judge-input": {
+			const value = inputs.judgeInput;
+			return value ? {
+				kind: "present",
+				value
+			} : { kind: "missing" };
 		}
-		if (opts.skip?.length) {
-			const skip = new Set(opts.skip);
-			candidates = candidates.filter((a) => !skip.has(a.id));
+		case "custom": {
+			const value = inputs.custom?.[analyst.id];
+			return value !== void 0 ? {
+				kind: "present",
+				value
+			} : { kind: "missing" };
 		}
-		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
-			};
-		});
+}
+function selectAnalysts(analysts, opts) {
+	let candidates = Array.from(analysts.values());
+	if (opts.only?.length) {
+		const only = new Set(opts.only);
+		candidates = candidates.filter((a) => only.has(a.id));
 	}
-	routeInput(analyst, inputs) {
-		switch (analyst.inputKind) {
-			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 value = inputs.custom?.[analyst.id];
-				return value !== void 0 ? {
-					kind: "present",
-					value
-				} : { kind: "missing" };
-			}
-		}
+	if (opts.skip?.length) {
+		const skip = new Set(opts.skip);
+		candidates = candidates.filter((a) => !skip.has(a.id));
 	}
-};
+	return candidates;
+}
+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");
+	return timeoutMs;
+}
+//#endregion
+//#region src/analyst/registry-snapshot.ts
+/** Immutable snapshots at exact execution's untrusted input and observational boundaries. */
+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 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 snapshotExecutionEvent(event, exact) {
+	return exact ? canonicalJsonSnapshot(event, "AnalystRegistry.runExact event") : event;
+}
+//#endregion
+//#region src/analyst/registry-exact-plan.ts
+/** Validate and freeze every input and identity before an exact analyst run starts. */
+function normalizeExactPlan(runId, inputs, runOpts, analysts, options) {
+	const exactRunId = snapshotExactRunId(runId);
+	const exact = snapshotExactRegistryRunOpts(runOpts);
+	const selected = normalizeExactAnalysts(selectExactAnalysts(analysts, exact.analystIds));
+	const registryChat = options.chat;
+	const registryChatIdentity = options.chatIdentity;
+	const registryHooks = options.hooks;
+	const registryHooksIdentity = 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: 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
+	};
+}
+function selectExactAnalysts(analysts, ids) {
+	return ids.map((id) => {
+		const analyst = analysts.get(id);
+		if (!analyst) throw new Error(`ExactRegistryRunOpts.analystIds names unknown analyst "${id}"`);
+		return {
+			registeredId: id,
+			analyst
+		};
+	});
+}
 const exactRunFields = [
 	"analystIds",
 	"budget",
@@ -2057,45 +1829,6 @@ function exactPriorFindingsSnapshot(findings) {
 		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]));
@@ -2105,45 +1838,372 @@ function exactFixedBudgets(exact, runnable, selected) {
 		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"))
+	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);
+}
+//#endregion
+//#region src/analyst/registry-execution.ts
+/** Execute one prepared plan with serial analyst isolation, lifecycle hooks, and accounting. */
+/** 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;
+	}
+};
+async function* 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 = plan.log;
+	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const started = Date.now();
+	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: plan.runId,
+		correlation_id: correlationId,
+		started_at: startedAt,
+		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);
+			executions.push({
+				summary,
+				findings: [],
+				budgetDebitUsd: 0
+			});
+			log(`[analyst] skip ${analyst.id} — run aborted`, {
+				runId: plan.runId,
+				reason: summary.reason
+			});
+			yield snapshotExecutionEvent({
+				type: "analyst-skipped",
+				summary
+			}, exact);
+			if (exact) {
+				executionFailure = abortReason(runSignal);
+				break;
+			}
+			continue;
+		}
+		if (input.kind === "missing") {
+			const summary = {
+				analyst_id: analyst.id,
+				status: "skipped",
+				reason: `missing input of kind '${analyst.inputKind}'`,
+				findings_count: 0,
+				latency_ms: 0,
+				usage: zeroUsage()
+			};
+			const execution = {
+				summary,
+				findings: [],
+				budgetDebitUsd: 0
+			};
+			executions.push(execution);
+			log(`[analyst] skip ${analyst.id} — missing input`, {
+				runId: plan.runId,
+				kind: analyst.inputKind
+			});
+			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 allocatedUsd = plan.executionSnapshot === void 0 ? allocateBudget(plan.budget.kind === "dynamic" ? plan.budget.policy : void 0, {
+			analyst,
+			remainingUsd,
+			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: plan.runId,
+			correlationId,
+			deadlineMs,
+			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,
+			upstreamFindings: chainedFindings,
+			recordUsage: (receipt) => {
+				if (!exact) {
+					assertValidAnalystUsageReceipt(receipt);
+					usageReceipts.push(receipt);
+					return;
+				}
+				usageReceipts.push(snapshotUsageReceiptOnce(receipt, `AnalystRegistry.runExact analyst "${analyst.id}" usage`));
+			}
+		};
+		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);
+			executions.push({
+				summary,
+				findings: [],
+				budgetDebitUsd: 0
+			});
+			yield snapshotExecutionEvent({
+				type: "analyst-skipped",
+				summary
+			}, exact);
+			if (exact) {
+				executionFailure = abortReason(runSignal);
+				break;
+			}
+			continue;
+		}
+		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 = 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: Date.now() - t0,
+				usage,
+				...exact ? { allocated_budget_usd: effectiveBudget ?? null } : {}
+			};
+			log(`[analyst] ok ${analyst.id}`, {
+				runId: plan.runId,
+				findings: findings.length,
+				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
+			});
+		} 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: findings.length,
+				latency_ms: Date.now() - t0,
+				usage,
+				...exact ? { allocated_budget_usd: effectiveBudget ?? null } : {},
+				error: {
+					class: errorClass,
+					message: errorMessage
+				}
+			};
+			log(`[analyst] FAIL ${analyst.id}`, {
+				runId: plan.runId,
+				error_class: errorClass,
+				error: errorMessage,
+				cost_usd: knownCostUsd(usage),
+				cost_kind: usage.cost.kind
+			});
+		}
+		logUncapturedBudgetWarning({
+			analyst,
+			runId: plan.runId,
+			budgetUsd: effectiveBudget,
+			usage,
+			log
+		});
+		const execution = {
+			summary,
+			findings,
+			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 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,
+		per_analyst: summaries,
+		total_cost_usd: cost.known,
+		total_cost_provenance: cost.provenance
 	};
-}
-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");
-	return timeoutMs;
+	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 });
 }
 async function waitForOperation(operation, signal, abortGraceMs) {
 	if (!signal) return operation;
@@ -2211,137 +2271,7 @@ function abortedBeforeStartSummary(analyst, signal, latencyMs = 0) {
 function abortReason(signal) {
 	return signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted", "AbortError");
 }
-/**
-* Default budget allocator: prefer the custom `allocate` callback if
-* provided; else weighted split when weights are set; else equal split
-* across `runningCount`. Returns undefined when no totalUsd is known.
-*/
-function allocateBudget(policy, args) {
-	if (!policy) return void 0;
-	if (policy.allocate) {
-		const allocated = policy.allocate({
-			analyst: args.analyst,
-			totalUsd: policy.totalUsd,
-			remainingUsd: args.remainingUsd,
-			runningCount: args.runningCount
-		});
-		if (allocated === void 0) {
-			if (policy.totalUsd !== void 0) throw new Error(`BudgetPolicy.allocate('${args.analyst.id}') cannot return undefined when totalUsd is set`);
-			return;
-		}
-		assertBudgetAmount(allocated, `BudgetPolicy.allocate('${args.analyst.id}')`);
-		return args.remainingUsd === void 0 ? allocated : Math.min(allocated, args.remainingUsd);
-	}
-	if (policy.totalUsd == null) return void 0;
-	const allocated = policy.weights ? policy.totalUsd * analystWeight(policy.weights, args.analyst.id) / args.totalWeight : policy.totalUsd / Math.max(1, args.runningCount);
-	return args.remainingUsd === void 0 ? allocated : Math.min(allocated, args.remainingUsd);
-}
-function validateBudgetPolicy(policy) {
-	if (!policy) return;
-	if (policy.totalUsd !== void 0) assertBudgetAmount(policy.totalUsd, "BudgetPolicy.totalUsd");
-	for (const [analystId, weight] of Object.entries(policy.weights ?? {})) assertBudgetAmount(weight, `BudgetPolicy.weights['${analystId}']`);
-}
-function assertBudgetAmount(value, field) {
-	if (!Number.isFinite(value) || value < 0) throw new Error(`${field} must be a non-negative finite number`);
-}
-function validateEffectiveBudget(budgetUsd, remainingUsd, analystId) {
-	if (budgetUsd !== void 0) assertBudgetAmount(budgetUsd, `AnalystContext.budgetUsd for '${analystId}'`);
-	if (remainingUsd === void 0) return budgetUsd;
-	if (budgetUsd === void 0) throw new Error(`AnalystContext.budgetUsd for '${analystId}' cannot be removed while an overall budget remains`);
-	if (budgetUsd > remainingUsd) throw new Error(`AnalystContext.budgetUsd for '${analystId}' (${budgetUsd}) exceeds the remaining overall budget (${remainingUsd})`);
-	return budgetUsd;
-}
-function analystWeight(weights, analystId) {
-	const weight = weights[analystId] ?? 1;
-	assertBudgetAmount(weight, `BudgetPolicy.weights['${analystId}']`);
-	return weight;
-}
-function zeroUsage() {
-	return {
-		calls: 0,
-		tokens: {
-			input: 0,
-			output: 0
-		},
-		cost: {
-			kind: "observed",
-			usd: 0
-		}
-	};
-}
-function resolveUsage(analyst, receipts, exact = false) {
-	if (receipts.length > 0) return mergeUsageReceipts(receipts, exact);
-	if (analyst.cost.kind === "deterministic") return zeroUsage();
-	return {
-		calls: null,
-		tokens: null,
-		cost: {
-			kind: "uncaptured",
-			usd: null
-		}
-	};
-}
-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: usageSum(receipts.map(knownCostUsd), exact, "known cost") } : {}
-	};
-}
-function knownCostUsd(receipt) {
-	return receipt.cost.kind === "uncaptured" ? receipt.knownCostUsd ?? 0 : receipt.cost.usd;
-}
-function budgetDebit(receipt, allocatedUsd) {
-	const known = knownCostUsd(receipt);
-	return receipt.cost.kind === "uncaptured" && allocatedUsd !== void 0 ? Math.max(known, allocatedUsd) : known;
-}
-function aggregateCostProvenance(costs, exact = false) {
-	if (costs.some((cost) => cost.kind === "uncaptured")) return {
-		kind: "uncaptured",
-		usd: null
-	};
-	const usd = usageSum(costs.map((cost) => cost.usd ?? 0), exact, "captured cost");
-	return costs.some((cost) => cost.kind === "estimated") ? {
-		kind: "estimated",
-		usd
-	} : {
-		kind: "observed",
-		usd
-	};
-}
-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 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.
-*
-*   - Array form  → the analyst sees only findings whose `analyst_id`
-*                   matches its own id, so a kind never reads
-*                   another kind's history by accident.
-*   - Record form → the analyst gets the entry keyed by its id, with
-*                   the `'*'` wildcard appended (in that order). Use
-*                   the wildcard when several kinds should see the same
-*                   historical findings.
-*/
+/** Return the analyst's own history, followed by any broadcast findings. */
 function selectPriorFindings(source, analystId) {
 	if (!source) return void 0;
 	if (Array.isArray(source)) {
@@ -2355,6 +2285,61 @@ function selectPriorFindings(source, analystId) {
 	return merged.length > 0 ? merged : void 0;
 }
 //#endregion
+//#region src/analyst/registry.ts
+var AnalystRegistry = class {
+	analysts = /* @__PURE__ */ new Map();
+	options;
+	constructor(options = {}) {
+		this.options = options;
+	}
+	register(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) => ({
+			id: a.id,
+			description: a.description,
+			version: a.version,
+			cost: a.cost
+		}));
+	}
+	async run(runId, inputs, runOpts = {}) {
+		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 executePlanStream(normalizeExactPlan(runId, inputs, runOpts, this.analysts, this.options))) yield event;
+	}
+	/**
+	* Streaming counterpart to `run()`. Emits `AnalystRunEvent` values
+	* in real time — `run-started`, then per-analyst `skipped` /
+	* `started` / `completed`, then a terminal `run-completed` whose
+	* payload is the full `AnalystRunResult`. UIs use this to render
+	* progress; persistence consumers use `run()` and read the result.
+	*
+	* Hooks (`onBeforeAnalyze` / `onAfterAnalyze` / `onError` /
+	* `onComplete`) fire as before — streaming is additive, not a hook
+	* replacement.
+	*/
+	async *runStream(runId, inputs, runOpts = {}) {
+		yield* executePlanStream(normalizeLegacyPlan(runId, inputs, runOpts, this.analysts, this.options));
+	}
+};
+//#endregion
 //#region src/analyst/default-registry.ts
 function buildDefaultAnalystRegistry(options = {}) {
 	if (options.definitions && !options.engine) throw new TypeError("buildDefaultAnalystRegistry: definitions require an engine — a definition cannot run without one");
@@ -2366,4 +2351,4 @@ function buildDefaultAnalystRegistry(options = {}) {
 //#endregion
 export { completedAnalystReviewQuality as _, KNOWLEDGE_POISONING_KIND_SPEC as a, validateAnalystReviewDecisions as b, FAILURE_MODE_KIND_SPEC as c, emitControlIntegrityFindings as d, behavioralAnalyst as f, assertUniqueFindingIds as g, analystRunDigest as h, DEFAULT_TRACE_ANALYST_KINDS as i, CONTROL_INTEGRITY_ANALYST as l, analystFindingDigest as m, AnalystRegistry as n, KNOWLEDGE_GAP_KIND_SPEC as o, deriveEfficiencyFindings as p, ExactAnalystRunExecutionError as r, IMPROVEMENT_KIND_SPEC as s, buildDefaultAnalystRegistry as t, ControlIntegrityAnalyst as u, readAnalystReview as v, snapshotAnalystRun as y };
 
-//# sourceMappingURL=default-registry-BhYGMVbV.js.map
+//# sourceMappingURL=default-registry-Cn1LQ2Ve.js.map