@tangle-network/agent-eval 0.118.3 → 0.119.1

package/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to `@tangle-network/agent-eval` and its sibling `agent-eval-
 
 ---
 
+## [0.119.1] — 2026-07-14 — portable improvement evidence
+
+### Added
+
+- `measuredComparisonFromSelfImproveResult()` converts paired held-out quality, cost, latency, uncertainty, power, decision, and provenance into the shared `AgentImprovementMeasuredComparison` contract.
+
+## [0.119.0] — 2026-07-14 — chained, metered trace analysis
+
+### Added
+
+- Trace analysts can consume findings produced earlier in the same ordered run and emit multiple evidence citations without changing the original singular-citation callback API.
+- Analyst summaries report provider calls, input, output, reasoning, cache-read, cache-write, dollar provenance, and known partial spend independently of finding count.
+
+### Fixed
+
+- All Ax analyst calls reserve spend before dispatch, disable hidden provider retries, honor cancellation, wait a bounded time for late receipts, and preserve known charges when token usage is unavailable.
+- Trace-analysis proposers record each model call directly in the campaign cost ledger instead of replacing them with one estimated wrapper receipt.
+- Direct Gemini 3 analysis keeps its output limit without sending Ax's incompatible thinking-level option.
+- Recovery findings pass through the same subject, evidence, and post-processing rules as primary findings, and malformed recovery calls fail visibly.
+- Budget allocation rejects invalid values and cannot exceed the remaining run budget or regain spend through malformed finding metadata.
+
+### Breaking
+
+- `SemanticConceptJudgeAdapterOpts.options` no longer accepts `costLedger` or `signal`; remove those fields because `AnalystRegistry` now supplies the run budget and cancellation signal and records the resulting usage.
+- `createTraceAnalystKind()` now requires `model` when passed an externally constructed Ax service; supply the service's model explicitly or construct it with `createAnalystAi()` so the model can be recovered safely.
+- `TraceAnalystGolden.expected` now uses `CanonicalRawAnalystFinding` with an `evidence` array; migrate singular `evidence_uri` and `evidence_excerpt` fields into the first array entry.
+
 ## [0.118.2] — 2026-07-13 — interoperable contracts and trace accounting
 
 ### Fixed

package/README.md

@@ -95,6 +95,31 @@ const traceRuns = fromOtelSpans({ spans: yourOtelSpans })
 await analyzeRuns({ runs: [...runs, ...traceRuns], raterScores })
 ```
 
+### 4. Export to PrimeIntellect
+
+Use this when you want PrimeIntellect Verifiers to run or train against tasks produced by Tangle evals, runtime runs, or knowledge runs.
+
+```ts
+import {
+  primeIntellectRowsFromRunRecords,
+  writePrimeIntellectEnvironmentPackage,
+} from '@tangle-network/agent-eval/primeintellect'
+
+const rows = primeIntellectRowsFromRunRecords({
+  records, // RunRecord[] with scenarioId
+  scenarios, // prompts plus answer or requiredSubstrings
+})
+
+await writePrimeIntellectEnvironmentPackage('prime-envs/refund-policy', {
+  name: 'refund-policy',
+  rows,
+  runRecords: records,
+})
+```
+
+The generated package contains `load_environment()`, `data/dataset.jsonl`, `data/run_records.jsonl`, and a manifest.
+Run it with `uv run vf-eval refund-policy` or upload it with `prime env push`.
+
 ---
 
 ## Core concepts
@@ -124,6 +149,7 @@ Each example: `README.md` + a single `index.ts` runnable via `pnpm tsx`. Prints
 |---|---|
 | `…/contract` | **The headline, frozen surface — new code starts here.** `defineAgentEval`, `selfImprove`, `analyzeRuns`, `runEval`, `runCampaign`, `runImprovementLoop`, `diffRuns`; intake adapters (`fromFeedbackTable`, `fromOtelSpans`); proposers (`gepaProposer`, `evolutionaryProposer`); gates (`defaultProductionGate`, `heldOutGate`, `paretoSignificanceGate`, `neutralizationGate`, `composeGate`); the deployment-outcome store; storage; and the five core types `Scenario` / `Dispatch` / `JudgeConfig` / `SurfaceProposer` / `Gate`. |
 | `…/hosted` | `createHostedClient` / `hostedClientFromEnv` + the wire types to ship eval-run events + trace spans to a hosted orchestrator (ours or your own implementation of the spec) |
+| `…/primeintellect` | Export validated `RunRecord`s plus scenario prompts into a PrimeIntellect Verifiers package: Python `load_environment()`, `data/dataset.jsonl`, `data/run_records.jsonl`, and export manifest |
 | `…/adapters/otel` | `createOtelBridge` — forwards OpenTelemetry-shape spans into the hosted-tier ingest, no `@opentelemetry/*` dependency |
 | `…/adapters/langchain` | Wrap any LangChain `Runnable` as a `Dispatch` (or `JudgeConfig`), no `@langchain/core` peer dep |
 | `…/adapters/http` | `httpDispatch` + `runDispatchServer` — run a campaign's worker on another machine (multi-region, remote worker execution) |

