@tangle-network/agent-eval 0.129.0 → 0.130.0

package/dist/default-registry-C-vFCSEc.js

@@ -0,0 +1,2579 @@
+import { i as CostLedger } from "./cost-ledger-DIgQUFZZ.js";
+import { f as maximumChargeForLlmRequest, l as costReceiptFromLlm, n as LlmClient, s as callLlm, u as costReceiptFromLlmError } from "./llm-client--GR4JbZE.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, r as runTraceAnalysisLoop, t as buildTraceAnalystTools } from "./tools-BmuN627J.js";
+import { i as combineAbortSignals } from "./run-score-iEEAWiBY.js";
+import { ai } from "@ax-llm/ax";
+import { z } from "zod";
+import { createHash, randomUUID } from "node:crypto";
+//#region src/analyst/ax-service.ts
+const configuredModels = /* @__PURE__ */ new WeakMap();
+/**
+* Construct the `AxAIService` an analyst kind calls through
+* (`createTraceAnalystKind({ ai })`).
+*
+* Ax's `ai()` pins `config.model` to the OpenAI catalog enum, but every
+* OpenAI-compatible router an analyst points at (router.tangle.tools,
+* cli-bridge) accepts arbitrary model ids (claude-code/sonnet, openai/gpt-5.4,
+* …). Consumers were each re-rolling `ai({ name, apiKey, apiURL, config })`
+* behind an `as (a: any) => any` cast to dodge the enum; this is the one
+* canonical constructor so they don't have to — and don't take a direct
+* `@ax-llm/ax` dependency for it.
+*/
+function createAnalystAi(config) {
+	const model = config.model.trim();
+	if (!model) throw new TypeError("createAnalystAi: model must be a non-empty string");
+	const service = ai({
+		name: config.provider ?? "openai",
+		apiKey: config.apiKey,
+		...config.baseUrl ? { apiURL: config.baseUrl } : {},
+		...config.headers ? { headers: config.headers } : {},
+		config: { model }
+	});
+	configuredModels.set(service, model);
+	return service;
+}
+function getConfiguredAnalystModel(service) {
+	return configuredModels.get(service);
+}
+/** Resolve the model before paid work so every request can be bounded and attributed. */
+function resolveAnalystModel(service, override) {
+	if (override !== void 0) {
+		const model = override.trim();
+		if (!model) throw new TypeError("createTraceAnalystKind: model must be a non-empty string");
+		return model;
+	}
+	const model = getConfiguredAnalystModel(service)?.trim();
+	if (!model) throw new TypeError("createTraceAnalystKind: model is required for Ax services not created by createAnalystAi()");
+	return model;
+}
+//#endregion
+//#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.
+*
+* These are the model-independent multiplier: the four trace-quality signals a
+* tolerant analyzer (e.g. HALO) re-derives per run inside the model — token
+* growth, output decay, tool monoculture, missing self-verification — computed
+* here once, in TypeScript, with zero model judgment. A finding that falls out
+* of arithmetic is trivially model-agnostic and cannot hallucinate the trend.
+*
+* 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/types.ts
+/**
+* Analyst contract — the missing orchestration layer over agent-eval's
+* existing analyzers (analyzeTraces, MultiLayerVerifier, RunCritic,
+* SemanticConceptJudge, JudgeFn, ...).
+*
+* Each existing primitive returns its own output shape. The Analyst
+* contract is the single envelope every primitive lifts into, so a
+* registry can run N analysts against a run and a single renderer can
+* compose findings without knowing which analyzer produced them.
+*
+* The contract is intentionally domain-agnostic: nothing here knows
+* about code, voice, RAG, or any particular agent stack. Analysts
+* declare what INPUT KIND they need (a trace store, an artifact dir,
+* a RunRecord, a JudgeInput, or `custom`), and the registry routes
+* the matching input from `AnalystRunInputs`.
+*/
+/**
+* Compute the stable finding_id from the identity-defining fields.
+* Default implementation hashes {analyst_id, area, subject, normalized claim}.
+* Analysts that emit findings whose claim text varies per run (timestamps,
+* counts) SHOULD either: (a) pass an explicit `id_basis` to fix the hash,
+* or (b) move the variable part into `rationale`/`metadata` and keep the
+* `claim` static.
+*/
+function computeFindingId(input) {
+	const basis = JSON.stringify({
+		a: input.analyst_id,
+		r: input.area,
+		s: input.subject ?? "",
+		c: normalizeClaim(input.id_basis ?? input.claim)
+	});
+	return `f_${createHash("sha256").update(basis).digest("hex").slice(0, 20)}`;
+}
+function normalizeClaim(c) {
+	return c.toLowerCase().replace(/\s+/g, " ").replace(/[.!?;:,]+$/g, "").trim();
+}
+/**
+* Convenience factory: produce a fully-formed AnalystFinding with the
+* id computed automatically. Analyst code stays terse.
+*/
+function makeFinding(init) {
+	const { id_basis, produced_at, ...rest } = init;
+	return {
+		schema_version: "1.0.0",
+		finding_id: computeFindingId({
+			analyst_id: rest.analyst_id,
+			area: rest.area,
+			subject: rest.subject,
+			claim: rest.claim,
+			id_basis
+		}),
+		produced_at: produced_at ?? (/* @__PURE__ */ new Date()).toISOString(),
+		...rest
+	};
+}
+//#endregion
+//#region src/analyst/behavioral-analyst.ts
+/**
+* `behavioralAnalyst` — a DETERMINISTIC analyst (cost.kind = 'deterministic',
+* never calls the LLM). It produces the efficiency/behavioral findings a
+* tolerant agentic analyzer (HALO) re-derives per run inside the model —
+* context bloat, output decay, tool monoculture, missing self-verification —
+* directly from arithmetic over spans (`computeTraceMetrics`).
+*
+* Why it matters: these findings are model-agnostic BY CONSTRUCTION (no model
+* in the loop), so they cannot return 0 on a weak model the way the Ax-RLM
+* does — and they are strictly more reliable than HALO, which spends tokens
+* re-deriving the same numbers and can hallucinate the trend. The agentic
+* RLM kinds remain for SEMANTIC findings that genuinely need a model; this
+* analyst owns the behavioral class.
+*/
+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 = "efficiency-behavioral";
+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.`
+};
+/**
+* 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;
+	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() {
+	return {
+		id: ANALYST_ID,
+		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",
+		async analyze(store) {
+			const overview = await store.getOverview();
+			const analyzedTraceIds = [...new Set(overview.sample_trace_ids)].sort();
+			const findingsById = /* @__PURE__ */ new Map();
+			for (const traceId of analyzedTraceIds) {
+				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,
+							traceIds: [traceId],
+							evidence: [...finding.evidence_refs]
+						});
+						continue;
+					}
+					current.traceIds.push(traceId);
+					current.evidence.push(...finding.evidence_refs);
+				}
+			}
+			return [...findingsById.values()].map(({ finding, traceIds, evidence }) => ({
+				...finding,
+				claim: AGGREGATE_CLAIM[finding.subject](traceIds.length, analyzedTraceIds.length),
+				rationale: `${traceIds.length}/${analyzedTraceIds.length} analyzed traces exhibited this pattern.`,
+				evidence_refs: evidence,
+				metadata: {
+					deterministic: true,
+					trace_ids: traceIds,
+					observed_trace_count: traceIds.length,
+					analyzed_trace_count: analyzedTraceIds.length
+				}
+			}));
+		}
+	};
+}
+//#endregion
+//#region src/analyst/ax-cost-service.ts
+/**
+* Meter every chat call an Ax program makes through the shared paid-call ledger.
+* The wrapper disables provider streaming because a stream has no complete usage
+* receipt until it is consumed, while Ax's analyst output is not streamed to users.
+*/
+function meterAxChatService(ai, options) {
+	assertPositiveInteger(options.maxOutputTokens, "maxOutputTokens");
+	const source = ai;
+	if (typeof source.chat !== "function") throw new TypeError("meterAxChatService: Ax service must implement chat()");
+	const providerChat = source.chat.bind(ai);
+	const chat = async (request, callOptions = {}) => {
+		const boundedRequest = boundOutputTokens(request, options.maxOutputTokens);
+		const model = modelName(boundedRequest.model) || options.defaultModel || "";
+		const canTurnOffThinking = canDisableThinking(ai, model);
+		const combined = combineSignals(options.signal, callOptions.abortSignal);
+		try {
+			const paid = await options.ledger.runPaidCall({
+				channel: "analyst",
+				phase: options.phase ?? "analyst.ax.chat",
+				actor: options.actor,
+				model,
+				tags: options.tags,
+				signal: combined.signal,
+				maximumCharge: maximumChargeForAxChatRequest(boundedRequest, model),
+				execute: async (executionSignal) => {
+					const providerOptions = {
+						...callOptions,
+						abortSignal: executionSignal,
+						retry: {
+							...callOptions.retry,
+							maxRetries: 0
+						},
+						stream: false,
+						showThoughts: false
+					};
+					if (canTurnOffThinking) providerOptions.thinkingTokenBudget = "none";
+					else Reflect.deleteProperty(providerOptions, "thinkingTokenBudget");
+					const response = await providerChat(boundedRequest, providerOptions);
+					if (response instanceof ReadableStream) throw new Error("meterAxChatService: provider returned a stream after stream:false");
+					return response;
+				},
+				receipt: (response) => costReceiptFromAxResponse(response, model)
+			});
+			if (!paid.succeeded) throw paid.error;
+			return paid.value;
+		} finally {
+			combined.dispose();
+		}
+	};
+	return new Proxy(ai, { get(target, property) {
+		if (property === "chat") return chat;
+		const value = Reflect.get(target, property, target);
+		return typeof value === "function" ? value.bind(target) : value;
+	} });
+}
+/** Conservative priced bound for one Ax text chat request. */
+function maximumChargeForAxChatRequest(request, defaultModel) {
+	const model = modelName(request.model) || defaultModel || "";
+	const maxTokens = request.modelConfig?.maxTokens;
+	const completions = request.modelConfig?.n;
+	if (!model || maxTokens === void 0 || completions === void 0) return void 0;
+	assertPositiveInteger(maxTokens, "request.modelConfig.maxTokens");
+	assertPositiveInteger(completions, "request.modelConfig.n");
+	const maximumOutputTokens = maxTokens * completions;
+	assertPositiveInteger(maximumOutputTokens, "maximum output tokens");
+	if (containsUnboundedOrCacheableContent(request)) return void 0;
+	let inputTokens;
+	try {
+		const pricedRequest = request.model === void 0 ? {
+			...request,
+			model
+		} : request;
+		inputTokens = new TextEncoder().encode(JSON.stringify(pricedRequest)).byteLength * completions;
+	} catch {
+		return;
+	}
+	assertPositiveInteger(inputTokens, "maximum input tokens");
+	return {
+		model,
+		inputTokens,
+		outputTokens: maximumOutputTokens
+	};
+}
+function boundOutputTokens(request, limit) {
+	const requested = request.modelConfig?.maxTokens;
+	if (requested !== void 0) assertPositiveInteger(requested, "request.modelConfig.maxTokens");
+	const completions = request.modelConfig?.n ?? 1;
+	assertPositiveInteger(completions, "request.modelConfig.n");
+	const maxTokens = requested === void 0 ? limit : Math.min(requested, limit);
+	return {
+		...request,
+		modelConfig: {
+			...request.modelConfig,
+			maxTokens,
+			n: completions
+		}
+	};
+}
+function costReceiptFromAxResponse(response, fallbackModel) {
+	const usage = response.modelUsage;
+	const tokens = usage?.tokens;
+	const model = usage?.model || fallbackModel;
+	if (!tokens || !validUsage(tokens.promptTokens) || !validUsage(tokens.completionTokens) || !validUsage(tokens.totalTokens) || tokens.totalTokens < tokens.promptTokens + tokens.completionTokens || !validOptionalUsage(tokens.cacheReadTokens) || !validOptionalUsage(tokens.cacheCreationTokens) || !validOptionalUsage(tokens.reasoningTokens) || !validOptionalUsage(tokens.thoughtsTokens)) return {
+		model,
+		inputTokens: 0,
+		outputTokens: 0,
+		usageUnknown: true
+	};
+	const cacheReadTokens = validUsage(tokens.cacheReadTokens) ? tokens.cacheReadTokens : 0;
+	const cacheCreationTokens = validUsage(tokens.cacheCreationTokens) ? tokens.cacheCreationTokens : 0;
+	const totalCacheTokens = cacheReadTokens + cacheCreationTokens;
+	const thoughtsTokens = validUsage(tokens.thoughtsTokens) ? tokens.thoughtsTokens : 0;
+	const reasoningTokens = Math.max(validUsage(tokens.reasoningTokens) ? tokens.reasoningTokens : 0, thoughtsTokens);
+	const separateReasoningTokens = reasoningTokens > tokens.completionTokens ? reasoningTokens : 0;
+	const additionalOutputTokens = Math.max(thoughtsTokens, separateReasoningTokens);
+	const outputTokens = tokens.completionTokens + additionalOutputTokens;
+	const directTotal = tokens.promptTokens + tokens.completionTokens;
+	if (!(/* @__PURE__ */ new Set([
+		directTotal,
+		directTotal + totalCacheTokens,
+		directTotal + additionalOutputTokens,
+		directTotal + totalCacheTokens + additionalOutputTokens
+	])).has(tokens.totalTokens)) return {
+		model,
+		inputTokens: 0,
+		outputTokens: 0,
+		usageUnknown: true
+	};
+	return {
+		model,
+		inputTokens: tokens.promptTokens,
+		outputTokens,
+		...reasoningTokens > 0 ? { reasoningTokens } : {},
+		...cacheReadTokens > 0 ? { cachedTokens: cacheReadTokens } : {},
+		...cacheCreationTokens > 0 ? { cacheWriteTokens: cacheCreationTokens } : {}
+	};
+}
+function combineSignals(first, second) {
+	if (!first) return {
+		signal: second,
+		dispose: () => {}
+	};
+	if (!second || first === second) return {
+		signal: first,
+		dispose: () => {}
+	};
+	if (typeof AbortSignal.any === "function") return {
+		signal: AbortSignal.any([first, second]),
+		dispose: () => {}
+	};
+	const controller = new AbortController();
+	const dispose = () => {
+		first.removeEventListener("abort", abortFromFirst);
+		second.removeEventListener("abort", abortFromSecond);
+	};
+	const abortFrom = (source) => {
+		if (!controller.signal.aborted) controller.abort(source.reason);
+		dispose();
+	};
+	const abortFromFirst = () => abortFrom(first);
+	const abortFromSecond = () => abortFrom(second);
+	if (first.aborted) abortFrom(first);
+	else if (second.aborted) abortFrom(second);
+	else {
+		first.addEventListener("abort", abortFromFirst, { once: true });
+		second.addEventListener("abort", abortFromSecond, { once: true });
+	}
+	return {
+		signal: controller.signal,
+		dispose
+	};
+}
+function containsUnboundedOrCacheableContent(request) {
+	if (request.functions?.some((fn) => fn.cache === true)) return true;
+	return request.chatPrompt.some((message) => {
+		if (message.cache === true) return true;
+		if (!("content" in message) || !Array.isArray(message.content)) return false;
+		return message.content.some((part) => part.cache === true || part.type !== "text");
+	});
+}
+function modelName(value) {
+	return typeof value === "string" ? value : "";
+}
+function canDisableThinking(ai, model) {
+	const namedAi = ai;
+	const serviceName = typeof namedAi.getName === "function" ? namedAi.getName() : "";
+	const modelId = model.slice(model.lastIndexOf("/") + 1);
+	return serviceName !== "GoogleGeminiAI" || !/^gemini-3(?:[.-]|$)/i.test(modelId);
+}
+function validUsage(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function validOptionalUsage(value) {
+	return value === void 0 || validUsage(value);
+}
+function assertPositiveInteger(value, field) {
+	if (!Number.isSafeInteger(value) || value <= 0) throw new RangeError(`meterAxChatService: ${field} must be a positive integer`);
+}
+//#endregion
+//#region src/analyst/finding-subject.ts
+/**
+* Typed `FindingSubject` — the canonical grammar every analyst kind emits.
+*
+* Background: kind actor prompts have always documented a subject grammar
+* (e.g. `system-prompt:<section>`, `agent-knowledge:wiki:<slug>`) but the
+* LLM was unconstrained — it could emit `subject: "fix the prompt"`
+* (prose) and downstream adapters routed on `startsWith(...)` would
+* silently skip it. Every per-vertical `ImprovementAdapter` had a
+* routing table that mostly caught nothing.
+*
+* This module fixes that:
+*   - `parseFindingSubject(raw)` — returns the typed `FindingSubject`
+*     when `raw` matches the grammar, else `null`. Used at the
+*     `RawAnalystFindingSchema` boundary so malformed subjects are
+*     rejected loudly instead of silently lifted into the registry.
+*   - `FindingSubjectKind` — the union of valid locus categories. Each
+*     variant carries the typed components downstream adapters resolve
+*     against the agent's surface manifest (no string parsing in the
+*     adapter).
+*   - `FINDING_SUBJECT_GRAMMAR_PROMPT` — single source of truth for the
+*     grammar string embedded in kind actor prompts. Drift between
+*     prompt and parser is impossible if every kind imports this.
+*
+* The grammar is intentionally NARROW — only loci the substrate's
+* default `ImprovementAdapter` / `KnowledgeAdapter` can act on. A
+* finding with a subject outside this set fails the parser; the kind
+* author either extends the grammar here (and adds adapter routing)
+* or rephrases the prompt to map onto an existing variant.
+*
+* `failure-mode` is the one exception — its subjects are free-form
+* cluster labels, not loci. The schema preserves them as
+* `{ kind: 'cluster', label }` and the adapters skip them (cluster
+* findings are evidence, not actionable mutations).
+*/
+const FINDING_SUBJECT_KINDS = [
+	"knowledge.wiki",
+	"knowledge.claim",
+	"knowledge.raw",
+	"knowledge.stale",
+	"system-prompt",
+	"skill",
+	"tool-doc",
+	"new-tool",
+	"mcp",
+	"hook",
+	"subagent",
+	"workflow",
+	"rollout-policy",
+	"agent-profile",
+	"code",
+	"rag",
+	"memory",
+	"scaffolding",
+	"output-schema",
+	"websearch.outdated",
+	"prior-run-summary",
+	"cluster"
+];
+/**
+* Parse a raw subject string emitted by an analyst kind's actor.
+*
+* Returns the typed `FindingSubject` when `raw` matches the grammar,
+* else `null`. Callers use the `null` return as a signal to either
+* (a) reject the finding at parse time (kinds that emit typed loci —
+* knowledge-gap, improvement, knowledge-poisoning) or (b) lift it as
+* a cluster label (failure-mode).
+*
+* Slugs are constrained to `[a-z0-9-]+` (lowercase kebab) to keep file
+* paths sane downstream. Topics / keys / sections allow any non-empty
+* string (free-form for the LLM's voice) but get trimmed.
+*
+* Empty / whitespace-only inputs return `null`. `undefined` returns
+* `null`. Both are surfaced by the caller as a rejected subject.
+*/
+function parseFindingSubject(raw) {
+	if (raw === null || raw === void 0) return null;
+	const trimmed = raw.trim();
+	if (trimmed.length === 0) return null;
+	const wiki = trimmed.match(/^agent-knowledge:wiki:([a-z0-9][a-z0-9-]*)(?:#([a-z0-9][a-z0-9-]*))?$/);
+	if (wiki) return {
+		kind: "knowledge.wiki",
+		slug: wiki[1],
+		...wiki[2] ? { heading: wiki[2] } : {}
+	};
+	const claim = trimmed.match(/^agent-knowledge:claim:(.+)$/);
+	if (claim && claim[1].trim().length > 0) return {
+		kind: "knowledge.claim",
+		topic: claim[1].trim()
+	};
+	const raw_ = trimmed.match(/^agent-knowledge:raw:(.+)$/);
+	if (raw_ && raw_[1].trim().length > 0) return {
+		kind: "knowledge.raw",
+		sourceId: raw_[1].trim()
+	};
+	const stale = trimmed.match(/^agent-knowledge:stale:([a-z0-9][a-z0-9-]*)$/);
+	if (stale) return {
+		kind: "knowledge.stale",
+		slug: stale[1]
+	};
+	const sp = trimmed.match(/^system-prompt:(.+)$/);
+	if (sp && sp[1].trim().length > 0) return {
+		kind: "system-prompt",
+		section: sp[1].trim()
+	};
+	const skill = trimmed.match(/^skill:([a-z0-9][a-z0-9_.-]*)$/);
+	if (skill) return {
+		kind: "skill",
+		name: skill[1]
+	};
+	const tdAspect = trimmed.match(/^tool-doc:([a-z0-9][a-z0-9_-]*):(.+)$/);
+	if (tdAspect && tdAspect[2].trim().length > 0) return {
+		kind: "tool-doc",
+		tool: tdAspect[1],
+		aspect: tdAspect[2].trim()
+	};
+	const td = trimmed.match(/^tool-doc:([a-z0-9][a-z0-9_-]*)$/);
+	if (td) return {
+		kind: "tool-doc",
+		tool: td[1]
+	};
+	const nt = trimmed.match(/^new-tool:([a-z0-9][a-z0-9_-]*)$/);
+	if (nt) return {
+		kind: "new-tool",
+		name: nt[1]
+	};
+	const mcp = trimmed.match(/^mcp:([a-z0-9][a-z0-9_.-]*)(?::([a-z0-9][a-z0-9_.-]*))?$/);
+	if (mcp) return {
+		kind: "mcp",
+		server: mcp[1],
+		...mcp[2] ? { tool: mcp[2] } : {}
+	};
+	const hook = trimmed.match(/^hook:([a-z0-9][a-z0-9_.-]*)$/);
+	if (hook) return {
+		kind: "hook",
+		name: hook[1]
+	};
+	const subagent = trimmed.match(/^subagent:([a-z0-9][a-z0-9_.-]*)$/);
+	if (subagent) return {
+		kind: "subagent",
+		name: subagent[1]
+	};
+	const workflow = trimmed.match(/^workflow:([a-z0-9][a-z0-9_.-]*)$/);
+	if (workflow) return {
+		kind: "workflow",
+		name: workflow[1]
+	};
+	const rolloutPolicy = trimmed.match(/^rollout-policy:(.+)$/);
+	if (rolloutPolicy && rolloutPolicy[1].trim().length > 0) return {
+		kind: "rollout-policy",
+		field: rolloutPolicy[1].trim()
+	};
+	const agentProfile = trimmed.match(/^agent-profile:(.+)$/);
+	if (agentProfile && agentProfile[1].trim().length > 0) return {
+		kind: "agent-profile",
+		field: agentProfile[1].trim()
+	};
+	const code = trimmed.match(/^code:(.+)$/);
+	if (code && code[1].trim().length > 0) return {
+		kind: "code",
+		path: code[1].trim()
+	};
+	const rag = trimmed.match(/^rag:([a-z0-9][a-z0-9_-]*):(.+)$/);
+	if (rag && rag[2].trim().length > 0) return {
+		kind: "rag",
+		corpus: rag[1],
+		docId: rag[2].trim()
+	};
+	const mem = trimmed.match(/^memory:(.+)$/);
+	if (mem && mem[1].trim().length > 0) return {
+		kind: "memory",
+		key: mem[1].trim()
+	};
+	const sc = trimmed.match(/^scaffolding:(.+)$/);
+	if (sc && sc[1].trim().length > 0) return {
+		kind: "scaffolding",
+		concern: sc[1].trim()
+	};
+	const os = trimmed.match(/^output-schema:(.+)$/);
+	if (os && os[1].trim().length > 0) return {
+		kind: "output-schema",
+		field: os[1].trim()
+	};
+	const ws = trimmed.match(/^websearch:outdated:(.+)$/);
+	if (ws && ws[1].trim().length > 0) return {
+		kind: "websearch.outdated",
+		topic: ws[1].trim()
+	};
+	const prs = trimmed.match(/^prior-run-summary:(.+)$/);
+	if (prs && prs[1].trim().length > 0) return {
+		kind: "prior-run-summary",
+		topic: prs[1].trim()
+	};
+	if (/^[a-z0-9][a-z0-9._-]*$/.test(trimmed) && trimmed.length <= 80) return {
+		kind: "cluster",
+		label: trimmed
+	};
+	return null;
+}
+/**
+* Render the parsed subject back to its canonical string form. Inverse
+* of `parseFindingSubject`; useful when the substrate constructs new
+* findings programmatically (e.g. for tests, replays, or
+* `id_basis` carry-forward).
+*/
+function renderFindingSubject(s) {
+	switch (s.kind) {
+		case "knowledge.wiki": return s.heading ? `agent-knowledge:wiki:${s.slug}#${s.heading}` : `agent-knowledge:wiki:${s.slug}`;
+		case "knowledge.claim": return `agent-knowledge:claim:${s.topic}`;
+		case "knowledge.raw": return `agent-knowledge:raw:${s.sourceId}`;
+		case "knowledge.stale": return `agent-knowledge:stale:${s.slug}`;
+		case "system-prompt": return `system-prompt:${s.section}`;
+		case "skill": return `skill:${s.name}`;
+		case "tool-doc": return s.aspect ? `tool-doc:${s.tool}:${s.aspect}` : `tool-doc:${s.tool}`;
+		case "new-tool": return `new-tool:${s.name}`;
+		case "mcp": return s.tool ? `mcp:${s.server}:${s.tool}` : `mcp:${s.server}`;
+		case "hook": return `hook:${s.name}`;
+		case "subagent": return `subagent:${s.name}`;
+		case "workflow": return `workflow:${s.name}`;
+		case "rollout-policy": return `rollout-policy:${s.field}`;
+		case "agent-profile": return `agent-profile:${s.field}`;
+		case "code": return `code:${s.path}`;
+		case "rag": return `rag:${s.corpus}:${s.docId}`;
+		case "memory": return `memory:${s.key}`;
+		case "scaffolding": return `scaffolding:${s.concern}`;
+		case "output-schema": return `output-schema:${s.field}`;
+		case "websearch.outdated": return `websearch:outdated:${s.topic}`;
+		case "prior-run-summary": return `prior-run-summary:${s.topic}`;
+		case "cluster": return s.label;
+	}
+}
+/**
+* The grammar text embedded into kind actor prompts. Kinds opt into
+* the subset of variants they emit (e.g. `improvement` excludes the
+* cluster variant; `failure-mode` includes ONLY the cluster variant).
+*
+* Drift between prompt and parser is impossible: every kind imports
+* this constant + the matching `expects` set, and the unit tests below
+* lock the table to the parser.
+*/
+const FINDING_SUBJECT_SYNTAX = {
+	"knowledge.wiki": "agent-knowledge:wiki:<slug>[#<heading>]",
+	"knowledge.claim": "agent-knowledge:claim:<topic>",
+	"knowledge.raw": "agent-knowledge:raw:<source-id>",
+	"knowledge.stale": "agent-knowledge:stale:<slug>",
+	"system-prompt": "system-prompt:<section>",
+	skill: "skill:<name>",
+	"tool-doc": "tool-doc:<tool>[:<aspect>]",
+	"new-tool": "new-tool:<name>",
+	mcp: "mcp:<server>[:<tool>]",
+	hook: "hook:<name>",
+	subagent: "subagent:<name>",
+	workflow: "workflow:<name>",
+	"rollout-policy": "rollout-policy:<field>",
+	"agent-profile": "agent-profile:<field>",
+	code: "code:<path>",
+	rag: "rag:<corpus>:<doc-id>",
+	memory: "memory:<key>",
+	scaffolding: "scaffolding:<concern>",
+	"output-schema": "output-schema:<field>",
+	"websearch.outdated": "websearch:outdated:<topic>",
+	"prior-run-summary": "prior-run-summary:<topic>",
+	cluster: "<lowercase-cluster-label>"
+};
+const FINDING_SUBJECT_PURPOSE = {
+	"knowledge.wiki": "create or update a wiki page",
+	"knowledge.claim": "draft a claim or relation",
+	"knowledge.raw": "curate a raw source",
+	"knowledge.stale": "mark a stale page",
+	"system-prompt": "revise a system-prompt section",
+	skill: "create or revise a skill",
+	"tool-doc": "revise a tool contract",
+	"new-tool": "propose a new tool",
+	mcp: "revise an MCP server or tool",
+	hook: "revise a lifecycle hook",
+	subagent: "revise a delegated agent",
+	workflow: "revise an orchestration workflow",
+	"rollout-policy": "revise budget, sampling, or stop policy",
+	"agent-profile": "revise another AgentProfile field",
+	code: "revise an implementation path",
+	rag: "ingest or correct a RAG document",
+	memory: "invalidate or set memory",
+	scaffolding: "revise preconditions, retries, or verification",
+	"output-schema": "constrain the output shape",
+	"websearch.outdated": "identify a stale web result",
+	"prior-run-summary": "identify a stale prior-run summary",
+	cluster: "name one failure cluster"
+};
+function renderFindingSubjectGrammar(kinds) {
+	return [
+		"Subjects MUST match one of these forms — anything else is rejected at parse time:",
+		...kinds.map((kind) => `  ${FINDING_SUBJECT_SYNTAX[kind]} — ${FINDING_SUBJECT_PURPOSE[kind]}`),
+		"Runtime ids are lowercase [a-z0-9_.-]+. Topics, keys, paths, and sections are free-form and trimmed."
+	].join("\n");
+}
+const FINDING_SUBJECT_GRAMMAR_PROMPT = renderFindingSubjectGrammar(FINDING_SUBJECT_KINDS);
+/**
+* The variants each kind is allowed to emit. Used at the kind factory
+* boundary so a knowledge-gap finding can't sneak in a `system-prompt:*`
+* subject (the improvement-analyst's job) and vice versa.
+*
+* `failure-mode` is restricted to `cluster` — the only kind that emits
+* a non-locus subject.
+*/
+const KIND_EXPECTED_SUBJECTS = {
+	"failure-mode": ["cluster"],
+	"knowledge-gap": [
+		"knowledge.wiki",
+		"knowledge.claim",
+		"knowledge.raw",
+		"knowledge.stale",
+		"tool-doc",
+		"system-prompt",
+		"skill",
+		"mcp",
+		"subagent",
+		"workflow",
+		"memory",
+		"websearch.outdated",
+		"prior-run-summary"
+	],
+	"knowledge-poisoning": [
+		"knowledge.wiki",
+		"knowledge.claim",
+		"knowledge.raw",
+		"tool-doc",
+		"system-prompt",
+		"skill",
+		"mcp",
+		"hook",
+		"memory",
+		"websearch.outdated",
+		"prior-run-summary"
+	],
+	improvement: [
+		"system-prompt",
+		"skill",
+		"tool-doc",
+		"new-tool",
+		"mcp",
+		"hook",
+		"subagent",
+		"workflow",
+		"rollout-policy",
+		"agent-profile",
+		"code",
+		"rag",
+		"memory",
+		"scaffolding",
+		"output-schema",
+		"knowledge.wiki",
+		"knowledge.claim"
+	]
+};
+/** Render only the subject forms one analyst kind is permitted to emit. */
+function findingSubjectGrammarPromptFor(kindId) {
+	const kinds = KIND_EXPECTED_SUBJECTS[kindId];
+	if (!kinds) throw new Error(`unknown analyst kind: ${kindId}`);
+	return renderFindingSubjectGrammar(kinds);
+}
+/**
+* Zod schema that validates a raw subject string and returns the parsed
+* `FindingSubject`. Embedded in `RawAnalystFindingSchema` via
+* `transform`, so `subject` arrives at the kind factory either as a
+* typed locus or as a parse error attached to a single Zod issue.
+*
+* Optionality is preserved: subjects ARE optional on the wire (some
+* findings are descriptive, not actionable). When present, they MUST
+* parse — emitting a malformed subject is a contract violation, not a
+* soft signal.
+*/
+const FindingSubjectStringSchema = z.string().refine((s) => parseFindingSubject(s) !== null, { message: "subject does not match the finding-subject grammar" });
+//#endregion
+//#region src/analyst/parse-tolerant.ts
+/**
+* Forgiving pre-parse for analyst findings. Weak models routinely emit
+* schema-correct content in an unusable wrapper — fenced ```json blocks, a
+* single object where an array is expected, trailing commas. Measured: GPT-4o
+* drops to 0% usable output purely from markdown-fence wrapping
+* (arXiv:2605.02363). A five-line de-fence recovers most of it. This module is
+* the de-fence/coerce step that runs BEFORE Zod, so a recoverable finding is
+* repaired, not dropped.
+*
+* Pure + deterministic. No model, no network.
+*/
+/** Strip a ```lang ... ``` (or bare ``` ... ```) code fence, if the string is one. */
+function stripCodeFences(text) {
+	const t = text.trim();
+	const m = t.match(/^```[a-zA-Z0-9]*\s*\n?([\s\S]*?)\n?```$/);
+	return m ? m[1].trim() : t;
+}
+/** Remove trailing commas before } or ] — the most common near-JSON defect. */
+function dropTrailingCommas(s) {
+	return s.replace(/,(\s*[}\]])/g, "$1");
+}
+/**
+* Best-effort parse of a string into JSON. De-fences, drops trailing commas,
+* then `JSON.parse`. Returns `undefined` (never throws) when unrecoverable.
+*/
+function coerceJson(text) {
+	const candidate = dropTrailingCommas(stripCodeFences(text));
+	try {
+		return JSON.parse(candidate);
+	} catch {
+		return;
+	}
+}
+/**
+* Coerce arbitrary actor/structurer output into an array of candidate finding
+* rows: a JSON string → parse; a single object → 1-element array; an array →
+* as-is; anything else → []. Callers still run each row through Zod
+* (`parseRawFinding`) — this only fixes the shape and never invents fields.
+*/
+function coerceToFindingRows(raw) {
+	let value = raw;
+	if (typeof value === "string") {
+		const parsed = coerceJson(value);
+		if (parsed === void 0) return [];
+		value = parsed;
+	}
+	if (Array.isArray(value)) return value;
+	if (value && typeof value === "object") {
+		const inner = value.findings;
+		if (Array.isArray(inner)) return inner;
+		return [value];
+	}
+	return [];
+}
+//#endregion
+//#region src/analyst/finding-signature.ts
+/**
+* Typed Ax output for analyst findings.
+*
+* Ax binds the field as `findings:json[]` so the provider emits native
+* structured output. At the kind-factory boundary every row is validated
+* before it becomes an `AnalystFinding`.
+*
+* Why not `f.object().array()` directly in the signature? The Ax
+* signature string `question:string -> findings:json[]` already lets
+* the provider emit JSON arrays. A Zod boundary is required either
+* way (the provider can return any JSON), and Zod gives us a single
+* validation surface independent of which Ax version is installed.
+*/
+const ANALYST_SEVERITIES = [
+	"critical",
+	"high",
+	"medium",
+	"low",
+	"info"
+];
+const RawAnalystEvidenceSchema = z.object({
+	uri: z.string().trim().min(1).max(2e3),
+	excerpt: z.string().max(2e3).optional()
+}).strict();
+const RawAnalystFindingBaseShape = {
+	severity: z.enum(ANALYST_SEVERITIES),
+	claim: z.string().min(1).max(2e3),
+	subject: z.string().max(400).refine((subject) => parseFindingSubject(subject) !== null, { message: "subject does not match the finding-subject grammar" }).optional(),
+	confidence: z.number().min(0).max(1),
+	rationale: z.string().max(4e3).optional(),
+	recommended_action: z.string().max(2e3).optional()
+};
+const RawAnalystFindingSchema = z.object({
+	...RawAnalystFindingBaseShape,
+	evidence: z.array(RawAnalystEvidenceSchema).min(1)
+}).strict();
+/**
+* Description embedded into the actor prompt so the LLM knows what
+* shape to emit. Kept here so kinds share one source of truth rather
+* than restating the schema in every prompt.
+*/
+const RAW_FINDING_SCHEMA_PROMPT = `Each finding MUST be a strict JSON object with:
+  - severity: "critical" | "high" | "medium" | "low" | "info"
+  - claim: one-sentence statement (max 2000 chars)
+  - subject?: one exact subject form listed by this kind; omit rather than guess
+  - evidence: REQUIRED non-empty array of {"uri": string, "excerpt"?: string}. Use real identifiers with span://, event://, artifact://, metric://, or finding://. Include a short exact quote in excerpt when available. If nothing is citable, do not emit the finding.
+  - confidence: number 0..1 (0.9+ exact evidence; 0.6-0.8 inferred pattern; <0.5 speculative)
+  - rationale?: one or two reasoning sentences
+  - recommended_action?: concrete imperative change; omit for descriptive findings
+
+Unknown fields are rejected. Do not emit area; the factory assigns it. Emit [] when there are no findings. Never fabricate evidence.`;
+/** Convert raw citations into the public finding evidence envelope. */
+function evidenceRefsFromRawFinding(finding) {
+	return finding.evidence.map(({ uri, excerpt }) => ({
+		kind: evidenceKindFromUri(uri),
+		uri,
+		excerpt
+	}));
+}
+function parseRawFinding(row, log) {
+	return parseFindingWithSchema(RawAnalystFindingSchema, row, log);
+}
+function parseFindingWithSchema(schema, row, log) {
+	const result = schema.safeParse(row);
+	if (result.success) return result.data;
+	if (typeof row === "string") {
+		const coerced = coerceJson(row);
+		if (coerced !== void 0) {
+			const retry = schema.safeParse(coerced);
+			if (retry.success) return retry.data;
+		}
+	}
+	log?.("finding rejected: schema failure", { issues: result.error.issues.map((i) => ({
+		path: i.path.join("."),
+		code: i.code,
+		message: i.message
+	})) });
+	return null;
+}
+function evidenceKindFromUri(uri) {
+	if (uri.startsWith("span://")) return "span";
+	if (uri.startsWith("event://")) return "event";
+	if (uri.startsWith("finding://")) return "finding";
+	if (uri.startsWith("metric://")) return "metric";
+	return "artifact";
+}
+//#endregion
+//#region src/analyst/structure-findings.ts
+/**
+* `structureFindings` — the deferred structuring pass (DSPy TwoStepAdapter /
+* HALO `synthesize_traces` analog). The agentic actor reasons FREE-FORM and
+* emits a prose `report` (which any model does reliably); this separate, cheap
+* call's ONLY job is to turn that report into `AnalystFinding[]`. Decoupling
+* reasoning from structuring is what makes the SEMANTIC findings model-agnostic
+* — the reasoning model never has to satisfy a strict typed-array contract
+* while it diagnoses.
+*
+* Forgiving: the response runs through `coerceToFindingRows` (de-fence, lift
+* single→array) before Zod, and on a zero-finding extraction from a substantive
+* report it reasks ONCE with the schema restated. Returns a typed outcome so a
+* legitimate "nothing to report" is distinguishable from a failed extraction
+* (no silent empty).
+*/
+const SYSTEM = [
+	"You convert a free-form trace-analysis report into a STRICT JSON array of findings.",
+	"Output ONLY the JSON array — no prose, no code fences.",
+	RAW_FINDING_SCHEMA_PROMPT,
+	"Omit subject when the report does not contain an exact valid locus.",
+	"If the report asserts NO problems, output exactly []."
+].join(" ");
+function buildRows(raw, opts) {
+	const rows = coerceToFindingRows(raw);
+	const out = [];
+	for (const row of rows) {
+		const parsed = parseRawFinding(row);
+		if (!parsed) continue;
+		const callbackResult = opts.processRow ? opts.processRow(parsed) : parsed;
+		if (!callbackResult) continue;
+		const processed = parseRawFinding(callbackResult);
+		if (!processed) continue;
+		out.push(makeFinding({
+			analyst_id: opts.analystId,
+			area: opts.area,
+			subject: processed.subject,
+			claim: processed.claim,
+			rationale: processed.rationale,
+			severity: processed.severity,
+			confidence: processed.confidence,
+			evidence_refs: evidenceRefsFromRawFinding(processed),
+			recommended_action: processed.recommended_action,
+			...opts.findingMetadata ? { metadata: { ...opts.findingMetadata } } : {}
+		}));
+	}
+	return out;
+}
+async function structureFindings(opts) {
+	const maxReasks = opts.maxReasks ?? 1;
+	if (!Number.isSafeInteger(maxReasks) || maxReasks < 0) throw new RangeError("structureFindings: maxReasks must be a non-negative safe integer");
+	const llm = {
+		baseUrl: opts.baseUrl,
+		apiKey: opts.apiKey,
+		fetch: opts.fetchImpl
+	};
+	const costLedger = opts.costLedger ?? new CostLedger();
+	let user = `TRACE-ANALYSIS REPORT:\n${opts.report}\n\nReturn the findings JSON array.`;
+	for (let attempt = 0; attempt <= maxReasks; attempt++) {
+		const request = {
+			model: opts.model,
+			messages: [{
+				role: "system",
+				content: SYSTEM
+			}, {
+				role: "user",
+				content: user
+			}],
+			maxTokens: opts.maxTokens ?? 2e3
+		};
+		const paid = await costLedger.runPaidCall({
+			channel: "analyst",
+			phase: opts.costPhase ?? "analyst.structure-findings",
+			actor: "structure-findings",
+			model: opts.model,
+			signal: opts.signal,
+			maximumCharge: maximumChargeForLlmRequest(request, llm),
+			tags: {
+				...opts.costTags,
+				analystId: opts.analystId,
+				attempt: String(attempt)
+			},
+			execute: (signal, callId) => callLlm(request, {
+				...llm,
+				signal,
+				idempotencyKey: callId
+			}),
+			receipt: costReceiptFromLlm,
+			receiptFromError: costReceiptFromLlmError
+		});
+		if (!paid.succeeded) throw paid.error;
+		const findings = buildRows(paid.value.content.trim(), opts);
+		if (findings.length > 0) return {
+			findings,
+			outcome: "ok"
+		};
+		if (opts.report.trim().length < 200) return {
+			findings: [],
+			outcome: "ok"
+		};
+		user = `${user}\n\nThat produced no valid findings. The report DOES describe issues — re-extract them as the strict JSON array described in the system prompt. Output ONLY the array.`;
+	}
+	return {
+		findings: [],
+		outcome: "extraction_failed"
+	};
+}
+/** Convert one ledger channel's complete call set into one analyst receipt. */
+function usageReceiptFromCostLedger(ledger, filter = "analyst") {
+	const resolvedFilter = typeof filter === "string" ? { channel: filter } : filter;
+	const summary = ledger.summary(resolvedFilter);
+	const receipts = ledger.list(resolvedFilter);
+	const hasReasoningUsage = receipts.some((receipt) => receipt.reasoningTokens !== void 0);
+	const hasCacheWriteUsage = receipts.some((receipt) => receipt.cacheWriteTokens !== void 0);
+	const cost = summary.pendingCalls > 0 || receipts.some((receipt) => receipt.costUnknown) ? {
+		kind: "uncaptured",
+		usd: null
+	} : receipts.every((receipt) => receipt.actualCostUsd !== void 0) ? {
+		kind: "observed",
+		usd: summary.totalCostUsd
+	} : {
+		kind: "estimated",
+		usd: summary.totalCostUsd
+	};
+	return {
+		calls: summary.totalCalls + summary.pendingCalls,
+		tokens: summary.usageComplete ? {
+			input: summary.inputTokens,
+			output: summary.outputTokens,
+			...hasReasoningUsage ? { reasoning: summary.reasoningTokens ?? 0 } : {},
+			...summary.cachedTokens > 0 ? { cached: summary.cachedTokens } : {},
+			...hasCacheWriteUsage ? { cacheWrite: summary.cacheWriteTokens ?? 0 } : {}
+		} : null,
+		cost,
+		...cost.kind === "uncaptured" ? { knownCostUsd: summary.totalCostUsd } : {}
+	};
+}
+/** Wait a bounded time for late provider receipts, then take one immutable snapshot. */
+async function settleUsageReceiptFromCostLedger(ledger, options = {}) {
+	const { timeoutMs: requestedTimeoutMs, ...requestedFilter } = options;
+	const filter = {
+		channel: requestedFilter.channel ?? "analyst",
+		...requestedFilter.phase === void 0 ? {} : { phase: requestedFilter.phase },
+		...requestedFilter.tags === void 0 ? {} : { tags: requestedFilter.tags }
+	};
+	const timeoutMs = validateUsageSettlementTimeout(requestedTimeoutMs);
+	const waitResult = ledger.summary(filter).pendingCalls === 0 ? true : ledger.waitForIdle ? await ledger.waitForIdle({ timeoutMs }) : false;
+	const pendingCalls = ledger.summary(filter).pendingCalls;
+	return {
+		settled: waitResult && pendingCalls === 0,
+		pendingCalls,
+		receipt: usageReceiptFromCostLedger(ledger, filter)
+	};
+}
+function validateUsageSettlementTimeout(timeoutMs) {
+	const resolved = timeoutMs ?? 5e3;
+	if (!Number.isSafeInteger(resolved) || resolved < 0 || resolved > 2147483647) throw new TypeError("settlementTimeoutMs must be a non-negative safe integer no greater than 2147483647");
+	return resolved;
+}
+//#endregion
+//#region src/analyst/kind-factory.ts
+/**
+* Build an `Analyst<TraceAnalysisStore>` from a kind spec.
+*
+* Lifts the Ax pipeline once at registration time so the registry
+* gets a stateless analyst. The Ax agent is freshly constructed per
+* `analyze()` call (the agent carries chat-log + usage state we don't
+* want shared across analyst runs).
+*/
+function createTraceAnalystKind(spec, opts) {
+	rejectRemovedKindOptions(spec);
+	const version = opts.versionSuffix ? `${spec.version}+${opts.versionSuffix}` : spec.version;
+	const model = resolveAnalystModel(opts.ai, opts.model);
+	const minimumEvidenceCitations = spec.minimumEvidenceCitations ?? 1;
+	if (!Number.isInteger(minimumEvidenceCitations) || minimumEvidenceCitations < 1) throw new TypeError("minimumEvidenceCitations must be a positive integer");
+	const settlementTimeoutMs = validateUsageSettlementTimeout(opts.settlementTimeoutMs);
+	return {
+		id: spec.id,
+		description: spec.description,
+		inputKind: "trace-store",
+		cost: {
+			...spec.cost,
+			settlement_timeout_ms: settlementTimeoutMs
+		},
+		version,
+		async analyze(store, ctx) {
+			const maxOutputTokens = spec.maxOutputTokens ?? 4096;
+			const costLedger = ctx.costLedger ?? new CostLedger(ctx.budgetUsd);
+			const costTags = {
+				...ctx.tags ?? {},
+				analystId: spec.id,
+				...ctx.correlationId ? { analystRunId: ctx.correlationId } : {}
+			};
+			const meteredAi = meterAxChatService(opts.ai, {
+				ledger: costLedger,
+				actor: spec.id,
+				maxOutputTokens,
+				defaultModel: model,
+				phase: ctx.costPhase,
+				signal: ctx.signal,
+				tags: costTags
+			});
+			try {
+				const tools = spec.buildTools(store);
+				const maxSubqueries = spec.subqueries?.maxCalls ?? 0;
+				const maxParallel = spec.subqueries?.maxParallel ?? 2;
+				const priorContext = renderPriorFindings(ctx.priorFindings);
+				const upstreamContext = renderUpstreamFindings(ctx.upstreamFindings);
+				const actorDescription = spec.actorDescription.trim() + priorContext + upstreamContext + "\n\n" + RAW_FINDING_SCHEMA_PROMPT + (minimumEvidenceCitations > 1 ? `\n\nThis kind requires at least ${minimumEvidenceCitations} evidence citations per finding; rows with fewer are rejected.` : "") + "\n\nFirst write `report`: a concise free-form prose diagnosis of what the traces show — what succeeded, what was suboptimal or failed — with concrete trace ids and numbers. THEN return the structured `findings` array (it MAY be empty when there is nothing to report).";
+				ctx.log?.(`analyst.kind ${spec.id} forward`, {
+					max_subqueries: maxSubqueries,
+					tool_count: tools.length,
+					tags: ctx.tags
+				});
+				const { report, findings: submittedFindings } = await runTraceAnalysisLoop({
+					id: spec.id,
+					description: spec.description,
+					prompt: actorDescription,
+					question: deriveQuestion(ctx, spec),
+					ai: meteredAi,
+					model,
+					tools,
+					findingType: "object",
+					maxSubqueries,
+					maxParallelSubqueries: maxParallel,
+					maxTurns: spec.maxTurns ?? 12,
+					maxRuntimeChars: spec.maxRuntimeChars ?? 6e3,
+					...ctx.signal ? { signal: ctx.signal } : {}
+				});
+				const expectedSubjects = KIND_EXPECTED_SUBJECTS[spec.id];
+				const out = [];
+				const rawRows = submittedFindings;
+				let rejectedWrongKind = 0;
+				let rejectedInsufficientEvidence = 0;
+				const processRow = (parsed) => {
+					const callbackResult = spec.postProcess ? spec.postProcess(parsed, ctx) : parsed;
+					if (!callbackResult) return null;
+					const postProcessed = parseRawFinding(callbackResult, ctx.log);
+					if (!postProcessed) return null;
+					if (expectedSubjects && postProcessed.subject !== void 0) {
+						const parsedSubject = parseFindingSubject(postProcessed.subject);
+						if (parsedSubject === null) {
+							ctx.log?.("finding rejected: subject failed to parse", {
+								kind: spec.id,
+								subject: postProcessed.subject
+							});
+							rejectedWrongKind += 1;
+							return null;
+						}
+						if (!expectedSubjects.includes(parsedSubject.kind)) {
+							ctx.log?.("finding rejected: subject variant not allowed for this kind", {
+								kind: spec.id,
+								subject_kind: parsedSubject.kind,
+								subject: postProcessed.subject,
+								allowed: expectedSubjects
+							});
+							rejectedWrongKind += 1;
+							return null;
+						}
+					}
+					const distinctEvidenceCitations = new Set(postProcessed.evidence.map((citation) => citation.uri.trim())).size;
+					if (distinctEvidenceCitations < minimumEvidenceCitations) {
+						ctx.log?.("finding rejected: insufficient evidence citations", {
+							kind: spec.id,
+							required: minimumEvidenceCitations,
+							received: postProcessed.evidence.length,
+							distinct: distinctEvidenceCitations
+						});
+						rejectedInsufficientEvidence += 1;
+						return null;
+					}
+					return postProcessed;
+				};
+				for (const row of rawRows) {
+					const parsed = parseRawFinding(row, ctx.log);
+					if (!parsed) continue;
+					const postProcessed = processRow(parsed);
+					if (!postProcessed) continue;
+					out.push(toAnalystFinding(spec, version, postProcessed));
+				}
+				ctx.log?.(`analyst.kind ${spec.id} done`, {
+					emitted: rawRows.length,
+					accepted: out.length,
+					rejected_wrong_subject: rejectedWrongKind,
+					rejected_insufficient_evidence: rejectedInsufficientEvidence
+				});
+				if (out.length === 0 && report.trim().length >= 200) {
+					if (opts.recovery) {
+						const wrongKindBefore = rejectedWrongKind;
+						const insufficientEvidenceBefore = rejectedInsufficientEvidence;
+						const recovered = await structureFindings({
+							report,
+							analystId: spec.id,
+							area: spec.area,
+							model: opts.recovery.model ?? model,
+							baseUrl: opts.recovery.baseUrl,
+							apiKey: opts.recovery.apiKey,
+							fetchImpl: opts.recovery.fetchImpl,
+							costLedger,
+							costPhase: ctx.costPhase,
+							costTags,
+							signal: ctx.signal,
+							maxTokens: Math.min(maxOutputTokens, 2e3),
+							processRow,
+							findingMetadata: { kind_version: version }
+						});
+						out.push(...recovered.findings);
+						ctx.log?.(`analyst.kind ${spec.id} recovery`, {
+							outcome: recovered.outcome,
+							recovered: recovered.findings.length,
+							rejected_wrong_subject: rejectedWrongKind - wrongKindBefore,
+							rejected_insufficient_evidence: rejectedInsufficientEvidence - insufficientEvidenceBefore
+						});
+					}
+					if (out.length === 0) {
+						const fallback = processRow({
+							claim: "Analyst produced a diagnosis but no structured findings — see report.",
+							rationale: report.slice(0, 1500),
+							severity: "info",
+							confidence: .3,
+							evidence: [{
+								uri: "report://summary",
+								excerpt: report.slice(0, 2e3)
+							}]
+						});
+						if (fallback) out.push(toAnalystFinding(spec, version, fallback, { outcome: "extraction_failed" }));
+						else throw new Error(`Trace analyst '${spec.id}' produced a substantive report, but no finding satisfied its acceptance rules`);
+					}
+				}
+				return out;
+			} finally {
+				const usage = await settleUsageReceiptFromCostLedger(costLedger, {
+					tags: {
+						analystId: spec.id,
+						...ctx.correlationId ? { analystRunId: ctx.correlationId } : {}
+					},
+					timeoutMs: settlementTimeoutMs
+				});
+				if (!usage.settled) ctx.log?.(`analyst.kind ${spec.id} provider settlement timed out`, {
+					pending_calls: usage.pendingCalls,
+					timeout_ms: settlementTimeoutMs
+				});
+				ctx.recordUsage?.(usage.receipt);
+			}
+		}
+	};
+}
+function rejectRemovedKindOptions(spec) {
+	const supplied = spec;
+	for (const [removed, replacement] of [
+		["recursion", "subqueries"],
+		["responderDescription", "actorDescription"],
+		["maxDepth", "subqueries"],
+		["maxParallelSubagents", "subqueries.maxParallel"],
+		["subagentDescription", "actorDescription"]
+	]) if (removed in supplied) throw new TypeError(`createTraceAnalystKind: '${removed}' is unsupported; use '${replacement}'`);
+}
+function deriveQuestion(ctx, spec) {
+	const focus = ctx.tags?.focus?.trim();
+	const task = `Analyze this trace dataset with the available tools and report ${spec.area} findings. ${spec.description}`;
+	return focus ? `${task} Focus: ${focus}.` : task;
+}
+function toAnalystFinding(spec, version, raw, metadata = {}) {
+	return makeFinding({
+		analyst_id: spec.id,
+		area: spec.area,
+		subject: raw.subject,
+		claim: raw.claim,
+		rationale: raw.rationale,
+		severity: raw.severity,
+		confidence: raw.confidence,
+		evidence_refs: evidenceRefsFromRawFinding(raw),
+		recommended_action: raw.recommended_action,
+		metadata: {
+			kind_version: version,
+			...metadata
+		}
+	});
+}
+/**
+* Render a compact prior-findings block the actor reads alongside its
+* brief. Each row is one line so the actor can scan dozens cheaply.
+* The kind's prompt instructs the actor to (a) check whether a new
+* cluster matches a prior `finding_id` (carry the id forward via
+* `id_basis` to keep diffs stable) and (b) raise severity / confidence
+* when a prior finding has reappeared without remediation.
+*
+* Returns the empty string when there are no prior findings — most
+* runs are "first-of-its-kind" and the prompt stays unchanged.
+*
+* Exported for tests + for consumers that build their own actor
+* prompts (e.g. specialized analysts living outside the default kinds).
+*/
+function renderPriorFindings(prior) {
+	if (!prior || prior.length === 0) return "";
+	const MAX_ROWS = 40;
+	const rows = prior.slice(0, MAX_ROWS).map((f) => {
+		const subject = f.subject ? ` [${f.subject}]` : "";
+		return `  - id=${f.finding_id} ${f.severity}${subject} ${truncateForContext(f.claim, 160)}`;
+	});
+	const overflow = prior.length > MAX_ROWS ? `\n  ... +${prior.length - MAX_ROWS} more prior findings (older history truncated)` : "";
+	return [
+		"",
+		"",
+		"PRIOR FINDINGS (from a previous run on related data):",
+		"When the work you do now matches a row below, REUSE the `finding_id` (pass it as `id_basis`) so the cross-run diff stays stable.",
+		"A finding that reappears with no remediation evidence SHOULD raise its `confidence` and may justify a higher `severity`.",
+		...rows,
+		overflow
+	].filter(Boolean).join("\n");
+}
+/** Render findings produced earlier in this same registry run. */
+function renderUpstreamFindings(upstream) {
+	if (!upstream || upstream.length === 0) return "";
+	const MAX_ROWS = 40;
+	const rows = upstream.slice(0, MAX_ROWS).map((finding) => {
+		const subject = finding.subject ? ` [${finding.subject}]` : "";
+		const action = finding.recommended_action ? ` action=${truncateForContext(finding.recommended_action, 120)}` : "";
+		const evidence = finding.evidence_refs[0] ? ` evidence=${truncateForContext(finding.evidence_refs[0].uri, 120)}` : "";
+		return `  - id=${finding.finding_id} source=${finding.analyst_id} ${finding.severity}${subject} claim=${truncateForContext(finding.claim, 160)}${action}${evidence}`;
+	});
+	const overflow = upstream.length > MAX_ROWS ? `\n  ... +${upstream.length - MAX_ROWS} more upstream findings (truncated)` : "";
+	return [
+		"",
+		"",
+		"UPSTREAM FINDINGS (produced earlier in this same registry run):",
+		"Use these as intermediate evidence. Build on them instead of repeating the same diagnosis, and cite a dependency with `finding://<id>`.",
+		...rows,
+		overflow
+	].filter(Boolean).join("\n");
+}
+function truncateForContext(s, max) {
+	if (s.length <= max) return s;
+	return `${s.slice(0, max - 1).trimEnd()}…`;
+}
+//#endregion
+//#region src/analyst/tool-groups.ts
+const TOOL_NAMES_BY_GROUP = {
+	all: /* @__PURE__ */ new Set(),
+	discovery: /* @__PURE__ */ new Set([
+		"getDatasetOverview",
+		"queryTraces",
+		"countTraces"
+	]),
+	discoveryAndRead: /* @__PURE__ */ new Set([
+		"getDatasetOverview",
+		"queryTraces",
+		"countTraces",
+		"viewTrace",
+		"viewSpans"
+	]),
+	discoveryAndSearch: /* @__PURE__ */ new Set([
+		"getDatasetOverview",
+		"queryTraces",
+		"countTraces",
+		"searchTrace",
+		"searchSpan"
+	]),
+	targeted: /* @__PURE__ */ new Set([
+		"getDatasetOverview",
+		"queryTraces",
+		"viewSpans",
+		"searchSpan"
+	])
+};
+/**
+* Build the tool set for a named group bound to a specific trace store.
+*
+* `all` returns every tool. Other groups filter `buildTraceAnalystTools`
+* by name to the documented subset. An unrecognised group name throws —
+* silently returning all tools would defeat the cost-control point.
+*/
+function buildTraceToolsForGroup(group, store) {
+	const all = buildTraceAnalystTools({ store });
+	if (group === "all") return all;
+	const allow = TOOL_NAMES_BY_GROUP[group];
+	if (!allow) throw new Error(`unknown trace tool group: ${group}`);
+	return all.filter((tool) => allow.has(tool.name));
+}
+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",
+	actorDescription: `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 \`traces.getDatasetOverview({})\` first. Use \`has_errors\`, \`models\`, \`agent_names\`, \`tools\`, and \`sample_trace_ids\` to size the failure surface.
+2. Use \`traces.queryTraces({ filters: { has_errors: true }, limit })\` to pull error-bearing traces. Combine with \`traces.countTraces\` to see what fraction of the dataset failed.
+3. For each candidate failure cluster, use \`traces.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 \`llmQuery\` 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.
+
+OBSERVABILITY rules:
+- Each non-final turn must emit at least one \`console.log\` for evidence.
+- Reuse runtime variables across turns; don't recompute.`,
+	buildTools: (store) => buildTraceToolsForGroup("all", store),
+	subqueries: {
+		maxCalls: 8,
+		maxParallel: 4
+	},
+	maxTurns: 24,
+	cost: { kind: "llm" }
+};
+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",
+	actorDescription: `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. \`traces.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 \`llmQuery\` 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.). But prefer to consume upstream findings when present — the kinds 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.
+
+OBSERVABILITY rules:
+- Each non-final turn must emit at least one \`console.log\` for evidence.`,
+	buildTools: (store) => buildTraceToolsForGroup("all", store),
+	subqueries: {
+		maxCalls: 8,
+		maxParallel: 4
+	},
+	maxTurns: 30,
+	maxRuntimeChars: 12e3,
+	cost: { kind: "llm" }
+};
+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",
+	actorDescription: `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. \`traces.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 \`traces.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 \`llmQuery\` 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's resilience, not a gap. Cite the *non-recovery* version when both exist.
+
+OBSERVABILITY rules:
+- Each non-final turn must emit at least one \`console.log\` for evidence.`,
+	buildTools: (store) => buildTraceToolsForGroup("discoveryAndSearch", store),
+	subqueries: {
+		maxCalls: 5,
+		maxParallel: 4
+	},
+	maxTurns: 18,
+	cost: { kind: "llm" }
+};
+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",
+	actorDescription: `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. \`traces.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 \`traces.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 nailed down. If you can only nail one, drop it — 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 \`llmQuery\` 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 — that's the system working. Reserve poisoning for cases where the false belief shaped downstream action.
+
+OBSERVABILITY rules:
+- Each non-final turn must emit at least one \`console.log\` for evidence.`,
+	buildTools: (store) => buildTraceToolsForGroup("all", store),
+	subqueries: {
+		maxCalls: 8,
+		maxParallel: 4
+	},
+	maxTurns: 20,
+	minimumEvidenceCitations: 2,
+	cost: { kind: "llm" }
+};
+//#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/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.
+*/
+var AnalystRegistry = class {
+	analysts = /* @__PURE__ */ new Map();
+	options;
+	constructor(options = {}) {
+		this.options = options;
+	}
+	register(analyst) {
+		if (!analyst.id) throw new Error("AnalystRegistry.register: analyst.id is required");
+		if (this.analysts.has(analyst.id)) throw new Error(`AnalystRegistry.register: duplicate analyst id "${analyst.id}"`);
+		if (!analyst.version) throw new Error(`AnalystRegistry.register: analyst "${analyst.id}" must declare a version`);
+		if (analyst.cost.kind === "deterministic" && analyst.cost.settlement_timeout_ms !== void 0) throw new TypeError(`AnalystRegistry.register: deterministic analyst "${analyst.id}" cannot declare settlement_timeout_ms`);
+		if (analyst.cost.settlement_timeout_ms !== void 0) validateUsageSettlementTimeout(analyst.cost.settlement_timeout_ms);
+		this.analysts.set(analyst.id, analyst);
+	}
+	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");
+	}
+	/**
+	* 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 = {}) {
+		const correlationId = `ar_${randomUUID().slice(0, 12)}`;
+		const log = this.options.log ?? (() => {});
+		const hooks = this.options.hooks ?? {};
+		const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+		const started = Date.now();
+		const timeoutMs = validateTimeout(runOpts.timeoutMs);
+		const deadlineMs = timeoutMs === void 0 ? void 0 : started + timeoutMs;
+		const timeoutSignal = timeoutMs === void 0 ? void 0 : AbortSignal.timeout(timeoutMs);
+		const runSignal = combineAbortSignals(runOpts.signal, timeoutSignal);
+		const selected = this.selectAnalysts(runOpts);
+		const budget = runOpts.budget ?? this.options.defaultBudget;
+		validateBudgetPolicy(budget);
+		yield {
+			type: "run-started",
+			run_id: runId,
+			correlation_id: correlationId,
+			started_at: startedAt,
+			analyst_ids: selected.map((a) => a.id)
+		};
+		const summaries = [];
+		const allFindings = [];
+		let totalCost = 0;
+		let remainingUsd = budget?.totalUsd;
+		const runnableAnalysts = selected.filter((a) => this.routeInput(a, inputs).kind !== "missing");
+		const runnableCount = runnableAnalysts.length;
+		const weights = budget?.weights;
+		const totalWeight = weights && budget?.totalUsd != null && !budget.allocate && runnableCount > 0 ? runnableAnalysts.reduce((sum, analyst) => sum + analystWeight(weights, analyst.id), 0) : void 0;
+		if (totalWeight === 0) throw new Error("BudgetPolicy.weights must allocate positive weight to a runnable analyst");
+		for (const analyst of selected) {
+			const t0 = Date.now();
+			if (runSignal?.aborted) {
+				const summary = abortedBeforeStartSummary(analyst, runSignal);
+				summaries.push(summary);
+				log(`[analyst] skip ${analyst.id} — run aborted`, {
+					runId,
+					reason: summary.reason
+				});
+				yield {
+					type: "analyst-skipped",
+					summary
+				};
+				continue;
+			}
+			const input = this.routeInput(analyst, inputs);
+			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()
+				};
+				summaries.push(summary);
+				log(`[analyst] skip ${analyst.id} — missing input`, {
+					runId,
+					kind: analyst.inputKind
+				});
+				await waitForHook(hooks.onAfterAnalyze ? () => hooks.onAfterAnalyze?.({
+					analyst,
+					summary,
+					findings: [],
+					runId
+				}) : void 0, runSignal);
+				yield {
+					type: "analyst-skipped",
+					summary
+				};
+				continue;
+			}
+			const perBudget = allocateBudget(budget, {
+				analyst,
+				remainingUsd,
+				runningCount: runnableCount,
+				totalWeight
+			});
+			const usageReceipts = [];
+			const ctx = {
+				runId,
+				correlationId,
+				deadlineMs,
+				budgetUsd: perBudget,
+				costLedger: runOpts.costLedger,
+				costPhase: runOpts.costPhase,
+				chat: this.options.chat,
+				tags: runOpts.tags,
+				log: (msg, fields) => log(`[${analyst.id}] ${msg}`, {
+					runId,
+					correlationId,
+					...fields
+				}),
+				signal: runSignal,
+				priorFindings: selectPriorFindings(runOpts.priorFindings, analyst.id),
+				upstreamFindings: runOpts.chainFindings && allFindings.length > 0 ? [...allFindings] : void 0,
+				recordUsage: (receipt) => {
+					assertValidUsageReceipt(receipt);
+					usageReceipts.push(receipt);
+				}
+			};
+			await waitForHook(hooks.onBeforeAnalyze ? () => hooks.onBeforeAnalyze?.({
+				analyst,
+				ctx,
+				runId
+			}) : void 0, runSignal);
+			if (runSignal?.aborted) {
+				const summary = abortedBeforeStartSummary(analyst, runSignal, Date.now() - t0);
+				summaries.push(summary);
+				log(`[analyst] skip ${analyst.id} — run aborted`, {
+					runId,
+					reason: summary.reason
+				});
+				yield {
+					type: "analyst-skipped",
+					summary
+				};
+				continue;
+			}
+			const effectiveBudget = validateEffectiveBudget(ctx.budgetUsd, remainingUsd, analyst.id);
+			yield {
+				type: "analyst-started",
+				analyst_id: analyst.id,
+				started_at: new Date(t0).toISOString()
+			};
+			let findings;
+			let summary;
+			try {
+				if (runSignal?.aborted) throw abortReason(runSignal);
+				findings = await waitForOperation(analyst.analyze(input.value, ctx), runSignal, analystAbortGraceMs(analyst));
+				const latency = Date.now() - t0;
+				const usage = resolveUsage(analyst, usageReceipts);
+				const cost = knownCostUsd(usage);
+				totalCost += cost;
+				if (typeof remainingUsd === "number") remainingUsd = Math.max(0, remainingUsd - budgetDebit(usage, effectiveBudget));
+				allFindings.push(...findings);
+				summary = {
+					analyst_id: analyst.id,
+					status: "ok",
+					findings_count: findings.length,
+					latency_ms: latency,
+					usage
+				};
+				summaries.push(summary);
+				log(`[analyst] ok ${analyst.id}`, {
+					runId,
+					findings: findings.length,
+					latency_ms: latency,
+					cost_usd: cost,
+					cost_kind: usage.cost.kind,
+					input_tokens: usage.tokens?.input ?? null,
+					output_tokens: usage.tokens?.output ?? null
+				});
+				if (effectiveBudget !== void 0 && usage.cost.kind === "uncaptured") log(`[analyst] WARN ${analyst.id} — USD cost uncaptured; budget not reconciled`, {
+					runId,
+					budget_usd: effectiveBudget,
+					cost_captured: false
+				});
+			} catch (err) {
+				const latency = Date.now() - t0;
+				const e = err instanceof Error ? err : new Error(String(err));
+				const hookFindings = runSignal?.aborted ? [] : await hooks.onError?.({
+					analyst,
+					error: e,
+					runId
+				}) ?? [];
+				if (hookFindings.length) allFindings.push(...hookFindings);
+				const usage = resolveUsage(analyst, usageReceipts);
+				const cost = knownCostUsd(usage);
+				totalCost += cost;
+				if (typeof remainingUsd === "number") remainingUsd = Math.max(0, remainingUsd - budgetDebit(usage, effectiveBudget));
+				const summary = {
+					analyst_id: analyst.id,
+					status: "failed",
+					findings_count: hookFindings.length,
+					latency_ms: latency,
+					usage,
+					error: {
+						class: e.constructor.name,
+						message: e.message
+					}
+				};
+				summaries.push(summary);
+				log(`[analyst] FAIL ${analyst.id}`, {
+					runId,
+					error_class: e.constructor.name,
+					error: e.message,
+					cost_usd: cost,
+					cost_kind: usage.cost.kind
+				});
+				if (effectiveBudget !== void 0 && usage.cost.kind === "uncaptured") log(`[analyst] WARN ${analyst.id} — USD cost uncaptured; budget not reconciled`, {
+					runId,
+					budget_usd: effectiveBudget,
+					cost_captured: false
+				});
+				await waitForHook(hooks.onAfterAnalyze ? () => hooks.onAfterAnalyze?.({
+					analyst,
+					summary,
+					findings: hookFindings,
+					runId
+				}) : void 0, runSignal);
+				yield {
+					type: "analyst-completed",
+					summary,
+					findings: hookFindings
+				};
+				continue;
+			}
+			await waitForHook(hooks.onAfterAnalyze ? () => hooks.onAfterAnalyze?.({
+				analyst,
+				summary,
+				findings,
+				runId
+			}) : void 0, runSignal);
+			yield {
+				type: "analyst-completed",
+				summary,
+				findings
+			};
+		}
+		const result = {
+			run_id: runId,
+			correlation_id: correlationId,
+			started_at: startedAt,
+			ended_at: (/* @__PURE__ */ new Date()).toISOString(),
+			findings: allFindings,
+			per_analyst: summaries,
+			total_cost_usd: totalCost,
+			total_cost_provenance: aggregateCostProvenance(summaries.map((summary) => summary.usage?.cost ?? {
+				kind: "uncaptured",
+				usd: null
+			}))
+		};
+		await waitForHook(hooks.onComplete ? () => hooks.onComplete?.({ result }) : void 0, runSignal);
+		yield {
+			type: "run-completed",
+			result
+		};
+	}
+	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;
+	}
+	routeInput(analyst, inputs) {
+		switch (analyst.inputKind) {
+			case "trace-store": return inputs.traceStore ? {
+				kind: "present",
+				value: inputs.traceStore
+			} : { kind: "missing" };
+			case "artifact-dir": return inputs.artifactDir ? {
+				kind: "present",
+				value: inputs.artifactDir
+			} : { kind: "missing" };
+			case "run-record": return inputs.runRecord ? {
+				kind: "present",
+				value: inputs.runRecord
+			} : { kind: "missing" };
+			case "judge-input": return inputs.judgeInput ? {
+				kind: "present",
+				value: inputs.judgeInput
+			} : { kind: "missing" };
+			case "custom": {
+				const v = inputs.custom?.[analyst.id];
+				return v !== void 0 ? {
+					kind: "present",
+					value: v
+				} : { kind: "missing" };
+			}
+		}
+	}
+};
+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) {
+	if (receipts.length > 0) return mergeUsageReceipts(receipts);
+	if (analyst.cost.kind === "deterministic") return zeroUsage();
+	return {
+		calls: null,
+		tokens: null,
+		cost: {
+			kind: "uncaptured",
+			usd: null
+		}
+	};
+}
+function mergeUsageReceipts(receipts) {
+	const calls = receipts.every((receipt) => receipt.calls !== null) ? receipts.reduce((sum, receipt) => sum + (receipt.calls ?? 0), 0) : null;
+	const tokens = receipts.every((receipt) => receipt.tokens !== null) ? receipts.reduce((sum, receipt) => ({
+		input: sum.input + (receipt.tokens?.input ?? 0),
+		output: sum.output + (receipt.tokens?.output ?? 0),
+		...sum.reasoning !== void 0 || receipt.tokens?.reasoning !== void 0 ? { reasoning: (sum.reasoning ?? 0) + (receipt.tokens?.reasoning ?? 0) } : {},
+		...sum.cached !== void 0 || receipt.tokens?.cached !== void 0 ? { cached: (sum.cached ?? 0) + (receipt.tokens?.cached ?? 0) } : {},
+		...sum.cacheWrite !== void 0 || receipt.tokens?.cacheWrite !== void 0 ? { cacheWrite: (sum.cacheWrite ?? 0) + (receipt.tokens?.cacheWrite ?? 0) } : {}
+	}), {
+		input: 0,
+		output: 0
+	}) : null;
+	const cost = aggregateCostProvenance(receipts.map((receipt) => receipt.cost));
+	return {
+		calls,
+		tokens,
+		cost,
+		...cost.kind === "uncaptured" ? { knownCostUsd: receipts.reduce((sum, receipt) => sum + knownCostUsd(receipt), 0) } : {}
+	};
+}
+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) {
+	if (costs.some((cost) => cost.kind === "uncaptured")) return {
+		kind: "uncaptured",
+		usd: null
+	};
+	const usd = costs.reduce((sum, cost) => sum + (cost.usd ?? 0), 0);
+	return costs.some((cost) => cost.kind === "estimated") ? {
+		kind: "estimated",
+		usd
+	} : {
+		kind: "observed",
+		usd
+	};
+}
+function assertValidUsageReceipt(receipt) {
+	if (receipt.calls !== null && (!Number.isInteger(receipt.calls) || receipt.calls < 0)) throw new Error("AnalystContext.recordUsage: calls must be a non-negative integer or null");
+	if (receipt.tokens) {
+		assertNonNegativeFinite(receipt.tokens.input, "tokens.input");
+		assertNonNegativeFinite(receipt.tokens.output, "tokens.output");
+		if (receipt.tokens.reasoning !== void 0) {
+			assertNonNegativeFinite(receipt.tokens.reasoning, "tokens.reasoning");
+			if (receipt.tokens.reasoning > receipt.tokens.output) throw new Error("AnalystContext.recordUsage: tokens.reasoning must not exceed tokens.output");
+		}
+		if (receipt.tokens.cached !== void 0) assertNonNegativeFinite(receipt.tokens.cached, "tokens.cached");
+		if (receipt.tokens.cacheWrite !== void 0) assertNonNegativeFinite(receipt.tokens.cacheWrite, "tokens.cacheWrite");
+	}
+	if (receipt.cost.kind !== "uncaptured") assertNonNegativeFinite(receipt.cost.usd, "cost.usd");
+	else if (receipt.cost.usd !== null) throw new Error("AnalystContext.recordUsage: uncaptured cost.usd must be null");
+	if (receipt.knownCostUsd !== void 0) assertNonNegativeFinite(receipt.knownCostUsd, "knownCostUsd");
+}
+function assertNonNegativeFinite(value, field) {
+	if (!Number.isFinite(value) || value < 0) throw new Error(`AnalystContext.recordUsage: ${field} must be a non-negative finite number`);
+}
+/**
+* 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(opts = {}) {
+	const registry = new AnalystRegistry(opts.registry);
+	if (opts.includeBehavioral !== false) registry.register(behavioralAnalyst());
+	if (opts.ai) {
+		const kinds = opts.kinds ?? DEFAULT_TRACE_ANALYST_KINDS;
+		for (const spec of kinds) registry.register(createTraceAnalystKind(spec, {
+			ai: opts.ai,
+			model: opts.model
+		}));
+	}
+	return registry;
+}
+//#endregion
+export { parseFindingSubject as A, stripCodeFences as C, FindingSubjectStringSchema as D, FINDING_SUBJECT_SYNTAX as E, makeFinding as F, computeTraceMetrics as I, createChatClient as L, behavioralAnalyst as M, deriveEfficiencyFindings as N, KIND_EXPECTED_SUBJECTS as O, computeFindingId as P, createAnalystAi as R, coerceToFindingRows as S, FINDING_SUBJECT_KINDS as T, RawAnalystEvidenceSchema as _, KNOWLEDGE_GAP_KIND_SPEC as a, parseRawFinding as b, buildTraceToolsForGroup as c, renderUpstreamFindings as d, settleUsageReceiptFromCostLedger as f, RAW_FINDING_SCHEMA_PROMPT as g, ANALYST_SEVERITIES as h, KNOWLEDGE_POISONING_KIND_SPEC as i, renderFindingSubject as j, findingSubjectGrammarPromptFor as k, createTraceAnalystKind as l, structureFindings as m, AnalystRegistry as n, IMPROVEMENT_KIND_SPEC as o, validateUsageSettlementTimeout as p, DEFAULT_TRACE_ANALYST_KINDS as r, FAILURE_MODE_KIND_SPEC as s, buildDefaultAnalystRegistry as t, renderPriorFindings as u, RawAnalystFindingSchema as v, FINDING_SUBJECT_GRAMMAR_PROMPT as w, coerceJson as x, evidenceRefsFromRawFinding as y };
+
+//# sourceMappingURL=default-registry-C-vFCSEc.js.map