@tangle-network/agent-eval 0.120.2 → 0.120.3

package/dist/analyst/index.d.ts

@@ -0,0 +1,3111 @@
+import { TCloud } from '@tangle-network/tcloud';
+import { AxAIArgs, AxAIService, AxFunction } from '@ax-llm/ax';
+import { z } from 'zod';
+
+/**
+ * Validator-output verdict — substrate primitive for "did this output pass,
+ * and how well?"
+ *
+ * Used by:
+ *   - `@tangle-network/agent-eval/matrix` — verdict per cell in the cartesian.
+ *   - `@tangle-network/agent-runtime` — Validator<Output, Verdict = DefaultVerdict>.
+ *     Runtime keeps `Validator` because it's coupled to runtime-shaped
+ *     `ValidationCtx` (iteration, signal, traceEmitter); the verdict TYPE
+ *     itself is a substrate concept and lives here.
+ *
+ * Repo layering: agent-eval is the substrate (no upward deps). Both
+ * agent-runtime and agent-knowledge consume this type FROM agent-eval —
+ * never the other way around. See CLAUDE.md "Repo layering" for the rule.
+ */
+/**
+ * Minimal verdict shape — `valid` + `score` are required; `scores` +
+ * `notes` are optional surface. Validators that need richer shapes
+ * parameterise `Validator<Output, MyVerdict>` with their own type.
+ *
+ * Need structured extras? Extend DefaultVerdict with typed fields — never
+ * serialize extras into `notes`.
+ */
+interface DefaultVerdict {
+    /** Whether the output meets the validator's pass criteria. */
+    valid: boolean;
+    /** Aggregate score in [0, 1]. Drivers use this for winner selection. */
+    score: number;
+    /** Per-dimension scores. Free-form; weighted into `score` by the validator. */
+    scores?: Record<string, number>;
+    /** Human-readable rationale; surfaces in trace + final-result `winner.verdict`. */
+    notes?: string;
+}
+
+/**
+ * Multi-layer verifier — ordered pipeline of verification layers.
+ *
+ * Different contract from {@link JudgeRunner} (which runs parallel
+ * specs against a sandbox). MultiLayerVerifier is a DAG of layers
+ * (install → typecheck → build → lint → serve → semantic → …) with
+ * dependency-based skip, per-layer findings, soft-fail semantics, and
+ * an aggregated `blendedScore` across all passed layers.
+ *
+ * Use when you want:
+ *   - ordered stages where a failing upstream stage skips downstream ones
+ *   - each stage produces rich `findings` (severity + message + evidence)
+ *   - a single composite score across stages with per-stage weights
+ *   - soft-fail stages whose failure doesn't abort the pipeline
+ *
+ * Use {@link JudgeRunner} when you want:
+ *   - N independent judges running in parallel against the same artifact
+ *   - no inter-judge dependencies
+ *   - boolean `passed` per judge + overall
+ *
+ * Both primitives compose — JudgeRunner can be invoked as a single
+ * layer inside a MultiLayerVerifier if that suits the caller.
+ */
+
+type LayerStatus = 'pass' | 'fail' | 'skipped' | 'error' | 'timeout';
+type Severity = 'critical' | 'major' | 'minor' | 'info';
+interface Finding {
+    severity: Severity;
+    message: string;
+    evidence?: string;
+    /** Optional layer name the finding belongs to (set by the verifier if omitted). */
+    layer?: string;
+    /**
+     * Free-form structured payload — used by `multiToolchainLayer` to attach
+     * `{ adapter: 'pnpm' }`, by judges to attach evidence pointers, etc.
+     * Renderers MAY interrogate; agent-eval primitives never assume shape.
+     */
+    detail?: Record<string, unknown>;
+}
+interface LayerResult {
+    layer: string;
+    status: LayerStatus;
+    /** 0..1 score, optional — layers that don't produce a numeric score omit. */
+    score?: number;
+    durationMs: number;
+    findings: Finding[];
+    /** Short human-readable summary (one line). */
+    reason?: string;
+    /**
+     * Numeric layer-level diagnostics: error counts, warning counts,
+     * cyclomatic complexity, total adapter wall-time, etc. Keyed by
+     * diagnostic name; null = "diagnostic not applicable / not measured."
+     * Renderers that know the keys can display them; ones that don't,
+     * ignore. Free-form on purpose — consumers type the value shape in
+     * their own namespace.
+     */
+    diagnostics?: Record<string, number | null>;
+    /** Any rich per-layer detail — rendered as-is by consumers that know the layer. */
+    detail?: Record<string, unknown>;
+}
+interface VerifyContext<Env = unknown> {
+    /** Per-run opaque context the caller provides. Layers destructure what they need. */
+    env: Env;
+    /** Previously-computed results from layers that already ran. */
+    prior: Record<string, LayerResult>;
+    /** Signal — if aborted, layers MUST bail within reasonable wall. */
+    signal: AbortSignal;
+}
+interface Layer<Env = unknown> {
+    name: string;
+    /** Stages that must have `status: 'pass'` before this layer runs. */
+    dependsOn?: string[];
+    /**
+     * Weight in the composite `blendedScore`. Default 1.0. Layers with weight 0
+     * contribute findings but not score.
+     */
+    weight?: number;
+    /**
+     * If true, a `fail` status contributes to `blendedScore` (as 0) instead of
+     * being dropped — use for layers whose failure is a real signal. Default:
+     * fail drops from numerator + denominator, matching VB's existing semantics.
+     */
+    failContributesToScore?: boolean;
+    /** Optional per-layer wall-cap in ms. Honored by the verifier (AbortSignal). */
+    capMs?: number;
+    run: (ctx: VerifyContext<Env>) => Promise<LayerResult> | LayerResult;
+}
+interface VerifyOptions<Env = unknown> {
+    env: Env;
+    /**
+     * Overall wall cap. Default: sum of layer capMs, or Infinity if any layer
+     * omits a cap. The verifier short-circuits remaining layers on overall cap.
+     */
+    overallCapMs?: number;
+    /** Called with each layer result as it completes. */
+    onLayer?: (result: LayerResult) => void;
+}
+/** Extends the substrate verdict spine: `valid` = `allPass` and `score` =
+ *  `blendedScore` — derived where the report is aggregated, so spine
+ *  consumers (drivers, gates) read this report without an adapter. */
+interface VerificationReport extends DefaultVerdict {
+    layers: LayerResult[];
+    passCount: number;
+    failCount: number;
+    skippedCount: number;
+    errorCount: number;
+    /** True iff at least one scored layer ran AND every scored layer passed. */
+    allPass: boolean;
+    /**
+     * Weighted mean of `score` across contributing layers. 0 when no layers
+     * contributed. See {@link Layer.failContributesToScore} for fail semantics.
+     */
+    blendedScore: number;
+    durationMs: number;
+    startedAt: string;
+    finishedAt: string;
+}
+/**
+ * Ordered DAG of verification layers with dependency-based skipping, per-layer findings, soft-fail semantics, and a blended composite score across all passed layers.
+ */
+declare class MultiLayerVerifier<Env = unknown> {
+    private readonly layers;
+    constructor(layers: Layer<Env>[]);
+    run(opts: VerifyOptions<Env>): Promise<VerificationReport>;
+}
+
+interface RunScore {
+    success: number;
+    goalProgress: number;
+    repoGroundedness: number;
+    driftPenalty: number;
+    toolUseQuality: number;
+    patchQuality: number;
+    testReality: number;
+    finalGate: number;
+    reviewerBlockers: number;
+    costUsd: number;
+    wallSeconds: number;
+    notes?: string[];
+}
+interface RunScoreWeights {
+    success: number;
+    goalProgress: number;
+    repoGroundedness: number;
+    driftPenalty: number;
+    toolUseQuality: number;
+    patchQuality: number;
+    testReality: number;
+    finalGate: number;
+    reviewerBlockers: number;
+    costUsd: number;
+    wallSeconds: number;
+}
+
+/**
+ * Error taxonomy for `@tangle-network/agent-eval`.
+ *
+ * Every error this package throws as part of its *public contract* extends
+ * `AgentEvalError`. Consumers can pattern-match by `instanceof <Subclass>` or
+ * by the stable string `code` carried on the base class.
+ *
+ * The codes are stable across minor versions; new codes can be added, but
+ * existing codes never change meaning. New subclasses are non-breaking.
+ *
+ * Internal invariant guards (`throw new Error('this should never happen')`)
+ * remain plain `Error`s on purpose — they're programmer-mistake assertions,
+ * not consumer-catchable contract failures.
+ */
+type AgentEvalErrorCode = 'validation' | 'not_found' | 'config' | 'capture_integrity' | 'judge' | 'verification' | 'replay' | 'backend_integrity' | 'profile_matrix';
+/**
+ * Base class for every contract error this package throws — carries the stable
+ * string `code` taxonomy so consumers can `instanceof`-match or switch on `code`.
+ */
+declare class AgentEvalError extends Error {
+    /** Stable string code. Survives minification; safe to switch on. */
+    readonly code: AgentEvalErrorCode;
+    constructor(code: AgentEvalErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Caller passed invalid arguments (out of range, mutually-exclusive options, bad shape). */
+declare class ValidationError extends AgentEvalError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+
+type AgentProfileCellSchemaVersion = 'agent-profile-cell/v1';
+type AgentProfileJson = string | number | boolean | null | AgentProfileJson[] | {
+    [key: string]: AgentProfileJson;
+};
+type AgentProfileDimensionValue = string | number | boolean | null;
+interface AgentProfileSource {
+    /** Runtime/profile contract being fingerprinted, e.g. `agent-interface-profile`. */
+    kind: string;
+    /** sha256 over the canonical source profile object. */
+    hash: string;
+}
+interface AgentProfileHarness {
+    id: string;
+    version?: string;
+    hash?: string;
+}
+interface AgentProfileCell {
+    schemaVersion: AgentProfileCellSchemaVersion;
+    cellId: string;
+    profileId: string;
+    sourceProfile: AgentProfileSource;
+    harness?: AgentProfileHarness;
+    model?: string;
+    promptHash?: string;
+    dimensions?: Record<string, AgentProfileDimensionValue>;
+}
+
+type RunStatus = 'running' | 'completed' | 'failed' | 'aborted';
+interface BudgetSpec {
+    tokens?: number;
+    wallMs?: number;
+    calls?: number;
+    usd?: number;
+}
+interface RunOutcome$1 {
+    score?: number;
+    pass?: boolean;
+    failureClass?: FailureClass;
+    notes?: string;
+}
+/**
+ * Layer — optional classification in a nested build workflow.
+ * `builder`: the meta-agent editing a project (e.g. agent-builder Forge chat).
+ * `app-build`: sandbox harness that compiled + tested the generated scaffold.
+ * `app-runtime`: a run of the generated agent against a domain scenario.
+ * `meta`: any meta-eval (judge replay, correlation analysis).
+ */
+type RunLayer = 'builder' | 'app-build' | 'app-runtime' | 'meta' | 'custom';
+interface Run {
+    runId: string;
+    /**
+     * Stable identifier of the scenario being executed.
+     *
+     * Always populated on the persisted Run — but `TraceEmitter.startRun` accepts
+     * input WITHOUT this field, substituting a sensible default
+     * (`run.layer ?? run.tags?.['kind'] ?? 'runtime'`) when the caller has no
+     * curated scenario to anchor to (runtime / operator / meta-eval runs). This
+     * keeps the persisted shape unambiguous for downstream filters + aggregations
+     * while removing the boilerplate of inventing placeholder ids at the call site.
+     */
+    scenarioId: string;
+    variantId?: string;
+    datasetVersion?: string;
+    /** Git SHA of agent code at run time. */
+    codeSha?: string;
+    /** Hash of the prompt template + any system prompt. */
+    promptSha?: string;
+    /** Model id + date + system-prompt hash, concatenated. */
+    modelFingerprint?: string;
+    seed?: number;
+    /** Arbitrary environment markers (shell, docker version, tz). */
+    envFingerprint?: Record<string, string>;
+    /** Version of the redaction rules applied to this run. */
+    redactionVersion?: string;
+    /** Parent run in a nested build workflow. A builder run's children are
+     *  app-build runs; those children are app-runtime runs. */
+    parentRunId?: string;
+    /** Stable project identifier — groups runs across chats + sessions. */
+    projectId?: string;
+    /** Chat/conversation identifier within a project. */
+    chatId?: string;
+    /** Layer classification — hint for aggregation; not enforced. */
+    layer?: RunLayer;
+    startedAt: number;
+    endedAt?: number;
+    status: RunStatus;
+    outcome?: RunOutcome$1;
+    budget?: BudgetSpec;
+    /** Free-form labels for downstream grouping. */
+    tags?: Record<string, string>;
+}
+type SpanKind = 'agent' | 'llm' | 'tool' | 'retrieval' | 'judge' | 'sandbox' | 'custom';
+type SpanStatus = 'ok' | 'error';
+interface SpanBase {
+    spanId: string;
+    parentSpanId?: string;
+    runId: string;
+    kind: SpanKind;
+    name: string;
+    startedAt: number;
+    endedAt?: number;
+    status?: SpanStatus;
+    error?: string;
+    /** Anything not covered by typed fields. Kept deliberately free-form. */
+    attributes?: Record<string, unknown>;
+}
+interface Message {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    tokens?: number;
+    /** Multi-modal content descriptors; blobs themselves live in Artifacts. */
+    images?: Array<{
+        artifactId?: string;
+        url?: string;
+        mime?: string;
+    }>;
+}
+interface LlmSpan extends SpanBase {
+    kind: 'llm';
+    model: string;
+    messages: Message[];
+    output?: string;
+    inputTokens?: number;
+    /** All generated tokens, including the reasoning subset when present. */
+    outputTokens?: number;
+    cachedTokens?: number;
+    cacheWriteTokens?: number;
+    /** Reasoning-token subset of `outputTokens`. */
+    reasoningTokens?: number;
+    costUsd?: number;
+    finishReason?: string;
+}
+interface ToolSpan extends SpanBase {
+    kind: 'tool';
+    toolName: string;
+    args: unknown;
+    /** False when the source observed the call but did not capture its arguments. */
+    argsCaptured?: boolean;
+    result?: unknown;
+    latencyMs?: number;
+}
+interface RetrievalSpan extends SpanBase {
+    kind: 'retrieval';
+    query: string;
+    hits: Array<{
+        docId: string;
+        score: number;
+        content?: string;
+    }>;
+}
+interface JudgeSpan extends SpanBase {
+    kind: 'judge';
+    judgeId: string;
+    /** Span this judgment applies to. */
+    targetSpanId: string;
+    dimension: string;
+    /** Numeric score (free-range; interpretation up to the judge). */
+    score: number;
+    rationale?: string;
+    evidence?: string;
+}
+interface SandboxSpan extends SpanBase {
+    kind: 'sandbox';
+    image?: string;
+    command?: string;
+    exitCode?: number;
+    testsTotal?: number;
+    testsPassed?: number;
+    stdoutHash?: string;
+    stderrHash?: string;
+    /** Duration in ms; the harness fills this explicitly (endedAt - startedAt may miss setup). */
+    wallMs?: number;
+}
+interface GenericSpan extends SpanBase {
+    kind: 'agent' | 'custom';
+}
+type Span = LlmSpan | ToolSpan | RetrievalSpan | JudgeSpan | SandboxSpan | GenericSpan;
+type EventKind = 'log' | 'error' | 'budget_decrement' | 'budget_breach' | 'state_mutation' | 'policy_violation' | 'redaction_applied' | 'custom';
+interface TraceEvent {
+    eventId: string;
+    runId: string;
+    spanId?: string;
+    kind: EventKind;
+    timestamp: number;
+    payload: Record<string, unknown>;
+}
+interface BudgetLedgerEntry {
+    runId: string;
+    dimension: keyof BudgetSpec;
+    limit: number;
+    consumed: number;
+    remaining: number;
+    timestamp: number;
+    breached: boolean;
+    /** Span that triggered this entry, if any. */
+    spanId?: string;
+}
+interface Artifact {
+    artifactId: string;
+    runId: string;
+    spanId?: string;
+    contentType: string;
+    sizeBytes: number;
+    /** sha256 in hex. */
+    hash: string;
+    /** External storage URL (R2, S3, filesystem path). */
+    storageUrl?: string;
+    /** Inline content for small blobs — keep under ~64KB. */
+    inlineContent?: string;
+}
+type FailureClass = 'success' | 'reasoning_error' | 'tool_selection_error' | 'tool_argument_error' | 'tool_recovery_failure' | 'hallucination' | 'instruction_following' | 'safety_refusal_miss' | 'policy_violation' | 'budget_exceeded' | 'format_drift' | 'permission_escalation' | 'pii_leak' | 'cost_overrun' | 'timeout' | 'sandbox_failure' | 'missing_user_data' | 'missing_domain_data' | 'missing_codebase_context' | 'missing_runtime_context' | 'missing_credentials' | 'missing_integration_connection' | 'missing_integration_scope' | 'integration_approval_required' | 'integration_auth_expired' | 'integration_provider_failure' | 'bad_integration_manifest' | 'unsafe_integration_write_denied' | 'stale_external_data' | 'bad_retrieval' | 'insufficient_evidence' | 'contradictory_evidence' | 'ambiguous_user_intent' | 'knowledge_readiness_blocked' | 'unknown';
+
+/**
+ * Paper-grade RunRecord schema + runtime validator.
+ *
+ * Every run that participates in a promotion gate, paper table, or
+ * researcher loop SHOULD be recorded as a `RunRecord`. The mandatory
+ * fields are exactly those the paper "Two Loops, Three Roles" requires
+ * for reproducibility: who/what/when/cost/seed/hash, plus the search vs
+ * holdout split tag and either a `searchScore` or a `holdoutScore`.
+ *
+ * This is intentionally NOT a replacement for the rich `Run` /
+ * `ProposeReviewReport` / `ScenarioResult` types already in the
+ * package. Those are runtime structures with full provenance. A
+ * `RunRecord` is the analysis-time projection — the JSON-friendly
+ * row you'd put in a parquet file or paste into a notebook.
+ *
+ * Validate at the boundary:
+ *
+ *   const rec = validateRunRecord(rawJson)         // throws on missing
+ *   const ok  = isRunRecord(rawJson)               // boolean check
+ *   const rec = parseRunRecordSafe(rawJson)        // { ok, value | error }
+ *
+ * The validator runs in pure TS — zod is intentionally NOT a
+ * dependency. Round-trip tested in `tests/run-record.test.ts`.
+ */
+
+/** Search/dev/holdout split tag. 'search' is the paper-grade alias for the
+ *  combined train+test pool that the optimizer is allowed to read. */
+type RunSplitTag = 'search' | 'dev' | 'holdout';
+interface RunTokenUsage {
+    input: number;
+    /** All generated tokens charged as output, including reasoning tokens. */
+    output: number;
+    /** Reasoning-token subset of `output`, when the provider reports it. */
+    reasoning?: number;
+    /** Prompt tokens served from a provider cache. */
+    cached?: number;
+    /** Prompt tokens written into a provider cache. */
+    cacheWrite?: number;
+}
+/**
+ * How a run's USD amount was obtained.
+ *
+ * `costUsd` remains mandatory for wire compatibility. New producers should
+ * always populate this discriminated union so a missing bill is never
+ * mistaken for an observed zero-dollar run. For `uncaptured`, `costUsd` uses
+ * the legacy `0` sentinel while this field carries the truthful null.
+ */
+type RunCostProvenance = {
+    kind: 'observed';
+    usd: number;
+} | {
+    kind: 'estimated';
+    usd: number;
+} | {
+    kind: 'uncaptured';
+    usd: null;
+};
+interface RunJudgeMetadata {
+    model: string;
+    promptVersion: string;
+    /** [0,1] confidence the judge declared. Constant judge confidence
+     *  across many runs is a fallback signal (see `canary.ts`). */
+    confidence: number;
+    /** True if the judge degraded to a fallback path (rules-only,
+     *  prior-call cache, etc.). The canary uses this to alert. */
+    fallback: boolean;
+}
+/**
+ * Per-judge / per-dimension breakdown for runs scored by an ensemble of
+ * judges over a multi-dimensional rubric.
+ *
+ * The collapsed `outcome.searchScore` / `holdoutScore` carries the
+ * composite the gate uses. The full breakdown belongs here so consumers
+ * can answer "which judge disagreed?", "which dimension dragged the
+ * composite down?", and "did half the panel fail?" without re-running.
+ *
+ * `perJudge[judgeId][dim]` is the canonical source; `perDimMean` and
+ * `composite` are convenience projections — derivable but precomputed so
+ * downstream IRR primitives (`interRaterReliability`,
+ * `corpusInterRaterAgreement`) and reporters don't pay the same
+ * aggregation twice.
+ *
+ * Fail-loud discipline: judges that errored out land in `failedJudges`
+ * by id. A missing key in `perJudge` is ambiguous (silent zero vs not
+ * run); the explicit list makes a partial-failure recorded as such.
+ */
+interface JudgeScoresRecord {
+    /** Per-judge per-dimension scores. `{ "kimi-k2.6": { helpfulness: 0.8, clarity: 0.7 }, ... }`. */
+    perJudge: Record<string, Record<string, number>>;
+    /** Per-dim mean across judges. Convenience — derivable from `perJudge`. */
+    perDimMean: Record<string, number>;
+    /** Composite mean across all dims and judges. Mirrors the score
+     *  the gate sees on `outcome.searchScore` / `holdoutScore`. */
+    composite: number;
+    /** Judges that errored or returned an unparseable verdict. Recorded
+     *  by id (e.g. `['glm-5.1']`) so a partial-failure case is explicit,
+     *  not inferred from missing keys in `perJudge`. */
+    failedJudges?: string[];
+    /** Free-form notes the judges emitted (joined across judges or
+     *  first-judge only — consumer's choice). */
+    notes?: string;
+}
+interface RunOutcome {
+    /** Score on the search/optimization split. Optional because a
+     *  holdout-only evaluation only fills `holdoutScore`. */
+    searchScore?: number;
+    /** Score on the held-out split. Optional because a search-only run
+     *  only fills `searchScore`. At least one must be present. */
+    holdoutScore?: number;
+    /** Bag of any other metric the run produced — judge dimensions,
+     *  pass/fail counters, latency stats, etc. Numeric only — keeps
+     *  reporters honest. */
+    raw: Record<string, number>;
+    /** Per-judge / per-dim breakdown. Consumers writing ensemble
+     *  judgements populate this; substrate primitives like
+     *  `interRaterReliability` and `corpusInterRaterAgreement` accept
+     *  these records as input. Optional — single-judge or scalar-only
+     *  runs leave it unset. */
+    judgeScores?: JudgeScoresRecord;
+    /** Authenticity / realness verdict — did the run build the REAL thing on the
+     *  intended infra, or fake it (see `./authenticity`)? Optional: only domains
+     *  with an authenticity config populate it. Carried in the corpus so the
+     *  flywheel / off-policy learning can optimize for real completion, not gamed
+     *  pass-rate. `score` is 0-1; `gated` is the anti-Goodhart flag — a gated run
+     *  must not count as a real success regardless of `score`. */
+    realness?: {
+        score: number;
+        gated: boolean;
+        reason?: string;
+    };
+}
+/**
+ * Mandatory paper-grade fields for a single evaluation run. Optional
+ * fields are extension points; mandatory fields throw if missing.
+ *
+ * Hash discipline:
+ *   - `promptHash` is the sha256 of the EFFECTIVE prompt sent to the
+ *     model (after any steering bundle merge).
+ *   - `configHash` is the sha256 of the effective run config (model,
+ *     temperature, tools, judges, splits). The pair (promptHash,
+ *     configHash) uniquely identifies an experiment cell.
+ *
+ * Model snapshot discipline:
+ *   - `model` MUST encode a snapshot version. Bare aliases like
+ *     `claude-sonnet-4` or `gpt-4o` are banned — they remap silently.
+ *     Use `claude-sonnet-4-6@2025-04-15` or `gpt-4o-2024-11-20`.
+ */
+interface RunRecord {
+    /** UUID for the run. */
+    runId: string;
+    /** Logical experiment grouping (a treatment vs a baseline within
+     *  the same sweep should share `experimentId`). */
+    experimentId: string;
+    /** Stable identifier for the candidate (variant) being run. The
+     *  promotion gate compares two `candidateId`s on matched items. */
+    candidateId: string;
+    /** RNG seed for the run. Always recorded — silent re-seeding is
+     *  the most common cause of non-reproducible numbers. */
+    seed: number;
+    /** Model identifier WITH snapshot version. */
+    model: string;
+    /** sha256 of the effective prompt (post-steering). */
+    promptHash: string;
+    /** sha256 of the effective config. */
+    configHash: string;
+    /** Git SHA the harness was run from. */
+    commitSha: string;
+    /** End-to-end wall-clock duration in milliseconds. */
+    wallMs: number;
+    /** Time spent queued before execution started, if known. */
+    queueMs?: number;
+    /** Total USD cost. Mandatory — runs without a cost number are
+     *  unbounded by definition and must not be admitted into the gate.
+     *  `0` is retained as the compatibility sentinel for an uncaptured amount;
+     *  inspect `costProvenance` before treating it as observed. */
+    costUsd: number;
+    /** Observed, model-priced estimate, or genuinely uncaptured USD amount.
+     *  Optional only so existing serialized RunRecords remain valid. */
+    costProvenance?: RunCostProvenance;
+    /** Token usage breakdown. */
+    tokenUsage: RunTokenUsage;
+    /** Judge-side metadata, if a judge was used. */
+    judgeMetadata?: RunJudgeMetadata;
+    /** Per-split scores + raw bag. */
+    outcome: RunOutcome;
+    /** Canonical, cross-agent failure class drawn from the shared
+     *  `FAILURE_CLASSES` taxonomy. This is the aggregation key that makes
+     *  "which failure dominates across the whole fleet" answerable in ONE
+     *  vocabulary — every agent classifies against the same enum. Producers
+     *  set it via the substrate classifier; leave unset only when the failure
+     *  genuinely can't be classified. */
+    failureClass?: FailureClass;
+    /** Free-form domain-specific failure detail, scoped UNDER `failureClass`
+     *  (e.g. failureClass='tool_recovery_failure', failureMode='forge_build_unsatisfied').
+     *  The within-agent drill-down; `failureClass` is the cross-agent key. */
+    failureMode?: string;
+    /** Which split this run was drawn from. */
+    splitTag: RunSplitTag;
+    /**
+     * Stable scenario identifier the run was scored against. Optional for
+     * backwards compatibility, but **strongly recommended**: every primitive
+     * that pairs runs by scenario (preferences, paired stats, BT tournament)
+     * keys on this. The campaign artifact populates it canonically; legacy
+     * runs without it fall back to inference from `outcome.raw.scenario_id`
+     * or `experimentId`.
+     */
+    scenarioId?: string;
+    /**
+     * Canonical identity for the agent profile cell that produced this row:
+     * profile artifact hash plus optional harness/model/prompt/reporting
+     * dimensions. Use `agentProfile.cellId` to group persona sweeps and
+     * longitudinal reports by the complete source profile, not by a loose
+     * candidate label or opaque config hash.
+     */
+    agentProfile?: AgentProfileCell;
+}
+
+/**
+ * RawProviderSink — first-class persistence for the actual HTTP-level
+ * request/response bodies of every LLM provider call.
+ *
+ * Why this is a separate sink from the structured `LlmSpan`:
+ *
+ *   - `LlmSpan` records the *intent* — model name, messages, output text,
+ *     usage. It's what dashboards read; it's NOT enough for forensics.
+ *   - When a downstream consumer reports "the verifier used the wrong route"
+ *     or "tokens look right but reasoning was missing," the only way to
+ *     answer is the raw HTTP body. Span fields can lie (a proxy can echo
+ *     a different `model` value than what actually answered); the raw
+ *     response is ground truth.
+ *
+ * Default behaviour: opt-in. Pass `rawSink` to `LlmClientOptions` (or the
+ * matrix runner / BuilderSession sets it up automatically) and every
+ * request, response, and error is recorded — including retries, with the
+ * attempt index attached so a flaky call's full event chain is recoverable.
+ *
+ * Redaction is enforced at sink time. The default redactor strips
+ * `Authorization`, `X-Api-Key`, `X-Auth-Token`, `Cookie` headers and any
+ * payload field whose key matches `apiKey | api_key | bearer | password |
+ * secret | token` (case-insensitive). Override via the sink constructor or
+ * the per-call `redactor`. The `redactedFields` array on the persisted
+ * event lets a reviewer see what was stripped without exposing the values.
+ */
+type RawProviderDirection = 'request' | 'response' | 'error';
+interface RawProviderEvent {
+    /** Stable id. Generated by the sink if omitted. */
+    eventId: string;
+    /** Trace context populated by `LlmClient` when the call is wrapped in a span. */
+    runId?: string;
+    spanId?: string;
+    /**
+     * Logical provider name. Free-form so callers can use whatever id matches
+     * their topology (`'openai'`, `'anthropic'`, `'tangle-router'`, …). When
+     * omitted, derived from `baseUrl` in `LlmClientOptions`.
+     */
+    provider: string;
+    model: string;
+    /** Endpoint path, e.g. `'/v1/chat/completions'`. */
+    endpoint: string;
+    /** Base URL used for the call (already-normalised — no trailing slash). */
+    baseUrl: string;
+    /** 0-indexed retry attempt. The first attempt is 0; a retried call gets 1, 2, … */
+    attemptIndex: number;
+    direction: RawProviderDirection;
+    /** Unix ms. */
+    timestamp: number;
+    /** Wall-clock duration of the call leg. Set on `response` and `error` events; null on `request`. */
+    durationMs?: number;
+    statusCode?: number;
+    requestHeaders?: Record<string, string>;
+    requestBody?: unknown;
+    responseHeaders?: Record<string, string>;
+    responseBody?: unknown;
+    /** Set on `direction: 'error'` events. */
+    errorMessage?: string;
+    /** Field paths the redactor stripped from this event ('header:Authorization', 'body.apiKey', …). */
+    redactedFields: string[];
+}
+interface RawProviderSinkFilter {
+    runId?: string;
+    spanId?: string;
+    direction?: RawProviderDirection;
+    attemptIndex?: number;
+}
+interface RawProviderSink {
+    record(event: RawProviderEvent): Promise<void>;
+    /** Optional listing — implementations that durably persist (file, db) should support this. */
+    list?(filter?: RawProviderSinkFilter): Promise<RawProviderEvent[]>;
+    /** Optional teardown for backed implementations. */
+    close?(): Promise<void>;
+}
+type ProviderRedactor = (event: RawProviderEvent) => RawProviderEvent;
+
+interface RunFilter {
+    scenarioId?: string;
+    variantId?: string;
+    status?: RunStatus;
+    since?: number;
+    until?: number;
+    tag?: {
+        key: string;
+        value: string;
+    };
+    parentRunId?: string;
+    projectId?: string;
+    chatId?: string;
+    layer?: RunLayer;
+}
+interface SpanFilter {
+    runId?: string;
+    parentSpanId?: string;
+    kind?: SpanKind;
+    name?: string;
+    toolName?: string;
+    judgeId?: string;
+    since?: number;
+    until?: number;
+}
+interface EventFilter {
+    runId?: string;
+    spanId?: string;
+    kind?: EventKind;
+    since?: number;
+    until?: number;
+}
+interface TraceStore {
+    appendRun(run: Run): Promise<void>;
+    updateRun(runId: string, patch: Partial<Run>): Promise<void>;
+    appendSpan(span: Span): Promise<void>;
+    updateSpan(spanId: string, patch: Partial<Span>): Promise<void>;
+    appendEvent(event: TraceEvent): Promise<void>;
+    appendArtifact(artifact: Artifact): Promise<void>;
+    appendBudgetEntry(entry: BudgetLedgerEntry): Promise<void>;
+    getRun(runId: string): Promise<Run | undefined>;
+    listRuns(filter?: RunFilter): Promise<Run[]>;
+    spans(filter?: SpanFilter): Promise<Span[]>;
+    events(filter?: EventFilter): Promise<TraceEvent[]>;
+    budget(runId: string): Promise<BudgetLedgerEntry[]>;
+    artifacts(runId: string): Promise<Artifact[]>;
+}
+
+interface RunTrace {
+    run: Run;
+    spans: Span[];
+    events: TraceEvent[];
+    artifacts: Artifact[];
+    budget: BudgetLedgerEntry[];
+}
+interface RunCriticOptions {
+    weights?: Partial<RunScoreWeights>;
+    driftPatterns?: RegExp[];
+}
+declare class RunCritic {
+    private readonly weights?;
+    private readonly driftPatterns;
+    constructor(options?: RunCriticOptions);
+    score(store: TraceStore, runId: string): Promise<RunScore>;
+    scoreTrace(trace: RunTrace): RunScore;
+    rank(score: RunScore): number;
+    private isDrift;
+}
+
+type CostChannel = 'agent' | 'judge' | 'verifier' | 'analyst' | 'driver' | (string & {});
+interface CostUsage {
+    inputTokens: number;
+    /** Includes reasoning tokens when the provider bills them as output. */
+    outputTokens: number;
+    /** Reasoning-token subset of outputTokens, when reported. */
+    reasoningTokens?: number;
+    /** Prompt tokens served from a provider cache. */
+    cachedTokens?: number;
+    /** Prompt tokens written into a provider cache. */
+    cacheWriteTokens?: number;
+}
+interface CostCallBase {
+    callId: string;
+    channel: CostChannel;
+    phase: string;
+    actor: string;
+    model: string;
+    maximumCostUsd?: number;
+    tags?: Record<string, string>;
+    timestamp: number;
+}
+interface CostReceipt extends CostCallBase, CostUsage {
+    status: 'settled';
+    costUsd: number;
+    costUnknown: boolean;
+    usageUnknown?: boolean;
+    pricing?: {
+        inputUsdPerThousand: number;
+        outputUsdPerThousand: number;
+    };
+    actualCostUsd?: number;
+    error?: string;
+}
+interface CostReceiptInput extends CostUsage {
+    model: string;
+    actualCostUsd?: number;
+    costUnknown?: boolean;
+    usageUnknown?: boolean;
+}
+type MaximumCharge = {
+    externallyEnforcedMaximumUsd: number;
+} | ({
+    model: string;
+} & CostUsage);
+interface RunPaidCallInput<T> {
+    callId?: string;
+    channel: CostChannel;
+    phase: string;
+    actor: string;
+    /** Used before a provider receipt exists and on failures without one. */
+    model?: string;
+    tags?: Record<string, string>;
+    signal?: AbortSignal;
+    /** Provider-enforced dollar maximum, or maximum priced token usage. Required when capped. */
+    maximumCharge?: MaximumCharge;
+    /** `callId` can be forwarded as the provider's idempotency key. */
+    execute(signal: AbortSignal, callId: string): Promise<T>;
+    receipt(value: T): CostReceiptInput;
+    receiptFromError?(error: Error): CostReceiptInput | undefined;
+}
+type PaidCallResult<T> = {
+    succeeded: true;
+    callId: string;
+    value: T;
+    receipt: CostReceipt;
+} | {
+    succeeded: false;
+    callId?: string;
+    error: Error;
+    receipt?: CostReceipt;
+};
+interface ChannelRollup {
+    channel: CostChannel;
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens?: number;
+    cachedTokens: number;
+    cacheWriteTokens?: number;
+    costUsd: number;
+    unpricedCalls: number;
+    unknownUsageCalls: number;
+}
+interface CostLedgerSummary {
+    totalCalls: number;
+    pendingCalls: number;
+    unresolvedCalls: number;
+    reservedCostUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    reasoningTokens?: number;
+    cachedTokens: number;
+    cacheWriteTokens?: number;
+    totalCostUsd: number;
+    byChannel: ChannelRollup[];
+    unpricedModels: string[];
+    fullyPriced: boolean;
+    usageComplete: boolean;
+    accountingComplete: boolean;
+    incompleteReasons: string[];
+}
+interface CostLedgerFilter {
+    channel?: CostChannel;
+    phase?: string;
+    tags?: Record<string, string>;
+}
+interface CostLedgerWaitOptions {
+    /** Maximum time to wait for active provider calls. Default 5 seconds. */
+    timeoutMs?: number;
+}
+/** Append-only storage. `append` must atomically reject stale revisions. */
+interface CostLedgerPersistence {
+    read(): {
+        revision: string;
+        events: string;
+    };
+    append(expectedRevision: string, event: string): string | undefined;
+}
+interface CostLedgerOptions {
+    costCeilingUsd?: number;
+    persistence?: CostLedgerPersistence;
+    /** Import already-settled receipts without admitting new paid work. */
+    receipts?: readonly CostReceipt[];
+}
+/** Run-wide paid-call admission, durable call state, receipts, and summaries. */
+declare class CostLedger {
+    private readonly records;
+    private readonly activeCallIds;
+    private readonly lateCallIds;
+    private readonly idleWaiters;
+    private completedTasks;
+    private revision;
+    private costLimitPersisted;
+    readonly costCeilingUsd?: number;
+    private readonly persistence?;
+    constructor(input?: number | CostLedgerOptions);
+    runPaidCall<T>(input: RunPaidCallInput<T>): Promise<PaidCallResult<T>>;
+    /** Wait until every call started by this ledger has produced a durable outcome. */
+    waitForIdle(options?: CostLedgerWaitOptions): Promise<boolean>;
+    /** Settle a call left pending by a crashed process after reconciling with the provider. */
+    reconcile(callId: string, observed: CostReceiptInput, options?: {
+        error?: string;
+    }): CostReceipt;
+    list(filter?: CostLedgerFilter): CostReceipt[];
+    summary(filter?: CostLedgerFilter): CostLedgerSummary;
+    markCompleted(count?: number): void;
+    costPerCompletedTask(): number | null;
+    private execute;
+    private captureLateOutcome;
+    private releaseActiveCall;
+    private commitOutcome;
+    private captureFailure;
+    private commitReceipt;
+    private resolveMaximum;
+    private hasIncompleteSettledCall;
+    private appendRecord;
+    private ensureCostLimitPersisted;
+    private appendEvent;
+}
+/** Public callback surface for a shared cost ledger.
+ *
+ * Declaration bundles may expose this type through multiple package subpaths.
+ * Keeping callback contracts structural lets those subpaths compose while the
+ * concrete {@link CostLedger} retains its private durable state.
+ */
+type CostLedgerHandle = Pick<CostLedger, Exclude<keyof CostLedger, 'waitForIdle'>> & Partial<Pick<CostLedger, 'waitForIdle'>>;
+
+/**
+ * LLM client with graceful degrade.
+ *
+ * OpenAI-compatible `/v1/chat/completions` client with:
+ *   - Exponential-backoff retry on 429 + 5xx gateway errors (502/503/504).
+ *   - Retry on transient network errors (fetch failed, AbortError, ECONNRESET).
+ *   - Graceful json_schema → json_object degrade on 400 with schema-reject body.
+ *   - Fenced-JSON stripping (```json ... ```) for models that wrap structured output.
+ *   - Configurable base URL + api key / bearer, works with LiteLLM proxies, OpenAI
+ *     directly, cli-bridge subscriptions, and any router that speaks the spec.
+ *
+ * Usage:
+ *   const { value, result } = await callLlmJson<MyType>(
+ *     { model: 'gpt-4o', messages: [...], jsonSchema: { name: 'x', schema: {...} } },
+ *     { baseUrl: 'https://router.tangle.tools/v1', apiKey: process.env.KEY },
+ *   )
+ *
+ * This is THE llm-calling seam for agent-eval primitives that need structured
+ * output (semantic concept judge, reviewer directives, critic scores). Primitives
+ * that need free-form text use `callLlm` and parse output themselves.
+ */
+
+interface LlmMessage {
+    role: 'system' | 'user' | 'assistant';
+    /**
+     * Either a plain text content string OR a multimodal content array
+     * (text + image_url parts) for vision-capable models.
+     */
+    content: string | Array<{
+        type: 'text';
+        text: string;
+    } | {
+        type: 'image_url';
+        image_url: {
+            url: string;
+            detail?: 'auto' | 'low' | 'high';
+        };
+    }>;
+}
+interface LlmCallRequest {
+    model: string;
+    messages: LlmMessage[];
+    /** Optional JSON-mode response format (response_format: json_object). */
+    jsonMode?: boolean;
+    /** Optional structured output via JSON Schema. Falls back to json_object on 400. */
+    jsonSchema?: {
+        name: string;
+        schema: Record<string, unknown>;
+    };
+    temperature?: number;
+    maxTokens?: number;
+    /** Per-call timeout, default 300s. */
+    timeoutMs?: number;
+}
+interface LlmUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    /** False when the provider omitted or malformed prompt/completion usage. */
+    captured?: boolean;
+    /** Proxies populate this when prompt caching is on. */
+    cachedPromptTokens?: number;
+}
+interface LlmCallResult {
+    /** The text content of the first choice. Empty string if none. */
+    content: string;
+    usage: LlmUsage;
+    /**
+     * Cost in USD. Pulled from proxy's `_response_cost` field when present;
+     * `null` when neither the proxy nor the caller can derive it.
+     */
+    costUsd: number | null;
+    /** Model name actually used (echoed from response). */
+    model: string;
+    /** Wall-clock duration of the HTTP call (last attempt, if retried). */
+    durationMs: number;
+    /**
+     * `finish_reason` echoed from the first choice (`stop`, `length`,
+     * `content_filter`, `tool_calls`, ...). `null` when the provider omits it.
+     * Exposed so a free-form `callLlm` caller CAN detect a truncated answer
+     * (`length`) instead of treating a cut-off completion as complete. Note:
+     * `callLlm` does not itself reject on it — acting on this signal is the
+     * caller's responsibility (in-repo free-form drivers do not yet enforce it).
+     */
+    finishReason?: string | null;
+    /**
+     * True when `content.trim()` is empty. An empty completion is a silent zero
+     * for free-form `callLlm` callers; this flag is the signal a caller can
+     * inspect to fail loud rather than proceed on an empty string. `callLlm`
+     * surfaces it but does not throw on it.
+     */
+    contentEmpty?: boolean;
+    /** Raw response body. */
+    raw: Record<string, unknown>;
+}
+interface LlmClientOptions {
+    /** Base URL (without trailing slash). Must end at the `/v1` prefix. */
+    baseUrl?: string;
+    /** Bearer token — either `apiKey` or `bearer` populates `Authorization: Bearer ...`. */
+    apiKey?: string;
+    bearer?: string;
+    /** Override for the `Authorization` header (e.g. `X-Auth: ...`). Takes precedence over apiKey/bearer. */
+    authHeader?: {
+        name: string;
+        value: string;
+    };
+    /** Stable provider idempotency key, reused across retries of this logical call. */
+    idempotencyKey?: string;
+    /** Default timeout in ms. Per-call can override. */
+    defaultTimeoutMs?: number;
+    /**
+     * Caller-supplied abort signal — e.g. a campaign-wide cancel. Linked to
+     * each attempt's per-attempt timeout controller, so aborting it cancels
+     * the in-flight fetch. A caller abort is FATAL: it is not retried even
+     * though an AbortError otherwise matches the transient patterns.
+     */
+    signal?: AbortSignal;
+    /**
+     * Cross-attempt wall-clock budget in ms, measured from the first attempt.
+     * Before launching each attempt the loop checks the remaining budget and
+     * stops retrying once it is exhausted, rather than waiting the full
+     * per-attempt timeout on every retry. Bounds total time independent of
+     * total attempts × `timeoutMs`.
+     */
+    deadlineMs?: number;
+    /** Total provider attempts. Legacy option name; default 3 (1 initial + 2 retries). */
+    maxRetries?: number;
+    /** Fetch implementation — defaults to global `fetch`. Override for custom transport (e.g. tests). */
+    fetch?: typeof fetch;
+    /**
+     * Optional raw HTTP capture sink. When provided, every request, response,
+     * and error (across all retry attempts) is recorded to the sink, with auth
+     * headers and credential-shaped body fields redacted by default. This is
+     * the layer-1 forensics primitive: structured `LlmSpan`s record intent,
+     * raw events record what actually crossed the wire.
+     */
+    rawSink?: RawProviderSink;
+    /**
+     * Logical provider id attached to raw events. When omitted, derived from
+     * `baseUrl` via `providerFromBaseUrl`.
+     */
+    provider?: string;
+    /** Trace context attached to raw events; populated by emitter-aware callers. */
+    traceContext?: {
+        runId?: string;
+        spanId?: string;
+    };
+    /** Override the redaction strategy for this call. Defaults to `defaultProviderRedactor`. */
+    redactor?: ProviderRedactor;
+}
+
+/**
+ * Semantic concept judge — "does the built artifact actually implement
+ * the features the user asked for?"
+ *
+ * Distinct from the domain/code/coherence judges in `judges.ts`:
+ *   - those judges score free-form conversational agent outputs along
+ *     quality dimensions (accuracy, depth, etc.)
+ *   - this judge scores a *built artifact* (served HTML + source files)
+ *     against an explicit list of expected concepts, returning per-concept
+ *     {present, score 0-10, evidence, severity}.
+ *
+ * The judge is strict about distinguishing (a) a working implementation
+ * from (b) a keyword-present stub. "// TODO: mint button" is NOT present.
+ * Only real, functional, wired-up code counts.
+ *
+ * Use via {@link createSemanticConceptJudge} or directly via
+ * {@link runSemanticConceptJudge}. Soft-fails (available=false) on LLM
+ * or JSON-parse errors so the caller can treat that as "layer skipped"
+ * rather than "layer failed" in a multi-layer pipeline.
+ */
+
+/**
+ * Implementation complexity class for weighted scoring.
+ *
+ * - `render` (default): the concept is a UI surface that displays static
+ *   data — render a list, show a counter, lay out a button. Single-file
+ *   work, no external integration.
+ * - `integrate`: the concept requires wiring a real external system —
+ *   wallet connect (wagmi + RainbowKit + chain config), payment provider
+ *   (Stripe Elements + intent + webhook), an API client with auth.
+ *   Multi-file, library-knowledge, runtime correctness matters.
+ * - `compute`: the concept requires algorithmic work — solver, simulator,
+ *   constraint propagation, ML inference. Correctness > UI polish.
+ *
+ * Default weights (when applied via `weightConcepts: 'complexity'`):
+ *   render=1.0, integrate=2.0, compute=2.5
+ *
+ * Cross-vertical scoring without complexity weighting silently inflates
+ * the rate of UI-heavy verticals (healthcare, fintech dashboards) vs
+ * integration-heavy verticals (DeFi, wallets) — all concepts treated
+ * equally even though the agent does 2-3x the work for `integrate`.
+ */
+type ConceptComplexity = 'render' | 'integrate' | 'compute';
+interface ConceptSpec {
+    name: string;
+    /** Short hints that help the judge; not used for matching. */
+    keywords?: string[];
+    /** Optional explicit weight; default 1.0. Overrides complexity-derived weight. */
+    weight?: number;
+    /** Implementation complexity class. Default `render`. */
+    complexity?: ConceptComplexity;
+}
+interface SemanticConceptJudgeInput {
+    /** Full natural-language prompt the agent was handed. */
+    userRequest: string;
+    /** Rendered HTML the preview returns (UI artifacts). Optional. */
+    servedHtml?: string;
+    /** Top-level source files from the agent's workdir. */
+    sourceFiles: Array<{
+        path: string;
+        content: string;
+    }>;
+    /** The expected concept list. */
+    expectedConcepts: ConceptSpec[];
+    /** Free-form metadata (id, difficulty) to inject into the prompt. */
+    artifactLabel?: string;
+    artifactDescription?: string;
+}
+/**
+ * Score-aggregation strategy. `mean` averages 0-10 scores uniformly.
+ * `complexity` applies the default weight table (render=1, integrate=2,
+ * compute=2.5) unless a concept has an explicit `weight`. `explicit`
+ * honors only `weight` (defaulting to 1 for unspecified).
+ */
+type ConceptWeightStrategy = 'mean' | 'complexity' | 'explicit';
+interface SemanticConceptJudgeOptions {
+    /** Model id to call. Default 'claude-sonnet-4-6' via agent-eval defaults. */
+    model?: string;
+    /** Per-call timeout. Default 300s. */
+    timeoutMs?: number;
+    /** Provider-enforced output limit. Default 16000. */
+    maxTokens?: number;
+    /** Pipeline budget for the prompt (source blob truncation). Default 45000. */
+    maxSourceChars?: number;
+    /** Per-file cap before inclusion. Default 20000. */
+    maxPerFileChars?: number;
+    /** HTML cap. Default 30000. */
+    maxHtmlChars?: number;
+    /** LlmClient config (baseUrl, apiKey, authHeader, …). */
+    llm?: LlmClientOptions;
+    costLedger?: CostLedgerHandle;
+    costPhase?: string;
+    signal?: AbortSignal;
+    /**
+     * Score aggregation strategy. Default `mean` — uniform average across
+     * concepts. Cross-vertical comparisons should use `complexity` to
+     * neutralize the integrate-vs-render asymmetry.
+     */
+    weightConcepts?: ConceptWeightStrategy;
+    /** Override the default complexity → weight table. */
+    complexityWeights?: Partial<Record<ConceptComplexity, number>>;
+}
+
+interface Scenario {
+    id: string;
+    persona: string;
+    label: string;
+    thesis: string;
+    dimensions: string[];
+    turns: Turn[];
+    artifactChecks: ArtifactCheck[];
+    systemPromptAppend?: string;
+}
+interface Turn {
+    user: string;
+    expectedBehaviors: string[];
+    adversarial?: boolean;
+    feedbackType?: 'correction' | 'rejection' | 'vague' | 'contradictory' | 'escalation';
+}
+interface ArtifactCheck {
+    type: 'vault_file_exists' | 'vault_file_contains' | 'block_extracted' | 'code_valid' | 'generation_produced' | 'tool_created' | string;
+    target: string;
+    contains?: string;
+    minCount?: number;
+    description: string;
+}
+interface TurnResult {
+    turnIndex: number;
+    userMessage: string;
+    agentResponse: string;
+    durationMs: number;
+    blocksExtracted: {
+        type: string;
+        title: string;
+    }[];
+    containsCode: boolean;
+    containsToolCall: boolean;
+}
+interface JudgeScore {
+    judgeName: string;
+    dimension: string;
+    score: number;
+    reasoning: string;
+    evidence?: string;
+}
+interface CollectedArtifacts {
+    vaultFiles: {
+        path: string;
+        content: string;
+    }[];
+    blocksExtracted: {
+        type: string;
+        fields: Record<string, string>;
+    }[];
+    codeBlocks: {
+        language: string;
+        code: string;
+    }[];
+    toolCalls: string[];
+}
+interface JudgeInput {
+    scenario: Scenario;
+    turns: TurnResult[];
+    artifacts: CollectedArtifacts;
+    /** Shared ledger for paid built-in judges. Direct calls default to an uncapped ledger. */
+    costLedger?: CostLedgerHandle;
+    costPhase?: string;
+    costTags?: Record<string, string>;
+    signal?: AbortSignal;
+    /** Exact maximum provider attempts configured on the supplied TCloud client. */
+    tcloudMaximumAttempts?: number;
+}
+type JudgeFn = (tc: TCloud, input: JudgeInput) => Promise<JudgeScore[]>;
+
+/**
+ * Shared types for the trace-analyst module.
+ *
+ * Wire format. The store interface speaks `OtlpSpanLike` rows — one JSONL
+ * line per span, OTLP-shaped. We do NOT depend on a specific tracing
+ * vendor at the type level. Adapter
+ * layers map upstream shapes onto this interface.
+ *
+ * Design constraint. Every read operation that can return arbitrary
+ * payload must carry a byte budget so the agent's tool result stays
+ * bounded regardless of input trace size. Oversized responses
+ * substitute a deterministic summary instead of bytes — see
+ * `ViewTraceOversized`.
+ */
+/** OTLP span kind (subset we actually use). */
+type TraceAnalystSpanKind = 'AGENT' | 'LLM' | 'TOOL' | 'CHAIN' | 'GUARDRAIL' | 'SPAN' | 'UNKNOWN';
+type TraceAnalystSpanStatus = 'OK' | 'ERROR' | 'UNSET';
+/** Subset of OTLP span fields the analyst exposes to the agent. The
+ *  store's job is to project upstream's full span shape down to this
+ *  view — the analyst never sees vendor extensions directly. */
+interface TraceAnalystSpan {
+    trace_id: string;
+    span_id: string;
+    parent_span_id: string | null;
+    name: string;
+    kind: TraceAnalystSpanKind;
+    start_time: string;
+    end_time: string;
+    duration_ms: number;
+    status: TraceAnalystSpanStatus;
+    status_message?: string;
+    service_name: string | null;
+    agent_name: string | null;
+    model_name: string | null;
+    tool_name: string | null;
+    /** Raw JSON-serialisable attribute map. May contain large strings;
+     *  callers must respect the per-attribute byte cap. */
+    attributes: Record<string, unknown>;
+}
+interface TraceAnalystTraceSummary {
+    trace_id: string;
+    service_name: string | null;
+    agent_name: string | null;
+    span_count: number;
+    has_errors: boolean;
+    start_time: string;
+    end_time: string;
+    duration_ms: number;
+    raw_jsonl_bytes: number;
+    models: string[];
+    tools: string[];
+}
+interface TraceAnalystFilters {
+    /** Restrict to traces that contain at least one error span. */
+    has_errors?: boolean;
+    /** Match if any span's `service.name` is in this list. */
+    service_names?: string[];
+    /** Match if any span's `agent.name` is in this list. */
+    agent_names?: string[];
+    /** Match if any LLM span's `llm.model_name` is in this list. */
+    model_names?: string[];
+    /** Match if any tool span's `tool.name` is in this list. */
+    tool_names?: string[];
+    /** ISO-8601 lower bound on the trace's earliest start time. */
+    start_time_after?: string;
+    /** ISO-8601 upper bound on the trace's earliest start time. */
+    start_time_before?: string;
+    /** Single regex applied to raw JSONL bytes for the trace. Opt-in;
+     *  expensive on large datasets. Use the indexed filters above first. */
+    regex_pattern?: string;
+}
+/** One distinct error signature across the dataset — the deterministic unit of
+ *  failure coverage. Signatures normalize volatile tokens (digits, hex/uuids,
+ *  paths, durations) out of the span `status_message` so semantically identical
+ *  failures collapse into one cluster. An analyst that accounts for every
+ *  cluster has, by construction, covered every distinct failure mode. */
+interface ErrorCluster {
+    /** Normalized status_message — the cluster key. */
+    signature: string;
+    /** A verbatim, un-normalized exemplar message (for exact-string citation). */
+    status_message_sample: string;
+    /** The span name that most often carries this signature, if any. */
+    span_name: string | null;
+    /** The tool that most often carries this signature, if any. */
+    tool_name: string | null;
+    trace_count: number;
+    span_count: number;
+    /** trace_count / total error traces in the matched set (0..1). */
+    prevalence: number;
+    /** Real trace ids carrying this signature (capped), passable to view/search. */
+    exemplar_trace_ids: string[];
+    /** Real span ids carrying this signature (capped). */
+    exemplar_span_ids: string[];
+}
+interface DatasetOverview {
+    total_traces: number;
+    raw_jsonl_bytes: number;
+    services: string[];
+    agents: string[];
+    models: string[];
+    tool_names: string[];
+    /** Up to 20 real trace ids the agent may pass to view/search tools. */
+    sample_trace_ids: string[];
+    errors: {
+        trace_count: number;
+        span_count: number;
+    };
+    /** The COMPLETE deterministic error-signature population, sorted by
+     *  trace_count desc. This is the failure-coverage checklist: an analysis is
+     *  complete only when every cluster here is accounted for. Empty when the
+     *  matched set has no error spans. */
+    error_clusters: ErrorCluster[];
+    time_range: {
+        earliest: string;
+        latest: string;
+    } | null;
+}
+interface QueryTracesPage {
+    traces: TraceAnalystTraceSummary[];
+    total: number;
+    has_more: boolean;
+}
+/** Full-trace view. When the response would exceed the per-call byte
+ *  budget, `oversized` is populated INSTEAD of `spans` so the agent
+ *  knows to switch to `searchTrace` / `viewSpans`. */
+interface ViewTraceResult {
+    trace_id: string;
+    spans?: TraceAnalystSpan[];
+    oversized?: ViewTraceOversized;
+}
+interface ViewTraceOversized {
+    span_count: number;
+    /** Names with their counts, sorted desc. Capped at 20 entries. */
+    top_span_names: Array<[string, number]>;
+    /** Largest single span body (bytes after attribute-cap projection). */
+    span_response_bytes_max: number;
+    error_span_count: number;
+}
+interface ViewSpansResult {
+    trace_id: string;
+    spans: TraceAnalystSpan[];
+    /** Number of requested span ids that were not found in the trace. */
+    missing_span_ids: string[];
+    /** Number of attribute fields truncated to fit the per-attribute cap. */
+    truncated_attribute_count: number;
+}
+interface SpanMatchRecord {
+    trace_id: string;
+    span_id: string;
+    span_name: string;
+    span_kind: TraceAnalystSpanKind;
+    /** JSON pointer-style path to the matched value, e.g.
+     *  `attributes."llm.input_messages"[2].content`. */
+    attribute_path: string;
+    matched_text: string;
+    context_before: string;
+    context_after: string;
+    match_offset: number;
+}
+interface SearchTraceResult {
+    trace_id: string;
+    hits: SpanMatchRecord[];
+    total_matches: number;
+    has_more: boolean;
+}
+interface SearchSpanResult {
+    trace_id: string;
+    span_id: string;
+    hits: SpanMatchRecord[];
+    total_matches: number;
+    has_more: boolean;
+}
+
+/**
+ * `TraceAnalysisStore` — read-side interface the trace-analyst calls
+ * through. Six operations, all bounded:
+ *
+ *   - `getOverview(filters?)` — dataset rollup + sample trace ids.
+ *   - `queryTraces(filters?, limit, offset)` — paginated summaries.
+ *   - `countTraces(filters?)` — cheap count without materialisation.
+ *   - `viewTrace(trace_id, perAttrCap)` — full span list, oversized → summary.
+ *   - `viewSpans(trace_id, span_ids, perAttrCap)` — surgical span fetch.
+ *   - `searchTrace(trace_id, regex, max_matches)` — bounded regex hits.
+ *   - `searchSpan(trace_id, span_id, regex, max_matches)` — single-span search.
+ *
+ * Multiple implementations ship in the core (`OtlpFileTraceStore`).
+ * Downstream callers can supply their own — e.g. a DuckDB-backed
+ * adapter or an in-memory adapter for tests — by implementing this
+ * interface.
+ *
+ * Filters compose with AND semantics. Empty/undefined fields impose
+ * no constraint. `regex_pattern` is the only opt-in raw-bytes scan —
+ * implementations may skip it via `count`/`overview` when not set.
+ */
+
+interface TraceAnalysisStore {
+    getOverview(filters?: TraceAnalystFilters): Promise<DatasetOverview>;
+    queryTraces(opts: {
+        filters?: TraceAnalystFilters;
+        limit: number;
+        offset?: number;
+    }): Promise<QueryTracesPage>;
+    countTraces(filters?: TraceAnalystFilters): Promise<number>;
+    viewTrace(opts: {
+        trace_id: string;
+        /** Override per-attribute byte cap. Defaults to discovery budget. */
+        per_attribute_byte_cap?: number;
+    }): Promise<ViewTraceResult>;
+    viewSpans(opts: {
+        trace_id: string;
+        span_ids: readonly string[];
+        /** Override per-attribute byte cap. Defaults to surgical budget. */
+        per_attribute_byte_cap?: number;
+    }): Promise<ViewSpansResult>;
+    searchTrace(opts: {
+        trace_id: string;
+        regex_pattern: string;
+        /** Hard cap on matches returned. Default 50. */
+        max_matches?: number;
+    }): Promise<SearchTraceResult>;
+    searchSpan(opts: {
+        trace_id: string;
+        span_id: string;
+        regex_pattern: string;
+        max_matches?: number;
+    }): Promise<SearchSpanResult>;
+}
+
+/**
+ * ChatClient — the single LLM abstraction analysts call.
+ *
+ * agent-eval already ships an `LlmClient` (OpenAI-compatible, retry,
+ * graceful JSON-schema degrade) and judges that talk to `TCloud`. Two
+ * mixed patterns force every analyst author to pick a transport, which
+ * couples analyst code to runtime concerns (cli-bridge vs router vs
+ * sandbox-sdk) it shouldn't know about.
+ *
+ * `ChatClient` is one interface every analyst takes via `AnalystContext.chat`.
+ * The operator decides at the registry boundary which transport binds
+ * to it. Analyst code stays transport-agnostic; swapping production
+ * (sandbox-sdk) for local dev (cli-bridge) or tests (mock) is a one-
+ * line factory call.
+ *
+ * Designed to coexist: existing `LlmClient` callers and existing
+ * `TCloud`-based judges keep working untouched. New analyst code uses
+ * `ChatClient`. When old call sites migrate, they pick up budgeting,
+ * cancellation, and unified telemetry for free.
+ */
+
+/**
+ * Unified chat interface. Mirrors LlmCallRequest/Result so the OpenAI-
+ * compatible mental model stays. Two methods: a one-shot `chat()` and
+ * an `streamChat()` for future agentic loops (not yet exposed).
+ */
+interface ChatClient {
+    /** Display name of the bound transport — included in telemetry. */
+    readonly transport: ChatTransport;
+    /** Default model when caller omits — operators bind this per environment. */
+    readonly defaultModel?: string;
+    /** Total provider attempts this transport can make for one chat call. */
+    readonly maximumAttempts?: number;
+    /** Implementations must enforce `req.maxTokens` when it is present. */
+    chat(req: ChatRequest, opts?: ChatCallOpts): Promise<ChatResponse>;
+}
+type ChatTransport = 'router' | 'sandbox-sdk' | 'cli-bridge' | 'direct-provider' | 'mock';
+interface ChatRequest extends Omit<LlmCallRequest, 'model'> {
+    /** Optional — falls back to ChatClient.defaultModel. */
+    model?: string;
+}
+type ChatResponse = LlmCallResult;
+interface ChatCallOpts {
+    /** Cancel the in-flight request. */
+    signal?: AbortSignal;
+    /** Hard USD ceiling for this single call (informational; the underlying transport may not enforce). */
+    maxCostUsd?: number;
+    /** Correlation tag carried into request headers when the transport allows. */
+    correlationId?: string;
+    /** Stable provider idempotency key for retries/redrives of one paid call. */
+    idempotencyKey?: string;
+}
+type CreateChatClientOpts = RouterTransportOpts | CliBridgeTransportOpts | DirectProviderTransportOpts | SandboxSdkTransportOpts | MockTransportOpts;
+interface BaseTransportOpts {
+    defaultModel?: string;
+    /** Total provider attempts. Required for opaque transports used in capped runs. */
+    maximumAttempts?: number;
+}
+interface RouterTransportOpts extends BaseTransportOpts {
+    transport: 'router';
+    baseUrl?: string;
+    apiKey: string;
+}
+interface CliBridgeTransportOpts extends BaseTransportOpts {
+    transport: 'cli-bridge';
+    baseUrl?: string;
+    bearer?: string;
+}
+interface DirectProviderTransportOpts extends BaseTransportOpts {
+    transport: 'direct-provider';
+    baseUrl: string;
+    apiKey: string;
+}
+/**
+ * Sandbox-SDK transport. Provided as a thin pass-through: the caller
+ * supplies a callable that mimics LlmClient.chat() against an already-
+ * configured Sandbox handle. We don't import the SDK here to keep
+ * agent-eval dep-free of @tangle-network/sandbox.
+ */
+interface SandboxSdkTransportOpts extends BaseTransportOpts {
+    transport: 'sandbox-sdk';
+    chat: (req: ChatRequest, opts?: ChatCallOpts) => Promise<ChatResponse>;
+}
+/**
+ * Mock transport for tests. The handler receives the request and returns
+ * whatever the test wants. No retries, no JSON-schema degrade.
+ */
+interface MockTransportOpts extends BaseTransportOpts {
+    transport: 'mock';
+    handler: (req: ChatRequest, opts?: ChatCallOpts) => Promise<ChatResponse>;
+}
+/**
+ * Build a ChatClient bound to a specific transport. The returned client
+ * is safe to share across analysts in a single registry run.
+ */
+declare function createChatClient(opts: CreateChatClientOpts): ChatClient;
+
+/**
+ * Analyst contract — the missing orchestration layer over agent-eval's
+ * existing analyzers (analyzeTraces, MultiLayerVerifier, RunCritic,
+ * SemanticConceptJudge, JudgeFn, ...).
+ *
+ * Each existing primitive returns its own output shape. The Analyst
+ * contract is the single envelope every primitive lifts into, so a
+ * registry can run N analysts against a run and a single renderer can
+ * compose findings without knowing which analyzer produced them.
+ *
+ * The contract is intentionally domain-agnostic: nothing here knows
+ * about code, voice, RAG, or any particular agent stack. Analysts
+ * declare what INPUT KIND they need (a trace store, an artifact dir,
+ * a RunRecord, a JudgeInput, or `custom`), and the registry routes
+ * the matching input from `AnalystRunInputs`.
+ */
+
+/**
+ * Unified envelope every analyst emits. Schema-versioned so renderers
+ * and time-series diffs survive future field additions.
+ */
+interface AnalystFinding {
+    schema_version: '1.0.0';
+    /**
+     * Stable hash over identity-defining fields (analyst_id + canonical
+     * claim + area + optional subject). Two findings from two runs that
+     * "are the same finding" share this id — that's what `diffFindings`
+     * uses to compute appeared/disappeared sets across runs.
+     */
+    finding_id: string;
+    analyst_id: string;
+    produced_at: string;
+    severity: AnalystSeverity;
+    /**
+     * Coarse classification. Renderers group by this. Free-form so
+     * domain-specific analysts can introduce categories without a
+     * schema change ('agent-reasoning', 'verification', 'cost',
+     * 'tool-use', 'safety', 'latency', 'data-quality', ...).
+     */
+    area: string;
+    claim: string;
+    rationale?: string;
+    evidence_refs: EvidenceRef[];
+    recommended_action?: string;
+    validation_plan?: string;
+    /** 0..1 — the analyst's own confidence. Not calibrated across analysts. */
+    confidence: number;
+    /**
+     * Optional subject the finding is about — leaf id, agent id, request
+     * id. Included in finding_id when present so per-subject findings
+     * diff cleanly across runs.
+     */
+    subject?: string;
+    /** FIREWALL provenance (docs/learning-flywheel.md): true iff this finding was
+     *  lifted from a JUDGE verdict (an acceptance score), not OBSERVED from the
+     *  agent's behavior. A judge-derived finding must NEVER be admitted as a
+     *  steering input — that is the held-out judge leaking into the loop. Set at
+     *  the lift site (createJudgeAdapter); checked by `assertNoJudgeVerdict`.
+     *  Provenance, not evidence presence, is the correct discriminator: an
+     *  evidence-less trace-analyst observation legitimately steers, while a judge
+     *  verdict that happens to cite an artifact must not. */
+    derived_from_judge?: boolean;
+    /** Analyst-private extras; renderers ignore unless they know the analyst. */
+    metadata?: Record<string, unknown>;
+}
+type AnalystSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+interface EvidenceRef {
+    /**
+     * Where the evidence lives. `span` and `event` refer to OTLP trace
+     * elements; `artifact` to a file inside the run's artifact tree;
+     * `finding` to another AnalystFinding (cross-analyst chaining);
+     * `metric` to a named scalar reading the renderer knows how to read.
+     */
+    kind: 'span' | 'event' | 'artifact' | 'finding' | 'metric';
+    uri: string;
+    excerpt?: string;
+}
+/**
+ * The discriminator the registry uses to pass the right input.
+ * `custom` is the escape hatch — analysts that need something else
+ * (e.g. an embedding cache, a partner SDK handle) read it from
+ * `AnalystRunInputs.custom[<analyst id>]`.
+ */
+type AnalystInputKind = 'trace-store' | 'artifact-dir' | 'run-record' | 'judge-input' | 'custom';
+interface AnalystCost {
+    /** `deterministic` analysts MUST NOT call the LLM. */
+    kind: 'deterministic' | 'llm';
+    /** Optional declared upper bound; the registry can enforce a budget. */
+    est_usd_per_run?: number;
+    /** Models the analyst expects to use (informational). */
+    models?: string[];
+    /** Maximum post-cancellation wait for provider usage. Model analysts default to 5 seconds. */
+    settlement_timeout_ms?: number;
+}
+interface AnalystRequirements {
+    /** Min number of shots / samples the analyst needs to produce signal. */
+    min_shots?: number;
+    /** Capabilities the runtime must supply (e.g. ['network', 'gpu']). */
+    capabilities?: string[];
+}
+/**
+ * What's passed to every analyst call. The registry resolves which
+ * field the analyst's `inputKind` selects and asserts it's present.
+ */
+interface AnalystRunInputs {
+    traceStore?: TraceAnalysisStore;
+    artifactDir?: string;
+    runRecord?: RunRecord;
+    judgeInput?: JudgeInput;
+    /** Keyed by analyst id; populated by callers that registered custom analysts. */
+    custom?: Record<string, unknown>;
+}
+interface AnalystContext {
+    runId: string;
+    /** Stable correlation id so logs from a single registry.run() share a tag. */
+    correlationId: string;
+    /** Enforced wall-clock deadline (epoch ms). */
+    deadlineMs?: number;
+    /** Per-analyst USD budget. Analysts MAY check before issuing LLM calls. */
+    budgetUsd?: number;
+    /** Shared paid-call account when the analyst runs inside a larger campaign. */
+    costLedger?: CostLedgerHandle;
+    /** Attribution phase used when writing to the shared paid-call account. */
+    costPhase?: string;
+    /**
+     * Shared chat client. Analysts that call an LLM go through this so
+     * the operator picks transport (sandbox-sdk | router | cli-bridge |
+     * direct-provider | mock) at the registry boundary without touching
+     * analyst code.
+     */
+    chat?: ChatClient;
+    /**
+     * Findings from a prior run the operator wants the analyst to see as
+     * retrieval context. Kinds that take advantage of cross-run memory
+     * (failure-mode "I saw this cluster last run", knowledge-gap "the wiki
+     * page I asked for is still missing") render these into the actor's
+     * working set. Filtering is the operator's job: pass the slice that
+     * matches the analyst's id, or pass everything and let the kind
+     * filter. Empty / absent means no cross-run context.
+     */
+    priorFindings?: ReadonlyArray<AnalystFinding>;
+    /**
+     * Findings emitted by analysts that completed earlier in this registry run.
+     * This is separate from `priorFindings`: upstream findings are dependency
+     * context for the current pass, while prior findings are cross-run memory.
+     * The registry populates this only when `RegistryRunOpts.chainFindings` is on.
+     */
+    upstreamFindings?: ReadonlyArray<AnalystFinding>;
+    /**
+     * Report metered work independently of findings. This keeps an empty finding
+     * set from erasing token/cost telemetry. Multiple receipts are accumulated.
+     */
+    recordUsage?: (receipt: AnalystUsageReceipt) => void;
+    /** Free-form runtime tags (env, host, op). Findings can echo these into metadata. */
+    tags?: Record<string, string>;
+    /** Logger callback — analysts SHOULD prefer this over console.* for testability. */
+    log?: (msg: string, fields?: Record<string, unknown>) => void;
+    /** Optional abort signal. Analysts SHOULD pass it through to LLM calls. */
+    signal?: AbortSignal;
+}
+/**
+ * The minimal contract. Concrete analysts can refine `TInput` so
+ * implementations stay type-safe (e.g. a trace analyst's `TInput` is
+ * `TraceAnalysisStore`); the registry passes the right field from
+ * `AnalystRunInputs` based on `inputKind`.
+ */
+interface Analyst<TInput = unknown> {
+    /** Stable identifier — appears in finding_id, telemetry, and registry exclusion lists. */
+    readonly id: string;
+    /** Human-readable. One sentence. */
+    readonly description: string;
+    readonly inputKind: AnalystInputKind;
+    readonly cost: AnalystCost;
+    readonly requires?: AnalystRequirements;
+    /** Bump on breaking changes to claim wording or area so old finding_ids don't collide. */
+    readonly version: string;
+    analyze(input: TInput, ctx: AnalystContext): Promise<AnalystFinding[]>;
+}
+/** Metered work performed by one analyst call. */
+interface AnalystUsageReceipt {
+    /** Number of model-usage records observed at the provider boundary. */
+    calls: number | null;
+    /** Null when the provider did not return token accounting. */
+    tokens: RunTokenUsage | null;
+    /** Observed, estimated, or explicitly uncaptured dollar cost. */
+    cost: RunCostProvenance;
+    /** Known lower bound when one or more calls have uncaptured cost. */
+    knownCostUsd?: number;
+}
+/**
+ * Compute the stable finding_id from the identity-defining fields.
+ * Default implementation hashes {analyst_id, area, subject, normalized claim}.
+ * Analysts that emit findings whose claim text varies per run (timestamps,
+ * counts) SHOULD either: (a) pass an explicit `id_basis` to fix the hash,
+ * or (b) move the variable part into `rationale`/`metadata` and keep the
+ * `claim` static.
+ */
+declare function computeFindingId(input: {
+    analyst_id: string;
+    area: string;
+    subject?: string;
+    claim: string;
+    /** Override the claim for hashing — use when the displayed claim has run-specific bits. */
+    id_basis?: string;
+}): string;
+/**
+ * Convenience factory: produce a fully-formed AnalystFinding with the
+ * id computed automatically. Analyst code stays terse.
+ */
+declare function makeFinding(init: Omit<AnalystFinding, 'schema_version' | 'finding_id' | 'produced_at'> & {
+    id_basis?: string;
+    produced_at?: string;
+}): AnalystFinding;
+interface AnalystRunSummary {
+    analyst_id: string;
+    status: 'ok' | 'skipped' | 'failed';
+    /** Why skipped — missing input, budget exceeded, capability unmet. */
+    reason?: string;
+    findings_count: number;
+    latency_ms: number;
+    cost_usd: number;
+    /**
+     * Additive receipt for model usage. Registry-produced summaries populate it
+     * even when the analyst emits no findings. `cost_usd` remains the legacy
+     * numeric field; inspect `usage.cost` before treating zero as observed.
+     */
+    usage?: AnalystUsageReceipt;
+    /** When `status='failed'`: the error class + message, never the full stack. */
+    error?: {
+        class: string;
+        message: string;
+    };
+}
+interface AnalystRunResult {
+    run_id: string;
+    correlation_id: string;
+    started_at: string;
+    ended_at: string;
+    findings: AnalystFinding[];
+    per_analyst: AnalystRunSummary[];
+    /** Total LLM cost in USD across all analysts in this registry.run(). */
+    total_cost_usd: number;
+    /**
+     * Provenance for `total_cost_usd`. When uncaptured, the numeric field is only
+     * the known subtotal and must not be treated as the run's total spend.
+     */
+    total_cost_provenance?: RunCostProvenance;
+}
+/**
+ * Events emitted by `AnalystRegistry.runStream(...)` in real time as
+ * the registry executes. UIs subscribe via `for await (const ev of
+ * registry.runStream(...))`; `registry.run(...)` is a thin collector
+ * over the same stream, so the two surfaces share their invariants.
+ *
+ * Per-finding events are intentionally omitted — analyzers are batch
+ * operations (an Ax actor returns the full `findings:json[]` at the
+ * end of the responder), so streaming inside one analyst would only
+ * emit partial JSON consumers can't render. The kind-completion event
+ * is the right granularity; subscribers wanting per-finding rendering
+ * iterate `event.findings` themselves.
+ */
+type AnalystRunEvent = {
+    type: 'run-started';
+    run_id: string;
+    correlation_id: string;
+    started_at: string;
+    /** The ordered list of analyst ids the registry will run. */
+    analyst_ids: ReadonlyArray<string>;
+} | {
+    type: 'analyst-skipped';
+    summary: AnalystRunSummary;
+} | {
+    type: 'analyst-started';
+    analyst_id: string;
+    started_at: string;
+} | {
+    type: 'analyst-completed';
+    /** `summary.status` is `'ok'` for clean completion or `'failed'` for thrown analysts. */
+    summary: AnalystRunSummary;
+    findings: ReadonlyArray<AnalystFinding>;
+} | {
+    type: 'run-completed';
+    result: AnalystRunResult;
+};
+
+/**
+ * Adapter factories — lift each existing agent-eval primitive into the
+ * Analyst contract without re-implementing it.
+ *
+ * Five primitives, five factories. Each one:
+ *   - Builds an Analyst with a stable id (caller chooses; defaults
+ *     given), a sensible default `inputKind`, a version derived from
+ *     the wrapped primitive's version + an adapter revision, and an
+ *     `analyze()` that calls the primitive and lifts its output to
+ *     AnalystFinding[] using `makeFinding()`.
+ *   - Maps severities: the existing `Severity` ('critical' | 'major' |
+ *     'minor' | 'info') projects onto AnalystSeverity ('critical' |
+ *     'high' | 'medium' | 'low' | 'info'); 'major' → 'high', 'minor' →
+ *     'medium'. Domain analysts that want finer-grained mapping override.
+ *
+ * Adapters never own state. Calling the same factory twice with the
+ * same primitive instance is safe.
+ */
+
+declare function liftSeverity(s: Severity): AnalystSeverity;
+interface VerifierAdapterOpts<Env> {
+    id?: string;
+    area?: string;
+    verifier: MultiLayerVerifier<Env>;
+    /**
+     * The verifier expects an `env` per run. Adapters take it from
+     * `AnalystRunInputs.custom[<id>]` via the registry's 'custom' routing.
+     */
+    options?: Omit<VerifyOptions<Env>, 'env'>;
+}
+declare function createVerifierAdapter<Env>(opts: VerifierAdapterOpts<Env>): Analyst<Env>;
+interface RunCriticAdapterOpts {
+    id?: string;
+    area?: string;
+    critic?: RunCritic;
+    /** Optional threshold below which a dimension is reported as a finding. Default 0.5. */
+    threshold?: number;
+}
+declare function createRunCriticAdapter(opts?: RunCriticAdapterOpts): Analyst<RunTrace>;
+interface JudgeAdapterOpts {
+    id?: string;
+    area?: string;
+    judge: JudgeFn;
+    /** TCloud handle the JudgeFn calls. */
+    tcloud: TCloud;
+    /** Optional cost classification — most judges call an LLM. */
+    cost?: Analyst['cost'];
+    /** Optional threshold below which a JudgeScore becomes a finding. Default 6 (on 0-10 scale). */
+    threshold?: number;
+}
+declare function createJudgeAdapter(opts: JudgeAdapterOpts): Analyst<JudgeInput>;
+interface SemanticConceptJudgeAdapterOpts {
+    id?: string;
+    area?: string;
+    /** Registry context owns cancellation and the per-analyst cost ledger. */
+    options?: Omit<SemanticConceptJudgeOptions, 'costLedger' | 'signal'>;
+    /** Maximum post-cancellation wait for a provider receipt. Default 5 seconds. */
+    settlementTimeoutMs?: number;
+}
+declare function createSemanticConceptJudgeAdapter(opts?: SemanticConceptJudgeAdapterOpts): Analyst<SemanticConceptJudgeInput>;
+
+interface CreateAnalystAiConfig {
+    /** OpenAI-compatible API key forwarded as `Authorization: Bearer`.
+     *  cli-bridge ignores the value on loopback but Ax requires a non-empty string. */
+    apiKey: string;
+    /** OpenAI-compatible base URL — e.g. `https://router.tangle.tools/v1` or a
+     *  cli-bridge loopback. */
+    baseUrl?: string;
+    /** Additional headers required by the gateway, such as tenant or execution policy. */
+    headers?: Record<string, string>;
+    /** Model id forwarded to analyst calls. */
+    model: string;
+    /** Ax provider name. Defaults to the OpenAI-compatible client. */
+    provider?: AxAIArgs<unknown>['name'];
+}
+/**
+ * Construct the `AxAIService` an analyst kind calls through
+ * (`createTraceAnalystKind({ ai })`).
+ *
+ * Ax's `ai()` pins `config.model` to the OpenAI catalog enum, but every
+ * OpenAI-compatible router an analyst points at (router.tangle.tools,
+ * cli-bridge) accepts arbitrary model ids (claude-code/sonnet, openai/gpt-5.4,
+ * …). Consumers were each re-rolling `ai({ name, apiKey, apiURL, config })`
+ * behind an `as (a: any) => any` cast to dodge the enum; this is the one
+ * canonical constructor so they don't have to — and don't take a direct
+ * `@ax-llm/ax` dependency for it.
+ */
+declare function createAnalystAi(config: CreateAnalystAiConfig): AxAIService;
+
+/**
+ * Deterministic behavioral metrics over OTLP spans — pure arithmetic, no LLM.
+ *
+ * These are the model-independent multiplier: the four trace-quality signals a
+ * tolerant analyzer (e.g. HALO) re-derives per run inside the model — token
+ * growth, output decay, tool monoculture, missing self-verification — computed
+ * here once, in TypeScript, with zero model judgment. A finding that falls out
+ * of arithmetic is trivially model-agnostic and cannot hallucinate the trend.
+ *
+ * General, not trace-specific: the detectors key off token trajectories and
+ * tool usage present in any agentic OTLP trace, not any one benchmark.
+ */
+
+type SuboptimalCode = 'monotonic-input-growth' | 'output-length-decay' | 'single-tool-dependency' | 'no-self-verification';
+interface SuboptimalSignal {
+    code: SuboptimalCode;
+    severity: 'high' | 'medium' | 'low';
+    /** Human-readable claim, with the backing numbers inlined. */
+    detail: string;
+    /** The exact figures the detector fired on — auditable, no model in the loop. */
+    evidence: Record<string, number | string | boolean>;
+}
+interface BehavioralMetrics {
+    /** The only trace represented by these metrics; null when spans are empty. */
+    traceId: string | null;
+    llmCallCount: number;
+    /** Causally serial LLM timelines. Parallel branches are never joined. */
+    tokenSequences: BehavioralTokenSequence[];
+    /** Token values from the longest serial timeline, retained for convenience. */
+    inputTokenTrajectory: number[];
+    outputTokenTrajectory: number[];
+    toolHistogram: Record<string, number>;
+    totalToolCalls: number;
+    distinctTools: number;
+    /** distinct/total tool calls; 1.0 when there are no tool calls. */
+    toolDiversityRatio: number;
+    hasSelfVerification: boolean;
+    signals: SuboptimalSignal[];
+}
+interface BehavioralTokenSequence {
+    scopeId: string;
+    spanIds: string[];
+    inputTokenTrajectory: Array<number | null>;
+    outputTokenTrajectory: Array<number | null>;
+}
+
+/**
+ * `behavioralAnalyst` — a DETERMINISTIC analyst (cost.kind = 'deterministic',
+ * never calls the LLM). It produces the efficiency/behavioral findings a
+ * tolerant agentic analyzer (HALO) re-derives per run inside the model —
+ * context bloat, output decay, tool monoculture, missing self-verification —
+ * directly from arithmetic over spans (`computeTraceMetrics`).
+ *
+ * Why it matters: these findings are model-agnostic BY CONSTRUCTION (no model
+ * in the loop), so they cannot return 0 on a weak model the way the Ax-RLM
+ * does — and they are strictly more reliable than HALO, which spends tokens
+ * re-deriving the same numbers and can hallucinate the trend. The agentic
+ * RLM kinds remain for SEMANTIC findings that genuinely need a model; this
+ * analyst owns the behavioral class.
+ */
+
+/**
+ * Map computed signals → structured AnalystFindings. Pure: no LLM, no clock
+ * dependence beyond `produced_at` (overridable for deterministic tests).
+ */
+declare function deriveEfficiencyFindings(metrics: BehavioralMetrics, opts?: {
+    analystId?: string;
+    producedAt?: string;
+}): AnalystFinding[];
+/** The deterministic behavioral/efficiency analyst (no LLM, any-model). */
+declare function behavioralAnalyst(): Analyst<TraceAnalysisStore>;
+
+/**
+ * Typed Ax output for analyst findings.
+ *
+ * Replaces the legacy `findings:string[]` pattern (where every bullet
+ * became a flat-severity `AnalystFinding`) with a structured object
+ * array. Ax binds the field as `findings:json[]` so the provider emits
+ * native structured output; at the kind-factory boundary we Zod-validate
+ * each emitted finding so malformed rows fail loud instead of being
+ * silently lifted with default severity.
+ *
+ * Why not `f.object().array()` directly in the signature? The Ax
+ * signature string `question:string -> findings:json[]` already lets
+ * the provider emit JSON arrays. A Zod boundary is required either
+ * way (the provider can return any JSON), and Zod gives us a single
+ * validation surface independent of which Ax version is installed.
+ */
+
+declare const ANALYST_SEVERITIES: readonly ["critical", "high", "medium", "low", "info"];
+declare const RawAnalystEvidenceSchema: z.ZodObject<{
+    uri: z.ZodString;
+    excerpt: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type RawAnalystEvidence = z.infer<typeof RawAnalystEvidenceSchema>;
+/** Original public schema retained for stored rows and callback contracts. */
+declare const RawAnalystFindingSchema: z.ZodObject<{
+    evidence_uri: z.ZodString;
+    evidence_excerpt: z.ZodOptional<z.ZodString>;
+    severity: z.ZodEnum<{
+        critical: "critical";
+        info: "info";
+        low: "low";
+        high: "high";
+        medium: "medium";
+    }>;
+    claim: z.ZodString;
+    subject: z.ZodOptional<z.ZodString>;
+    confidence: z.ZodNumber;
+    rationale: z.ZodOptional<z.ZodString>;
+    recommended_action: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+type RawAnalystFinding = z.infer<typeof RawAnalystFindingSchema>;
+/**
+ * Canonical plural-evidence contract. The preprocessor accepts the original
+ * `evidence_uri` / `evidence_excerpt` pair and normalizes it into one evidence
+ * item so persisted rows and older model fixtures remain readable. New output
+ * always receives the plural shape.
+ */
+declare const CanonicalRawAnalystFindingSchema: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodObject<{
+    evidence: z.ZodArray<z.ZodObject<{
+        uri: z.ZodString;
+        excerpt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    severity: z.ZodEnum<{
+        critical: "critical";
+        info: "info";
+        low: "low";
+        high: "high";
+        medium: "medium";
+    }>;
+    claim: z.ZodString;
+    subject: z.ZodOptional<z.ZodString>;
+    confidence: z.ZodNumber;
+    rationale: z.ZodOptional<z.ZodString>;
+    recommended_action: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+type CanonicalRawAnalystFinding = z.infer<typeof CanonicalRawAnalystFindingSchema>;
+/**
+ * Description embedded into the actor prompt so the LLM knows what
+ * shape to emit. Kept here so kinds share one source of truth rather
+ * than restating the schema in every prompt.
+ */
+declare const RAW_FINDING_SCHEMA_PROMPT = "Each finding MUST be a strict JSON object with:\n  - severity: \"critical\" | \"high\" | \"medium\" | \"low\" | \"info\"\n  - claim: one-sentence statement (max 2000 chars)\n  - subject?: one exact subject form listed by this kind; omit rather than guess\n  - 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.\n  - confidence: number 0..1 (0.9+ exact evidence; 0.6-0.8 inferred pattern; <0.5 speculative)\n  - rationale?: one or two reasoning sentences\n  - recommended_action?: concrete imperative change; omit for descriptive findings\n\nUnknown fields are rejected. Do not emit area; the factory assigns it. Emit [] when there are no findings. Never fabricate evidence.";
+/** Convert canonical raw citations into the public finding evidence envelope. */
+declare function evidenceRefsFromRawFinding(finding: CanonicalRawAnalystFinding): EvidenceRef[];
+/**
+ * Validate the original singular-evidence shape. This public parser retains
+ * its pre-canonicalization result type so existing callback code and stored
+ * rows continue to receive exactly the object accepted by
+ * {@link RawAnalystFindingSchema}.
+ */
+declare function parseRawFinding(row: unknown, log?: (msg: string, fields?: Record<string, unknown>) => void): RawAnalystFinding | null;
+/** Validate model output and normalize original singular citations. */
+declare function parseCanonicalRawFinding(row: unknown, log?: (msg: string, fields?: Record<string, unknown>) => void): CanonicalRawAnalystFinding | null;
+
+/**
+ * Analyst-kind factory — the typed way to define trace analysts.
+ *
+ * A "kind" is a specialized analyst whose actor prompt, tool subset,
+ * and bounded Ax subqueries target one failure-mode lens (failure-mode
+ * classification, knowledge gap discovery, knowledge poisoning,
+ * self-improvement, ...). Kinds emit findings in the typed
+ * `CanonicalRawAnalystFinding` shape via a JSON-array Ax output; the factory
+ * validates each row with Zod and lifts it into `AnalystFinding[]`.
+ *
+ * Composition rules:
+ *   - Each kind owns its actor description. No generic "answer this
+ *     question" prompt — the prompt names the failure lens.
+ *   - Each kind picks a narrow tool subset from `ANALYST_TOOL_GROUPS`.
+ *     A kind that never needs full-trace dumps can drop `viewTrace` /
+ *     `viewSpans` and stay cheap.
+ *   - Each kind declares its subquery + parallelism budget. Discovery-heavy
+ *     kinds can fan out more bounded semantic questions than narrow lenses.
+ *
+ * Optimizer hook: kinds may declare `goldens` — labeled examples used
+ * by `AxBootstrapFewShot` / `AxGEPA` to fit the actor
+ * description programmatically. Stored on the kind, not the registry,
+ * because the right metric is kind-specific.
+ */
+
+/**
+ * Per-kind specification. The factory turns this into a regular
+ * `Analyst<TraceAnalysisStore>` ready for `AnalystRegistry.register()`.
+ */
+interface TraceAnalystKindSpec {
+    /** Stable id. Appears in finding_id, telemetry, and registry exclusions. */
+    id: string;
+    /** One-sentence description shown in `registry.list()`. */
+    description: string;
+    /** Coarse classification stamped on every emitted finding (`failure-mode`, `knowledge-gap`, ...). */
+    area: string;
+    /** Bump on any breaking change to the actor prompt or output schema. */
+    version: string;
+    /** Actor system prompt. Must instruct the LLM to emit `findings` per the schema. */
+    actorDescription: string;
+    /** Tool functions the actor may call. Pick narrow subsets via `ANALYST_TOOL_GROUPS`. */
+    buildTools: (store: TraceAnalysisStore) => AxFunction[];
+    /** Bounded semantic subqueries. `maxCalls: 0` disables model fan-out. */
+    subqueries?: {
+        maxCalls: number;
+        maxParallel?: number;
+    };
+    /** Actor turn cap. Default 12. */
+    maxTurns?: number;
+    /** Runtime char cap. Default 6000. */
+    maxRuntimeChars?: number;
+    /** Maximum output tokens for every actor and subquery model call. Default 4096. */
+    maxOutputTokens?: number;
+    /** Cost classification surfaced in `registry.list()` and budget enforcement. */
+    cost: AnalystCost;
+    /** Per-finding-row hook — kinds may reject / rewrite before lifting. */
+    postProcess?: (row: RawAnalystFinding, ctx: AnalystContext) => RawAnalystFinding | null;
+    /** Minimum citations per finding. Default 1; rows below it are rejected. */
+    minimumEvidenceCitations?: number;
+    /** Optional optimizer hook — populated when a kind wants to fit its prompt against labeled examples. */
+    goldens?: TraceAnalystGolden[];
+}
+/**
+ * One labeled example consumed by Ax optimizers (MIPRO / GEPA / Bootstrap).
+ * Each input is the same `{question}` an analyst would receive; `expected`
+ * is the ground-truth finding set a fitted prompt should produce on this
+ * input. Metric: kind-specific (default: F1 on `finding_id` overlap).
+ */
+interface TraceAnalystGolden {
+    question: string;
+    expected: ReadonlyArray<Omit<CanonicalRawAnalystFinding, 'confidence'>>;
+}
+interface CreateTraceAnalystKindOpts {
+    /** AxAIService bound at registration time. */
+    ai: AxAIService;
+    /** Required unless `ai` was created by {@link createAnalystAi}. */
+    model?: string;
+    /** Override the spec's `version` (e.g. when an optimizer has fitted a new prompt). */
+    versionSuffix?: string;
+    /**
+     * Optional two-phase recovery: when the agentic harvest is empty but the
+     * actor produced a substantive free-form `report`, extract findings from that
+     * prose via a tolerant chat-completions pass (`structureFindings`) — no
+     * strict-emission contract, so it works on weak models. Omit to leave the
+     * actor's harvest as-is (the report is still surfaced fail-loud either way).
+     */
+    recovery?: {
+        baseUrl: string;
+        apiKey?: string;
+        model?: string;
+        fetchImpl?: typeof fetch;
+    };
+    /** Maximum post-cancellation wait for a provider receipt. Default 5 seconds. */
+    settlementTimeoutMs?: number;
+}
+/**
+ * Build an `Analyst<TraceAnalysisStore>` from a kind spec.
+ *
+ * Lifts the Ax pipeline once at registration time so the registry
+ * gets a stateless analyst. The Ax agent is freshly constructed per
+ * `analyze()` call (the agent carries chat-log + usage state we don't
+ * want shared across analyst runs).
+ */
+declare function createTraceAnalystKind(spec: TraceAnalystKindSpec, opts: CreateTraceAnalystKindOpts): Analyst<TraceAnalysisStore>;
+/**
+ * Render a compact prior-findings block the actor reads alongside its
+ * brief. Each row is one line so the actor can scan dozens cheaply.
+ * The kind's prompt instructs the actor to (a) check whether a new
+ * cluster matches a prior `finding_id` (carry the id forward via
+ * `id_basis` to keep diffs stable) and (b) raise severity / confidence
+ * when a prior finding has reappeared without remediation.
+ *
+ * Returns the empty string when there are no prior findings — most
+ * runs are "first-of-its-kind" and the prompt stays unchanged.
+ *
+ * Exported for tests + for consumers that build their own actor
+ * prompts (e.g. specialized analysts living outside the default kinds).
+ */
+declare function renderPriorFindings(prior: AnalystContext['priorFindings']): string;
+/** Render findings produced earlier in this same registry run. */
+declare function renderUpstreamFindings(upstream: AnalystContext['upstreamFindings']): string;
+
+/**
+ * AnalystRegistry — orchestrate N analysts against one run.
+ *
+ * Owns three responsibilities and only three:
+ *   1. Registration — ids must be unique; bad registrations fail loudly
+ *      at register-time, not run-time.
+ *   2. Routing — each analyst declares its `inputKind`; the registry
+ *      picks the matching field from AnalystRunInputs and skips the
+ *      analyst with a logged reason if it's missing.
+ *   3. Isolation — one analyst's exception MUST NOT stop other analysts.
+ *      Failed analysts produce zero findings + a 'failed' summary row.
+ *
+ * Cross-cutting concerns (telemetry, error → finding conversion, cost
+ * ingestion, storage rotation) live in `AnalystHooks`. Budget shaping
+ * (equal split vs weighted vs custom) lives in `BudgetPolicy`. Both
+ * have sensible defaults; consumers override only what they need.
+ */
+
+interface AnalystHooks {
+    /** Before analyze() — last chance to mutate ctx (e.g. inject tags, override budget). */
+    onBeforeAnalyze?(args: {
+        analyst: Analyst;
+        ctx: AnalystContext;
+        runId: string;
+    }): void | Promise<void>;
+    /** After every analyst (ok | failed | skipped). Use for telemetry, ingestion, rotation. */
+    onAfterAnalyze?(args: {
+        analyst: Analyst;
+        summary: AnalystRunSummary;
+        findings: AnalystFinding[];
+        runId: string;
+    }): void | Promise<void>;
+    /**
+     * On analyst exception. Hook MAY return findings to convert the
+     * error into structured findings; the summary still reports 'failed'.
+     * Return void to keep the default empty-findings behavior.
+     */
+    onError?(args: {
+        analyst: Analyst;
+        error: Error;
+        runId: string;
+    }): AnalystFinding[] | undefined | Promise<AnalystFinding[] | undefined>;
+    /** Once after registry.run() completes. Use for final aggregation, persistence. */
+    onComplete?(args: {
+        result: AnalystRunResult;
+    }): void | Promise<void>;
+}
+interface BudgetPolicy {
+    /** Overall USD cap across the registry.run(). */
+    totalUsd?: number;
+    /** Per-analyst weight for the default allocator. Missing ids get weight 1. */
+    weights?: Record<string, number>;
+    /**
+     * Custom allocator — receives the analyst, remaining/total budget, and
+     * the count of analysts that will run. Returns the per-analyst budget
+     * (or undefined only when the run has no overall cap). Overrides weights
+     * when set.
+     */
+    allocate?: (args: {
+        analyst: Analyst;
+        totalUsd: number | undefined;
+        remainingUsd: number | undefined;
+        runningCount: number;
+    }) => number | undefined;
+}
+interface AnalystRegistryOptions {
+    /** Shared chat client passed to every LLM analyst via AnalystContext. */
+    chat?: ChatClient;
+    /** Logger callback. Defaults to a no-op. */
+    log?: (msg: string, fields?: Record<string, unknown>) => void;
+    /** Hooks invoked around analyze() — observability + customization seam. */
+    hooks?: AnalystHooks;
+    /** Default budget when run() doesn't override. */
+    defaultBudget?: BudgetPolicy;
+}
+interface RegistryRunOpts {
+    /** Restrict to a subset of registered analysts by id. */
+    only?: string[];
+    /** Skip these analysts even if registered. Useful for cheap iteration. */
+    skip?: string[];
+    /** Budget policy — totalUsd + optional weights/allocator. Falls back to options.defaultBudget. */
+    budget?: BudgetPolicy;
+    /** Active-work cap for the complete registry run. Model receipt settlement may follow. */
+    timeoutMs?: number;
+    /** Abort signal — forwarded into every analyst's context. */
+    signal?: AbortSignal;
+    /** Shared paid-call account forwarded to every analyst. */
+    costLedger?: CostLedgerHandle;
+    /** Attribution phase for calls written to `costLedger`. */
+    costPhase?: string;
+    /** Tags echoed into AnalystContext.tags — useful for tracking environment/version in findings. */
+    tags?: Record<string, string>;
+    /**
+     * Prior-run findings made available as retrieval context to every
+     * analyst via `ctx.priorFindings`. The registry forwards the slice
+     * whose `analyst_id` matches each registered analyst so a kind sees
+     * only its own history. Pass `{ '*': findings }` to broadcast to
+     * every analyst (useful when several kinds share the same historical
+     * context). For findings from this run, use `chainFindings` instead.
+     */
+    priorFindings?: ReadonlyArray<AnalystFinding> | Record<string, ReadonlyArray<AnalystFinding>>;
+    /**
+     * Pass findings produced earlier in this registry run to each later analyst
+     * via `ctx.upstreamFindings`. Registration order is dependency order.
+     * Disabled by default because independent analyst suites must opt in.
+     */
+    chainFindings?: boolean;
+}
+declare class AnalystRegistry {
+    private readonly analysts;
+    private readonly options;
+    constructor(options?: AnalystRegistryOptions);
+    register(analyst: Analyst): void;
+    list(): ReadonlyArray<{
+        id: string;
+        description: string;
+        version: string;
+        cost: Analyst['cost'];
+    }>;
+    run(runId: string, inputs: AnalystRunInputs, runOpts?: RegistryRunOpts): Promise<AnalystRunResult>;
+    /**
+     * 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.
+     */
+    runStream(runId: string, inputs: AnalystRunInputs, runOpts?: RegistryRunOpts): AsyncGenerator<AnalystRunEvent, void, void>;
+    private selectAnalysts;
+    private routeInput;
+}
+
+/**
+ * `buildDefaultAnalystRegistry` — the canonical analyst suite, so consumers
+ * stop hand-wiring `new AnalystRegistry()` + per-kind `createTraceAnalystKind`.
+ *
+ * The deterministic `behavioralAnalyst` is ALWAYS registered (it needs no
+ * model and is model-agnostic by construction). The agentic RLM kinds are
+ * registered only when an `ai` service is supplied — so a caller with no LLM
+ * still gets the full behavioral/efficiency diagnosis, and the substrate's
+ * "any model (including no model)" guarantee holds at the suite level.
+ */
+
+interface DefaultAnalystRegistryOptions {
+    /** Ax service for the agentic RLM kinds. Omit → only the deterministic analyst. */
+    ai?: AxAIService;
+    /** Required unless `ai` was created by `createAnalystAi`. */
+    model?: string;
+    /** Which agentic kinds to register when `ai` is present. Default = the shipped suite. */
+    kinds?: readonly TraceAnalystKindSpec[];
+    /** Set false to omit the deterministic behavioral analyst (default: include). */
+    includeBehavioral?: boolean;
+    /** Forwarded to the AnalystRegistry constructor (signal, tags, priorFindings). */
+    registry?: AnalystRegistryOptions;
+}
+declare function buildDefaultAnalystRegistry(opts?: DefaultAnalystRegistryOptions): AnalystRegistry;
+
+/**
+ * Typed `FindingSubject` — the canonical grammar every analyst kind emits.
+ *
+ * Background: kind actor prompts have always documented a subject grammar
+ * (e.g. `system-prompt:<section>`, `agent-knowledge:wiki:<slug>`) but the
+ * LLM was unconstrained — it could emit `subject: "fix the prompt"`
+ * (prose) and downstream adapters routed on `startsWith(...)` would
+ * silently skip it. Every per-vertical `ImprovementAdapter` had a
+ * routing table that mostly caught nothing.
+ *
+ * This module fixes that:
+ *   - `parseFindingSubject(raw)` — returns the typed `FindingSubject`
+ *     when `raw` matches the grammar, else `null`. Used at the
+ *     `RawAnalystFindingSchema` boundary so malformed subjects are
+ *     rejected loudly instead of silently lifted into the registry.
+ *   - `FindingSubjectKind` — the union of valid locus categories. Each
+ *     variant carries the typed components downstream adapters resolve
+ *     against the agent's surface manifest (no string parsing in the
+ *     adapter).
+ *   - `FINDING_SUBJECT_GRAMMAR_PROMPT` — single source of truth for the
+ *     grammar string embedded in kind actor prompts. Drift between
+ *     prompt and parser is impossible if every kind imports this.
+ *
+ * The grammar is intentionally NARROW — only loci the substrate's
+ * default `ImprovementAdapter` / `KnowledgeAdapter` can act on. A
+ * finding with a subject outside this set fails the parser; the kind
+ * author either extends the grammar here (and adds adapter routing)
+ * or rephrases the prompt to map onto an existing variant.
+ *
+ * `failure-mode` is the one exception — its subjects are free-form
+ * cluster labels, not loci. The schema preserves them as
+ * `{ kind: 'cluster', label }` and the adapters skip them (cluster
+ * findings are evidence, not actionable mutations).
+ */
+
+/**
+ * Discriminated union of every locus the substrate can route findings to.
+ *
+ * Adapters narrow on `kind` and use the typed components (no string
+ * parsing). Adding a variant here REQUIRES updating the parser, the
+ * grammar prompt, and at least one adapter — by design.
+ */
+type FindingSubject = {
+    kind: 'knowledge.wiki';
+    slug: string;
+    heading?: string;
+} | {
+    kind: 'knowledge.claim';
+    topic: string;
+} | {
+    kind: 'knowledge.raw';
+    sourceId: string;
+} | {
+    kind: 'knowledge.stale';
+    slug: string;
+} | {
+    kind: 'system-prompt';
+    section: string;
+} | {
+    kind: 'skill';
+    name: string;
+} | {
+    kind: 'tool-doc';
+    tool: string;
+    aspect?: string;
+} | {
+    kind: 'new-tool';
+    name: string;
+} | {
+    kind: 'mcp';
+    server: string;
+    tool?: string;
+} | {
+    kind: 'hook';
+    name: string;
+} | {
+    kind: 'subagent';
+    name: string;
+} | {
+    kind: 'workflow';
+    name: string;
+} | {
+    kind: 'rollout-policy';
+    field: string;
+} | {
+    kind: 'agent-profile';
+    field: string;
+} | {
+    kind: 'code';
+    path: string;
+} | {
+    kind: 'rag';
+    corpus: string;
+    docId: string;
+} | {
+    kind: 'memory';
+    key: string;
+} | {
+    kind: 'scaffolding';
+    concern: string;
+} | {
+    kind: 'output-schema';
+    field: string;
+} | {
+    kind: 'websearch.outdated';
+    topic: string;
+} | {
+    kind: 'prior-run-summary';
+    topic: string;
+} | {
+    kind: 'cluster';
+    label: string;
+};
+type FindingSubjectKind = FindingSubject['kind'];
+declare const FINDING_SUBJECT_KINDS: ReadonlyArray<FindingSubjectKind>;
+/**
+ * Parse a raw subject string emitted by an analyst kind's actor.
+ *
+ * Returns the typed `FindingSubject` when `raw` matches the grammar,
+ * else `null`. Callers use the `null` return as a signal to either
+ * (a) reject the finding at parse time (kinds that emit typed loci —
+ * knowledge-gap, improvement, knowledge-poisoning) or (b) lift it as
+ * a cluster label (failure-mode).
+ *
+ * Slugs are constrained to `[a-z0-9-]+` (lowercase kebab) to keep file
+ * paths sane downstream. Topics / keys / sections allow any non-empty
+ * string (free-form for the LLM's voice) but get trimmed.
+ *
+ * Empty / whitespace-only inputs return `null`. `undefined` returns
+ * `null`. Both are surfaced by the caller as a rejected subject.
+ */
+declare function parseFindingSubject(raw: string | null | undefined): FindingSubject | null;
+/**
+ * Render the parsed subject back to its canonical string form. Inverse
+ * of `parseFindingSubject`; useful when the substrate constructs new
+ * findings programmatically (e.g. for tests, replays, or
+ * `id_basis` carry-forward).
+ */
+declare function renderFindingSubject(s: FindingSubject): string;
+/**
+ * The grammar text embedded into kind actor prompts. Kinds opt into
+ * the subset of variants they emit (e.g. `improvement` excludes the
+ * cluster variant; `failure-mode` includes ONLY the cluster variant).
+ *
+ * Drift between prompt and parser is impossible: every kind imports
+ * this constant + the matching `expects` set, and the unit tests below
+ * lock the table to the parser.
+ */
+declare const FINDING_SUBJECT_SYNTAX: Readonly<Record<FindingSubjectKind, string>>;
+declare const FINDING_SUBJECT_GRAMMAR_PROMPT: string;
+/**
+ * The variants each kind is allowed to emit. Used at the kind factory
+ * boundary so a knowledge-gap finding can't sneak in a `system-prompt:*`
+ * subject (the improvement-analyst's job) and vice versa.
+ *
+ * `failure-mode` is restricted to `cluster` — the only kind that emits
+ * a non-locus subject.
+ */
+declare const KIND_EXPECTED_SUBJECTS: Record<string, ReadonlyArray<FindingSubjectKind>>;
+/** Render only the subject forms one analyst kind is permitted to emit. */
+declare function findingSubjectGrammarPromptFor(kindId: string): string;
+/**
+ * Zod schema that validates a raw subject string and returns the parsed
+ * `FindingSubject`. Embedded in `RawAnalystFindingSchema` via
+ * `transform`, so `subject` arrives at the kind factory either as a
+ * typed locus or as a parse error attached to a single Zod issue.
+ *
+ * Optionality is preserved: subjects ARE optional on the wire (some
+ * findings are descriptive, not actionable). When present, they MUST
+ * parse — emitting a malformed subject is a contract violation, not a
+ * soft signal.
+ */
+declare const FindingSubjectStringSchema: z.ZodString;
+
+/**
+ * FindingsStore — durable persistence for AnalystFinding rows + a diff
+ * helper so we can answer "what changed since the last run?" without
+ * recomputing analysts.
+ *
+ * On-disk shape is JSONL: one finding per line, append-only, locked via
+ * LockedJsonlAppender. Operators get crash-safety (no partial JSON),
+ * cheap reads (sequential parse), and trivial backup (rsync the file).
+ *
+ * Reads are non-locking: a reader sees a consistent snapshot of all
+ * fully-written lines and skips an incomplete trailing line if the
+ * writer is mid-append. Cross-process locking is intentionally out of
+ * scope (see locked-jsonl-appender.ts).
+ *
+ * The store is run-scoped: callers pass `runId` on append and on load,
+ * which keeps multi-run files cleanly partitioned. The `diffFindings`
+ * helper compares two run-id sets using stable `finding_id` semantics —
+ * the diff is the cross-run signal the regression dashboard renders.
+ */
+
+/**
+ * One persisted row. We attach `run_id` on disk so a single file can
+ * hold multiple runs and the diff helper can query without re-walking
+ * separate files.
+ */
+interface PersistedFinding extends AnalystFinding {
+    run_id: string;
+}
+declare class FindingsStore {
+    readonly path: string;
+    private readonly appender;
+    constructor(path: string);
+    append(runId: string, findings: AnalystFinding[]): Promise<void>;
+    /** Load every persisted finding. Discards malformed trailing lines silently. */
+    loadAll(): PersistedFinding[];
+    /** Filter to a single run. */
+    loadRun(runId: string): PersistedFinding[];
+}
+interface FindingsDiff {
+    /** New finding ids in `current` that weren't in `previous`. */
+    appeared: PersistedFinding[];
+    /** Finding ids in `previous` that aren't in `current`. */
+    disappeared: PersistedFinding[];
+    /** Same finding id present in both runs and unchanged per the materiality test. */
+    persisted: PersistedFinding[];
+    /**
+     * Same finding id in both runs but at least one non-identity field
+     * shifted per `DiffPolicy.isMaterial`. Reported as [previous, current].
+     */
+    changed: Array<{
+        previous: PersistedFinding;
+        current: PersistedFinding;
+    }>;
+}
+interface DiffPolicy {
+    /**
+     * Predicate that decides whether two findings (same finding_id) count
+     * as a material change. Defaults to {@link defaultIsMaterial}: severity
+     * shift, confidence Δ > 0.05, or evidence count change. Compliance /
+     * perf consumers MAY supply a stricter predicate (e.g. rationale text
+     * diff, metric Δ thresholds).
+     */
+    isMaterial?: (previous: AnalystFinding, current: AnalystFinding) => boolean;
+}
+/**
+ * Default materiality test. Deliberately narrow so LLM-reword churn
+ * doesn't flood the diff. Stricter tests are opt-in via DiffPolicy.
+ */
+declare function defaultIsMaterial(a: AnalystFinding, b: AnalystFinding): boolean;
+/**
+ * Diff two findings sets by stable finding_id. Callers typically load
+ * the two run-id slices from the same store and pass them in.
+ */
+declare function diffFindings(previous: PersistedFinding[], current: PersistedFinding[], policy?: DiffPolicy): FindingsDiff;
+
+/**
+ * Failure-mode analyst — classifies what went wrong and why.
+ *
+ * Brief: read the trace dataset, identify the top failure modes across
+ * runs, classify each with severity + evidence, and surface them as
+ * findings. The actor's job is *taxonomy + evidence*, not fix-design —
+ * that's the improvement-analyst's job.
+ *
+ * Eight bounded model subqueries let the actor compare candidate
+ * clusters in parallel after it has loaded representative evidence.
+ */
+
+declare const FAILURE_MODE_KIND_SPEC: TraceAnalystKindSpec;
+
+/**
+ * Improvement analyst — actionable self-improvement findings.
+ *
+ * Brief: read findings from upstream analysts (failure-mode,
+ * knowledge-gap, knowledge-poisoning) AND the trace dataset itself,
+ * then propose **concrete edits** to the agent's runtime: prompt
+ * additions, RAG documents to ingest, tool descriptions to rewrite,
+ * scaffolding changes to make, memory entries to invalidate. Each
+ * finding is one proposed edit with the locus, the diff, and the
+ * expected effect.
+ *
+ * This is the self-improvement loop's last mile: the prior
+ * kinds describe *what's wrong*; this kind describes *what to change*.
+ *
+ * Eight bounded model subqueries let the actor compare competing fix
+ * directions over the same cited evidence before recommending one.
+ */
+
+declare const IMPROVEMENT_KIND_SPEC: TraceAnalystKindSpec;
+
+/**
+ * Knowledge-gap analyst — what did the agent NOT know that it needed?
+ *
+ * Brief: find moments in the trace where the agent had to guess, ask
+ * the user to fill in context, recover from a wrong assumption, or
+ * loop on a retrieval. Each finding names a *missing or outdated piece
+ * of knowledge* the agent's curated knowledge base should have held —
+ * or a downstream lookup (web, docs, tool description) that surfaced
+ * stale or outdated information.
+ *
+ * The primary expected store is `@tangle-network/agent-knowledge`: a
+ * Karpathy-style wiki the agent maintains with raw ↔ curated pages,
+ * source anchors, and claim/relation triples. A gap is anything the
+ * agent had to discover at run-time that should already have lived
+ * there. Secondary loci: web-search results that returned outdated
+ * pages, tool descriptions that omitted critical behavior, system-
+ * prompt sections that didn't cover the case.
+ *
+ * Distinct from failure-mode: failure-mode classifies *how* it broke;
+ * knowledge-gap names the *information* whose absence (or staleness)
+ * caused the break. One failure-mode often maps to several gaps.
+ *
+ * Five bounded model subqueries let the actor compare candidate gaps
+ * across source layers after it has loaded the relevant excerpts.
+ */
+
+declare const KNOWLEDGE_GAP_KIND_SPEC: TraceAnalystKindSpec;
+
+/**
+ * Knowledge-poisoning analyst — what FALSE information misled the agent?
+ *
+ * Brief: find moments where the agent acted on information that was
+ * *wrong* — stale memory, RAG documents that contradicted ground truth,
+ * tool descriptions that lied about return shapes, system-prompt
+ * instructions that no longer matched reality, prior-run summaries that
+ * cached a wrong decision.
+ *
+ * Distinct from knowledge-gap: a gap is "the agent didn't know X"; a
+ * poisoning is "the agent confidently used X, but X was wrong." Gaps
+ * surface as questions / self-correction; poisonings surface as
+ * confident-but-wrong actions that downstream evidence contradicts.
+ *
+ * Eight bounded model subqueries let the actor independently assess
+ * the action and contradiction excerpts for candidate poisonings.
+ */
+
+declare const KNOWLEDGE_POISONING_KIND_SPEC: TraceAnalystKindSpec;
+
+/**
+ * Default analyst kinds focused on agent failure + recursive
+ * self-improvement.
+ *
+ * The four kinds chain: failure-mode classifies; knowledge-gap and
+ * knowledge-poisoning explain *why* in two orthogonal ways; improvement
+ * proposes concrete edits. Register all four against the same trace
+ * store in this order and run the registry with `chainFindings: true`
+ * to pass each completed kind's findings to the kinds that follow it.
+ */
+
+/**
+ * The default kind suite. Order is the run order operators should
+ * use: failure-mode first (no upstream deps), gap + poisoning next
+ * (both depend on failures), improvement last (chains all three).
+ */
+declare const DEFAULT_TRACE_ANALYST_KINDS: readonly TraceAnalystKindSpec[];
+
+/**
+ * Skill-usage analyst — a DETERMINISTIC `Analyst` over a Claude/Codex skill
+ * library + its trace corpus. Unlike the trace-store kinds (failure-mode,
+ * improvement, ...) this kind calls no LLM: it mines real usage and skill
+ * structure and emits findings by rule.
+ *
+ * It exists because the naive "Skill-tool invocation count" lies low — it
+ * misses orchestrated sub-dispatch (a leaf skill run BY /pursue or /governor
+ * logs under the parent), slash-command entry, local-script bypass, and
+ * on-disk artifacts. The 2026-05-30 skill audit found 39/53 skills at zero
+ * direct invocations, yet only one was a genuine cut: the rest were
+ * measurement-invisible or discovery-limited. This analyst encodes that
+ * lesson as a multi-signal usage model so a cheap repeatable pass can keep
+ * the library honest, and so the expensive audit workflow's verdicts can
+ * GEPA-distill it toward agreement (see `gold/skill-verdicts.gold.jsonl`).
+ *
+ * Report-building (`buildSkillUsageReport`, an fs scan) is separated from
+ * finding emission (`SkillUsageAnalyst.analyze`, pure) so the slow scan runs
+ * once at the registry boundary and the rule logic stays unit-testable.
+ */
+
+type SkillKind = 'public' | 'private';
+/** One skill's multi-signal usage + structure. All counts are deterministic. */
+interface SkillUsageRecord {
+    name: string;
+    kind: SkillKind;
+    /** Absolute path to the skill's SKILL.md. */
+    path: string;
+    lines: number;
+    /** `"skill":"<name>"` Skill-tool invocations across the trace corpus. */
+    directInvocations: number;
+    /** `<command-name>/<name>` slash invocations across the trace corpus. */
+    slashInvocations: number;
+    /** Sibling skills whose SKILL.md dispatches to this one (`/<name>`). Proxy
+     *  for orchestrated sub-dispatch the per-skill counter cannot see. */
+    inboundRefs: number;
+    /** On-disk artifacts attributable to the skill (e.g. `.evolve/<name>/**`). */
+    artifactCount: number;
+    /** Tangle-private reference count in the body (leak signal for public skills). */
+    tanglePrivateRefs: number;
+    hasReferencesDir: boolean;
+    hasEvalsDir: boolean;
+    /** Body mentions `skill-runs.jsonl` (visible to /reflect + /governor). */
+    logsRuns: boolean;
+    /** Description carries an explicit `Triggers:` clause / trigger phrases. */
+    hasTriggerPhrases: boolean;
+}
+interface SkillUsageReport {
+    generatedFromTraces: number;
+    records: SkillUsageRecord[];
+}
+interface SkillUsageScanConfig {
+    /** Dirs holding `*.jsonl` transcripts (Claude `~/.claude/projects`, Codex sessions). */
+    transcriptDirs: string[];
+    /** Skill roots to scan; each dir directly under `root` with a `SKILL.md` is a skill. */
+    skillRoots: {
+        root: string;
+        kind: SkillKind;
+    }[];
+    /** Roots scanned for `<root>/.evolve/<skill>` artifact dirs. */
+    artifactRoots?: string[];
+    /** Token-prefixed mappings: skill name → extra artifact subpaths under an artifactRoot
+     *  (e.g. reflect → `.evolve/reflections`). Catches non-eponymous artifact dirs. */
+    artifactAliases?: Record<string, string[]>;
+    /** Cap files read per transcript dir (bounds a huge corpus); 0 = unbounded. */
+    maxTranscriptsPerDir?: number;
+}
+/** Scan the corpus + skill roots into a {@link SkillUsageReport}. Deterministic. */
+declare function buildSkillUsageReport(config: SkillUsageScanConfig): SkillUsageReport;
+/** Pure rule pass over a report → findings. Exported for direct/unit use. */
+declare function emitSkillUsageFindings(report: SkillUsageReport, producedAt: string): AnalystFinding[];
+declare class SkillUsageAnalyst implements Analyst<SkillUsageReport> {
+    readonly id = "skill-usage";
+    readonly description = "Deterministic multi-signal skill-usage analysis: flags dead skills, measurement-invisible (orchestrated) usage, discovery gaps, public-repo leaks, bloat, missing evals, and missing run-logging.";
+    readonly inputKind: "custom";
+    readonly cost: {
+        kind: "deterministic";
+        est_usd_per_run: number;
+    };
+    readonly version = "1.0.0";
+    analyze(input: SkillUsageReport, ctx: AnalystContext): Promise<AnalystFinding[]>;
+}
+declare const SKILL_USAGE_ANALYST: SkillUsageAnalyst;
+
+/**
+ * Forgiving pre-parse for analyst findings. Weak models routinely emit
+ * schema-correct content in an unusable wrapper — fenced ```json blocks, a
+ * single object where an array is expected, trailing commas. Measured: GPT-4o
+ * drops to 0% usable output purely from markdown-fence wrapping
+ * (arXiv:2605.02363). A five-line de-fence recovers most of it. This module is
+ * the de-fence/coerce step that runs BEFORE Zod, so a recoverable finding is
+ * repaired, not dropped.
+ *
+ * Pure + deterministic. No model, no network.
+ */
+/** Strip a ```lang ... ``` (or bare ``` ... ```) code fence, if the string is one. */
+declare function stripCodeFences(text: string): string;
+/**
+ * Best-effort parse of a string into JSON. De-fences, drops trailing commas,
+ * then `JSON.parse`. Returns `undefined` (never throws) when unrecoverable.
+ */
+declare function coerceJson(text: string): unknown;
+/**
+ * Coerce arbitrary actor/structurer output into an array of candidate finding
+ * rows: a JSON string → parse; a single object → 1-element array; an array →
+ * as-is; anything else → []. Callers still run each row through Zod
+ * (`parseCanonicalRawFinding`) — this only fixes the SHAPE, never invents fields.
+ */
+declare function coerceToFindingRows(raw: unknown): unknown[];
+
+type PolicyEditSchemaVersion = 'policy-edit/v1';
+declare const POLICY_EDIT_AXES: readonly ["carrier", "representation", "budget", "sampling", "output_contract", "tool_contract", "routing", "memory", "agent_profile", "deployment_target"];
+type PolicyEditAxis = (typeof POLICY_EDIT_AXES)[number];
+declare const POLICY_EDIT_TARGET_SURFACES: readonly ["prompt", "tool-contract", "runtime-config", "memory", "agent-profile", "code", "deployment"];
+type PolicyEditTargetSurface = (typeof POLICY_EDIT_TARGET_SURFACES)[number];
+type PolicyEditRisk = 'low' | 'medium' | 'high' | 'unknown';
+type PolicyEditGainDirection = 'increase' | 'decrease';
+type PolicyEditGainUnit = 'absolute' | 'relative' | 'percent' | 'score';
+interface PolicyEditTarget {
+    surface: PolicyEditTargetSurface;
+    /** Stable path inside the target surface, for example `system-prompt:tools`
+     * or `budget.maxTurns`. */
+    path?: string;
+    /** Optional canonical deployment identity. Store the existing cell, not a
+     * local profile shape. */
+    agentProfileCell?: AgentProfileCell;
+    /** Human label when the path is not enough for a readable audit trail. */
+    label?: string;
+}
+type PolicyEditChange = {
+    kind: 'text';
+    mode: 'append' | 'prepend' | 'replace';
+    value: string;
+    /** Required when `mode === 'replace'`; exact match only. */
+    find?: string;
+} | {
+    kind: 'json';
+    mode: 'set' | 'merge' | 'remove';
+    path: string;
+    value?: AgentProfileJson;
+};
+interface PolicyEditExpectedGain {
+    /** Metric this edit is expected to move, e.g. `holdout.composite`. */
+    metric: string;
+    direction: PolicyEditGainDirection;
+    /** Positive magnitude in the metric's native units. */
+    amount: number;
+    unit?: PolicyEditGainUnit;
+    rationale?: string;
+}
+interface PolicyEditSource {
+    findingIds: string[];
+    analystIds: string[];
+    evidenceRefs: EvidenceRef[];
+    /** Mirrors `AnalystFinding.derived_from_judge`; admission rejects it. */
+    derivedFromJudge?: boolean;
+}
+interface PolicyEdit {
+    schemaVersion: PolicyEditSchemaVersion;
+    editId: string;
+    axis: PolicyEditAxis;
+    target: PolicyEditTarget;
+    change: PolicyEditChange;
+    claim: string;
+    expectedGain: PolicyEditExpectedGain;
+    confidence: number;
+    risk: PolicyEditRisk;
+    source: PolicyEditSource;
+    rationale?: string;
+    validationPlan?: string;
+    metadata?: Record<string, unknown>;
+}
+declare const POLICY_EDIT_CANDIDATE_RECORD_SCHEMA: "tangle.policy-edit-candidate.v1";
+/** JSON-safe attribution carried with a measured candidate and its scores. */
+interface PolicyEditCandidateRecord {
+    schema: typeof POLICY_EDIT_CANDIDATE_RECORD_SCHEMA;
+    policyEdit: PolicyEdit;
+}
+type PolicyEditInit = Omit<PolicyEdit, 'schemaVersion' | 'editId'> & {
+    schemaVersion?: PolicyEditSchemaVersion;
+    editId?: string;
+};
+declare class PolicyEditValidationError extends ValidationError {
+    readonly path: string;
+    constructor(message: string, path?: string);
+}
+interface FindingToPolicyEditOptions {
+    expectedGain?: PolicyEditExpectedGain | ((finding: AnalystFinding) => PolicyEditExpectedGain | null | undefined);
+    risk?: PolicyEditRisk | ((finding: AnalystFinding) => PolicyEditRisk);
+    defaultAxis?: PolicyEditAxis;
+    defaultTargetSurface?: PolicyEditTargetSurface;
+}
+interface PolicyEditAdmissionOptions {
+    minScore?: number;
+    minExpectedGain?: number;
+    allowHighRisk?: boolean;
+    requireEvidence?: boolean;
+}
+interface PolicyEditAdmission {
+    edit: PolicyEdit;
+    decision: 'admit' | 'reject';
+    score: number;
+    reasons: string[];
+}
+declare function makePolicyEdit(init: PolicyEditInit): PolicyEdit;
+declare function computePolicyEditId(edit: Omit<PolicyEdit, 'editId'> | PolicyEdit): string;
+declare function validatePolicyEdit(input: unknown): PolicyEdit;
+declare function makePolicyEditCandidateRecord(edit: PolicyEdit): PolicyEditCandidateRecord;
+declare function validatePolicyEditCandidateRecord(input: unknown): PolicyEditCandidateRecord;
+declare function isPolicyEdit(input: unknown): input is PolicyEdit;
+declare function policyEditsFromFindings(findings: ReadonlyArray<AnalystFinding>, opts?: FindingToPolicyEditOptions): PolicyEdit[];
+declare function policyEditFromFinding(finding: AnalystFinding, opts?: FindingToPolicyEditOptions): PolicyEdit | null;
+declare function scorePolicyEditReadiness(edit: PolicyEdit, opts?: PolicyEditAdmissionOptions): number;
+declare function admitPolicyEdit(edit: PolicyEdit, opts?: PolicyEditAdmissionOptions): PolicyEditAdmission;
+declare function applyPolicyEditToSurface(surface: unknown, edit: PolicyEdit): unknown;
+
+/** DESCRIPTIVE predicate: does the finding cite at least one observable
+ *  (span/event/artifact) evidence ref. Useful for ranking evidence quality or
+ *  rendering — it is NOT the steer gate. Evidence presence is the WRONG
+ *  discriminator for steering: a legitimate trace-analyst observation may cite
+ *  nothing (it would be wrongly rejected), and a judge verdict may cite an
+ *  artifact (it would be wrongly admitted). Use `assertNoJudgeVerdict` to gate
+ *  steering; use this only where "is this grounded in observable evidence" is the
+ *  literal question. */
+declare function isTraceObservable(finding: AnalystFinding): boolean;
+/** True iff the finding is a JUDGE VERDICT (an acceptance score lifted into a
+ *  finding), identified by provenance set at the lift site — independent of
+ *  whatever evidence it cites. */
+declare function isJudgeVerdict(finding: AnalystFinding): boolean;
+/**
+ * THE steer firewall. Fail-loud guard for any path that admits analyst findings
+ * as STEERING input (the `f(trace)` role): rejects — naming the offenders — any
+ * finding whose provenance is a judge verdict, rather than let `J` leak into the
+ * loop. Returns the findings unchanged for chaining.
+ *
+ * Call this at the chokepoint where a detector that ALSO scores/gates has its
+ * findings turned into a steer (the judge-and-steer dual-role case). It keys on
+ * provenance, so it correctly admits evidence-less trace-analyst observations and
+ * correctly rejects an artifact-citing judge verdict — the cases an evidence
+ * check gets backwards.
+ *
+ * It is necessary, not sufficient: it stops PROVENANCE-tagged verdicts. A judge
+ * whose output is laundered through a hand-built finding with no provenance flag
+ * is out of its reach — provenance must be honestly set at every judge→finding
+ * lift (today: createJudgeAdapter). That is why the integrity rule lives at the
+ * lift site, and why ProposeContext.judgeScores?: never is the complementary
+ * compile-time tripwire on the obvious direct channel.
+ */
+declare function assertNoJudgeVerdict(findings: ReadonlyArray<AnalystFinding>, context?: string): ReadonlyArray<AnalystFinding>;
+
+/**
+ * `structureFindings` — the deferred structuring pass (DSPy TwoStepAdapter /
+ * HALO `synthesize_traces` analog). The agentic actor reasons FREE-FORM and
+ * emits a prose `report` (which any model does reliably); this separate, cheap
+ * call's ONLY job is to turn that report into `AnalystFinding[]`. Decoupling
+ * reasoning from structuring is what makes the SEMANTIC findings model-agnostic
+ * — the reasoning model never has to satisfy a strict typed-array contract
+ * while it diagnoses.
+ *
+ * Forgiving: the response runs through `coerceToFindingRows` (de-fence, lift
+ * single→array) before Zod, and on a zero-finding extraction from a substantive
+ * report it reasks ONCE with the schema restated. Returns a typed outcome so a
+ * legitimate "nothing to report" is distinguishable from a failed extraction
+ * (no silent empty).
+ */
+
+interface StructureFindingsOptions {
+    /** The actor's free-form diagnosis prose. */
+    report: string;
+    analystId: string;
+    /** Coarse classification stamped on every extracted finding. */
+    area: string;
+    model: string;
+    baseUrl: string;
+    apiKey?: string;
+    /** Optional ledger for direct use. */
+    costLedger?: CostLedgerHandle;
+    costPhase?: string;
+    costTags?: Record<string, string>;
+    maxTokens?: number;
+    signal?: AbortSignal;
+    /** Max reask attempts after a zero/invalid extraction. Default 1. */
+    maxReasks?: number;
+    /** Apply the caller's normal finding rules before a recovered row is lifted. */
+    processRow?: (row: RawAnalystFinding) => RawAnalystFinding | null;
+    /** Apply canonical multi-citation rules after any original callback. */
+    processCanonicalRow?: (row: CanonicalRawAnalystFinding) => CanonicalRawAnalystFinding | null;
+    /** Provenance copied onto every recovered finding. */
+    findingMetadata?: Record<string, unknown>;
+    /** Test seam: inject a fetch (no network in unit tests). */
+    fetchImpl?: LlmClientOptions['fetch'];
+}
+interface StructureFindingsResult {
+    findings: AnalystFinding[];
+    outcome: 'ok' | 'extraction_failed';
+}
+declare function structureFindings(opts: StructureFindingsOptions): Promise<StructureFindingsResult>;
+
+/**
+ * Pre-curated tool subsets for analyst kinds.
+ *
+ * The full trace-analyst tool set is seven functions. Most kinds only
+ * need three or four. Picking from named groups instead of importing
+ * the whole bundle keeps every kind's actor-context budget tight and
+ * makes "what can this analyst see?" obvious at registration time.
+ *
+ * Each function in the group keeps its full `name`/`description` from
+ * `buildTraceAnalystTools` — we filter, we don't re-implement.
+ */
+
+/** Named tool sets. Kinds pass `tools: TRACE_TOOL_GROUPS.failureForensics` etc. */
+type TraceToolGroupName = 
+/** All seven tools. Use for open-ended discovery kinds. */
+'all'
+/** Overview + paginated query + count. No deep reads. Cheap. */
+ | 'discovery'
+/** Discovery + viewTrace + viewSpans. Deep-read but no regex search. */
+ | 'discoveryAndRead'
+/** Discovery + search tools. For pattern-matching across many traces. */
+ | 'discoveryAndSearch'
+/** Discovery + viewSpans + searchSpan. Targeted-span work after another kind narrows down. */
+ | 'targeted';
+/**
+ * Build the tool set for a named group bound to a specific trace store.
+ *
+ * `all` returns every tool. Other groups filter `buildTraceAnalystTools`
+ * by name to the documented subset. An unrecognised group name throws —
+ * silently returning all tools would defeat the cost-control point.
+ */
+declare function buildTraceToolsForGroup(group: TraceToolGroupName, store: TraceAnalysisStore): AxFunction[];
+
+export { ANALYST_SEVERITIES, type Analyst, type AnalystContext, type AnalystCost, type AnalystFinding, type AnalystHooks, type AnalystInputKind, AnalystRegistry, type AnalystRegistryOptions, type AnalystRequirements, type AnalystRunEvent, type AnalystRunInputs, type AnalystRunResult, type AnalystRunSummary, type AnalystSeverity, type AnalystUsageReceipt, type BudgetPolicy, type CanonicalRawAnalystFinding, CanonicalRawAnalystFindingSchema, type ChatCallOpts, type ChatClient, type ChatRequest, type ChatResponse, type ChatTransport, type CliBridgeTransportOpts, type CreateAnalystAiConfig, type CreateChatClientOpts, type CreateTraceAnalystKindOpts, DEFAULT_TRACE_ANALYST_KINDS, type DefaultAnalystRegistryOptions, type DiffPolicy, type DirectProviderTransportOpts, type EvidenceRef, FAILURE_MODE_KIND_SPEC, FINDING_SUBJECT_GRAMMAR_PROMPT, FINDING_SUBJECT_KINDS, FINDING_SUBJECT_SYNTAX, type FindingSubject, type FindingSubjectKind, FindingSubjectStringSchema, type FindingToPolicyEditOptions, type FindingsDiff, FindingsStore, IMPROVEMENT_KIND_SPEC, type JudgeAdapterOpts, KIND_EXPECTED_SUBJECTS, KNOWLEDGE_GAP_KIND_SPEC, KNOWLEDGE_POISONING_KIND_SPEC, type MockTransportOpts, POLICY_EDIT_AXES, POLICY_EDIT_CANDIDATE_RECORD_SCHEMA, POLICY_EDIT_TARGET_SURFACES, type PersistedFinding, type PolicyEdit, type PolicyEditAdmission, type PolicyEditAdmissionOptions, type PolicyEditAxis, type PolicyEditCandidateRecord, type PolicyEditChange, type PolicyEditExpectedGain, type PolicyEditGainDirection, type PolicyEditGainUnit, type PolicyEditInit, type PolicyEditRisk, type PolicyEditSchemaVersion, type PolicyEditSource, type PolicyEditTarget, type PolicyEditTargetSurface, PolicyEditValidationError, RAW_FINDING_SCHEMA_PROMPT, type RawAnalystEvidence, RawAnalystEvidenceSchema, type RawAnalystFinding, RawAnalystFindingSchema, type RegistryRunOpts, type RouterTransportOpts, type RunCriticAdapterOpts, SKILL_USAGE_ANALYST, type SandboxSdkTransportOpts, type SemanticConceptJudgeAdapterOpts, SkillUsageAnalyst, type SkillUsageRecord, type SkillUsageReport, type SkillUsageScanConfig, type StructureFindingsOptions, type StructureFindingsResult, type TraceAnalystGolden, type TraceAnalystKindSpec, type TraceToolGroupName, type VerifierAdapterOpts, admitPolicyEdit, applyPolicyEditToSurface, assertNoJudgeVerdict, behavioralAnalyst, buildDefaultAnalystRegistry, buildSkillUsageReport, buildTraceToolsForGroup, coerceJson, coerceToFindingRows, computeFindingId, computePolicyEditId, createAnalystAi, createChatClient, createJudgeAdapter, createRunCriticAdapter, createSemanticConceptJudgeAdapter, createTraceAnalystKind, createVerifierAdapter, defaultIsMaterial, deriveEfficiencyFindings, diffFindings, emitSkillUsageFindings, evidenceRefsFromRawFinding, findingSubjectGrammarPromptFor, isJudgeVerdict, isPolicyEdit, isTraceObservable, liftSeverity, makeFinding, makePolicyEdit, makePolicyEditCandidateRecord, parseCanonicalRawFinding, parseFindingSubject, parseRawFinding, policyEditFromFinding, policyEditsFromFindings, renderFindingSubject, renderPriorFindings, renderUpstreamFindings, scorePolicyEditReadiness, stripCodeFences, structureFindings, validatePolicyEdit, validatePolicyEditCandidateRecord };