package/dist/analyst/index.d.ts

@@ -1,5 +1,5 @@
 import { TCloud } from '@tangle-network/tcloud';
-import { AxAIService, AxFunction } from '@ax-llm/ax';
+import { AxAIArgs, AxAIService, AxFunction } from '@ax-llm/ax';
 import { z } from 'zod';
 
 /**
@@ -800,8 +800,14 @@ declare class RunCritic {
 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;
@@ -868,7 +874,9 @@ interface ChannelRollup {
     calls: number;
     inputTokens: number;
     outputTokens: number;
+    reasoningTokens?: number;
     cachedTokens: number;
+    cacheWriteTokens?: number;
     costUsd: number;
     unpricedCalls: number;
     unknownUsageCalls: number;
@@ -880,7 +888,9 @@ interface CostLedgerSummary {
     reservedCostUsd: number;
     inputTokens: number;
     outputTokens: number;
+    reasoningTokens?: number;
     cachedTokens: number;
+    cacheWriteTokens?: number;
     totalCostUsd: number;
     byChannel: ChannelRollup[];
     unpricedModels: string[];
@@ -894,6 +904,10 @@ interface CostLedgerFilter {
     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(): {
@@ -913,6 +927,7 @@ declare class CostLedger {
     private readonly records;
     private readonly activeCallIds;
     private readonly lateCallIds;
+    private readonly idleWaiters;
     private completedTasks;
     private revision;
     private costLimitPersisted;
@@ -920,6 +935,8 @@ declare class CostLedger {
     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;
@@ -930,6 +947,7 @@ declare class CostLedger {
     costPerCompletedTask(): number | null;
     private execute;
     private captureLateOutcome;
+    private releaseActiveCall;
     private commitOutcome;
     private captureFailure;
     private commitReceipt;
@@ -945,7 +963,7 @@ declare class CostLedger {
  * Keeping callback contracts structural lets those subpaths compose while the
  * concrete {@link CostLedger} retains its private durable state.
  */
-type CostLedgerHandle = Pick<CostLedger, keyof CostLedger>;
+type CostLedgerHandle = Pick<CostLedger, Exclude<keyof CostLedger, 'waitForIdle'>> & Partial<Pick<CostLedger, 'waitForIdle'>>;
 
 /**
  * LLM client with graceful degrade.
@@ -1688,6 +1706,8 @@ interface AnalystCost {
     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. */
