@tangle-network/agent-eval 0.118.3 → 0.119.1

package/dist/{chunk-VNLWDTDA.js → chunk-S5TT5R3L.js}

@@ -6,11 +6,11 @@ import {
 } from "./chunk-NJC7U437.js";
 import {
   CostLedger
-} from "./chunk-MLHRFWQK.js";
+} from "./chunk-JHOJHHU7.js";
 import {
-  TraceFileMissingError,
-  buildTraceAnalystTools
-} from "./chunk-6QIM2EAP.js";
+  buildTraceAnalystTools,
+  runTraceAnalysisLoop
+} from "./chunk-PXD6ZFNY.js";
 import {
   validateAgentProfileCell
 } from "./chunk-XJYR7XFV.js";
@@ -21,6 +21,41 @@ import {
   ValidationError
 } from "./chunk-ONWEPEDO.js";
 
+// src/analyst/ax-service.ts
+import { ai } from "@ax-llm/ax";
+var configuredModels = /* @__PURE__ */ new WeakMap();
+function createAnalystAi(config) {
+  const model = config.model.trim();
+  if (!model) throw new TypeError("createAnalystAi: model must be a non-empty string");
+  const args = {
+    name: config.provider ?? "openai",
+    apiKey: config.apiKey,
+    ...config.baseUrl ? { apiURL: config.baseUrl } : {},
+    ...config.headers ? { headers: config.headers } : {},
+    config: { model }
+  };
+  const service = ai(args);
+  configuredModels.set(service, model);
+  return service;
+}
+function getConfiguredAnalystModel(service) {
+  return configuredModels.get(service);
+}
+function resolveAnalystModel(service, override) {
+  if (override !== void 0) {
+    const model2 = override.trim();
+    if (!model2) throw new TypeError("createTraceAnalystKind: model must be a non-empty string");
+    return model2;
+  }
+  const model = getConfiguredAnalystModel(service)?.trim();
+  if (!model) {
+    throw new TypeError(
+      "createTraceAnalystKind: model is required for Ax services not created by createAnalystAi()"
+    );
+  }
+  return model;
+}
+
 // src/analyst/types.ts
 import { createHash } from "crypto";
 function computeFindingId(input) {
@@ -345,47 +380,63 @@ function coerceToFindingRows(raw) {
 // src/analyst/finding-signature.ts
 import { z as z2 } from "zod";
 var ANALYST_SEVERITIES = ["critical", "high", "medium", "low", "info"];
-var RawAnalystFindingSchema = z2.object({
+var RawAnalystEvidenceSchema = z2.object({
+  uri: z2.string().trim().min(1).max(2e3),
+  excerpt: z2.string().max(2e3).optional()
+}).strict();
+var RawAnalystFindingBaseShape = {
   severity: z2.enum(ANALYST_SEVERITIES),
   claim: z2.string().min(1).max(2e3),
-  /**
-   * Subject locus the finding is about. Validated at parse time
-   * against the documented grammar (`finding-subject.ts`). Findings
-   * with a malformed subject are rejected — they would have been
-   * silently skipped by every downstream adapter, so failing loud at
-   * parse time turns a hidden no-op into a kind-prompt audit signal.
-   *
-   * Optional because purely descriptive findings (no actionable
-   * locus) are legitimate; they just don't route through the
-   * KnowledgeAdapter / ImprovementAdapter.
-   */
-  subject: z2.string().max(400).refine((s) => parseFindingSubject(s) !== null, {
+  subject: z2.string().max(400).refine((subject) => parseFindingSubject(subject) !== null, {
     message: "subject does not match the finding-subject grammar"
   }).optional(),
-  evidence_uri: z2.string().min(1).max(2e3),
-  evidence_excerpt: z2.string().max(2e3).optional(),
   confidence: z2.number().min(0).max(1),
   rationale: z2.string().max(4e3).optional(),
   recommended_action: z2.string().max(2e3).optional()
+};
+var RawAnalystFindingSchema = z2.object({
+  ...RawAnalystFindingBaseShape,
+  evidence_uri: z2.string().min(1).max(2e3).refine((uri) => uri.trim().length > 0, { message: "evidence_uri must not be blank" }),
+  evidence_excerpt: z2.string().max(2e3).optional()
 }).strict();
-var RAW_FINDING_SCHEMA_PROMPT = `Each finding MUST be a JSON object with these fields:
-  - severity: one of "critical" | "high" | "medium" | "low" | "info"
+var CanonicalRawAnalystFindingObjectSchema = z2.object({
+  ...RawAnalystFindingBaseShape,
+  evidence: z2.array(RawAnalystEvidenceSchema).min(1)
+}).strict();
+var CanonicalRawAnalystFindingSchema = z2.preprocess(
+  normalizeLegacySingleCitation,
+  CanonicalRawAnalystFindingObjectSchema
+);
+var 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?: the routing locus this finding is about. It MUST be one of the exact subject forms listed in this kind's instructions above (e.g. \`system-prompt:<section>\`, \`agent-knowledge:wiki:<slug>\`, \`tool-doc:<tool>\`). A free phrase, a bare noun, or any form not in that list is REJECTED at parse time and the finding is discarded \u2014 omit subject entirely rather than guess a form.
-  - evidence_uri: REQUIRED, never blank. Exactly one of "span://<trace_id>/<span_id>" (trace evidence), "artifact://<relative-path>" (files), "metric://<name>" (named scalars) \u2014 ALWAYS cite a real id surfaced by the tools. If you have no citable id, do not emit the finding.
-  - evidence_excerpt?: short quote (<=2000 chars) from the cited span/artifact
-  - confidence: number 0..1 \u2014 0.9+ when backed by exact quotes, 0.6-0.8 for inferred patterns, <0.5 for speculative
-  - rationale?: one or two sentences explaining the reasoning
-  - recommended_action?: concrete change phrased as an imperative ("Add ...", "Replace ...", "Stop ...") \u2014 omit when the finding is purely descriptive
+  - 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
 
-Emit an empty array when the question has no findings to report. Do not fabricate evidence.`;
+Unknown fields are rejected. Do not emit area; the factory assigns it. Emit [] when there are no findings. Never fabricate evidence.`;
+function evidenceRefsFromRawFinding(finding) {
+  return finding.evidence.map(({ uri, excerpt }) => ({
+    kind: evidenceKindFromUri(uri),
+    uri,
+    excerpt
+  }));
+}
 function parseRawFinding(row, log) {
-  const result = RawAnalystFindingSchema.safeParse(row);
+  return parseFindingWithSchema(RawAnalystFindingSchema, row, log);
+}
+function parseCanonicalRawFinding(row, log) {
+  return parseFindingWithSchema(CanonicalRawAnalystFindingSchema, 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 = RawAnalystFindingSchema.safeParse(coerced);
+      const retry = schema.safeParse(coerced);
       if (retry.success) return retry.data;
     }
   }
@@ -398,40 +449,98 @@ function parseRawFinding(row, log) {
   });
   return null;
 }
+function normalizeLegacySingleCitation(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return value;
+  const row = value;
+  if ("evidence" in row) {
+    if (!("evidence_uri" in row) || !Array.isArray(row.evidence)) return value;
+    const { evidence, evidence_uri: uri2, evidence_excerpt: excerpt2, ...rest2 } = row;
+    let alreadyPresent = false;
+    const mergedEvidence = evidence.map((citation) => {
+      if (citation === null || typeof citation !== "object" || Array.isArray(citation) || citation.uri !== uri2) {
+        return citation;
+      }
+      alreadyPresent = true;
+      const current = citation;
+      return excerpt2 === void 0 || current.excerpt !== void 0 ? citation : { ...current, excerpt: excerpt2 };
+    });
+    return {
+      ...rest2,
+      evidence: alreadyPresent ? mergedEvidence : [...evidence, { uri: uri2, ...excerpt2 === void 0 ? {} : { excerpt: excerpt2 } }]
+    };
+  }
+  if (!("evidence_uri" in row)) return value;
+  const { evidence_uri: uri, evidence_excerpt: excerpt, ...rest } = row;
+  return {
+    ...rest,
+    evidence: [{ uri, ...excerpt === void 0 ? {} : { excerpt } }]
+  };
+}
+function toLegacyRawAnalystFinding(finding) {
+  const primaryEvidence = finding.evidence[0];
+  if (!primaryEvidence) {
+    throw new TypeError("Canonical raw analyst findings require at least one evidence citation");
+  }
+  const { evidence: _evidence, ...rest } = finding;
+  return {
+    ...rest,
+    evidence_uri: primaryEvidence.uri,
+    ...primaryEvidence.excerpt === void 0 ? {} : { evidence_excerpt: primaryEvidence.excerpt }
+  };
+}
+function applyLegacyRawFindingCallback(finding, callback, log) {
+  const callbackResult = callback(toLegacyRawAnalystFinding(finding));
+  if (callbackResult === null) return null;
+  const parsed = parseCanonicalRawFinding(callbackResult, log);
+  if (!parsed) return null;
+  const primaryEvidence = parsed.evidence[0];
+  if (!primaryEvidence) {
+    throw new TypeError("Canonical raw analyst findings require at least one evidence citation");
+  }
+  const remainingEvidence = finding.evidence.slice(1).filter((citation) => citation.uri !== primaryEvidence.uri);
+  return {
+    ...parsed,
+    evidence: [primaryEvidence, ...remainingEvidence]
+  };
+}
+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";
+}
 
 // src/analyst/structure-findings.ts
 var SYSTEM = [
   "You convert a free-form trace-analysis report into a STRICT JSON array of findings.",
   "Output ONLY the JSON array \u2014 no prose, no code fences.",
-  'Each element: {"severity":"critical|high|medium|low|info","claim":string,"evidence_uri":string,',
-  '"subject"?:string,"rationale"?:string,"recommended_action"?:string,"confidence":number(0..1)}.',
-  'evidence_uri cites the trace element the report referenced (e.g. "span://<trace>/<span>") or "report://summary".',
+  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, analystId, area) {
+function buildRows(raw, opts) {
   const rows = coerceToFindingRows(raw);
   const out = [];
   for (const row of rows) {
-    const normalized = row && typeof row === "object" && !Array.isArray(row) && !row.evidence_uri ? { ...row, evidence_uri: "report://summary" } : row;
-    const parsed = parseRawFinding(normalized);
+    const parsed = parseCanonicalRawFinding(row);
     if (!parsed) continue;
+    const callbackProcessed = opts.processRow ? applyLegacyRawFindingCallback(parsed, opts.processRow) : parsed;
+    if (!callbackProcessed) continue;
+    const processed = opts.processCanonicalRow ? opts.processCanonicalRow(callbackProcessed) : callbackProcessed;
+    if (!processed) continue;
     out.push(
       makeFinding({
-        analyst_id: analystId,
-        area,
-        subject: parsed.subject,
-        claim: parsed.claim,
-        rationale: parsed.rationale,
-        severity: parsed.severity,
-        confidence: parsed.confidence,
-        evidence_refs: [
-          {
-            kind: parsed.evidence_uri.startsWith("span://") ? "span" : "artifact",
-            uri: parsed.evidence_uri,
-            excerpt: parsed.evidence_excerpt
-          }
-        ],
-        recommended_action: parsed.recommended_action
+        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 } } : {}
       })
     );
   }
@@ -439,6 +548,9 @@ function buildRows(raw, analystId, area) {
 }
 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:
@@ -459,8 +571,9 @@ Return the findings JSON array.`;
       phase: opts.costPhase ?? "analyst.structure-findings",
       actor: "structure-findings",
       model: opts.model,
+      signal: opts.signal,
       maximumCharge: maximumChargeForLlmRequest(request, llm),
-      tags: { analystId: opts.analystId, attempt: String(attempt) },
+      tags: { ...opts.costTags, analystId: opts.analystId, attempt: String(attempt) },
       execute: (signal, callId) => callLlm(request, { ...llm, signal, idempotencyKey: callId }),
       receipt: costReceiptFromLlm,
       receiptFromError: costReceiptFromLlmError
@@ -468,7 +581,7 @@ Return the findings JSON array.`;
     if (!paid.succeeded) throw paid.error;
     const res = paid.value;
     const text = res.content.trim();
-    const findings = buildRows(text, opts.analystId, opts.area);
+    const findings = buildRows(text, opts);
     if (findings.length > 0) return { findings, outcome: "ok" };
     if (opts.report.trim().length < 200) return { findings: [], outcome: "ok" };
     user = `${user}
@@ -478,150 +591,459 @@ That produced no valid findings. The report DOES describe issues \u2014 re-extra
   return { findings: [], outcome: "extraction_failed" };
 }
 
+// src/analyst/ax-cost-service.ts
+function meterAxChatService(ai2, options) {
+  assertPositiveInteger(options.maxOutputTokens, "maxOutputTokens");
+  const source = ai2;
+  if (typeof source.chat !== "function") {
+    throw new TypeError("meterAxChatService: Ax service must implement chat()");
+  }
+  const providerChat = source.chat.bind(ai2);
+  const chat = async (request, callOptions = {}) => {
+    const boundedRequest = boundOutputTokens(request, options.maxOutputTokens);
+    const model = modelName(boundedRequest.model) || options.defaultModel || "";
+    const canTurnOffThinking = canDisableThinking(ai2, 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(ai2, {
+    get(target, property) {
+      if (property === "chat") return chat;
+      const value = Reflect.get(target, property, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    }
+  });
+}
+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 void 0;
+  }
+  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;
+  const validTotals = /* @__PURE__ */ new Set([
+    directTotal,
+    directTotal + totalCacheTokens,
+    directTotal + additionalOutputTokens,
+    directTotal + totalCacheTokens + additionalOutputTokens
+  ]);
+  if (!validTotals.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(ai2, model) {
+  const namedAi = ai2;
+  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`);
+  }
+}
+
+// src/analyst/usage-receipt.ts
+var DEFAULT_USAGE_SETTLEMENT_TIMEOUT_MS = 5e3;
+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 costUncaptured = summary.pendingCalls > 0 || receipts.some((receipt) => receipt.costUnknown);
+  const cost = costUncaptured ? { 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 } : {}
+  };
+}
+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 initial = ledger.summary(filter);
+  const waitResult = initial.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 ?? DEFAULT_USAGE_SETTLEMENT_TIMEOUT_MS;
+  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;
+}
+
 // src/analyst/kind-factory.ts
-import { AxJSRuntime, agent } from "@ax-llm/ax";
 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,
+    cost: { ...spec.cost, settlement_timeout_ms: settlementTimeoutMs },
     version,
     async analyze(store, ctx) {
-      const tools = spec.buildTools(store);
-      const maxDepth = spec.recursion?.maxDepth ?? 0;
-      const maxParallel = spec.recursion?.maxParallelSubagents ?? 2;
-      const priorContext = renderPriorFindings(ctx.priorFindings);
-      const functions = tools;
-      const actorDescription = spec.actorDescription.trim() + priorContext + "\n\n" + RAW_FINDING_SCHEMA_PROMPT + "\n\nFirst write `report`: a concise free-form prose diagnosis of what the traces show \u2014 what succeeded, what was suboptimal or failed \u2014 with concrete trace ids and numbers. THEN return the structured `findings` array (it MAY be empty when there is nothing to report). Use `final(...)` with the `{ report, findings }` payload when you are done.";
-      const ax = agent(
-        "question:string -> report:string, findings:json[]",
-        {
-          agentIdentity: {
-            name: spec.id,
-            description: spec.description
-          },
-          contextFields: ["question"],
-          runtime: new AxJSRuntime({
-            permissions: [],
-            blockDynamicImport: true,
-            allowedModules: [],
-            freezeIntrinsics: true,
-            blockShadowRealm: true,
-            preventGlobalThisExtensions: false
-          }),
-          mode: maxDepth > 0 ? "advanced" : "simple",
-          recursionOptions: maxDepth > 0 ? { maxDepth } : void 0,
+      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 ? `
+
+This 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 \u2014 what succeeded, what was suboptimal or failed \u2014 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 completed = 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,
-          maxBatchedLlmQueryConcurrency: maxParallel,
-          promptLevel: "detailed",
-          // Trace analysis depends on exact prior tool results and runtime variables.
-          contextPolicy: { preset: "full", budget: "balanced" },
-          functions,
-          actorOptions: {
-            description: actorDescription,
-            ...opts.model ? { model: opts.model } : {},
-            showThoughts: false,
-            thinkingTokenBudget: "none"
-          },
-          responderOptions: {
-            description: spec.responderDescription ?? "Pass through the actor's `report` prose verbatim, and format the `findings` array exactly as the actor produced it. Do not add, drop, or summarize entries.",
-            ...opts.model ? { model: opts.model } : {},
-            showThoughts: false
-          },
-          bubbleErrors: [TraceFileMissingError]
-        }
-      );
-      ctx.log?.(`analyst.kind ${spec.id} forward`, {
-        max_depth: maxDepth,
-        tool_count: tools.length,
-        tags: ctx.tags
-      });
-      const result = await ax.forward(opts.ai, { question: deriveQuestion(ctx, spec) });
-      const expectedSubjects = KIND_EXPECTED_SUBJECTS[spec.id];
-      const out = [];
-      const rawRows = Array.isArray(result.findings) ? result.findings : [];
-      let rejectedWrongKind = 0;
-      for (const row of rawRows) {
-        const parsed = parseRawFinding(row, ctx.log);
-        if (!parsed) continue;
-        if (expectedSubjects && parsed.subject !== void 0) {
-          const parsedSubject = parseFindingSubject(parsed.subject);
-          if (parsedSubject === null) {
-            ctx.log?.("finding rejected: subject failed to parse", {
-              kind: spec.id,
-              subject: parsed.subject
-            });
-            rejectedWrongKind += 1;
-            continue;
+          ...ctx.signal ? { signal: ctx.signal } : {}
+        });
+        const { report, findings: submittedFindings } = completed;
+        const expectedSubjects = KIND_EXPECTED_SUBJECTS[spec.id];
+        const out = [];
+        const rawRows = submittedFindings;
+        let rejectedWrongKind = 0;
+        let rejectedInsufficientEvidence = 0;
+        const processRow = (parsed) => {
+          const postProcessed = spec.postProcess ? applyLegacyRawFindingCallback(
+            parsed,
+            (row) => spec.postProcess?.(row, ctx) ?? null,
+            ctx.log
+          ) : parsed;
+          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;
+            }
           }
-          if (!expectedSubjects.includes(parsedSubject.kind)) {
-            ctx.log?.("finding rejected: subject variant not allowed for this kind", {
+          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,
-              subject_kind: parsedSubject.kind,
-              subject: parsed.subject,
-              allowed: expectedSubjects
+              required: minimumEvidenceCitations,
+              received: postProcessed.evidence.length,
+              distinct: distinctEvidenceCitations
             });
-            rejectedWrongKind += 1;
-            continue;
+            rejectedInsufficientEvidence += 1;
+            return null;
           }
+          return postProcessed;
+        };
+        for (const row of rawRows) {
+          const parsed = parseCanonicalRawFinding(row, ctx.log);
+          if (!parsed) continue;
+          const postProcessed = processRow(parsed);
+          if (!postProcessed) continue;
+          out.push(toAnalystFinding(spec, version, postProcessed));
         }
-        const postProcessed = spec.postProcess?.(parsed, ctx) ?? parsed;
-        if (!postProcessed) continue;
-        out.push(toAnalystFinding(spec, postProcessed));
-      }
-      ctx.log?.(`analyst.kind ${spec.id} done`, {
-        emitted: rawRows.length,
-        accepted: out.length,
-        rejected_wrong_subject: rejectedWrongKind
-      });
-      const report = typeof result.report === "string" ? result.report : "";
-      if (out.length === 0 && report.trim().length >= 200) {
-        if (opts.recovery) {
-          const recovered = await structureFindings({
-            report,
-            analystId: spec.id,
-            area: spec.area,
-            model: opts.recovery.model ?? opts.model ?? "",
-            baseUrl: opts.recovery.baseUrl,
-            apiKey: opts.recovery.apiKey,
-            fetchImpl: opts.recovery.fetchImpl
-          });
-          out.push(...recovered.findings);
-          ctx.log?.(`analyst.kind ${spec.id} recovery`, {
-            outcome: recovered.outcome,
-            recovered: recovered.findings.length
-          });
-        }
-        if (out.length === 0) {
-          out.push(
-            makeFinding({
-              analyst_id: spec.id,
+        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),
+              processCanonicalRow: 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 \u2014 see report.",
               rationale: report.slice(0, 1500),
               severity: "info",
               confidence: 0.3,
-              evidence_refs: [
-                { kind: "artifact", uri: "report://summary", excerpt: report.slice(0, 2e3) }
-              ],
-              metadata: { outcome: "extraction_failed" }
-            })
-          );
+              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);
       }
-      return out;
     }
   };
 }
+function rejectRemovedKindOptions(spec) {
+  const supplied = spec;
+  const migrations = [
+    ["recursion", "subqueries"],
+    ["responderDescription", "actorDescription"],
+    ["maxDepth", "subqueries"],
+    ["maxParallelSubagents", "subqueries.maxParallel"],
+    ["subagentDescription", "actorDescription"]
+  ];
+  for (const [removed, replacement] of migrations) {
+    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, raw) {
+function toAnalystFinding(spec, version, raw, metadata = {}) {
   return makeFinding({
     analyst_id: spec.id,
     area: spec.area,
@@ -630,25 +1052,11 @@ function toAnalystFinding(spec, raw) {
     rationale: raw.rationale,
     severity: raw.severity,
     confidence: raw.confidence,
-    evidence_refs: [
-      {
-        kind: evidenceKindFromUri(raw.evidence_uri),
-        uri: raw.evidence_uri,
-        excerpt: raw.evidence_excerpt
-      }
-    ],
+    evidence_refs: evidenceRefsFromRawFinding(raw),
     recommended_action: raw.recommended_action,
-    metadata: { kind_version: spec.version }
+    metadata: { kind_version: version, ...metadata }
   });
 }
-function evidenceKindFromUri(uri) {
-  if (uri.startsWith("span://")) return "span";
-  if (uri.startsWith("artifact://")) return "artifact";
-  if (uri.startsWith("metric://")) return "metric";
-  if (uri.startsWith("event://")) return "event";
-  if (uri.startsWith("finding://")) return "finding";
-  return "artifact";
-}
 function renderPriorFindings(prior) {
   if (!prior || prior.length === 0) return "";
   const MAX_ROWS = 40;
@@ -668,6 +1076,26 @@ function renderPriorFindings(prior) {
     overflow
   ].filter(Boolean).join("\n");
 }
+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 ? `
+  ... +${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()}\u2026`;
@@ -713,43 +1141,30 @@ DISCOVERY \u2192 CLUSTER \u2192 CITE protocol:
 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 cluster you can defend with evidence, emit ONE finding with:
-   - \`area\` = "failure-mode"
-   - \`subject\` = a lowercase cluster label matching the subject grammar above ("tool-call-loop", "auth-revoked-mid-run", ...)
-   - \`claim\` = one sentence stating the mode
-   - \`severity\` = "critical" when it blocks the run, "high" when the run finished degraded, "medium" when it slowed convergence
-   - \`evidence_uri\` = \`span://<trace_id>/<span_id>\` of the most representative span
-   - \`evidence_excerpt\` = the exact quote (e.g. error message, stuck tool call payload, contradictory turn output)
-   - \`confidence\` = 0.85+ when multiple traces show the same shape; 0.6-0.8 for a single-trace inference; <0.5 for speculative.
-   - \`recommended_action\` = imperative-phrased fix idea (kept short \u2014 the improvement-analyst will expand on these)
+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 \u2014 do NOT pad with low-confidence speculation.
 
-**Delegate aggressively.** The recursion budget is there to be used:
-- After your first \`getDatasetOverview\` + \`queryTraces\` calls, you should have 3-6 candidate failure clusters in mind. Spawn one \`llmQuery\` per cluster in a single batch \u2014 they investigate in parallel.
-- A sub-investigator that finds its cluster is actually two distinct modes should split again at its own level. Recursion is meant to discover sub-modes, not to do trivial drilling that the parent could do in-line.
-- Pass narrow context to each subagent: { question: 'investigate the auth-revoked-mid-run cluster', context: { trace_ids: ['abc', 'def'], suspected_root_cause: 'token refresh skipped on idle sessions' } }. Subagents need enough context to skip re-discovery but not the whole conversation.
-- Each subagent returns its findings as JSON; the parent merges them. Do NOT have subagents call \`final()\` \u2014 they return their findings list to you, and you call \`final()\` once at the top.
+**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.
-- Call \`final({ findings: [...] })\` exactly once, after you've gathered evidence for every cluster you intend to report.`;
+- Reuse runtime variables across turns; don't recompute.`;
 var 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.0.0",
+  version: "1.2.0",
   actorDescription: ACTOR_PROMPT,
   buildTools: (store) => buildTraceToolsForGroup("all", store),
-  recursion: { maxDepth: 3, maxParallelSubagents: 4 },
+  subqueries: { maxCalls: 8, maxParallel: 4 },
   maxTurns: 24,
   cost: { kind: "llm" }
 };
 
 // src/analyst/kinds/improvement.ts
 var subjectGrammar2 = findingSubjectGrammarPromptFor("improvement");
-var ACTOR_PROMPT2 = `You are a recursive-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.
+var ACTOR_PROMPT2 = `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.
 
@@ -769,36 +1184,26 @@ DISCOVERY \u2192 CANDIDATE-FIXES \u2192 COMPETE \u2192 CITE protocol:
    - **Skill / MCP / hook / subagent** \u2014 change the reusable profile component responsible for the behavior
    - **Workflow / rollout policy** \u2014 change orchestration, budget, sampling, or stopping behavior
    - **Code** \u2014 change an implementation path when profile edits cannot repair the behavior
-3. **Compete candidate fixes via subagents.** For each failure cluster, spawn one \`llmQuery\` per candidate-fix axis you want to evaluate. Each subagent's job: simulate the fix on the cited traces and report (i) likely effect, (ii) side effects, (iii) implementation cost as small/medium/large. Pass the cluster's failing trace_ids and the candidate axis as context.
-4. After subagents return, **pick the winning candidate per cluster** based on (effect / cost) and emit ONE finding. Discard the losing candidates \u2014 the output is the recommendation, not the candidate set.
-5. **Cross-reference upstream findings.** If a finding cites a prior failure-mode or knowledge-gap finding, use \`evidence_uri = "finding://<prior-finding-id>"\` (the registry supports this kind). This builds the dependency graph that lets the dashboard show "fix #X resolves failure modes A, B, C."
+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 with:
-- \`area\` = "improvement"
-- \`subject\` = one exact locus form from the subject grammar above
-- \`claim\` = one sentence stating the edit ("Add a precondition check to refuse tool X calls without arg Y")
-- \`severity\` = leverage rating: "critical" when fix resolves a critical failure mode; "high" when it resolves a high; "medium" when it's a quality-of-life win; "info" when it's a cleanup with no behavioral effect
-- \`evidence_uri\` = the failure-mode finding id this fix targets (\`finding://<id>\`) when it exists; else the most representative span
-- \`evidence_excerpt\` = a fragment showing the problem the fix targets
-- \`confidence\` = 0.85+ when the fix is mechanical and the failure mode is well-evidenced; 0.6-0.8 when the fix requires judgment; <0.5 for speculative
-- \`rationale\` = why this candidate beat its alternatives (2 sentences max)
-- \`recommended_action\` = the **literal edit**, phrased as a diff or a quoted replacement: "Replace section X with: '...'" or "Add tool with description: '...'" or "Set retry policy to max_attempts=3 with exponential backoff"
+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 \u2014 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.
-- Call \`final({ findings: [...] })\` exactly once at the top level.`;
+- Each non-final turn must emit at least one \`console.log\` for evidence.`;
 var 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.0.0",
+  version: "1.2.0",
   actorDescription: ACTOR_PROMPT2,
   buildTools: (store) => buildTraceToolsForGroup("all", store),
-  recursion: { maxDepth: 3, maxParallelSubagents: 4 },
+  subqueries: { maxCalls: 8, maxParallel: 4 },
   maxTurns: 30,
   maxRuntimeChars: 12e3,
   cost: { kind: "llm" }
@@ -825,31 +1230,22 @@ DISCOVERY \u2192 ATTRIBUTE-TO-LAYER \u2192 CITE protocol:
    - 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 gap you can defend with evidence, emit ONE finding with:
-   - \`area\` = "knowledge-gap"
-   - \`subject\` = one exact locus form from the subject grammar above
-   - \`claim\` = a sentence naming the missing or stale knowledge ("wiki has no page on invoice line-item shape, agent had to re-derive it from raw spans")
-   - \`severity\` = "high" when the gap caused a failure or a clarifying question; "medium" when it caused unnecessary turns; "low" when it caused minor inefficiency
-   - \`evidence_uri\` = \`span://<trace_id>/<span_id>\` of the moment the gap surfaced (the question, the self-correction, the retrieval miss, the stale web result)
-   - \`evidence_excerpt\` = exact quote where the agent showed the gap
-   - \`confidence\` = 0.85+ when the agent itself articulated the gap; 0.6-0.8 when inferred from behavior
-   - \`recommended_action\` = phrased as a wiki edit when the locus is \`agent-knowledge:*\` ("Create wiki page \`invoice-line-items\` with claims: ..."), or as a prompt/tool-doc edit otherwise
+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.
 
-**Delegate per layer.** After your first scan, you should have candidates spread across \`agent-knowledge:*\`, \`websearch:outdated\`, \`tool-doc:*\`, \`system-prompt:*\`, and \`memory:*\`. Spawn one \`llmQuery\` per layer in parallel \u2014 each subagent runs a focused detection (e.g. the \`agent-knowledge\` subagent looks for both missing-pages AND stale-pages; the \`websearch\` subagent looks specifically for date staleness signals; the \`tool-doc\` subagent looks for tool-call argument errors a fuller description would have prevented). Subagents return findings; you merge and emit one \`final({ findings })\` at the top.
+**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 \u2014 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.
-- Call \`final({ findings: [...] })\` exactly once at the top level.`;
+- Each non-final turn must emit at least one \`console.log\` for evidence.`;
 var KNOWLEDGE_GAP_KIND_SPEC = {
   id: "knowledge-gap",
   description: "Identifies missing or stale pieces of knowledge \u2014 primarily against the agent-knowledge wiki \u2014 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.0.0",
+  version: "1.2.0",
   actorDescription: ACTOR_PROMPT3,
   buildTools: (store) => buildTraceToolsForGroup("discoveryAndSearch", store),
-  recursion: { maxDepth: 2, maxParallelSubagents: 4 },
+  subqueries: { maxCalls: 5, maxParallel: 4 },
   maxTurns: 18,
   cost: { kind: "llm" }
 };
@@ -876,32 +1272,24 @@ DISCOVERY \u2192 DUAL-VERIFY \u2192 CITE protocol:
    - 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 \u2014 single-evidence poisoning findings are too speculative to be useful.
 
-**Delegate the dual-verify.** Use the recursion budget so each candidate poisoning gets one subagent investigating "did the agent act?" and one investigating "is the belief false?". After your first scan, fire off N parallel \`llmQuery\` pairs (one cluster per pair). Subagents return their findings; you accept only the ones where BOTH halves of the pair were confirmed.
+**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 with:
-- \`area\` = "knowledge-poisoning"
-- \`subject\` = the source of the false belief using one exact form from the subject grammar above
-- \`claim\` = one sentence: "agent believed X (from source S); evidence in trace shows X is false"
-- \`severity\` = "critical" when poisoning caused a wrong user-visible action; "high" when caught internally but wasted significant work; "medium" for inefficiency only
-- \`evidence_uri\` = \`span://<trace_id>/<span_id>\` of the action span (the moment the agent acted on the false belief)
-- \`evidence_excerpt\` = exact quote of the confident-but-wrong claim or action
-- \`confidence\` = 0.85+ when both halves are exact-quote backed; 0.6-0.8 when one half is inferred
-- \`recommended_action\` = where the source should be updated and how ("Update wiki page \`X\` claim \`Y\` to '...'", "Invalidate raw source \`Z\` and re-curate", "Replace system-prompt section X with 'tool foo now returns Y'")
+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 \u2014 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.
-- Call \`final({ findings: [...] })\` exactly once at the top level.`;
+- Each non-final turn must emit at least one \`console.log\` for evidence.`;
 var 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.0.0",
+  version: "1.2.0",
   actorDescription: ACTOR_PROMPT4,
   buildTools: (store) => buildTraceToolsForGroup("all", store),
-  recursion: { maxDepth: 2, maxParallelSubagents: 4 },
+  subqueries: { maxCalls: 8, maxParallel: 4 },
   maxTurns: 20,
+  minimumEvidenceCitations: 2,
   cost: { kind: "llm" }
 };
 
@@ -929,6 +1317,14 @@ var AnalystRegistry = class {
     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() {
@@ -963,9 +1359,13 @@ var AnalystRegistry = class {
     const hooks = this.options.hooks ?? {};
     const startedAt = (/* @__PURE__ */ new Date()).toISOString();
     const started = Date.now();
-    const deadlineMs = runOpts.timeoutMs ? started + runOpts.timeoutMs : void 0;
+    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,
@@ -977,94 +1377,173 @@ var AnalystRegistry = class {
     const allFindings = [];
     let totalCost = 0;
     let remainingUsd = budget?.totalUsd;
-    const runnableCount = selected.filter(
-      (a) => this.routeInput(a, inputs).kind !== "missing"
-    ).length;
+    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 summary2 = abortedBeforeStartSummary(analyst, runSignal);
+        summaries.push(summary2);
+        log(`[analyst] skip ${analyst.id} \u2014 run aborted`, { runId, reason: summary2.reason });
+        yield { type: "analyst-skipped", summary: summary2 };
+        continue;
+      }
       const input = this.routeInput(analyst, inputs);
       if (input.kind === "missing") {
-        const summary = {
+        const summary2 = {
           analyst_id: analyst.id,
           status: "skipped",
           reason: `missing input of kind '${analyst.inputKind}'`,
           findings_count: 0,
           latency_ms: 0,
-          cost_usd: 0
+          cost_usd: 0,
+          usage: zeroUsage()
         };
-        summaries.push(summary);
+        summaries.push(summary2);
         log(`[analyst] skip ${analyst.id} \u2014 missing input`, { runId, kind: analyst.inputKind });
-        await hooks.onAfterAnalyze?.({ analyst, summary, findings: [], runId });
-        yield { type: "analyst-skipped", summary };
+        await waitForHook(
+          hooks.onAfterAnalyze ? () => hooks.onAfterAnalyze?.({ analyst, summary: summary2, findings: [], runId }) : void 0,
+          runSignal
+        );
+        yield { type: "analyst-skipped", summary: summary2 };
         continue;
       }
       const perBudget = allocateBudget(budget, {
         analyst,
         remainingUsd,
-        runningCount: runnableCount
+        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: runOpts.signal,
-        priorFindings: selectPriorFindings(runOpts.priorFindings, analyst.id)
+        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 hooks.onBeforeAnalyze?.({ analyst, ctx, runId });
+      await waitForHook(
+        hooks.onBeforeAnalyze ? () => hooks.onBeforeAnalyze?.({ analyst, ctx, runId }) : void 0,
+        runSignal
+      );
+      if (runSignal?.aborted) {
+        const summary2 = abortedBeforeStartSummary(analyst, runSignal, Date.now() - t0);
+        summaries.push(summary2);
+        log(`[analyst] skip ${analyst.id} \u2014 run aborted`, { runId, reason: summary2.reason });
+        yield { type: "analyst-skipped", summary: summary2 };
+        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 {
-        const findings = await analyst.analyze(input.value, ctx);
+        if (runSignal?.aborted) throw abortReason(runSignal);
+        findings = await waitForOperation(
+          analyst.analyze(input.value, ctx),
+          runSignal,
+          analystAbortGraceMs(analyst)
+        );
         const latency = Date.now() - t0;
-        const cost = sumFindingCost(findings);
+        const usage = resolveUsage(analyst, findings, usageReceipts);
+        const cost = knownCostUsd(usage);
         totalCost += cost;
-        if (typeof remainingUsd === "number") remainingUsd = Math.max(0, remainingUsd - cost);
+        if (typeof remainingUsd === "number") {
+          remainingUsd = Math.max(0, remainingUsd - budgetDebit(usage, effectiveBudget));
+        }
         allFindings.push(...findings);
-        const summary = {
+        summary = {
           analyst_id: analyst.id,
           status: "ok",
           findings_count: findings.length,
           latency_ms: latency,
-          cost_usd: cost
+          cost_usd: cost,
+          usage
         };
         summaries.push(summary);
         log(`[analyst] ok ${analyst.id}`, {
           runId,
           findings: findings.length,
           latency_ms: latency,
-          cost_usd: cost
+          cost_usd: cost,
+          cost_kind: usage.cost.kind,
+          input_tokens: usage.tokens?.input ?? null,
+          output_tokens: usage.tokens?.output ?? null
         });
-        await hooks.onAfterAnalyze?.({ analyst, summary, findings, runId });
-        yield { type: "analyst-completed", summary, findings };
+        if (effectiveBudget !== void 0 && usage.cost.kind === "uncaptured") {
+          log(`[analyst] WARN ${analyst.id} \u2014 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 = await hooks.onError?.({ analyst, error: e, runId }) ?? [];
+        const hookFindings = runSignal?.aborted ? [] : await hooks.onError?.({ analyst, error: e, runId }) ?? [];
         if (hookFindings.length) allFindings.push(...hookFindings);
-        const summary = {
+        const usage = resolveUsage(analyst, hookFindings, usageReceipts);
+        const cost = knownCostUsd(usage);
+        totalCost += cost;
+        if (typeof remainingUsd === "number") {
+          remainingUsd = Math.max(0, remainingUsd - budgetDebit(usage, effectiveBudget));
+        }
+        const summary2 = {
           analyst_id: analyst.id,
           status: "failed",
           findings_count: hookFindings.length,
           latency_ms: latency,
-          cost_usd: 0,
+          cost_usd: cost,
+          usage,
           error: { class: e.constructor.name, message: e.message }
         };
-        summaries.push(summary);
+        summaries.push(summary2);
         log(`[analyst] FAIL ${analyst.id}`, {
           runId,
           error_class: e.constructor.name,
-          error: e.message
+          error: e.message,
+          cost_usd: cost,
+          cost_kind: usage.cost.kind
         });
-        await hooks.onAfterAnalyze?.({ analyst, summary, findings: hookFindings, runId });
-        yield { type: "analyst-completed", summary, findings: hookFindings };
+        if (effectiveBudget !== void 0 && usage.cost.kind === "uncaptured") {
+          log(`[analyst] WARN ${analyst.id} \u2014 USD cost uncaptured; budget not reconciled`, {
+            runId,
+            budget_usd: effectiveBudget,
+            cost_captured: false
+          });
+        }
+        await waitForHook(
+          hooks.onAfterAnalyze ? () => hooks.onAfterAnalyze?.({ analyst, summary: summary2, findings: hookFindings, runId }) : void 0,
+          runSignal
+        );
+        yield { type: "analyst-completed", summary: summary2, 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,
@@ -1073,9 +1552,15 @@ var AnalystRegistry = class {
       ended_at: (/* @__PURE__ */ new Date()).toISOString(),
       findings: allFindings,
       per_analyst: summaries,
-      total_cost_usd: totalCost
+      total_cost_usd: totalCost,
+      total_cost_provenance: aggregateCostProvenance(
+        summaries.map((summary) => summary.usage?.cost ?? { kind: "uncaptured", usd: null })
+      )
     };
-    await hooks.onComplete?.({ result });
+    await waitForHook(
+      hooks.onComplete ? () => hooks.onComplete?.({ result }) : void 0,
+      runSignal
+    );
     yield { type: "run-completed", result };
   }
   selectAnalysts(opts) {
@@ -1107,31 +1592,263 @@ var AnalystRegistry = class {
     }
   }
 };
+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;
+}
+function combineAbortSignals(caller, timeout) {
+  if (!caller) return timeout;
+  if (!timeout) return caller;
+  return AbortSignal.any([caller, timeout]);
+}
+async function waitForOperation(operation, signal, abortGraceMs) {
+  if (!signal) return operation;
+  if (signal.aborted) {
+    void 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,
+    cost_usd: 0,
+    usage: zeroUsage()
+  };
+}
+function abortReason(signal) {
+  return signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted", "AbortError");
+}
 function allocateBudget(policy, args) {
   if (!policy) return void 0;
   if (policy.allocate) {
-    return policy.allocate({
+    const allocated2 = policy.allocate({
       analyst: args.analyst,
       totalUsd: policy.totalUsd,
       remainingUsd: args.remainingUsd,
       runningCount: args.runningCount
     });
+    if (allocated2 === void 0) {
+      if (policy.totalUsd !== void 0) {
+        throw new Error(
+          `BudgetPolicy.allocate('${args.analyst.id}') cannot return undefined when totalUsd is set`
+        );
+      }
+      return void 0;
+    }
+    assertBudgetAmount(allocated2, `BudgetPolicy.allocate('${args.analyst.id}')`);
+    return args.remainingUsd === void 0 ? allocated2 : Math.min(allocated2, args.remainingUsd);
   }
   if (policy.totalUsd == null) return void 0;
-  if (policy.weights) {
-    const w = policy.weights[args.analyst.id] ?? 1;
-    const totalWeight = Math.max(1, args.runningCount);
-    return policy.totalUsd * w / totalWeight;
+  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, findings, receipts) {
+  const legacyCost = sumFindingCost(findings);
+  if (receipts.length > 0) {
+    const merged = mergeUsageReceipts(receipts);
+    return merged.cost.kind === "uncaptured" && legacyCost.captured ? { ...merged, knownCostUsd: Math.max(merged.knownCostUsd ?? 0, legacyCost.usd) } : merged;
+  }
+  if (legacyCost.captured) {
+    return {
+      calls: null,
+      tokens: null,
+      cost: { kind: "observed", usd: legacyCost.usd }
+    };
+  }
+  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`);
   }
-  return policy.totalUsd / Math.max(1, args.runningCount);
 }
 function sumFindingCost(findings) {
   let sum = 0;
+  let captured = false;
   for (const f of findings) {
     const c = f.metadata?.cost_usd;
-    if (typeof c === "number" && Number.isFinite(c)) sum += c;
+    if (c === void 0) continue;
+    if (typeof c !== "number" || !Number.isFinite(c) || c < 0) {
+      throw new Error(
+        `Analyst finding '${f.finding_id}' metadata.cost_usd must be a non-negative finite number`
+      );
+    }
+    sum += c;
+    captured = true;
   }
-  return sum;
+  return { usd: sum, captured };
 }
 function selectPriorFindings(source, analystId) {
   if (!source) return void 0;
@@ -1891,6 +2608,7 @@ function finiteOrZero(value) {
 }
 
 export {
+  createAnalystAi,
   computeFindingId,
   makeFinding,
   FINDING_SUBJECT_KINDS,
@@ -1905,12 +2623,19 @@ export {
   coerceJson,
   coerceToFindingRows,
   ANALYST_SEVERITIES,
+  RawAnalystEvidenceSchema,
   RawAnalystFindingSchema,
+  CanonicalRawAnalystFindingSchema,
   RAW_FINDING_SCHEMA_PROMPT,
+  evidenceRefsFromRawFinding,
   parseRawFinding,
+  parseCanonicalRawFinding,
   structureFindings,
+  settleUsageReceiptFromCostLedger,
+  validateUsageSettlementTimeout,
   createTraceAnalystKind,
   renderPriorFindings,
+  renderUpstreamFindings,
   buildTraceToolsForGroup,
   FAILURE_MODE_KIND_SPEC,
   IMPROVEMENT_KIND_SPEC,
@@ -1940,4 +2665,4 @@ export {
   aggregateRunScore,
   clamp012 as clamp01
 };
-//# sourceMappingURL=chunk-VNLWDTDA.js.map
+//# sourceMappingURL=chunk-S5TT5R3L.js.map