@tangle-network/agent-eval 0.137.0 → 0.139.0

package/dist/default-registry-BgJJItGr.js

@@ -0,0 +1,2364 @@
+import { n as LlmClient } from "./llm-client-bkztEfIx.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 { $ as spanEpochMillis, H as snapshotExactExecutionPlan, R as findingSubjectGrammarPromptFor, U as deepFreezeCanonicalJson, V as snapshotExactExecutionComponentIdentity, t as createTraceAnalyst } from "./kind-factory-CFxA0JQX.js";
+import { i as validateUsageSettlementTimeout, o as makeFinding, t as assertValidAnalystUsageReceipt } from "./usage-receipt-CgxMEBZq.js";
+import { i as hashCanonical, r as canonicalString } from "./canonical-D011XM8r.js";
+import { t as analyzeSupervisorRunIntegrity } from "./integrity-CCXTftiL.js";
+import { o as combineAbortSignals } from "./proposal-findings-2GIUo1et.js";
+import { z } from "zod";
+import { randomUUID } from "node:crypto";
+//#region src/analyst/chat-client.ts
+/**
+* Provider-neutral chat contract for every model call made by agent-eval.
+*
+* Callers choose the transport at the package boundary with `createChatClient`.
+* Evaluation code receives canonical requests and results without importing a
+* provider SDK.
+*/
+/**
+* Build a ChatClient bound to a specific transport. The returned client
+* is safe to share across analysts in a single registry run.
+*/
+function createChatClient(opts) {
+	switch (opts.transport) {
+		case "router": return wrapLlmClient(opts.transport, opts.defaultModel, new LlmClient({
+			baseUrl: opts.baseUrl ?? "https://router.tangle.tools/v1",
+			apiKey: opts.apiKey,
+			maximumAttempts: opts.maximumAttempts
+		}));
+		case "cli-bridge": return wrapLlmClient(opts.transport, opts.defaultModel, new LlmClient({
+			baseUrl: opts.baseUrl ?? "http://127.0.0.1:3344/v1",
+			apiKey: opts.bearer ?? "",
+			maximumAttempts: opts.maximumAttempts
+		}));
+		case "direct-provider": return wrapLlmClient(opts.transport, opts.defaultModel, new LlmClient({
+			baseUrl: opts.baseUrl,
+			apiKey: opts.apiKey,
+			maximumAttempts: opts.maximumAttempts
+		}));
+		case "sandbox-sdk": return {
+			transport: "sandbox-sdk",
+			defaultModel: opts.defaultModel,
+			maximumAttempts: opts.maximumAttempts,
+			chat: async (req, callOpts) => opts.chat(resolveModel(req, opts.defaultModel), callOpts)
+		};
+		case "custom": return {
+			transport: "custom",
+			defaultModel: opts.defaultModel,
+			maximumAttempts: opts.maximumAttempts,
+			chat: async (req, callOpts) => opts.chat(resolveModel(req, opts.defaultModel), callOpts)
+		};
+		case "mock": return {
+			transport: "mock",
+			defaultModel: opts.defaultModel,
+			maximumAttempts: 1,
+			chat: async (req, callOpts) => opts.handler(resolveModel(req, opts.defaultModel), callOpts)
+		};
+	}
+}
+function wrapLlmClient(transport, defaultModel, inner) {
+	return {
+		transport,
+		defaultModel,
+		maximumAttempts: inner.maximumAttempts,
+		chat: (req, callOpts) => {
+			const request = {
+				model: resolveModel(req, defaultModel).model,
+				messages: req.messages,
+				jsonMode: req.jsonMode,
+				jsonSchema: req.jsonSchema,
+				temperature: req.temperature,
+				maxTokens: req.maxTokens,
+				thinking: req.thinking,
+				timeoutMs: req.timeoutMs
+			};
+			return inner.call(request, {
+				signal: callOpts?.signal,
+				idempotencyKey: callOpts?.idempotencyKey
+			});
+		}
+	};
+}
+function resolveModel(req, defaultModel) {
+	if (req.model) return req;
+	if (!defaultModel) throw new Error("ChatClient.chat: no model on request and no defaultModel on the client. Either pass req.model or bind defaultModel at createChatClient().");
+	return {
+		...req,
+		model: defaultModel
+	};
+}
+//#endregion
+//#region src/trace-analyst/behavioral-metrics.ts
+/**
+* Deterministic behavioral metrics over OTLP spans — pure arithmetic, no LLM.
+*
+* It computes token growth, output decay, tool monoculture, and missing
+* self-verification once in TypeScript with no model judgment.
+*
+* General, not trace-specific: the detectors key off token trajectories and
+* tool usage present in any agentic OTLP trace, not any one benchmark.
+*/
+/** ≥ this input-token growth ratio across a run, with no compression, fires. */
+const INPUT_GROWTH_FACTOR = 3;
+/** Tool-usage signals need at least this many calls to be meaningful. */
+const MIN_TOOL_CALLS = 3;
+/** Tool names that read or check state count as self-verification, not mutation.
+*  Covers the inspect verbs plus the read/search tools real harnesses use to
+*  verify (Claude Code Read/Grep/Glob, codex read_file/ls/cat, git status/diff,
+*  test/lint). A pure shell tool (Bash/exec_command) is intentionally NOT matched
+*  — its name can't tell a `pytest` from an `rm`. */
+const VERIFY_RE = /verif|eval|inspect|check|assert|validat|review|confirm|read|grep|glob|search|view|\blist\b|\bls\b|\bcat\b|\bfind\b|diff|status|\btest|lint|typecheck/i;
+function num(v) {
+	return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+function numAttr(attrs, keys) {
+	for (const key of keys) {
+		const value = num(attrs[key]);
+		if (value !== null) return value;
+	}
+	return null;
+}
+function inputTokensOf(s) {
+	const exactContext = num(s.attributes[LLM_CONTEXT_TOKENS]);
+	if (exactContext !== null) return exactContext;
+	return numAttr(s.attributes, LLM_INPUT_TOKEN_ATTR_KEYS) ?? num(s.attributes["llm.usage.input_tokens"]);
+}
+function outputTokensOf(s) {
+	return numAttr(s.attributes, LLM_OUTPUT_TOKEN_ATTR_KEYS) ?? num(s.attributes["llm.usage.output_tokens"]);
+}
+function stepOf(s) {
+	return num(s.attributes.step);
+}
+function toolNameOf(s) {
+	if (s.tool_name) return s.tool_name;
+	for (const key of TOOL_NAME_ATTR_KEYS) {
+		const t = s.attributes[key];
+		if (typeof t === "string" && t.length > 0) return t;
+	}
+	return null;
+}
+/**
+* Reduce a span list to behavioral metrics + fired suboptimality signals.
+* Pure + deterministic: same spans → same output, on any machine, no model.
+*/
+function computeTraceMetrics(spans) {
+	const traceIds = new Set(spans.map((span) => span.trace_id));
+	if (traceIds.size > 1) throw new Error(`computeTraceMetrics: expected spans from one trace, received ${traceIds.size} traces`);
+	const traceId = traceIds.values().next().value ?? null;
+	const samples = spans.map((span) => ({
+		span,
+		input: inputTokensOf(span),
+		output: outputTokensOf(span),
+		step: stepOf(span)
+	}));
+	const llmSamples = samples.filter((sample) => sample.span.kind === "LLM");
+	const tokenSamples = llmSamples.length > 0 ? llmSamples : samples.filter((sample) => sample.input !== null || sample.output !== null);
+	const tokenSequences = buildTokenSequences(tokenSamples, spans);
+	const primarySequence = tokenSequences[0];
+	const inputTokenTrajectory = primarySequence?.inputTokenTrajectory.filter((value) => value !== null) ?? [];
+	const outputTokenTrajectory = primarySequence?.outputTokenTrajectory.filter((value) => value !== null) ?? [];
+	const toolHistogram = {};
+	let hasSelfVerification = false;
+	for (const s of spans) {
+		const tool = toolNameOf(s);
+		if (tool) {
+			toolHistogram[tool] = (toolHistogram[tool] ?? 0) + 1;
+			if (VERIFY_RE.test(tool)) hasSelfVerification = true;
+		}
+	}
+	const totalToolCalls = Object.values(toolHistogram).reduce((a, b) => a + b, 0);
+	const distinctTools = Object.keys(toolHistogram).length;
+	const toolDiversityRatio = totalToolCalls === 0 ? 1 : distinctTools / totalToolCalls;
+	const signals = [];
+	const seenTokenSignals = /* @__PURE__ */ new Set();
+	for (const sequence of tokenSequences) for (const signal of tokenSignals(sequence)) {
+		if (seenTokenSignals.has(signal.code)) continue;
+		seenTokenSignals.add(signal.code);
+		signals.push(signal);
+	}
+	if (totalToolCalls >= MIN_TOOL_CALLS && distinctTools === 1) {
+		const only = Object.keys(toolHistogram)[0];
+		signals.push({
+			code: "single-tool-dependency",
+			severity: "medium",
+			detail: `All ${totalToolCalls} observed tool calls are \`${only}\`; no alternate tool call was observed.`,
+			evidence: {
+				tool: only,
+				calls: totalToolCalls,
+				distinct_tools: 1
+			}
+		});
+	}
+	if (totalToolCalls >= MIN_TOOL_CALLS && !hasSelfVerification) signals.push({
+		code: "no-self-verification",
+		severity: "medium",
+		detail: `${totalToolCalls} tool calls were observed without a verification-named tool call.`,
+		evidence: {
+			tool_calls: totalToolCalls,
+			verification_calls: 0
+		}
+	});
+	return {
+		traceId,
+		llmCallCount: tokenSamples.length,
+		tokenSequences,
+		inputTokenTrajectory,
+		outputTokenTrajectory,
+		toolHistogram,
+		totalToolCalls,
+		distinctTools,
+		toolDiversityRatio,
+		hasSelfVerification,
+		signals
+	};
+}
+function buildTokenSequences(samples, spans) {
+	const executionScopeFor = createTokenExecutionScopeResolver(new Map(spans.map((span) => [span.span_id, span])));
+	const scopedSamples = samples.map((sample) => ({
+		sample,
+		...executionScopeFor(sample.span)
+	}));
+	const trackByLane = executionTrackByLane(scopedSamples);
+	const byTrack = /* @__PURE__ */ new Map();
+	for (const scoped of scopedSamples) {
+		const trackId = trackByLane.get(scoped.key);
+		const track = byTrack.get(trackId) ?? {
+			scopeId: scoped.scopeId,
+			samples: []
+		};
+		track.samples.push(scoped.sample);
+		byTrack.set(trackId, track);
+	}
+	const sequences = [];
+	for (const { scopeId, samples: tracked } of byTrack.values()) {
+		const runs = serialTokenRuns([...tracked].sort(compareTokenSamples));
+		runs.forEach((run, index) => {
+			sequences.push({
+				scopeId: runs.length === 1 ? scopeId : `${scopeId}#${index + 1}`,
+				spanIds: run.map((sample) => sample.span.span_id),
+				inputTokenTrajectory: run.map((sample) => sample.input),
+				outputTokenTrajectory: run.map((sample) => sample.output)
+			});
+		});
+	}
+	return sequences.sort((a, b) => b.spanIds.length - a.spanIds.length || a.scopeId.localeCompare(b.scopeId) || a.spanIds[0].localeCompare(b.spanIds[0]));
+}
+function createTokenExecutionScopeResolver(spansById) {
+	const cache = /* @__PURE__ */ new Map();
+	return (span) => {
+		const ancestry = resolveAncestorScope(span.parent_span_id, spansById, cache);
+		const rootId = ancestry.rootId;
+		const scopeId = ancestry.agentId ? `span:${ancestry.agentId}` : ancestry.missingParentId ? `parent:${ancestry.missingParentId}` : rootId ? `root:${rootId}` : span.agent_name ? `agent:${span.agent_name}` : `trace:${span.trace_id}`;
+		const scopeSpanId = ancestry.agentId ?? ancestry.missingParentId ?? rootId;
+		const laneSpan = ancestry.laneSpanId ? spansById.get(ancestry.laneSpanId) : void 0;
+		const direct = scopeSpanId === null || ancestry.laneSpanId === scopeSpanId;
+		const timedSpan = direct ? span : laneSpan;
+		return {
+			key: JSON.stringify([scopeId, direct ? span.span_id : ancestry.laneSpanId]),
+			scopeKey: scopeId,
+			scopeId,
+			start: timedSpan ? spanEpochMillis(timedSpan.start_time) : null,
+			end: timedSpan ? spanEpochMillis(timedSpan.end_time) : null
+		};
+	};
+}
+function resolveAncestorScope(startId, spansById, cache) {
+	const empty = {
+		agentId: null,
+		rootId: null,
+		missingParentId: null,
+		laneSpanId: null
+	};
+	if (!startId) return empty;
+	const path = [];
+	const pathIndex = /* @__PURE__ */ new Map();
+	let currentId = startId;
+	let resolved = empty;
+	while (currentId) {
+		const cached = cache.get(currentId);
+		if (cached) {
+			resolved = cached;
+			break;
+		}
+		const cycleStart = pathIndex.get(currentId);
+		if (cycleStart !== void 0) {
+			resolved = {
+				agentId: null,
+				rootId: [...path.slice(cycleStart)].sort()[0],
+				missingParentId: null,
+				laneSpanId: [...path.slice(cycleStart)].sort()[0]
+			};
+			break;
+		}
+		const current = spansById.get(currentId);
+		if (!current) {
+			resolved = {
+				agentId: null,
+				rootId: null,
+				missingParentId: currentId,
+				laneSpanId: currentId
+			};
+			break;
+		}
+		if (current.kind === "AGENT") {
+			resolved = {
+				agentId: current.span_id,
+				rootId: null,
+				missingParentId: null,
+				laneSpanId: current.span_id
+			};
+			break;
+		}
+		pathIndex.set(currentId, path.length);
+		path.push(currentId);
+		currentId = current.parent_span_id;
+	}
+	for (let index = path.length - 1; index >= 0; index -= 1) {
+		if (resolved.agentId === null && resolved.rootId === null) resolved = {
+			...resolved,
+			rootId: path[index],
+			laneSpanId: path[index]
+		};
+		else if (resolved.laneSpanId === (resolved.agentId ?? resolved.missingParentId ?? resolved.rootId)) resolved = {
+			...resolved,
+			laneSpanId: path[index]
+		};
+		cache.set(path[index], resolved);
+	}
+	return resolved;
+}
+function compareTokenSamples(a, b) {
+	const aStart = spanEpochMillis(a.span.start_time);
+	const bStart = spanEpochMillis(b.span.start_time);
+	if (aStart === null && bStart !== null) return 1;
+	if (aStart !== null && bStart === null) return -1;
+	if (aStart !== null && bStart !== null && aStart !== bStart) return aStart - bStart;
+	if (a.step !== null && b.step !== null && a.step !== b.step) return a.step - b.step;
+	return a.span.span_id.localeCompare(b.span.span_id);
+}
+function serialTokenRuns(ordered) {
+	const runs = [];
+	let serial = [];
+	let overlap = [];
+	let overlapEnd = Number.NEGATIVE_INFINITY;
+	const flushSerial = () => {
+		if (serial.length > 0) runs.push(serial);
+		serial = [];
+	};
+	const flushOverlap = () => {
+		if (overlap.length === 1) serial.push(overlap[0]);
+		else if (overlap.length > 1) {
+			flushSerial();
+			for (const sample of overlap) runs.push([sample]);
+		}
+		overlap = [];
+		overlapEnd = Number.NEGATIVE_INFINITY;
+	};
+	for (const sample of ordered) {
+		const start = spanEpochMillis(sample.span.start_time);
+		const end = spanEpochMillis(sample.span.end_time);
+		if (start === null || end === null || sample.span.duration_ms <= 0 || end < start) {
+			flushOverlap();
+			flushSerial();
+			runs.push([sample]);
+			continue;
+		}
+		if (overlap.length > 0 && start >= overlapEnd) flushOverlap();
+		overlap.push(sample);
+		overlapEnd = Math.max(overlapEnd, end);
+	}
+	flushOverlap();
+	flushSerial();
+	return runs;
+}
+function tokenSignals(sequence) {
+	const signals = [];
+	const inputs = sequence.inputTokenTrajectory;
+	const outputs = sequence.outputTokenTrajectory;
+	if (inputs.length >= 3 && inputs.every((value) => value !== null)) {
+		const first = inputs[0];
+		const last = inputs[inputs.length - 1];
+		const isMonotonic = everyAdjacent(inputs, (previous, current) => current >= previous);
+		const growthFromZero = first === 0 && last > 0;
+		const growth = growthFromZero ? Infinity : first > 0 ? last / first : 0;
+		if (isMonotonic && last > first && growth >= INPUT_GROWTH_FACTOR) {
+			const growthLabel = growthFromZero ? "0→nonzero (unbounded)" : `${growth.toFixed(1)}x`;
+			signals.push({
+				code: "monotonic-input-growth",
+				severity: "high",
+				detail: `LLM input tokens grew ${growthLabel} (${first}→${last}) across ${inputs.length} serial calls without an intervening decrease.`,
+				evidence: {
+					first,
+					last,
+					growth_x: growthFromZero ? "unbounded" : Number(growth.toFixed(2)),
+					calls: inputs.length,
+					scope: sequence.scopeId,
+					first_span_id: sequence.spanIds[0],
+					last_span_id: sequence.spanIds[sequence.spanIds.length - 1]
+				}
+			});
+		}
+	}
+	if (inputs.length >= 3 && inputs.length === outputs.length && inputs.every((value) => value !== null) && outputs.every((value) => value !== null)) {
+		const first = outputs[0];
+		const last = outputs[outputs.length - 1];
+		const inputIsMonotonic = everyAdjacent(inputs, (previous, current) => current >= previous);
+		const outputIsMonotonic = everyAdjacent(outputs, (previous, current) => current <= previous);
+		const inputGrew = inputs[inputs.length - 1] > inputs[0];
+		if (inputIsMonotonic && inputGrew && outputIsMonotonic && last < first) signals.push({
+			code: "output-length-decay",
+			severity: "medium",
+			detail: `LLM output tokens shrank ${first}→${last} over ${outputs.length} serial calls while input tokens increased monotonically.`,
+			evidence: {
+				first,
+				last,
+				calls: outputs.length,
+				scope: sequence.scopeId,
+				first_span_id: sequence.spanIds[0],
+				last_span_id: sequence.spanIds[sequence.spanIds.length - 1]
+			}
+		});
+	}
+	return signals;
+}
+function everyAdjacent(values, predicate) {
+	return values.slice(1).every((current, index) => predicate(values[index], current));
+}
+//#endregion
+//#region src/analyst/behavioral-analyst.ts
+/**
+* Deterministic behavioral analysis over arithmetic in trace spans.
+* This pass is cheap and repeatable; semantic analysis remains the job of
+* model-backed analysts. Relative quality requires a labeled comparison.
+*/
+const RECOMMENDED_ACTION = {
+	"monotonic-input-growth": "Inspect context assembly; if prior history is repeatedly included, summarize completed work before the next model call.",
+	"output-length-decay": "Check late-step completeness; if shorter responses omit required work, add explicit completion criteria to the agent instructions.",
+	"single-tool-dependency": "Test whether an inspect or verification tool improves outcomes after the repeated call fails or returns no progress.",
+	"no-self-verification": "After state-changing actions, require an observable check before the agent proceeds."
+};
+const ANALYST_ID$1 = "efficiency-behavioral";
+const DEFAULT_MAX_TRACES = 1e3;
+const DEFAULT_MAX_EVIDENCE_REFS = 20;
+const TRACE_PAGE_SIZE = 200;
+const AGGREGATE_CLAIM = {
+	"monotonic-input-growth": (observed, analyzed) => `${observed}/${analyzed} analyzed traces showed input tokens grow from zero to nonzero or to at least 3x their initial value across at least 3 serial model calls without a decrease.`,
+	"output-length-decay": (observed, analyzed) => `${observed}/${analyzed} analyzed traces showed output tokens decrease while input tokens increased monotonically across at least 3 serial model calls.`,
+	"single-tool-dependency": (observed, analyzed) => `${observed}/${analyzed} analyzed traces used only one named tool across at least 3 tool calls.`,
+	"no-self-verification": (observed, analyzed) => `${observed}/${analyzed} analyzed traces had at least 3 tool calls without a verification-named tool call.`
+};
+async function listTraceIds(store, maxTraces, signal) {
+	const traceIds = /* @__PURE__ */ new Set();
+	let offset = 0;
+	let expectedTotal;
+	while (true) {
+		signal?.throwIfAborted();
+		const page = await store.queryTraces({
+			limit: TRACE_PAGE_SIZE,
+			offset
+		});
+		if (expectedTotal === void 0) expectedTotal = page.total;
+		if (page.total !== expectedTotal) throw new Error(`behavioralAnalyst: trace count changed during pagination (${expectedTotal} to ${page.total})`);
+		if (page.total > maxTraces) throw new RangeError(`behavioralAnalyst: ${page.total} traces exceed maxTraces=${maxTraces}; filter the store or raise the explicit limit`);
+		for (const trace of page.traces) traceIds.add(trace.trace_id);
+		if (traceIds.size > maxTraces) throw new RangeError(`behavioralAnalyst: more than maxTraces=${maxTraces} unique traces were returned`);
+		if (!page.has_more) break;
+		if (page.traces.length === 0) throw new Error("behavioralAnalyst: trace store returned an empty page with has_more=true");
+		offset += page.traces.length;
+	}
+	if (traceIds.size !== expectedTotal) throw new Error(`behavioralAnalyst: pagination returned ${traceIds.size}/${expectedTotal ?? 0} unique traces`);
+	return [...traceIds].sort();
+}
+/**
+* Map computed signals → structured AnalystFindings. Pure: no LLM, no clock
+* dependence beyond `produced_at` (overridable for deterministic tests).
+*/
+function deriveEfficiencyFindings(metrics, opts = {}) {
+	const analystId = opts.analystId ?? ANALYST_ID$1;
+	const traceId = metrics.traceId;
+	return metrics.signals.map((sig) => makeFinding({
+		analyst_id: analystId,
+		area: "efficiency",
+		subject: sig.code,
+		claim: sig.detail,
+		severity: sig.severity,
+		confidence: 1,
+		evidence_refs: [{
+			kind: "metric",
+			uri: traceId ? `metric://trace/${encodeURIComponent(traceId)}/efficiency/${sig.code}` : `metric://efficiency/${sig.code}`,
+			excerpt: JSON.stringify(sig.evidence)
+		}],
+		recommended_action: RECOMMENDED_ACTION[sig.code],
+		metadata: {
+			deterministic: true,
+			evidence: sig.evidence,
+			...traceId ? { trace_id: traceId } : {}
+		},
+		id_basis: sig.code,
+		...opts.producedAt ? { produced_at: opts.producedAt } : {}
+	}));
+}
+/** The deterministic behavioral/efficiency analyst (no LLM, any-model). */
+function behavioralAnalyst(options = {}) {
+	const maxTraces = positiveInteger(options.maxTraces ?? DEFAULT_MAX_TRACES, "maxTraces");
+	const maxEvidenceRefsPerFinding = positiveInteger(options.maxEvidenceRefsPerFinding ?? DEFAULT_MAX_EVIDENCE_REFS, "maxEvidenceRefsPerFinding");
+	return {
+		id: ANALYST_ID$1,
+		description: "Deterministic behavioral/efficiency findings over OTLP spans — token-growth, output-decay, tool-monoculture, missing self-verification. Zero LLM; model-agnostic by construction.",
+		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();
+			for (const traceId of analyzedTraceIds) {
+				context.signal?.throwIfAborted();
+				const viewed = await store.viewTrace({ trace_id: traceId });
+				if (viewed.trace_id !== traceId) throw new Error(`behavioralAnalyst: requested trace '${traceId}', received '${viewed.trace_id}'`);
+				if (!viewed.spans) throw new Error(`behavioralAnalyst: trace '${traceId}' is oversized; complete spans are required`);
+				const metrics = computeTraceMetrics(viewed.spans);
+				if (metrics.traceId !== null && metrics.traceId !== traceId) throw new Error(`behavioralAnalyst: requested trace '${traceId}', received '${metrics.traceId}'`);
+				for (const finding of deriveEfficiencyFindings(metrics)) {
+					const current = findingsById.get(finding.finding_id);
+					if (!current) {
+						findingsById.set(finding.finding_id, {
+							finding,
+							observedTraceCount: 1,
+							evidenceTraceIds: [traceId],
+							evidence: [...finding.evidence_refs]
+						});
+						continue;
+					}
+					current.observedTraceCount += 1;
+					if (current.evidence.length < maxEvidenceRefsPerFinding) {
+						current.evidenceTraceIds.push(traceId);
+						current.evidence.push(...finding.evidence_refs);
+					}
+				}
+			}
+			return [...findingsById.values()].map(({ finding, observedTraceCount, evidenceTraceIds, evidence }) => ({
+				...finding,
+				claim: AGGREGATE_CLAIM[finding.subject](observedTraceCount, analyzedTraceIds.length),
+				rationale: `${observedTraceCount}/${analyzedTraceIds.length} analyzed traces exhibited this pattern.`,
+				evidence_refs: evidence,
+				metadata: {
+					deterministic: true,
+					evidence_trace_ids: evidenceTraceIds,
+					omitted_evidence_trace_count: observedTraceCount - evidenceTraceIds.length,
+					observed_trace_count: observedTraceCount,
+					analyzed_trace_count: analyzedTraceIds.length
+				}
+			}));
+		}
+	};
+}
+function positiveInteger(value, name) {
+	if (!Number.isSafeInteger(value) || value < 1) throw new RangeError(`behavioralAnalyst: ${name} must be a positive safe integer`);
+	return value;
+}
+//#endregion
+//#region src/analyst/kinds/control-integrity.ts
+const ANALYST_ID = "control-integrity";
+function shown(value) {
+	if (value === void 0) return "<absent>";
+	const encoded = JSON.stringify(value);
+	return encoded === void 0 ? String(value) : encoded;
+}
+function evidenceRef(namespace, value) {
+	return {
+		kind: "metric",
+		uri: `supervisor-run://${encodeURIComponent(namespace)}/${value.path}`,
+		excerpt: shown(value.value)
+	};
+}
+/** Translate typed supervisor-run integrity issues into the shared analyst envelope. */
+function emitControlIntegrityFindings(input, producedAt) {
+	const report = analyzeSupervisorRunIntegrity(input, { capturedAt: producedAt });
+	return report.issues.map((issue) => makeFinding({
+		analyst_id: ANALYST_ID,
+		produced_at: producedAt,
+		area: issue.area,
+		severity: issue.severity,
+		subject: `${report.runRef}/${issue.subject}`,
+		claim: issue.claim,
+		rationale: issue.detail,
+		evidence_refs: issue.evidence.map((value) => evidenceRef(report.runRef, value)),
+		recommended_action: issue.recommendedAction,
+		validation_plan: "Re-run this deterministic analyst on the retained SupervisorRunSources or SupervisorRunTree after correcting the producer.",
+		confidence: 1,
+		metadata: {
+			integrity_code: issue.code,
+			integrity_input: report.input,
+			integrity_run_ref: report.runRef,
+			integrity_subject: issue.subject,
+			...issue.metadata
+		}
+	}));
+}
+/** Deterministic Analyst adapter for `SupervisorRunSources | SupervisorRunTree`. */
+var ControlIntegrityAnalyst = class {
+	id = ANALYST_ID;
+	description = "Deterministic supervisor-run integrity checks with explicit unavailable evidence.";
+	inputKind = "custom";
+	cost = {
+		kind: "deterministic",
+		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" });
+		return findings;
+	}
+};
+const CONTROL_INTEGRITY_ANALYST = new ControlIntegrityAnalyst();
+const FAILURE_MODE_KIND_SPEC = {
+	id: "failure-mode",
+	description: "Clusters trace-dataset failures into distinct failure modes with cited evidence and a short recommended action.",
+	area: "failure-mode",
+	version: "1.2.0",
+	instructions: `You are a failure-mode classifier for an OTLP trace dataset. Your job is to identify the **distinct ways agents failed** in this dataset, not to grade individual runs.
+
+${findingSubjectGrammarPromptFor("failure-mode")}
+
+DISCOVERY → CLUSTER → CITE protocol:
+
+1. Call \`getDatasetOverview({})\` first. Use \`has_errors\`, \`models\`, \`agent_names\`, \`tools\`, and \`sample_trace_ids\` to size the failure surface.
+2. Use \`queryTraces(filters={"has_errors": true}, limit=...)\` to pull error-bearing traces. Combine with \`countTraces\` to see what fraction of the dataset failed.
+3. For each candidate failure cluster, use \`searchTrace\` with regex like \`STATUS_CODE_ERROR\`, \`MaxTurnsExceeded\`, \`assertion\`, \`unauthorized\`, \`timeout\`, \`429\`, \`5\\d\\d\`, the agent's specific error strings, or the names of its tools. Pull one or two representative traces per cluster, **not all** of them.
+4. **Cluster, do not enumerate.** Two failures with the same root cause should be ONE finding citing both traces, not two findings. The point of this analyst is to compress N runs into K modes.
+5. For each defensible cluster, emit ONE finding. Use a lowercase cluster label matching the subject grammar ("tool-call-loop", "auth-revoked-mid-run", ...). Rate it critical when it blocks the run, high when the run finishes degraded, and medium when it slows convergence. Cite representative spans and include exact error, payload, or contradictory-output quotes. Use confidence 0.85+ when multiple traces show the same shape, 0.6-0.8 for a single-trace inference, and <0.5 for speculation. Keep the imperative fix idea short; the improvement analyst expands it.
+
+If the dataset has no failures, return an empty findings array — do NOT pad with low-confidence speculation.
+
+**Use subqueries over loaded evidence.** After the first scan, load representative span excerpts for each candidate cluster. Then send one bounded \`llm_query\` per cluster in one batch, including the exact excerpts and asking it to classify the root cause. Subqueries cannot call trace tools. Merge or split clusters yourself from their classifications and the cited source evidence.`,
+	toolGroup: "all",
+	limits: {
+		maxLlmCalls: 8,
+		maxIterations: 24,
+		maxToolCalls: 64
+	}
+};
+const IMPROVEMENT_KIND_SPEC = {
+	id: "improvement",
+	description: "Converts upstream failure / gap / poisoning findings into concrete locus-named edits (prompt, tool-doc, RAG, scaffolding) with leverage grades.",
+	area: "improvement",
+	version: "1.2.0",
+	instructions: `You are a self-improvement analyst. Your job is to propose **concrete, locus-named edits** the agent's runtime should adopt to fix the failure modes, knowledge gaps, and poisonings present in this dataset.
+
+Upstream analysts have already classified the problems. Your job is to convert each problem into a *change to make* and grade its expected leverage. Each finding is one proposed edit.
+
+${findingSubjectGrammarPromptFor("improvement")}
+
+DISCOVERY → CANDIDATE-FIXES → COMPETE → CITE protocol:
+
+1. \`getDatasetOverview({})\` first. Note the agents, tools, and any system-prompt fingerprints (look for the prompt text echoed in early spans).
+2. For each high-severity failure pattern, generate 2-3 candidate fixes. Real candidate axes:
+   - **System-prompt edit** — add an instruction, remove a misleading one, restructure precedence
+   - **Tool description edit** — rewrite a tool's description so the agent picks it correctly / passes valid args
+   - **New tool** — add a tool the agent kept emulating in code
+   - **RAG ingestion** — add a document or correct a stale one
+   - **Memory invalidation** — clear cached prior-run decisions that no longer apply
+   - **Scaffolding** — add a precondition check, a retry policy, a turn budget, a verification step
+   - **Output schema** — narrow the agent's output to forbid the failure shape
+   - **Skill / MCP / hook / subagent** — change the reusable profile component responsible for the behavior
+   - **Workflow / rollout policy** — change orchestration, budget, sampling, or stopping behavior
+   - **Code** — change an implementation path when profile edits cannot repair the behavior
+3. **Compare candidate fixes with bounded subqueries.** Load the representative failure excerpts, then send one \`llm_query\` per candidate-fix axis the same evidence. Ask for likely effect, side effects, and implementation scope. Subqueries cannot call trace tools; trace ids alone are insufficient context.
+4. After the comparisons return, **pick the winning candidate per cluster** based on expected effect and risk, then emit ONE finding. Keep the alternatives and rejection reasons in the rationale so the recommendation is auditable.
+5. **Cross-reference upstream findings.** Cite prior failure-mode or knowledge-gap findings as \`finding://<prior-finding-id>\`. This builds the dependency graph that lets the dashboard show "fix #X resolves failure modes A, B, C."
+
+For each winning recommendation, emit ONE finding. Use one exact locus from the subject grammar and state the edit in one sentence. Match leverage to the source failure's severity; use medium for quality-of-life changes and info for cleanup with no behavioral effect. Cite the targeted \`finding://<id>\` when available and the most representative span when useful. Quote the problem being fixed. Use confidence 0.85+ for a mechanical fix to a well-evidenced failure, 0.6-0.8 when judgment is required, and <0.5 for speculation. Explain in at most two sentences why this candidate beat its alternatives. The recommended action must be the literal diff, quoted replacement, tool description, or setting change.
+
+If no upstream failure findings exist in this run, derive your own from the trace dataset using the failure-mode protocol inline (\`searchTrace\` for STATUS_CODE_ERROR / MaxTurnsExceeded / etc.). Prefer upstream findings when present because the analysts are designed to chain.
+
+Do NOT propose a fix you cannot defend with evidence. "Tighten the prompt" is not a finding; "Add 'When the user asks for X, always Y' to the system prompt section "request-classification"" is.`,
+	toolGroup: "all",
+	limits: {
+		maxLlmCalls: 8,
+		maxIterations: 30,
+		maxToolCalls: 80,
+		maxOutputChars: 12e3
+	}
+};
+const KNOWLEDGE_GAP_KIND_SPEC = {
+	id: "knowledge-gap",
+	description: "Identifies missing or stale pieces of knowledge — primarily against the agent-knowledge wiki — and attributes each to the runtime layer (wiki page, claim, raw source, websearch, tool-doc, system-prompt, memory) that should have held it.",
+	area: "knowledge-gap",
+	version: "1.2.0",
+	instructions: `You are a knowledge-gap analyst for an OTLP trace dataset. Your job is to identify the **specific pieces of information the agent lacked, or that were stale**, that caused poor decisions.
+
+The agent under analysis maintains a curated knowledge base via \`@tangle-network/agent-knowledge\` — a wiki of \`KnowledgePage\`s with raw source anchors, claims, and relations. The primary expected store of agent-knowable facts IS that wiki. A "knowledge gap" is anything the agent had to discover or guess at run-time that the wiki should have held — or an outdated/contradictory fact the agent picked up from a non-wiki source.
+
+${findingSubjectGrammarPromptFor("knowledge-gap")}
+
+DISCOVERY → ATTRIBUTE-TO-LAYER → CITE protocol:
+
+1. \`getDatasetOverview({})\` first. Note which agents, tools, and models appear.
+2. Pull traces where the agent shows gap signals. The strongest signals are:
+   - Self-correction turns ("I assumed X but…", "let me re-check", "actually,")
+   - Clarifying-question turns where the agent asked the user something the runtime should have surfaced
+   - Repeated retrieval / lookup calls for the same artifact with slightly varied queries
+   - Tool errors that name a missing argument or unknown resource
+   - Web-search calls returning pages dated before a known cutoff for content that changes (versioned APIs, schemas, policies)
+   - Agent quoting a tool's docs / system prompt incorrectly because the actual text was insufficient
+   - Fabricated identifiers that don't appear in dataset \`sample_trace_ids\`
+   Use \`searchTrace\` with patterns like \`I (don.?t|do not) know\`, \`assumed\`, \`unclear\`, \`could you (clarify|tell me|provide)\`, \`not found\`, \`undefined\`, \`unknown\`, \`null\`, dates older than the analysis window, or the agent's specific clarification phrases.
+3. For each gap, identify the **layer of the runtime that should have prevented it** and use its exact locus from the subject grammar above.
+4. For each defensible gap, emit ONE finding. Use an exact locus from the subject grammar and name the missing or stale knowledge (for example, "wiki has no page on invoice line-item shape; agent re-derived it from raw spans"). Rate it high when it caused failure or a clarifying question, medium for unnecessary turns, and low for minor inefficiency. Cite the span where the question, correction, retrieval miss, or stale result surfaced and quote it exactly. Use confidence 0.85+ when the agent articulated the gap and 0.6-0.8 when inferred. Recommend a concrete wiki edit for an agent-knowledge locus or a prompt/tool-description edit otherwise.
+
+**Compare layers over loaded evidence.** After the first scan, load the exact excerpts behind candidates across \`agent-knowledge:*\`, \`websearch:outdated\`, \`tool-doc:*\`, \`system-prompt:*\`, and \`memory:*\`. Use one bounded \`llm_query\` per layer to classify those excerpts. Subqueries cannot call trace tools. Merge their classifications into the final finding set only when the source excerpts support them.
+
+Do NOT report a gap that the agent later recovered from cleanly within the same turn. That is resilience, not a gap. Cite the non-recovery version when both exist.`,
+	toolGroup: "discoveryAndSearch",
+	limits: {
+		maxLlmCalls: 5,
+		maxIterations: 18,
+		maxToolCalls: 48
+	}
+};
+const KNOWLEDGE_POISONING_KIND_SPEC = {
+	id: "knowledge-poisoning",
+	description: "Identifies confident-but-wrong actions caused by stale memory, contradicting RAG, deprecated tool docs, or outdated system-prompt instructions.",
+	area: "knowledge-poisoning",
+	version: "1.2.0",
+	instructions: `You are a knowledge-poisoning analyst for an OTLP trace dataset. Your job is to identify cases where the agent **confidently used wrong information** — not where it lacked information (that's the knowledge-gap analyst).
+
+${findingSubjectGrammarPromptFor("knowledge-poisoning")}
+
+DISCOVERY → DUAL-VERIFY → CITE protocol:
+
+1. \`getDatasetOverview({})\` first. Identify the agents, models, and tools.
+2. Pull traces where the agent's confident action was later contradicted. Strongest signals:
+   - Agent stated a fact in one span; a later span surfaced contradictory evidence; the agent then proceeded anyway or fabricated reconciliation.
+   - Tool call with stale arguments (an id that no longer exists, an API shape that changed).
+   - Agent cited an \`agent-knowledge\` wiki page or claim whose content contradicts the trace's own evidence — the wiki itself drifted.
+   - Web-search result the agent cited that returned an outdated page; agent treated it as canonical.
+   - System-prompt instruction the agent followed that ground-truth evidence in the trace contradicts (e.g. prompt says "use endpoint A"; tool reply says "endpoint A deprecated, use B").
+   - Repeated wrong-shape parsing despite the tool's actual output proving the shape.
+3. Use \`searchTrace\` with regex on phrases like \`actually\`, \`turns out\`, \`previously assumed\`, \`old version\`, \`deprecated\`, \`updated to\`, \`now uses\`, or specific entity names you suspect have changed.
+4. For each candidate poisoning, **DUAL-VERIFY**:
+   - Confirm the agent actually acted on the false belief (cite the span where it did)
+   - Confirm the belief is actually false in this trace's own evidence (cite the span that contradicts it)
+   Only emit a finding when both halves are supported. If you can only support one, drop it because single-evidence poisoning findings are too speculative to be useful.
+
+**Independently assess both halves.** Load the action excerpt and contradicting excerpt yourself, then send bounded \`llm_query\` calls the exact evidence for "did the agent act?" and "does the trace contradict the belief?" Subqueries cannot call trace tools. Accept a poisoning only when both assessments and the source excerpts support it.
+
+For each confirmed poisoning, emit ONE finding. Use the source of the false belief as the exact subject. State "agent believed X (from source S); trace evidence shows X is false." Rate it critical for a wrong user-visible action, high when caught internally after significant waste, and medium for inefficiency. Cite BOTH the action span and the contradicting span with exact quotes. Use confidence 0.85+ when both halves have exact quotes and 0.6-0.8 when one half is inferred. Recommend the literal source correction: update the wiki claim, invalidate and re-curate the raw source, or replace the stale prompt/tool instruction.
+
+Do NOT report a finding if the agent caught and corrected the false belief in the same turn. Reserve poisoning for cases where the false belief shaped downstream action.`,
+	toolGroup: "all",
+	limits: {
+		maxLlmCalls: 8,
+		maxIterations: 20,
+		maxToolCalls: 64
+	},
+	minimumEvidenceCitations: 2
+};
+//#endregion
+//#region src/analyst/kinds/index.ts
+/**
+* The default kind suite. Order is the run order operators should
+* use: failure-mode first (no upstream deps), gap + poisoning next
+* (both depend on failures), improvement last (chains all three).
+*/
+const DEFAULT_TRACE_ANALYST_KINDS = [
+	FAILURE_MODE_KIND_SPEC,
+	KNOWLEDGE_GAP_KIND_SPEC,
+	KNOWLEDGE_POISONING_KIND_SPEC,
+	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.
+*
+* 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.
+*/
+/** 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}"`);
+		}
+		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 = 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
+		};
+		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());
+		if (opts.only?.length) {
+			const only = new Set(opts.only);
+			candidates = candidates.filter((a) => only.has(a.id));
+		}
+		if (opts.skip?.length) {
+			const skip = new Set(opts.skip);
+			candidates = candidates.filter((a) => !skip.has(a.id));
+		}
+		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": {
+				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" };
+			}
+		}
+	}
+};
+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");
+	return timeoutMs;
+}
+async function waitForOperation(operation, signal, abortGraceMs) {
+	if (!signal) return operation;
+	if (signal.aborted) {
+		operation.catch(() => {});
+		throw abortReason(signal);
+	}
+	return new Promise((resolve, reject) => {
+		let settlementTimer;
+		const cleanup = () => {
+			signal.removeEventListener("abort", onAbort);
+			if (settlementTimer) clearTimeout(settlementTimer);
+		};
+		const onAbort = () => {
+			if (abortGraceMs === 0) {
+				cleanup();
+				reject(abortReason(signal));
+				return;
+			}
+			settlementTimer = setTimeout(() => {
+				cleanup();
+				reject(abortReason(signal));
+			}, abortGraceMs);
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		operation.then((value) => {
+			cleanup();
+			if (signal.aborted) reject(abortReason(signal));
+			else resolve(value);
+		}, (error) => {
+			cleanup();
+			reject(signal.aborted ? abortReason(signal) : error);
+		});
+	});
+}
+async function waitForHook(operation, signal) {
+	if (operation === void 0 || signal?.aborted) return void 0;
+	try {
+		return await waitForOperation(Promise.resolve().then(() => {
+			if (signal?.aborted) throw abortReason(signal);
+			return operation();
+		}), signal, 0);
+	} catch (error) {
+		if (signal?.aborted) return void 0;
+		throw error;
+	}
+}
+function analystAbortGraceMs(analyst) {
+	if (analyst.cost.kind === "deterministic") return 0;
+	const settlementMs = validateUsageSettlementTimeout(analyst.cost.settlement_timeout_ms);
+	if (settlementMs === 0) return 0;
+	return Math.min(settlementMs + 100, 2147483647);
+}
+function abortedBeforeStartSummary(analyst, signal, latencyMs = 0) {
+	const reason = abortReason(signal);
+	return {
+		analyst_id: analyst.id,
+		status: "skipped",
+		reason: `${reason.name}: ${reason.message}`,
+		findings_count: 0,
+		latency_ms: latencyMs,
+		usage: zeroUsage()
+	};
+}
+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.
+*/
+function selectPriorFindings(source, analystId) {
+	if (!source) return void 0;
+	if (Array.isArray(source)) {
+		const own = source.filter((f) => f.analyst_id === analystId);
+		return own.length > 0 ? own : void 0;
+	}
+	const record = source;
+	const own = record[analystId] ?? [];
+	const wildcard = record["*"] ?? [];
+	const merged = [...own, ...wildcard];
+	return merged.length > 0 ? merged : void 0;
+}
+//#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");
+	const registry = new AnalystRegistry(options.registry);
+	if (options.includeBehavioral !== false) registry.register(behavioralAnalyst(options.behavioral));
+	if (options.engine) for (const definition of options.definitions ?? DEFAULT_TRACE_ANALYST_KINDS) registry.register(createTraceAnalyst(definition, { engine: options.engine }));
+	return registry;
+}
+//#endregion
+export { createChatClient as C, computeTraceMetrics as S, CONTROL_INTEGRITY_ANALYST as _, analystFindingDigest as a, behavioralAnalyst 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, 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, ControlIntegrityAnalyst as v, deriveEfficiencyFindings as x, emitControlIntegrityFindings as y };
+
+//# sourceMappingURL=default-registry-BgJJItGr.js.map