@tangle-network/agent-eval 0.120.2 → 0.120.3

package/dist/chunk-5CVUPHJ4.js

@@ -0,0 +1,2668 @@
+import {
+  callLlm,
+  costReceiptFromLlm,
+  costReceiptFromLlmError,
+  maximumChargeForLlmRequest
+} from "./chunk-NJC7U437.js";
+import {
+  CostLedger
+} from "./chunk-ZMXDQ4K7.js";
+import {
+  buildTraceAnalystTools,
+  runTraceAnalysisLoop
+} from "./chunk-PXD6ZFNY.js";
+import {
+  validateAgentProfileCell
+} from "./chunk-XJYR7XFV.js";
+import {
+  canonicalize
+} from "./chunk-VSMTAMNK.js";
+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) {
+  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();
+}
+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
+  };
+}
+
+// src/analyst/finding-subject.ts
+import { z } from "zod";
+var 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"
+];
+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;
+}
+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;
+  }
+}
+var 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>"
+};
+var 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 \u2014 anything else is rejected at parse time:",
+    ...kinds.map((kind) => `  ${FINDING_SUBJECT_SYNTAX[kind]} \u2014 ${FINDING_SUBJECT_PURPOSE[kind]}`),
+    "Runtime ids are lowercase [a-z0-9_.-]+. Topics, keys, paths, and sections are free-form and trimmed."
+  ].join("\n");
+}
+var FINDING_SUBJECT_GRAMMAR_PROMPT = renderFindingSubjectGrammar(FINDING_SUBJECT_KINDS);
+var 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"
+  ]
+};
+function findingSubjectGrammarPromptFor(kindId) {
+  const kinds = KIND_EXPECTED_SUBJECTS[kindId];
+  if (!kinds) throw new Error(`unknown analyst kind: ${kindId}`);
+  return renderFindingSubjectGrammar(kinds);
+}
+var FindingSubjectStringSchema = z.string().refine((s) => parseFindingSubject(s) !== null, {
+  message: "subject does not match the finding-subject grammar"
+});
+
+// src/analyst/parse-tolerant.ts
+function stripCodeFences(text) {
+  const t = text.trim();
+  const fence = /^```[a-zA-Z0-9]*\s*\n?([\s\S]*?)\n?```$/;
+  const m = t.match(fence);
+  return m ? m[1].trim() : t;
+}
+function dropTrailingCommas(s) {
+  return s.replace(/,(\s*[}\]])/g, "$1");
+}
+function coerceJson(text) {
+  const candidate = dropTrailingCommas(stripCodeFences(text));
+  try {
+    return JSON.parse(candidate);
+  } catch {
+    return void 0;
+  }
+}
+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 [];
+}
+
+// src/analyst/finding-signature.ts
+import { z as z2 } from "zod";
+var ANALYST_SEVERITIES = ["critical", "high", "medium", "low", "info"];
+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: z2.string().max(400).refine((subject) => parseFindingSubject(subject) !== null, {
+    message: "subject does not match the finding-subject grammar"
+  }).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 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?: 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.`;
+function evidenceRefsFromRawFinding(finding) {
+  return finding.evidence.map(({ uri, excerpt }) => ({
+    kind: evidenceKindFromUri(uri),
+    uri,
+    excerpt
+  }));
+}
+function parseRawFinding(row, log) {
+  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 = 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 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.",
+  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 = 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: 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:
+${opts.report}
+
+Return 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 res = paid.value;
+    const text = res.content.trim();
+    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}
+
+That produced no valid findings. The report DOES describe issues \u2014 re-extract them as the strict JSON array described in the system prompt. Output ONLY the array.`;
+  }
+  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
+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 ? `
+
+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,
+          ...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;
+            }
+          }
+          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 = parseCanonicalRawFinding(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),
+              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: [{ 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;
+  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, 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 }
+  });
+}
+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 ? `
+  ... +${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");
+}
+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`;
+}
+
+// src/analyst/tool-groups.ts
+var 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"])
+};
+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));
+}
+
+// src/analyst/kinds/failure-mode.ts
+var subjectGrammar = findingSubjectGrammarPromptFor("failure-mode");
+var ACTOR_PROMPT = `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.
+
+${subjectGrammar}
+
+DISCOVERY \u2192 CLUSTER \u2192 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 \u2014 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.`;
+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.2.0",
+  actorDescription: ACTOR_PROMPT,
+  buildTools: (store) => buildTraceToolsForGroup("all", store),
+  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 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.
+
+${subjectGrammar2}
+
+DISCOVERY \u2192 CANDIDATE-FIXES \u2192 COMPETE \u2192 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** \u2014 add an instruction, remove a misleading one, restructure precedence
+   - **Tool description edit** \u2014 rewrite a tool's description so the agent picks it correctly / passes valid args
+   - **New tool** \u2014 add a tool the agent kept emulating in code
+   - **RAG ingestion** \u2014 add a document or correct a stale one
+   - **Memory invalidation** \u2014 clear cached prior-run decisions that no longer apply
+   - **Scaffolding** \u2014 add a precondition check, a retry policy, a turn budget, a verification step
+   - **Output schema** \u2014 narrow the agent's output to forbid the failure shape
+   - **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. **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 \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.`;
+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.2.0",
+  actorDescription: ACTOR_PROMPT2,
+  buildTools: (store) => buildTraceToolsForGroup("all", store),
+  subqueries: { maxCalls: 8, maxParallel: 4 },
+  maxTurns: 30,
+  maxRuntimeChars: 12e3,
+  cost: { kind: "llm" }
+};
+
+// src/analyst/kinds/knowledge-gap.ts
+var subjectGrammar3 = findingSubjectGrammarPromptFor("knowledge-gap");
+var ACTOR_PROMPT3 = `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\` \u2014 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 \u2014 or an outdated/contradictory fact the agent picked up from a non-wiki source.
+
+${subjectGrammar3}
+
+DISCOVERY \u2192 ATTRIBUTE-TO-LAYER \u2192 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\u2026", "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 \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.`;
+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.2.0",
+  actorDescription: ACTOR_PROMPT3,
+  buildTools: (store) => buildTraceToolsForGroup("discoveryAndSearch", store),
+  subqueries: { maxCalls: 5, maxParallel: 4 },
+  maxTurns: 18,
+  cost: { kind: "llm" }
+};
+
+// src/analyst/kinds/knowledge-poisoning.ts
+var subjectGrammar4 = findingSubjectGrammarPromptFor("knowledge-poisoning");
+var ACTOR_PROMPT4 = `You are a knowledge-poisoning analyst for an OTLP trace dataset. Your job is to identify cases where the agent **confidently used wrong information** \u2014 not where it lacked information (that's the knowledge-gap analyst).
+
+${subjectGrammar4}
+
+DISCOVERY \u2192 DUAL-VERIFY \u2192 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 \u2014 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 \u2014 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 \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.`;
+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.2.0",
+  actorDescription: ACTOR_PROMPT4,
+  buildTools: (store) => buildTraceToolsForGroup("all", store),
+  subqueries: { maxCalls: 8, maxParallel: 4 },
+  maxTurns: 20,
+  minimumEvidenceCitations: 2,
+  cost: { kind: "llm" }
+};
+
+// src/analyst/kinds/index.ts
+var DEFAULT_TRACE_ANALYST_KINDS = [
+  FAILURE_MODE_KIND_SPEC,
+  KNOWLEDGE_GAP_KIND_SPEC,
+  KNOWLEDGE_POISONING_KIND_SPEC,
+  IMPROVEMENT_KIND_SPEC
+];
+
+// src/analyst/registry.ts
+import { randomUUID } from "crypto";
+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 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 summary2 = {
+          analyst_id: analyst.id,
+          status: "skipped",
+          reason: `missing input of kind '${analyst.inputKind}'`,
+          findings_count: 0,
+          latency_ms: 0,
+          cost_usd: 0,
+          usage: zeroUsage()
+        };
+        summaries.push(summary2);
+        log(`[analyst] skip ${analyst.id} \u2014 missing input`, { runId, kind: analyst.inputKind });
+        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,
+        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 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 {
+        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, findings, 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,
+          cost_usd: cost,
+          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} \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 = runSignal?.aborted ? [] : await hooks.onError?.({ analyst, error: e, runId }) ?? [];
+        if (hookFindings.length) allFindings.push(...hookFindings);
+        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: cost,
+          usage,
+          error: { class: e.constructor.name, message: e.message }
+        };
+        summaries.push(summary2);
+        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} \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,
+      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;
+}
+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) {
+    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;
+  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`);
+  }
+}
+function sumFindingCost(findings) {
+  let sum = 0;
+  let captured = false;
+  for (const f of findings) {
+    const c = f.metadata?.cost_usd;
+    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 { usd: sum, captured };
+}
+function selectPriorFindings(source, analystId) {
+  if (!source) return void 0;
+  if (Array.isArray(source)) {
+    const own2 = source.filter((f) => f.analyst_id === analystId);
+    return own2.length > 0 ? own2 : void 0;
+  }
+  const record = source;
+  const own = record[analystId] ?? [];
+  const wildcard = record["*"] ?? [];
+  const merged = [...own, ...wildcard];
+  return merged.length > 0 ? merged : void 0;
+}
+
+// src/analyst/steer-firewall.ts
+var OBSERVABLE_KINDS = /* @__PURE__ */ new Set([
+  "span",
+  "event",
+  "artifact"
+]);
+function isTraceObservable(finding) {
+  return finding.evidence_refs.some((ref) => OBSERVABLE_KINDS.has(ref.kind));
+}
+function isJudgeVerdict(finding) {
+  return finding.derived_from_judge === true;
+}
+function assertNoJudgeVerdict(findings, context = "steer") {
+  const leaks = findings.filter(isJudgeVerdict);
+  if (leaks.length > 0) {
+    throw new Error(
+      `${context}: a judge verdict cannot be admitted as steering input \u2014 that is the held-out judge leaking into the loop. Offending judge-derived findings: [${leaks.map((f) => f.finding_id).join(", ")}]. Steering consumes observations of behavior, never acceptance verdicts.`
+    );
+  }
+  return findings;
+}
+
+// src/analyst/policy-edit.ts
+import { createHash as createHash2 } from "crypto";
+var POLICY_EDIT_AXES = [
+  "carrier",
+  "representation",
+  "budget",
+  "sampling",
+  "output_contract",
+  "tool_contract",
+  "routing",
+  "memory",
+  "agent_profile",
+  "deployment_target"
+];
+var POLICY_EDIT_TARGET_SURFACES = [
+  "prompt",
+  "tool-contract",
+  "runtime-config",
+  "memory",
+  "agent-profile",
+  "code",
+  "deployment"
+];
+var POLICY_EDIT_CANDIDATE_RECORD_SCHEMA = "tangle.policy-edit-candidate.v1";
+var PolicyEditValidationError = class extends ValidationError {
+  path;
+  constructor(message, path = "") {
+    super(path ? `${message} (at ${path})` : message);
+    this.path = path;
+  }
+};
+var DEFAULT_MIN_SCORE = 0.7;
+var DEFAULT_MIN_EXPECTED_GAIN = 0.01;
+var POLICY_EDIT_ID = /^policy-edit:sha256:[0-9a-f]{64}$/;
+function makePolicyEdit(init) {
+  const normalized = normalizePolicyEdit({
+    schemaVersion: "policy-edit/v1",
+    ...init,
+    source: normalizeSource(init.source)
+  });
+  const edit = {
+    ...normalized,
+    editId: init.editId ?? computePolicyEditId(normalized)
+  };
+  return validatePolicyEdit(edit);
+}
+function computePolicyEditId(edit) {
+  const { editId: _editId, schemaVersion, ...material } = edit;
+  void _editId;
+  const canonical = JSON.stringify(canonicalize({ schemaVersion, ...material }));
+  return `policy-edit:sha256:${createHash2("sha256").update(canonical).digest("hex")}`;
+}
+function validatePolicyEdit(input) {
+  if (input === null || typeof input !== "object") {
+    throw new PolicyEditValidationError("expected object");
+  }
+  const obj = input;
+  expectLiteral(obj.schemaVersion, "policy-edit/v1", "schemaVersion");
+  expectString(obj.editId, "editId");
+  if (!POLICY_EDIT_ID.test(obj.editId)) {
+    throw new PolicyEditValidationError(
+      "editId must match policy-edit:sha256:<64 lowercase hex chars>",
+      "editId"
+    );
+  }
+  expectOneOf(obj.axis, POLICY_EDIT_AXES, "axis");
+  validateTarget(obj.target);
+  validateChange(obj.change);
+  expectString(obj.claim, "claim");
+  validateExpectedGain(obj.expectedGain);
+  expectConfidence(obj.confidence, "confidence");
+  expectOneOf(obj.risk, ["low", "medium", "high", "unknown"], "risk");
+  validateSource(obj.source);
+  if (obj.rationale !== void 0) expectString(obj.rationale, "rationale");
+  if (obj.validationPlan !== void 0) expectString(obj.validationPlan, "validationPlan");
+  if (obj.metadata !== void 0 && (obj.metadata === null || typeof obj.metadata !== "object")) {
+    throw new PolicyEditValidationError("expected object", "metadata");
+  }
+  const expectedId = computePolicyEditId(obj);
+  if (obj.editId !== expectedId) {
+    throw new PolicyEditValidationError("editId does not match policy edit content", "editId");
+  }
+  return obj;
+}
+function makePolicyEditCandidateRecord(edit) {
+  return validatePolicyEditCandidateRecord({
+    schema: POLICY_EDIT_CANDIDATE_RECORD_SCHEMA,
+    policyEdit: edit
+  });
+}
+function validatePolicyEditCandidateRecord(input) {
+  if (input === null || typeof input !== "object" || Array.isArray(input)) {
+    throw new PolicyEditValidationError("expected object", "candidateRecord");
+  }
+  const obj = input;
+  const keys = Object.keys(obj).sort();
+  if (keys.length !== 2 || keys[0] !== "policyEdit" || keys[1] !== "schema") {
+    throw new PolicyEditValidationError("expected exactly schema and policyEdit", "candidateRecord");
+  }
+  expectLiteral(obj.schema, POLICY_EDIT_CANDIDATE_RECORD_SCHEMA, "candidateRecord.schema");
+  const policyEdit = validatePolicyEdit(obj.policyEdit);
+  assertJsonSafe(policyEdit, "candidateRecord.policyEdit");
+  const snapshot = JSON.parse(JSON.stringify(policyEdit));
+  return {
+    schema: POLICY_EDIT_CANDIDATE_RECORD_SCHEMA,
+    policyEdit: validatePolicyEdit(snapshot)
+  };
+}
+function isPolicyEdit(input) {
+  try {
+    validatePolicyEdit(input);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function policyEditsFromFindings(findings, opts = {}) {
+  assertNoJudgeVerdict(findings, "policyEditsFromFindings");
+  const edits = [];
+  for (const finding of findings) {
+    const edit = policyEditFromFinding(finding, opts);
+    if (edit) edits.push(edit);
+  }
+  return edits;
+}
+function policyEditFromFinding(finding, opts = {}) {
+  assertNoJudgeVerdict([finding], "policyEditFromFinding");
+  if (!finding.recommended_action?.trim()) return null;
+  const expectedGain = resolveExpectedGain(finding, opts);
+  if (!expectedGain) return null;
+  const routed = routeFindingSubject(finding.subject, opts);
+  const risk = resolveRisk(finding, opts);
+  return makePolicyEdit({
+    axis: routed.axis,
+    target: routed.target,
+    change: { kind: "text", mode: "append", value: finding.recommended_action.trim() },
+    claim: finding.claim,
+    rationale: finding.rationale,
+    expectedGain,
+    confidence: finding.confidence,
+    risk,
+    validationPlan: finding.validation_plan,
+    source: {
+      findingIds: [finding.finding_id],
+      analystIds: [finding.analyst_id],
+      evidenceRefs: finding.evidence_refs,
+      derivedFromJudge: finding.derived_from_judge
+    }
+  });
+}
+function scorePolicyEditReadiness(edit, opts = {}) {
+  validatePolicyEdit(edit);
+  const minExpectedGain = opts.minExpectedGain ?? DEFAULT_MIN_EXPECTED_GAIN;
+  const evidenceScore = Math.min(1, edit.source.evidenceRefs.length / 2);
+  const confidenceScore = clamp01(edit.confidence);
+  const gainScore = clamp01(
+    Math.abs(edit.expectedGain.amount) / Math.max(minExpectedGain * 5, 1e-3)
+  );
+  const targetScore = targetSpecificityScore(edit);
+  const riskPenalty = edit.risk === "high" && opts.allowHighRisk !== true ? 0.35 : edit.risk === "unknown" ? 0.2 : 0;
+  return clamp01(
+    0.3 * evidenceScore + 0.25 * confidenceScore + 0.25 * gainScore + 0.2 * targetScore - riskPenalty
+  );
+}
+function admitPolicyEdit(edit, opts = {}) {
+  const validated = validatePolicyEdit(edit);
+  const score = scorePolicyEditReadiness(validated, opts);
+  const reasons = [];
+  const minExpectedGain = opts.minExpectedGain ?? DEFAULT_MIN_EXPECTED_GAIN;
+  const requireEvidence = opts.requireEvidence ?? true;
+  if (validated.source.derivedFromJudge) {
+    reasons.push("source is judge-derived; judge verdicts cannot steer policy edits");
+  }
+  if (requireEvidence && validated.source.evidenceRefs.length === 0) {
+    reasons.push("missing evidence refs");
+  }
+  if (Math.abs(validated.expectedGain.amount) < minExpectedGain) {
+    reasons.push(`expected gain below ${minExpectedGain}`);
+  }
+  if (validated.risk === "high" && opts.allowHighRisk !== true) {
+    reasons.push("high-risk edit requires explicit allowHighRisk");
+  }
+  if (score < (opts.minScore ?? DEFAULT_MIN_SCORE)) {
+    reasons.push(
+      `readiness score ${score.toFixed(3)} below ${(opts.minScore ?? DEFAULT_MIN_SCORE).toFixed(3)}`
+    );
+  }
+  return {
+    edit: validated,
+    decision: reasons.length === 0 ? "admit" : "reject",
+    score,
+    reasons
+  };
+}
+function applyPolicyEditToSurface(surface, edit) {
+  const validated = validatePolicyEdit(edit);
+  if (validated.change.kind === "text") return applyTextChange(surface, validated.change);
+  return applyJsonChange(surface, validated.change);
+}
+function routeFindingSubject(subject, opts) {
+  const parsed = parseFindingSubject(subject);
+  if (!parsed) {
+    return {
+      axis: opts.defaultAxis ?? "representation",
+      target: { surface: opts.defaultTargetSurface ?? "prompt" }
+    };
+  }
+  return routeParsedSubject(parsed);
+}
+function routeParsedSubject(subject) {
+  switch (subject.kind) {
+    case "system-prompt":
+      return {
+        axis: "representation",
+        target: { surface: "prompt", path: `system-prompt:${subject.section}` }
+      };
+    case "skill":
+      return {
+        axis: "agent_profile",
+        target: { surface: "agent-profile", path: `skill:${subject.name}` }
+      };
+    case "tool-doc":
+      return {
+        axis: "tool_contract",
+        target: {
+          surface: "tool-contract",
+          path: subject.aspect ? `tool-doc:${subject.tool}:${subject.aspect}` : `tool-doc:${subject.tool}`
+        }
+      };
+    case "new-tool":
+      return {
+        axis: "tool_contract",
+        target: { surface: "tool-contract", path: `new-tool:${subject.name}` }
+      };
+    case "mcp":
+      return {
+        axis: "tool_contract",
+        target: {
+          surface: "agent-profile",
+          path: subject.tool ? `mcp:${subject.server}:${subject.tool}` : `mcp:${subject.server}`
+        }
+      };
+    case "hook":
+      return {
+        axis: "agent_profile",
+        target: { surface: "agent-profile", path: `hook:${subject.name}` }
+      };
+    case "subagent":
+      return {
+        axis: "routing",
+        target: { surface: "agent-profile", path: `subagent:${subject.name}` }
+      };
+    case "workflow":
+      return {
+        axis: "routing",
+        target: { surface: "runtime-config", path: `workflow:${subject.name}` }
+      };
+    case "rollout-policy":
+      return {
+        axis: rolloutPolicyAxis(subject.field),
+        target: { surface: "runtime-config", path: `rollout-policy:${subject.field}` }
+      };
+    case "agent-profile":
+      return {
+        axis: "agent_profile",
+        target: { surface: "agent-profile", path: `agent-profile:${subject.field}` }
+      };
+    case "code":
+      return {
+        axis: "representation",
+        target: { surface: "code", path: `code:${subject.path}` }
+      };
+    case "rag":
+      return {
+        axis: "memory",
+        target: { surface: "memory", path: `rag:${subject.corpus}:${subject.docId}` }
+      };
+    case "memory":
+      return { axis: "memory", target: { surface: "memory", path: `memory:${subject.key}` } };
+    case "scaffolding":
+      return {
+        axis: "routing",
+        target: { surface: "runtime-config", path: `scaffolding:${subject.concern}` }
+      };
+    case "output-schema":
+      return {
+        axis: "output_contract",
+        target: { surface: "runtime-config", path: `output-schema:${subject.field}` }
+      };
+    case "knowledge.wiki":
+      return {
+        axis: "memory",
+        target: {
+          surface: "memory",
+          path: `agent-knowledge:wiki:${subject.slug}${subject.heading ? `#${subject.heading}` : ""}`
+        }
+      };
+    case "knowledge.claim":
+      return {
+        axis: "memory",
+        target: { surface: "memory", path: `agent-knowledge:claim:${subject.topic}` }
+      };
+    case "knowledge.raw":
+      return {
+        axis: "memory",
+        target: { surface: "memory", path: `agent-knowledge:raw:${subject.sourceId}` }
+      };
+    case "knowledge.stale":
+      return {
+        axis: "memory",
+        target: { surface: "memory", path: `agent-knowledge:stale:${subject.slug}` }
+      };
+    case "websearch.outdated":
+      return {
+        axis: "memory",
+        target: { surface: "memory", path: `websearch:outdated:${subject.topic}` }
+      };
+    case "prior-run-summary":
+      return {
+        axis: "memory",
+        target: { surface: "memory", path: `prior-run-summary:${subject.topic}` }
+      };
+    case "cluster":
+      return { axis: "representation", target: { surface: "prompt", path: subject.label } };
+  }
+}
+function rolloutPolicyAxis(field) {
+  const normalized = field.toLowerCase();
+  if (/budget|max(?:imum)?[-_. ]?(?:turns?|tokens?|cost)|timeout|deadline/.test(normalized)) {
+    return "budget";
+  }
+  if (/temperature|top[-_. ]?p|sampling|seed|shots?|parallel|concurrency/.test(normalized)) {
+    return "sampling";
+  }
+  if (/output|schema|format/.test(normalized)) return "output_contract";
+  return "routing";
+}
+function resolveExpectedGain(finding, opts) {
+  if (typeof opts.expectedGain === "function") return opts.expectedGain(finding) ?? null;
+  if (opts.expectedGain) return opts.expectedGain;
+  return readExpectedGainFromMetadata(finding.metadata);
+}
+function readExpectedGainFromMetadata(metadata) {
+  const raw = readPolicyEditMetadata(metadata)?.expectedGain ?? readPolicyEditMetadata(metadata)?.expected_gain;
+  if (!raw || typeof raw !== "object") return null;
+  const obj = raw;
+  if (typeof obj.metric !== "string" || obj.direction !== "increase" && obj.direction !== "decrease" || typeof obj.amount !== "number") {
+    return null;
+  }
+  const out = {
+    metric: obj.metric,
+    direction: obj.direction,
+    amount: obj.amount
+  };
+  if (obj.unit === "absolute" || obj.unit === "relative" || obj.unit === "percent" || obj.unit === "score") {
+    out.unit = obj.unit;
+  }
+  if (typeof obj.rationale === "string") out.rationale = obj.rationale;
+  return out;
+}
+function readPolicyEditMetadata(metadata) {
+  const raw = metadata?.policyEdit ?? metadata?.policy_edit;
+  return raw && typeof raw === "object" ? raw : null;
+}
+function resolveRisk(finding, opts) {
+  if (typeof opts.risk === "function") return opts.risk(finding);
+  if (opts.risk) return opts.risk;
+  const raw = readPolicyEditMetadata(finding.metadata)?.risk;
+  if (raw === "low" || raw === "medium" || raw === "high" || raw === "unknown") return raw;
+  if (finding.severity === "critical" || finding.severity === "high") return "medium";
+  return "low";
+}
+function applyTextChange(surface, change) {
+  if (typeof surface !== "string") {
+    throw new PolicyEditValidationError("text policy edits require a string surface", "change");
+  }
+  if (change.mode === "append") {
+    if (hasExactTextBlock(surface, change.value)) return surface;
+    return `${surface.trimEnd()}
+
+${change.value}`.trimStart();
+  }
+  if (change.mode === "prepend") {
+    if (hasExactTextBlock(surface, change.value)) return surface;
+    return `${change.value}
+
+${surface.trimStart()}`.trimEnd();
+  }
+  const find = expectNonEmpty(change.find, "change.find");
+  if (!surface.includes(find)) {
+    throw new PolicyEditValidationError("replace target not found in surface", "change.find");
+  }
+  return surface.replace(find, change.value);
+}
+function applyJsonChange(surface, change) {
+  const root = parseJsonSurface(surface);
+  const path = splitPath(change.path);
+  if (change.mode === "remove") return setJsonAtPath(root, path, void 0, "remove");
+  if (change.mode === "set") return setJsonAtPath(root, path, change.value ?? null, "set");
+  const prior = readJsonAtPath(root, path);
+  const merged = prior && typeof prior === "object" && !Array.isArray(prior) && change.value && typeof change.value === "object" && !Array.isArray(change.value) ? { ...prior, ...change.value } : change.value ?? null;
+  return setJsonAtPath(root, path, merged, "set");
+}
+function parseJsonSurface(surface) {
+  if (typeof surface === "string") {
+    try {
+      return JSON.parse(surface);
+    } catch {
+      throw new PolicyEditValidationError(
+        "json policy edits require a JSON string surface",
+        "change"
+      );
+    }
+  }
+  assertJson(surface, "surface");
+  return surface;
+}
+function readJsonAtPath(root, path) {
+  let cursor = root;
+  for (const part of path) {
+    if (!cursor || typeof cursor !== "object" || Array.isArray(cursor)) return void 0;
+    cursor = cursor[part];
+  }
+  return cursor;
+}
+function setJsonAtPath(root, path, value, mode) {
+  if (path.length === 0) {
+    if (mode === "remove") return null;
+    return value ?? null;
+  }
+  if (root === null || typeof root !== "object" || Array.isArray(root)) {
+    throw new PolicyEditValidationError("json edit root must be an object", "change.path");
+  }
+  const out = { ...root };
+  let cursor = out;
+  for (let i = 0; i < path.length - 1; i++) {
+    const key = path[i];
+    const existing = cursor[key];
+    if (mode === "remove" && (!existing || typeof existing !== "object" || Array.isArray(existing))) {
+      return out;
+    }
+    const next = existing && typeof existing === "object" && !Array.isArray(existing) ? { ...existing } : {};
+    cursor[key] = next;
+    cursor = next;
+  }
+  const leaf = path[path.length - 1];
+  if (mode === "remove") delete cursor[leaf];
+  else cursor[leaf] = value ?? null;
+  return out;
+}
+function normalizePolicyEdit(input) {
+  const out = {
+    schemaVersion: "policy-edit/v1",
+    axis: input.axis,
+    target: normalizeTarget(input.target),
+    change: normalizeChange(input.change),
+    claim: input.claim.trim(),
+    expectedGain: normalizeExpectedGain(input.expectedGain),
+    confidence: input.confidence,
+    risk: input.risk,
+    source: normalizeSource(input.source)
+  };
+  if (input.rationale?.trim()) out.rationale = input.rationale.trim();
+  if (input.validationPlan?.trim()) out.validationPlan = input.validationPlan.trim();
+  if (input.metadata) out.metadata = input.metadata;
+  return out;
+}
+function assertJsonSafe(value, path, ancestors = /* @__PURE__ */ new WeakSet()) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return;
+  if (typeof value === "number") {
+    if (Number.isFinite(value)) return;
+    throw new PolicyEditValidationError("expected finite JSON number", path);
+  }
+  if (typeof value !== "object") {
+    throw new PolicyEditValidationError("expected JSON-safe value", path);
+  }
+  if (ancestors.has(value)) {
+    throw new PolicyEditValidationError("cyclic value is not JSON-safe", path);
+  }
+  ancestors.add(value);
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      if (!(i in value)) {
+        throw new PolicyEditValidationError("sparse array is not JSON-safe", `${path}.${i}`);
+      }
+      assertJsonSafe(value[i], `${path}.${i}`, ancestors);
+    }
+  } else {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new PolicyEditValidationError("expected plain JSON object", path);
+    }
+    if (Object.getOwnPropertySymbols(value).length > 0) {
+      throw new PolicyEditValidationError("symbol keys are not JSON-safe", path);
+    }
+    for (const [key, child] of Object.entries(value)) {
+      assertJsonSafe(child, `${path}.${key}`, ancestors);
+    }
+  }
+  ancestors.delete(value);
+}
+function normalizeTarget(target) {
+  const out = { surface: target.surface };
+  if (target.path?.trim()) out.path = target.path.trim();
+  if (target.agentProfileCell)
+    out.agentProfileCell = validateAgentProfileCell(target.agentProfileCell);
+  if (target.label?.trim()) out.label = target.label.trim();
+  return out;
+}
+function normalizeChange(change) {
+  if (change.kind === "text") {
+    const out2 = {
+      kind: "text",
+      mode: change.mode,
+      value: change.value.trim()
+    };
+    if (change.find?.trim()) out2.find = change.find.trim();
+    return out2;
+  }
+  const out = {
+    kind: "json",
+    mode: change.mode,
+    path: change.path.trim()
+  };
+  if (change.value !== void 0) out.value = change.value;
+  return out;
+}
+function normalizeExpectedGain(gain) {
+  const out = {
+    metric: gain.metric.trim(),
+    direction: gain.direction,
+    amount: gain.amount
+  };
+  if (gain.unit) out.unit = gain.unit;
+  if (gain.rationale?.trim()) out.rationale = gain.rationale.trim();
+  return out;
+}
+function normalizeSource(source) {
+  const out = {
+    findingIds: uniqueSorted(source.findingIds.map((s) => s.trim()).filter(Boolean)),
+    analystIds: uniqueSorted(source.analystIds.map((s) => s.trim()).filter(Boolean)),
+    evidenceRefs: source.evidenceRefs
+  };
+  if (source.derivedFromJudge) out.derivedFromJudge = true;
+  return out;
+}
+function validateTarget(target) {
+  if (!target || typeof target !== "object")
+    throw new PolicyEditValidationError("expected object", "target");
+  const obj = target;
+  expectOneOf(obj.surface, POLICY_EDIT_TARGET_SURFACES, "target.surface");
+  if (obj.path !== void 0) expectString(obj.path, "target.path");
+  if (obj.label !== void 0) expectString(obj.label, "target.label");
+  if (obj.agentProfileCell !== void 0) validateAgentProfileCell(obj.agentProfileCell);
+}
+function validateChange(change) {
+  if (!change || typeof change !== "object")
+    throw new PolicyEditValidationError("expected object", "change");
+  const obj = change;
+  if (obj.kind !== "text" && obj.kind !== "json") {
+    throw new PolicyEditValidationError("kind must be text or json", "change.kind");
+  }
+  if (obj.kind === "text") {
+    expectOneOf(obj.mode, ["append", "prepend", "replace"], "change.mode");
+    expectString(obj.value, "change.value");
+    if (obj.mode === "replace") expectString(obj.find, "change.find");
+    return;
+  }
+  expectOneOf(obj.mode, ["set", "merge", "remove"], "change.mode");
+  expectString(obj.path, "change.path");
+  if (obj.value !== void 0) assertJson(obj.value, "change.value");
+}
+function validateExpectedGain(gain) {
+  if (!gain || typeof gain !== "object")
+    throw new PolicyEditValidationError("expected object", "expectedGain");
+  const obj = gain;
+  expectString(obj.metric, "expectedGain.metric");
+  expectOneOf(obj.direction, ["increase", "decrease"], "expectedGain.direction");
+  if (!Number.isFinite(obj.amount) || obj.amount <= 0) {
+    throw new PolicyEditValidationError(
+      "amount must be a positive finite number",
+      "expectedGain.amount"
+    );
+  }
+  if (obj.unit !== void 0) {
+    expectOneOf(
+      obj.unit,
+      ["absolute", "relative", "percent", "score"],
+      "expectedGain.unit"
+    );
+  }
+  if (obj.rationale !== void 0) expectString(obj.rationale, "expectedGain.rationale");
+}
+function validateSource(source) {
+  if (!source || typeof source !== "object")
+    throw new PolicyEditValidationError("expected object", "source");
+  const obj = source;
+  expectNonEmptyStringArray(obj.findingIds, "source.findingIds");
+  expectNonEmptyStringArray(obj.analystIds, "source.analystIds");
+  if (!Array.isArray(obj.evidenceRefs)) {
+    throw new PolicyEditValidationError("expected array", "source.evidenceRefs");
+  }
+  for (const [i, ref] of obj.evidenceRefs.entries())
+    validateEvidenceRef(ref, `source.evidenceRefs.${i}`);
+  if (obj.derivedFromJudge !== void 0 && typeof obj.derivedFromJudge !== "boolean") {
+    throw new PolicyEditValidationError("expected boolean", "source.derivedFromJudge");
+  }
+}
+function validateEvidenceRef(ref, path) {
+  if (!ref || typeof ref !== "object") throw new PolicyEditValidationError("expected object", path);
+  const obj = ref;
+  expectOneOf(obj.kind, ["span", "event", "artifact", "finding", "metric"], `${path}.kind`);
+  expectString(obj.uri, `${path}.uri`);
+  if (obj.excerpt !== void 0) expectString(obj.excerpt, `${path}.excerpt`);
+}
+function assertJson(value, path) {
+  if (value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value)) {
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const [i, item] of value.entries()) assertJson(item, `${path}.${i}`);
+    return;
+  }
+  if (typeof value === "object") {
+    for (const [key, item] of Object.entries(value)) {
+      if (!key) throw new PolicyEditValidationError("empty object key", path);
+      assertJson(item, `${path}.${key}`);
+    }
+    return;
+  }
+  throw new PolicyEditValidationError("expected JSON-compatible value", path);
+}
+function targetSpecificityScore(edit) {
+  let score = 0.4;
+  if (edit.target.path) score += 0.25;
+  if (edit.target.agentProfileCell) score += 0.15;
+  if (edit.change.kind === "json" || edit.change.mode === "replace") score += 0.2;
+  else if (edit.change.value.length > 0) score += 0.1;
+  return clamp01(score);
+}
+function splitPath(path) {
+  const parts = path.split(".").map((p) => p.trim()).filter(Boolean);
+  if (parts.length === 0)
+    throw new PolicyEditValidationError("path must not be empty", "change.path");
+  return parts;
+}
+function expectLiteral(value, expected, path) {
+  if (value !== expected) throw new PolicyEditValidationError(`expected ${expected}`, path);
+}
+function expectString(value, path) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new PolicyEditValidationError("expected non-empty string", path);
+  }
+}
+function expectNonEmpty(value, path) {
+  expectString(value, path);
+  return value;
+}
+function expectConfidence(value, path) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+    throw new PolicyEditValidationError("expected finite number in [0,1]", path);
+  }
+}
+function hasExactTextBlock(surface, value) {
+  const needle = normalizeTextBlock(value);
+  const normalizedSurface = surface.replace(/\r\n/g, "\n");
+  return [...normalizedSurface.split(/\n{2,}/), ...normalizedSurface.split("\n")].some(
+    (block) => normalizeTextBlock(block) === needle
+  );
+}
+function normalizeTextBlock(value) {
+  return value.replace(/\r\n/g, "\n").trim();
+}
+function expectOneOf(value, allowed, path) {
+  if (typeof value !== "string" || !allowed.includes(value)) {
+    throw new PolicyEditValidationError(`expected one of ${allowed.join(", ")}`, path);
+  }
+}
+function expectStringArray(value, path) {
+  if (!Array.isArray(value)) throw new PolicyEditValidationError("expected array", path);
+  for (const [i, item] of value.entries()) expectString(item, `${path}.${i}`);
+}
+function expectNonEmptyStringArray(value, path) {
+  expectStringArray(value, path);
+  if (value.length === 0) throw new PolicyEditValidationError("expected non-empty array", path);
+}
+function uniqueSorted(values) {
+  return [...new Set(values)].sort();
+}
+function clamp01(n) {
+  if (!Number.isFinite(n)) return 0;
+  if (n < 0) return 0;
+  if (n > 1) return 1;
+  return n;
+}
+
+// src/run-score.ts
+var DEFAULT_RUN_SCORE_WEIGHTS = {
+  success: 4,
+  goalProgress: 2,
+  repoGroundedness: 1.5,
+  driftPenalty: -1.5,
+  toolUseQuality: 1,
+  patchQuality: 1.25,
+  testReality: 1.5,
+  finalGate: 3,
+  reviewerBlockers: -2,
+  costUsd: -0.2,
+  wallSeconds: -0.1
+};
+function aggregateRunScore(score, weights = {}) {
+  const w = { ...DEFAULT_RUN_SCORE_WEIGHTS, ...weights };
+  return w.success * clamp012(score.success) + w.goalProgress * clamp012(score.goalProgress) + w.repoGroundedness * clamp012(score.repoGroundedness) + w.driftPenalty * clamp012(score.driftPenalty) + w.toolUseQuality * clamp012(score.toolUseQuality) + w.patchQuality * clamp012(score.patchQuality) + w.testReality * clamp012(score.testReality) + w.finalGate * clamp012(score.finalGate) + w.reviewerBlockers * clamp012(score.reviewerBlockers) + w.costUsd * Math.max(0, finiteOrZero(score.costUsd)) + w.wallSeconds * Math.max(0, finiteOrZero(score.wallSeconds) / 60);
+}
+function clamp012(value) {
+  if (!Number.isFinite(value)) return 0;
+  return Math.max(0, Math.min(1, value));
+}
+function finiteOrZero(value) {
+  return Number.isFinite(value) ? value : 0;
+}
+
+export {
+  createAnalystAi,
+  computeFindingId,
+  makeFinding,
+  FINDING_SUBJECT_KINDS,
+  parseFindingSubject,
+  renderFindingSubject,
+  FINDING_SUBJECT_SYNTAX,
+  FINDING_SUBJECT_GRAMMAR_PROMPT,
+  KIND_EXPECTED_SUBJECTS,
+  findingSubjectGrammarPromptFor,
+  FindingSubjectStringSchema,
+  stripCodeFences,
+  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,
+  KNOWLEDGE_GAP_KIND_SPEC,
+  KNOWLEDGE_POISONING_KIND_SPEC,
+  DEFAULT_TRACE_ANALYST_KINDS,
+  AnalystRegistry,
+  isTraceObservable,
+  isJudgeVerdict,
+  assertNoJudgeVerdict,
+  POLICY_EDIT_AXES,
+  POLICY_EDIT_TARGET_SURFACES,
+  POLICY_EDIT_CANDIDATE_RECORD_SCHEMA,
+  PolicyEditValidationError,
+  makePolicyEdit,
+  computePolicyEditId,
+  validatePolicyEdit,
+  makePolicyEditCandidateRecord,
+  validatePolicyEditCandidateRecord,
+  isPolicyEdit,
+  policyEditsFromFindings,
+  policyEditFromFinding,
+  scorePolicyEditReadiness,
+  admitPolicyEdit,
+  applyPolicyEditToSurface,
+  DEFAULT_RUN_SCORE_WEIGHTS,
+  aggregateRunScore,
+  clamp012 as clamp01
+};
+//# sourceMappingURL=chunk-5CVUPHJ4.js.map