@@ -1711,10 +1731,14 @@ interface AnalystContext {
     runId: string;
     /** Stable correlation id so logs from a single registry.run() share a tag. */
     correlationId: string;
-    /** Wall-clock deadline (epoch ms). Analysts SHOULD honor for graceful cancel. */
+    /** 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 |
@@ -1732,6 +1756,18 @@ interface AnalystContext {
      * 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. */
@@ -1757,6 +1793,17 @@ interface Analyst<TInput = unknown> {
     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}.
@@ -1789,6 +1836,12 @@ interface AnalystRunSummary {
     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;
@@ -1804,6 +1857,11 @@ interface AnalystRunResult {
     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
@@ -1896,7 +1954,10 @@ declare function createJudgeAdapter(opts: JudgeAdapterOpts): Analyst<JudgeInput>
 interface SemanticConceptJudgeAdapterOpts {
     id?: string;
     area?: string;
-    options?: SemanticConceptJudgeOptions;
+    /** 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>;
 
@@ -1906,11 +1967,13 @@ interface CreateAnalystAiConfig {
     apiKey: string;
     /** OpenAI-compatible base URL — e.g. `https://router.tangle.tools/v1` or a
      *  cli-bridge loopback. */
-    baseUrl: string;
-    /** Model id forwarded to the analyst actor + responder. */
+    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?: 'openai' | 'anthropic';
+    provider?: AxAIArgs<unknown>['name'];
 }
 /**
  * Construct the `AxAIService` an analyst kind calls through
@@ -2016,7 +2079,15 @@ declare function behavioralAnalyst(): Analyst<TraceAnalysisStore>;
  */
 
 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";
@@ -2026,35 +2097,63 @@ declare const RawAnalystFindingSchema: z.ZodObject<{
     }>;
     claim: z.ZodString;
     subject: z.ZodOptional<z.ZodString>;
-    evidence_uri: z.ZodString;
-    evidence_excerpt: 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 JSON object with these fields:\n  - severity: one of \"critical\" | \"high\" | \"medium\" | \"low\" | \"info\"\n  - claim: one-sentence statement (max 2000 chars)\n  - subject?: the routing locus this finding is about. It MUST be one of the exact subject forms listed in this kind's instructions above (e.g. `system-prompt:<section>`, `agent-knowledge:wiki:<slug>`, `tool-doc:<tool>`). A free phrase, a bare noun, or any form not in that list is REJECTED at parse time and the finding is discarded \u2014 omit subject entirely rather than guess a form.\n  - evidence_uri: REQUIRED, never blank. Exactly one of \"span://<trace_id>/<span_id>\" (trace evidence), \"artifact://<relative-path>\" (files), \"metric://<name>\" (named scalars) \u2014 ALWAYS cite a real id surfaced by the tools. If you have no citable id, do not emit the finding.\n  - evidence_excerpt?: short quote (<=2000 chars) from the cited span/artifact\n  - confidence: number 0..1 \u2014 0.9+ when backed by exact quotes, 0.6-0.8 for inferred patterns, <0.5 for speculative\n  - rationale?: one or two sentences explaining the reasoning\n  - recommended_action?: concrete change phrased as an imperative (\"Add ...\", \"Replace ...\", \"Stop ...\") \u2014 omit when the finding is purely descriptive\n\nEmit an empty array when the question has no findings to report. Do not fabricate evidence.";
+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 one row emitted by the LLM. Returns the typed finding on
- * success; returns `null` and logs the reason on failure so the kind
- * factory can skip-and-count rather than abort the whole analyst run.
+ * 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 Ax recursion config target one failure-mode lens (failure-mode
- * classification, knowledge gap discovery, knowledge poisoning, recursive
- * self-improvement, ...). Kinds emit findings in the typed `RawAnalystFinding`
- * shape via a JSON-array Ax output; the factory validates each row with
- * Zod and lifts it into `AnalystFinding[]` with no shape guessing.
+ * 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
@@ -2062,12 +2161,11 @@ declare function parseRawFinding(row: unknown, log?: (msg: string, fields?: Reco
  *   - 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 recursion + parallelism budget. Discovery-
- *     heavy kinds (failure-mode) get higher `maxDepth`; lens kinds
- *     (poisoning) usually stay at 0 since they have a tighter brief.
+ *   - 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 `AxMiPRO` / `AxBootstrapFewShot` / `AxGEPA` to fit the actor
+ * by `AxBootstrapFewShot` / `AxGEPA` to fit the actor
  * description programmatically. Stored on the kind, not the registry,
  * because the right metric is kind-specific.
  */
@@ -2087,23 +2185,25 @@ interface TraceAnalystKindSpec {
     version: string;
     /** Actor system prompt. Must instruct the LLM to emit `findings` per the schema. */
     actorDescription: string;
-    /** Responder system prompt; falls back to a minimal "format the findings" instruction. */
-    responderDescription?: string;
     /** Tool functions the actor may call. Pick narrow subsets via `ANALYST_TOOL_GROUPS`. */
     buildTools: (store: TraceAnalysisStore) => AxFunction[];
-    /** Recursion budget. `maxDepth: 0` disables subagents. */
-    recursion?: {
-        maxDepth: number;
-        maxParallelSubagents?: number;
+    /** 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[];
 }
@@ -2115,12 +2215,12 @@ interface TraceAnalystKindSpec {
  */
 interface TraceAnalystGolden {
     question: string;
-    expected: ReadonlyArray<Omit<RawAnalystFinding, 'confidence'>>;
+    expected: ReadonlyArray<Omit<CanonicalRawAnalystFinding, 'confidence'>>;
 }
 interface CreateTraceAnalystKindOpts {
     /** AxAIService bound at registration time. */
     ai: AxAIService;
-    /** Optional model override; falls back to the AI service's default. */
+    /** 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;
@@ -2137,6 +2237,8 @@ interface CreateTraceAnalystKindOpts {
         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.
@@ -2162,6 +2264,8 @@ declare function createTraceAnalystKind(spec: TraceAnalystKindSpec, opts: Create
  * 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.
@@ -2218,7 +2322,8 @@ interface BudgetPolicy {
     /**
      * Custom allocator — receives the analyst, remaining/total budget, and
      * the count of analysts that will run. Returns the per-analyst budget
-     * (or undefined to leave it uncapped). Overrides weights when set.
+     * (or undefined only when the run has no overall cap). Overrides weights
+     * when set.
      */
     allocate?: (args: {
         analyst: Analyst;
@@ -2244,10 +2349,14 @@ interface RegistryRunOpts {
     skip?: string[];
     /** Budget policy — totalUsd + optional weights/allocator. Falls back to options.defaultBudget. */
     budget?: BudgetPolicy;
-    /** Wall-clock cap. Analysts SHOULD honor `ctx.deadlineMs`. */
+    /** 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>;
     /**
@@ -2255,10 +2364,16 @@ interface RegistryRunOpts {
      * 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 for cross-kind chaining where the improvement
-     * analyst consumes upstream failure findings).
+     * 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;
@@ -2302,7 +2417,7 @@ declare class AnalystRegistry {
 interface DefaultAnalystRegistryOptions {
     /** Ax service for the agentic RLM kinds. Omit → only the deterministic analyst. */
     ai?: AxAIService;
-    /** Model for the agentic kinds (falls back to the ai service default). */
+    /** 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[];
@@ -2570,19 +2685,14 @@ declare function diffFindings(previous: PersistedFinding[], current: PersistedFi
  * findings. The actor's job is *taxonomy + evidence*, not fix-design —
  * that's the improvement-analyst's job.
  *
- * Recursion is deep (`maxDepth: 3`) because real failure-mode
- * discovery is genuinely tree-shaped: the actor splits the dataset
- * into candidate clusters, each cluster spawns a focused investigator
- * that drills into representative traces, and a deeply-recursed
- * investigator may itself split a confounded mode into two sub-modes.
- * Each level fans out 4-way, so the analyst can investigate up to
- * ~16 leaf clusters before hitting the depth ceiling.
+ * 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, recursive self-improvement findings.
+ * Improvement analyst — actionable self-improvement findings.
  *
  * Brief: read findings from upstream analysts (failure-mode,
  * knowledge-gap, knowledge-poisoning) AND the trace dataset itself,
@@ -2592,14 +2702,11 @@ declare const FAILURE_MODE_KIND_SPEC: TraceAnalystKindSpec;
  * finding is one proposed edit with the locus, the diff, and the
  * expected effect.
  *
- * This is the recursive-self-improvement loop's last mile: the prior
+ * This is the self-improvement loop's last mile: the prior
  * kinds describe *what's wrong*; this kind describes *what to change*.
  *
- * Recursion is deep (`maxDepth: 3`) because real improvement proposals
- * are competitive: for each failure-mode there are usually 2-3 viable
- * fix directions (tighten prompt vs add tool vs adjust scaffolding),
- * and the actor should explore each with a focused subagent before
- * picking the highest-leverage one to recommend.
+ * 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;
@@ -2626,8 +2733,8 @@ declare const IMPROVEMENT_KIND_SPEC: TraceAnalystKindSpec;
  * knowledge-gap names the *information* whose absence (or staleness)
  * caused the break. One failure-mode often maps to several gaps.
  *
- * Recursion (`maxDepth: 2`) is enough to fan out one subagent per
- * candidate gap-source layer; each subagent runs a focused detection.
+ * 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;
@@ -2646,10 +2753,8 @@ declare const KNOWLEDGE_GAP_KIND_SPEC: TraceAnalystKindSpec;
  * surface as questions / self-correction; poisonings surface as
  * confident-but-wrong actions that downstream evidence contradicts.
  *
- * Recursion is moderate (`maxDepth: 2`) because each candidate
- * poisoning typically needs two sub-investigations: one to confirm
- * the agent acted on the false belief, one to confirm the belief
- * itself is actually false in ground truth.
+ * Eight bounded model subqueries let the actor independently assess
+ * the action and contradiction excerpts for candidate poisonings.
  */
 
 declare const KNOWLEDGE_POISONING_KIND_SPEC: TraceAnalystKindSpec;
@@ -2661,8 +2766,8 @@ declare const KNOWLEDGE_POISONING_KIND_SPEC: TraceAnalystKindSpec;
  * 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 and the registry runs them in dependency order if the operator
- * pipes findings between them.
+ * store in this order and run the registry with `chainFindings: true`
+ * to pass each completed kind's findings to the kinds that follow it.
  */
 
 /**
@@ -2778,7 +2883,7 @@ 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
- * (`parseRawFinding`) — this only fixes the SHAPE, never invents fields.
+ * (`parseCanonicalRawFinding`) — this only fixes the SHAPE, never invents fields.
  */
 declare function coerceToFindingRows(raw: unknown): unknown[];
 
@@ -2950,9 +3055,17 @@ interface StructureFindingsOptions {
     /** 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'];
 }
@@ -2995,4 +3108,4 @@ type TraceToolGroupName =
  */
 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 BudgetPolicy, 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 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, findingSubjectGrammarPromptFor, isJudgeVerdict, isPolicyEdit, isTraceObservable, liftSeverity, makeFinding, makePolicyEdit, makePolicyEditCandidateRecord, parseFindingSubject, parseRawFinding, policyEditFromFinding, policyEditsFromFindings, renderFindingSubject, renderPriorFindings, scorePolicyEditReadiness, stripCodeFences, structureFindings, validatePolicyEdit, validatePolicyEditCandidateRecord };
+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 };