@tangle-network/agent-eval 0.128.1 → 0.129.0

package/dist/analyst/index.d.ts

@@ -1,4 +1,3 @@
-import { TCloud } from '@tangle-network/tcloud';
 import { AxAIArgs, AxAIService, AxFunction } from '@ax-llm/ax';
 import { z } from 'zod';
 
@@ -983,9 +982,8 @@ type CostLedgerHandle = Pick<CostLedger, Exclude<keyof CostLedger, 'listPending'
  *     { 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.
+ * `createChatClient` wraps this implementation for provider-neutral package
+ * entry points. Direct callers can use `callLlm` or `callLlmJson`.
  */
 
 interface LlmMessage {
@@ -1096,8 +1094,8 @@ interface LlmClientOptions {
      * total attempts × `timeoutMs`.
      */
     deadlineMs?: number;
-    /** Total provider attempts. Legacy option name; default 3 (1 initial + 2 retries). */
-    maxRetries?: number;
+    /** Total provider attempts. Default 3. */
+    maximumAttempts?: number;
     /** Token rates used when the provider omits cost or package pricing does not cover the model. */
     customTokenPricing?: CustomTokenPricing;
     /**
@@ -1243,6 +1241,91 @@ interface SemanticConceptJudgeOptions {
     complexityWeights?: Partial<Record<ConceptComplexity, number>>;
 }
 
+/**
+ * Provider-neutral chat contract for every model call made by agent-eval.
+ *
+ * Callers choose the transport at the package boundary with `createChatClient`.
+ * Evaluation code receives canonical requests and results without importing a
+ * provider SDK.
+ */
+
+/**
+ * Unified chat interface using the package's canonical LLM request and result.
+ */
+interface ChatClient {
+    /** Display name of the bound transport, included in telemetry. */
+    readonly transport: ChatTransport;
+    /** Default model when the caller omits one. */
+    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' | 'custom' | '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 | CustomTransportOpts | 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. The caller supplies a canonical chat function for an
+ * already-configured Sandbox handle, so agent-eval does not import the SDK.
+ */
+interface SandboxSdkTransportOpts extends BaseTransportOpts {
+    transport: 'sandbox-sdk';
+    chat: (req: ChatRequest, opts?: ChatCallOpts) => Promise<ChatResponse>;
+}
+/** Caller-adapted SDK or transport returning the canonical ChatResponse shape. */
+interface CustomTransportOpts extends BaseTransportOpts {
+    transport: 'custom';
+    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;
+
 interface Scenario {
     id: string;
     persona: string;
@@ -1309,10 +1392,8 @@ interface JudgeInput {
     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[]>;
+type JudgeFn = (chat: ChatClient, input: JudgeInput) => Promise<JudgeScore[]>;
 
 /**
  * Shared types for the trace-analyst module.
@@ -1542,103 +1623,6 @@ interface TraceAnalysisStore {
     }): 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,
@@ -1859,13 +1843,8 @@ interface AnalystRunSummary {
     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;
+    /** Additive model usage and cost provenance for this analyst. */
+    usage: AnalystUsageReceipt;
     /** When `status='failed'`: the error class + message, never the full stack. */
     error?: {
         class: string;
@@ -1967,8 +1946,8 @@ interface JudgeAdapterOpts {
     id?: string;
     area?: string;
     judge: JudgeFn;
-    /** TCloud handle the JudgeFn calls. */
-    tcloud: TCloud;
+    /** Chat client passed to the JudgeFn. */
+    chat: ChatClient;
     /** 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). */
@@ -2088,12 +2067,9 @@ 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.
+ * Ax binds the field as `findings:json[]` so the provider emits native
+ * structured output. At the kind-factory boundary every row is validated
+ * before it becomes an `AnalystFinding`.
  *
  * Why not `f.object().array()` directly in the signature? The Ax
  * signature string `question:string -> findings:json[]` already lets
@@ -2108,40 +2084,16 @@ declare const RawAnalystEvidenceSchema: z.ZodObject<{
     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.ZodPreprocess<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";
+        critical: "critical";
+        info: "info";
         medium: "medium";
     }>;
     claim: z.ZodString;
@@ -2149,25 +2101,17 @@ declare const CanonicalRawAnalystFindingSchema: z.ZodPreprocess<z.ZodObject<{
     confidence: z.ZodNumber;
     rationale: z.ZodOptional<z.ZodString>;
     recommended_action: z.ZodOptional<z.ZodString>;
-}, z.core.$strict>>;
-type CanonicalRawAnalystFinding = z.infer<typeof CanonicalRawAnalystFindingSchema>;
+}, z.core.$strict>;
+type RawAnalystFinding = z.infer<typeof RawAnalystFindingSchema>;
 /**
  * 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}.
- */
+/** Convert raw citations into the public finding evidence envelope. */
+declare function evidenceRefsFromRawFinding(finding: RawAnalystFinding): EvidenceRef[];
 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.
@@ -2176,7 +2120,7 @@ declare function parseCanonicalRawFinding(row: unknown, log?: (msg: string, fiel
  * 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
+ * `RawAnalystFinding` shape via a JSON-array Ax output; the factory
  * validates each row with Zod and lifts it into `AnalystFinding[]`.
  *
  * Composition rules:
@@ -2239,7 +2183,7 @@ interface TraceAnalystKindSpec {
  */
 interface TraceAnalystGolden {
     question: string;
-    expected: ReadonlyArray<Omit<CanonicalRawAnalystFinding, 'confidence'>>;
+    expected: ReadonlyArray<Omit<RawAnalystFinding, 'confidence'>>;
 }
 interface CreateTraceAnalystKindOpts {
     /** AxAIService bound at registration time. */
@@ -2907,7 +2851,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
- * (`parseCanonicalRawFinding`) — this only fixes the SHAPE, never invents fields.
+ * (`parseRawFinding`) — this only fixes the shape and never invents fields.
  */
 declare function coerceToFindingRows(raw: unknown): unknown[];
 
@@ -2980,8 +2924,6 @@ interface StructureFindingsOptions {
     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). */
@@ -3026,4 +2968,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 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 FindingsDiff, FindingsStore, IMPROVEMENT_KIND_SPEC, type JudgeAdapterOpts, KIND_EXPECTED_SUBJECTS, KNOWLEDGE_GAP_KIND_SPEC, KNOWLEDGE_POISONING_KIND_SPEC, type MockTransportOpts, type PersistedFinding, 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, assertNoJudgeVerdict, behavioralAnalyst, buildDefaultAnalystRegistry, buildSkillUsageReport, buildTraceToolsForGroup, coerceJson, coerceToFindingRows, computeFindingId, createAnalystAi, createChatClient, createJudgeAdapter, createRunCriticAdapter, createSemanticConceptJudgeAdapter, createTraceAnalystKind, createVerifierAdapter, defaultIsMaterial, deriveEfficiencyFindings, diffFindings, emitSkillUsageFindings, evidenceRefsFromRawFinding, findingSubjectGrammarPromptFor, isJudgeVerdict, isTraceObservable, liftSeverity, makeFinding, parseCanonicalRawFinding, parseFindingSubject, parseRawFinding, renderFindingSubject, renderPriorFindings, renderUpstreamFindings, stripCodeFences, structureFindings };
+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 ChatCallOpts, type ChatClient, type ChatRequest, type ChatResponse, type ChatTransport, type CliBridgeTransportOpts, type CreateAnalystAiConfig, type CreateChatClientOpts, type CreateTraceAnalystKindOpts, type CustomTransportOpts, 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 FindingsDiff, FindingsStore, IMPROVEMENT_KIND_SPEC, type JudgeAdapterOpts, KIND_EXPECTED_SUBJECTS, KNOWLEDGE_GAP_KIND_SPEC, KNOWLEDGE_POISONING_KIND_SPEC, type MockTransportOpts, type PersistedFinding, 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, assertNoJudgeVerdict, behavioralAnalyst, buildDefaultAnalystRegistry, buildSkillUsageReport, buildTraceToolsForGroup, coerceJson, coerceToFindingRows, computeFindingId, createAnalystAi, createChatClient, createJudgeAdapter, createRunCriticAdapter, createSemanticConceptJudgeAdapter, createTraceAnalystKind, createVerifierAdapter, defaultIsMaterial, deriveEfficiencyFindings, diffFindings, emitSkillUsageFindings, evidenceRefsFromRawFinding, findingSubjectGrammarPromptFor, isJudgeVerdict, isTraceObservable, liftSeverity, makeFinding, parseFindingSubject, parseRawFinding, renderFindingSubject, renderPriorFindings, renderUpstreamFindings, stripCodeFences, structureFindings };

package/dist/analyst/index.js

@@ -9,11 +9,10 @@ import {
   diffFindings,
   emitSkillUsageFindings,
   runSemanticConceptJudge
-} from "../chunk-ZUUWPZCV.js";
+} from "../chunk-DODXQREJ.js";
 import {
   ANALYST_SEVERITIES,
   AnalystRegistry,
-  CanonicalRawAnalystFindingSchema,
   DEFAULT_TRACE_ANALYST_KINDS,
   FAILURE_MODE_KIND_SPEC,
   FINDING_SUBJECT_GRAMMAR_PROMPT,
@@ -40,7 +39,6 @@ import {
   evidenceRefsFromRawFinding,
   findingSubjectGrammarPromptFor,
   makeFinding,
-  parseCanonicalRawFinding,
   parseFindingSubject,
   parseRawFinding,
   renderFindingSubject,
@@ -50,13 +48,13 @@ import {
   stripCodeFences,
   structureFindings,
   validateUsageSettlementTimeout
-} from "../chunk-DJKY2TSY.js";
+} from "../chunk-BSO5JDQH.js";
 import "../chunk-HHWE3POT.js";
 import "../chunk-WGXIEX7P.js";
-import "../chunk-PBE2LOSS.js";
+import "../chunk-SFLLL76A.js";
 import {
   CostLedger
-} from "../chunk-WS3NZZQQ.js";
+} from "../chunk-VCZ5FQYW.js";
 import "../chunk-VI2UW6B6.js";
 import "../chunk-P6FYH6K4.js";
 import "../chunk-PC4UYEBM.js";
@@ -206,7 +204,7 @@ function createJudgeAdapter(opts) {
     cost: opts.cost ?? { kind: "llm" },
     version: `judge-${ADAPTER_REV}`,
     async analyze(input) {
-      const scores = await opts.judge(opts.tcloud, input);
+      const scores = await opts.judge(opts.chat, input);
       return scores.filter((s) => normalize10(s.score) < threshold).map((s) => liftJudgeScore(id, area, s));
     }
   };
@@ -334,7 +332,6 @@ function assertNoJudgeVerdict(findings, context = "steer") {
 export {
   ANALYST_SEVERITIES,
   AnalystRegistry,
-  CanonicalRawAnalystFindingSchema,
   DEFAULT_TRACE_ANALYST_KINDS,
   FAILURE_MODE_KIND_SPEC,
   FINDING_SUBJECT_GRAMMAR_PROMPT,
@@ -376,7 +373,6 @@ export {
   isTraceObservable,
   liftSeverity,
   makeFinding,
-  parseCanonicalRawFinding,
   parseFindingSubject,
   parseRawFinding,
   renderFindingSubject,

package/dist/analyst/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/analyst/adapters.ts","../../src/analyst/steer-firewall.ts"],"sourcesContent":["/**\n * Adapter factories — lift each existing agent-eval primitive into the\n * Analyst contract without re-implementing it.\n *\n * Five primitives, five factories. Each one:\n *   - Builds an Analyst with a stable id (caller chooses; defaults\n *     given), a sensible default `inputKind`, a version derived from\n *     the wrapped primitive's version + an adapter revision, and an\n *     `analyze()` that calls the primitive and lifts its output to\n *     AnalystFinding[] using `makeFinding()`.\n *   - Maps severities: the existing `Severity` ('critical' | 'major' |\n *     'minor' | 'info') projects onto AnalystSeverity ('critical' |\n *     'high' | 'medium' | 'low' | 'info'); 'major' → 'high', 'minor' →\n *     'medium'. Domain analysts that want finer-grained mapping override.\n *\n * Adapters never own state. Calling the same factory twice with the\n * same primitive instance is safe.\n */\n\nimport { CostLedger } from '../cost-ledger'\nimport type {\n  Finding as LayerFinding,\n  Severity as LayerSeverity,\n  MultiLayerVerifier,\n  VerifyOptions,\n} from '../multi-layer-verifier'\nimport { RunCritic, type RunTrace } from '../run-critic'\nimport {\n  runSemanticConceptJudge,\n  SEMANTIC_CONCEPT_JUDGE_VERSION,\n  type SemanticConceptJudgeInput,\n  type SemanticConceptJudgeOptions,\n  type SemanticConceptJudgeResult,\n} from '../semantic-concept-judge'\nimport type { JudgeFn, JudgeInput, JudgeScore, TCloud } from '../types'\nimport type { Analyst, AnalystFinding, AnalystSeverity } from './types'\nimport { makeFinding } from './types'\nimport { settleUsageReceiptFromCostLedger, validateUsageSettlementTimeout } from './usage-receipt'\n\nconst ADAPTER_REV = '1'\n\n// ── Severity bridges ───────────────────────────────────────────────\n\nexport function liftSeverity(s: LayerSeverity): AnalystSeverity {\n  switch (s) {\n    case 'critical':\n      return 'critical'\n    case 'major':\n      return 'high'\n    case 'minor':\n      return 'medium'\n    case 'info':\n      return 'info'\n  }\n}\n\n// ── 1. MultiLayerVerifier → Analyst ─────────────────────────────────\n\nexport interface VerifierAdapterOpts<Env> {\n  id?: string\n  area?: string\n  verifier: MultiLayerVerifier<Env>\n  /**\n   * The verifier expects an `env` per run. Adapters take it from\n   * `AnalystRunInputs.custom[<id>]` via the registry's 'custom' routing.\n   */\n  options?: Omit<VerifyOptions<Env>, 'env'>\n}\n\nexport function createVerifierAdapter<Env>(opts: VerifierAdapterOpts<Env>): Analyst<Env> {\n  const id = opts.id ?? 'multi-layer-verifier'\n  const area = opts.area ?? 'verification'\n  return {\n    id,\n    description:\n      \"Runs a MultiLayerVerifier and lifts each layer's findings into the analyst envelope.\",\n    inputKind: 'custom',\n    cost: { kind: 'deterministic' },\n    version: `verifier-${ADAPTER_REV}`,\n    async analyze(env, ctx) {\n      const report = await opts.verifier.run({ env, ...opts.options })\n      const out: AnalystFinding[] = []\n      for (const layer of report.layers) {\n        for (const finding of layer.findings) {\n          out.push(liftLayerFinding(id, area, layer.layer, finding))\n        }\n        // Layer-level signal: a failed/error layer is itself a finding\n        // even if it didn't emit per-finding rows.\n        if (layer.status === 'fail' || layer.status === 'error' || layer.status === 'timeout') {\n          out.push(\n            makeFinding({\n              analyst_id: id,\n              area,\n              subject: layer.layer,\n              claim: `layer \"${layer.layer}\" ${layer.status}: ${layer.reason ?? 'no reason given'}`,\n              severity:\n                layer.status === 'error' ? 'high' : layer.status === 'timeout' ? 'medium' : 'high',\n              confidence: 1,\n              evidence_refs: [],\n              metadata: {\n                layer_status: layer.status,\n                duration_ms: layer.durationMs,\n                score: layer.score,\n                diagnostics: layer.diagnostics,\n              },\n            }),\n          )\n        }\n      }\n      ctx.log?.('verifier complete', {\n        layers: report.layers.length,\n        blended: report.blendedScore,\n        all_pass: report.allPass,\n      })\n      return out\n    },\n  }\n}\n\nfunction liftLayerFinding(\n  analyst_id: string,\n  area: string,\n  layer: string,\n  f: LayerFinding,\n): AnalystFinding {\n  return makeFinding({\n    analyst_id,\n    area,\n    subject: f.layer ?? layer,\n    claim: f.message,\n    severity: liftSeverity(f.severity),\n    confidence: 0.85,\n    evidence_refs: f.evidence\n      ? [{ kind: 'artifact', uri: 'inline:evidence', excerpt: f.evidence }]\n      : [],\n    metadata: f.detail,\n  })\n}\n\n// ── 2. RunCritic → Analyst ──────────────────────────────────────────\n\nexport interface RunCriticAdapterOpts {\n  id?: string\n  area?: string\n  critic?: RunCritic\n  /** Optional threshold below which a dimension is reported as a finding. Default 0.5. */\n  threshold?: number\n}\n\nexport function createRunCriticAdapter(opts: RunCriticAdapterOpts = {}): Analyst<RunTrace> {\n  const id = opts.id ?? 'run-critic'\n  const area = opts.area ?? 'run-quality'\n  const critic = opts.critic ?? new RunCritic()\n  const threshold = opts.threshold ?? 0.5\n  return {\n    id,\n    description:\n      'Scores a single run across success / grounding / drift / tool-quality and surfaces below-threshold dimensions.',\n    inputKind: 'custom',\n    cost: { kind: 'deterministic' },\n    version: `run-critic-${ADAPTER_REV}`,\n    async analyze(trace) {\n      const score = critic.scoreTrace(trace)\n      const out: AnalystFinding[] = []\n      const dims: Array<[keyof typeof score, AnalystSeverity, string]> = [\n        ['success', 'critical', 'run did not complete successfully'],\n        ['goalProgress', 'high', 'goal progress is low'],\n        ['repoGroundedness', 'high', 'output is poorly grounded in the repository'],\n        ['toolUseQuality', 'medium', 'tool use quality is low'],\n        ['patchQuality', 'medium', 'no real patch/edit evidence'],\n        ['testReality', 'high', 'no real test/build evidence'],\n        ['finalGate', 'critical', 'final gate is blocking'],\n      ]\n      for (const [dim, sev, msg] of dims) {\n        const value = score[dim] as number\n        if (typeof value === 'number' && value < threshold) {\n          out.push(\n            makeFinding({\n              analyst_id: id,\n              area,\n              subject: dim,\n              claim: msg,\n              rationale: `${dim}=${value.toFixed(2)} below threshold ${threshold}`,\n              severity: sev,\n              confidence: 1,\n              evidence_refs: [],\n              metadata: { dimension: dim, value, threshold, run_id: trace.run.runId },\n            }),\n          )\n        }\n      }\n      // Drift penalty is high → surface as a finding (inverse threshold).\n      if (score.driftPenalty > 1 - threshold) {\n        out.push(\n          makeFinding({\n            analyst_id: id,\n            area,\n            subject: 'drift',\n            claim: 'agent output drifted from repository signal',\n            rationale: `driftPenalty=${score.driftPenalty.toFixed(2)}`,\n            severity: 'medium',\n            confidence: 0.9,\n            evidence_refs: [],\n            metadata: { drift_penalty: score.driftPenalty, notes: score.notes },\n          }),\n        )\n      }\n      return out\n    },\n  }\n}\n\n// ── 3. JudgeFn → Analyst ────────────────────────────────────────────\n\nexport interface JudgeAdapterOpts {\n  id?: string\n  area?: string\n  judge: JudgeFn\n  /** TCloud handle the JudgeFn calls. */\n  tcloud: TCloud\n  /** Optional cost classification — most judges call an LLM. */\n  cost?: Analyst['cost']\n  /** Optional threshold below which a JudgeScore becomes a finding. Default 6 (on 0-10 scale). */\n  threshold?: number\n}\n\nexport function createJudgeAdapter(opts: JudgeAdapterOpts): Analyst<JudgeInput> {\n  const id = opts.id ?? 'judge'\n  const area = opts.area ?? 'judge'\n  const threshold = opts.threshold ?? 6\n  return {\n    id,\n    description:\n      'Wraps an agent-eval JudgeFn into an analyst; below-threshold dimensions surface as findings.',\n    inputKind: 'judge-input',\n    cost: opts.cost ?? { kind: 'llm' },\n    version: `judge-${ADAPTER_REV}`,\n    async analyze(input) {\n      const scores = await opts.judge(opts.tcloud, input)\n      return scores\n        .filter((s) => normalize10(s.score) < threshold)\n        .map((s) => liftJudgeScore(id, area, s))\n    },\n  }\n}\n\nfunction normalize10(s: number): number {\n  // JudgeScore convention is 0-10 but some judges emit 0-1. Coerce to 0-10.\n  return s <= 1 ? s * 10 : s\n}\n\nfunction liftJudgeScore(analyst_id: string, area: string, s: JudgeScore): AnalystFinding {\n  const score10 = normalize10(s.score)\n  const severity: AnalystSeverity =\n    score10 < 3 ? 'critical' : score10 < 5 ? 'high' : score10 < 7 ? 'medium' : 'low'\n  return makeFinding({\n    analyst_id,\n    area,\n    subject: s.dimension,\n    claim: `${s.judgeName}/${s.dimension} scored ${score10.toFixed(1)}/10`,\n    rationale: s.reasoning,\n    severity,\n    confidence: 0.8,\n    evidence_refs: s.evidence\n      ? [{ kind: 'artifact', uri: 'inline:evidence', excerpt: s.evidence }]\n      : [],\n    // Provenance: this finding IS a judge verdict (an acceptance score), not an\n    // observation of behavior. The steer firewall (assertNoJudgeVerdict) rejects\n    // it from steering — even when it cites an artifact above — because letting a\n    // verdict steer the next attempt is the held-out judge leaking into the loop.\n    derived_from_judge: true,\n    metadata: { judge_name: s.judgeName, dimension: s.dimension, score_10: score10 },\n  })\n}\n\n// ── 4. SemanticConceptJudge → Analyst ──────────────────────────────\n\nexport interface SemanticConceptJudgeAdapterOpts {\n  id?: string\n  area?: string\n  /** Registry context owns cancellation and the per-analyst cost ledger. */\n  options?: Omit<SemanticConceptJudgeOptions, 'costLedger' | 'signal'>\n  /** Maximum post-cancellation wait for a provider receipt. Default 5 seconds. */\n  settlementTimeoutMs?: number\n}\n\nexport function createSemanticConceptJudgeAdapter(\n  opts: SemanticConceptJudgeAdapterOpts = {},\n): Analyst<SemanticConceptJudgeInput> {\n  const id = opts.id ?? 'semantic-concept-judge'\n  const area = opts.area ?? 'concept-coverage'\n  const settlementTimeoutMs = validateUsageSettlementTimeout(opts.settlementTimeoutMs)\n  return {\n    id,\n    description:\n      'Runs the semantic-concept judge and surfaces missing / weak concepts as findings.',\n    inputKind: 'custom',\n    cost: {\n      kind: 'llm',\n      models: opts.options?.model ? [opts.options.model] : undefined,\n      settlement_timeout_ms: settlementTimeoutMs,\n    },\n    version: `${SEMANTIC_CONCEPT_JUDGE_VERSION}-adapter-${ADAPTER_REV}`,\n    async analyze(input, ctx) {\n      const costLedger = new CostLedger(ctx.budgetUsd)\n      let result: SemanticConceptJudgeResult\n      try {\n        result = await runSemanticConceptJudge(input, {\n          ...opts.options,\n          costLedger,\n          signal: ctx.signal,\n        })\n      } finally {\n        const usage = await settleUsageReceiptFromCostLedger(costLedger, {\n          channel: 'judge',\n          timeoutMs: settlementTimeoutMs,\n        })\n        if (!usage.settled) {\n          ctx.log?.('semantic-concept judge provider settlement timed out', {\n            pending_calls: usage.pendingCalls,\n            timeout_ms: settlementTimeoutMs,\n          })\n        }\n        ctx.recordUsage?.(usage.receipt)\n      }\n      if (!result.available) {\n        return [\n          makeFinding({\n            analyst_id: id,\n            area,\n            claim: 'semantic-concept judge unavailable',\n            rationale: result.error,\n            severity: 'info',\n            confidence: 1,\n            evidence_refs: [],\n            metadata: { reason: result.error },\n          }),\n        ]\n      }\n      const out: AnalystFinding[] = []\n      for (const f of result.findings) {\n        // Only surface gaps: missing concepts or low scores. Concepts at\n        // 7+/10 with present=true are not findings — they're successes.\n        if (f.present && f.score >= 7) continue\n        out.push(\n          makeFinding({\n            analyst_id: id,\n            area,\n            subject: f.concept,\n            claim: f.present\n              ? `concept \"${f.concept}\" is weak (${f.score}/10)`\n              : `concept \"${f.concept}\" is missing`,\n            rationale: f.evidence,\n            severity: liftSeverity(f.severity),\n            confidence: 0.85,\n            evidence_refs: [{ kind: 'artifact', uri: 'inline:evidence', excerpt: f.evidence }],\n            metadata: {\n              concept: f.concept,\n              present: f.present,\n              score_10: f.score,\n            },\n          }),\n        )\n      }\n      return out\n    },\n  }\n}\n","// The realness-oracle firewall (docs/learning-flywheel.md, \"The steer is f(trace)\").\n//\n// A realness/authenticity signal has TWO legitimate roles that must stay\n// separated by a firewall:\n//   (a) anchor judge J — write-only: scores the chosen output, gates promotion,\n//       NEVER seen by the worker/optimizer mid-run (else the loop games it).\n//   (b) steer f(trace) — an analyst observes the agent's OWN behavior in the\n//       trace (\"imported a stub\", \"used a non-crypto PRNG where encryption was\n//       required\") and steers the next attempt. Legitimate, because it is derived\n//       from OBSERVABLE BEHAVIOR, not from J's held-out verdict.\n//\n// The correct discriminator is PROVENANCE, not evidence presence. A judge verdict\n// lifted into a finding (createJudgeAdapter → liftJudgeScore) is a verdict even\n// when it cites an artifact; an evidence-less trace-analyst bullet is an\n// observation even though it cites nothing. So the firewall keys on\n// `AnalystFinding.derived_from_judge` (set at the judge lift site), NOT on whether\n// evidence_refs is populated. The instant a verdict steers the next attempt it is\n// a back-channel for J and the loop Goodharts realness exactly as it would\n// Goodhart pass-rate.\n\nimport type { AnalystFinding, EvidenceRef } from './types'\n\n/** Evidence grounded in the agent's OWN execution: OTLP trace elements\n *  (`span`/`event`) or the artifact it produced (`artifact`). */\nconst OBSERVABLE_KINDS: ReadonlySet<EvidenceRef['kind']> = new Set<EvidenceRef['kind']>([\n  'span',\n  'event',\n  'artifact',\n])\n\n/** DESCRIPTIVE predicate: does the finding cite at least one observable\n *  (span/event/artifact) evidence ref. Useful for ranking evidence quality or\n *  rendering — it is NOT the steer gate. Evidence presence is the WRONG\n *  discriminator for steering: a legitimate trace-analyst observation may cite\n *  nothing (it would be wrongly rejected), and a judge verdict may cite an\n *  artifact (it would be wrongly admitted). Use `assertNoJudgeVerdict` to gate\n *  steering; use this only where \"is this grounded in observable evidence\" is the\n *  literal question. */\nexport function isTraceObservable(finding: AnalystFinding): boolean {\n  return finding.evidence_refs.some((ref) => OBSERVABLE_KINDS.has(ref.kind))\n}\n\n/** True iff the finding is a JUDGE VERDICT (an acceptance score lifted into a\n *  finding), identified by provenance set at the lift site — independent of\n *  whatever evidence it cites. */\nexport function isJudgeVerdict(finding: AnalystFinding): boolean {\n  return finding.derived_from_judge === true\n}\n\n/**\n * THE steer firewall. Fail-loud guard for any path that admits analyst findings\n * as STEERING input (the `f(trace)` role): rejects — naming the offenders — any\n * finding whose provenance is a judge verdict, rather than let `J` leak into the\n * loop. Returns the findings unchanged for chaining.\n *\n * Call this at the chokepoint where a detector that ALSO scores/gates has its\n * findings turned into a steer (the judge-and-steer dual-role case). It keys on\n * provenance, so it correctly admits evidence-less trace-analyst observations and\n * correctly rejects an artifact-citing judge verdict — the cases an evidence\n * check gets backwards.\n *\n * It is necessary, not sufficient: it stops PROVENANCE-tagged verdicts. A judge\n * whose output is laundered through a hand-built finding with no provenance flag\n * is out of its reach — provenance must be honestly set at every judge→finding\n * lift (today: createJudgeAdapter). That is why the integrity rule lives at the\n * lift site, and why ProposeContext.judgeScores?: never is the complementary\n * compile-time tripwire on the obvious direct channel.\n */\nexport function assertNoJudgeVerdict(\n  findings: ReadonlyArray<AnalystFinding>,\n  context = 'steer',\n): ReadonlyArray<AnalystFinding> {\n  const leaks = findings.filter(isJudgeVerdict)\n  if (leaks.length > 0) {\n    throw new Error(\n      `${context}: a judge verdict cannot be admitted as steering input — that is the ` +\n        `held-out judge leaking into the loop. Offending judge-derived findings: [${leaks\n          .map((f) => f.finding_id)\n          .join(', ')}]. Steering consumes observations of behavior, never acceptance verdicts.`,\n    )\n  }\n  return findings\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuCA,IAAM,cAAc;AAIb,SAAS,aAAa,GAAmC;AAC9D,UAAQ,GAAG;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,EACX;AACF;AAeO,SAAS,sBAA2B,MAA8C;AACvF,QAAM,KAAK,KAAK,MAAM;AACtB,QAAM,OAAO,KAAK,QAAQ;AAC1B,SAAO;AAAA,IACL;AAAA,IACA,aACE;AAAA,IACF,WAAW;AAAA,IACX,MAAM,EAAE,MAAM,gBAAgB;AAAA,IAC9B,SAAS,YAAY,WAAW;AAAA,IAChC,MAAM,QAAQ,KAAK,KAAK;AACtB,YAAM,SAAS,MAAM,KAAK,SAAS,IAAI,EAAE,KAAK,GAAG,KAAK,QAAQ,CAAC;AAC/D,YAAM,MAAwB,CAAC;AAC/B,iBAAW,SAAS,OAAO,QAAQ;AACjC,mBAAW,WAAW,MAAM,UAAU;AACpC,cAAI,KAAK,iBAAiB,IAAI,MAAM,MAAM,OAAO,OAAO,CAAC;AAAA,QAC3D;AAGA,YAAI,MAAM,WAAW,UAAU,MAAM,WAAW,WAAW,MAAM,WAAW,WAAW;AACrF,cAAI;AAAA,YACF,YAAY;AAAA,cACV,YAAY;AAAA,cACZ;AAAA,cACA,SAAS,MAAM;AAAA,cACf,OAAO,UAAU,MAAM,KAAK,KAAK,MAAM,MAAM,KAAK,MAAM,UAAU,iBAAiB;AAAA,cACnF,UACE,MAAM,WAAW,UAAU,SAAS,MAAM,WAAW,YAAY,WAAW;AAAA,cAC9E,YAAY;AAAA,cACZ,eAAe,CAAC;AAAA,cAChB,UAAU;AAAA,gBACR,cAAc,MAAM;AAAA,gBACpB,aAAa,MAAM;AAAA,gBACnB,OAAO,MAAM;AAAA,gBACb,aAAa,MAAM;AAAA,cACrB;AAAA,YACF,CAAC;AAAA,UACH;AAAA,QACF;AAAA,MACF;AACA,UAAI,MAAM,qBAAqB;AAAA,QAC7B,QAAQ,OAAO,OAAO;AAAA,QACtB,SAAS,OAAO;AAAA,QAChB,UAAU,OAAO;AAAA,MACnB,CAAC;AACD,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAEA,SAAS,iBACP,YACA,MACA,OACA,GACgB;AAChB,SAAO,YAAY;AAAA,IACjB;AAAA,IACA;AAAA,IACA,SAAS,EAAE,SAAS;AAAA,IACpB,OAAO,EAAE;AAAA,IACT,UAAU,aAAa,EAAE,QAAQ;AAAA,IACjC,YAAY;AAAA,IACZ,eAAe,EAAE,WACb,CAAC,EAAE,MAAM,YAAY,KAAK,mBAAmB,SAAS,EAAE,SAAS,CAAC,IAClE,CAAC;AAAA,IACL,UAAU,EAAE;AAAA,EACd,CAAC;AACH;AAYO,SAAS,uBAAuB,OAA6B,CAAC,GAAsB;AACzF,QAAM,KAAK,KAAK,MAAM;AACtB,QAAM,OAAO,KAAK,QAAQ;AAC1B,QAAM,SAAS,KAAK,UAAU,IAAI,UAAU;AAC5C,QAAM,YAAY,KAAK,aAAa;AACpC,SAAO;AAAA,IACL;AAAA,IACA,aACE;AAAA,IACF,WAAW;AAAA,IACX,MAAM,EAAE,MAAM,gBAAgB;AAAA,IAC9B,SAAS,cAAc,WAAW;AAAA,IAClC,MAAM,QAAQ,OAAO;AACnB,YAAM,QAAQ,OAAO,WAAW,KAAK;AACrC,YAAM,MAAwB,CAAC;AAC/B,YAAM,OAA6D;AAAA,QACjE,CAAC,WAAW,YAAY,mCAAmC;AAAA,QAC3D,CAAC,gBAAgB,QAAQ,sBAAsB;AAAA,QAC/C,CAAC,oBAAoB,QAAQ,6CAA6C;AAAA,QAC1E,CAAC,kBAAkB,UAAU,yBAAyB;AAAA,QACtD,CAAC,gBAAgB,UAAU,6BAA6B;AAAA,QACxD,CAAC,eAAe,QAAQ,6BAA6B;AAAA,QACrD,CAAC,aAAa,YAAY,wBAAwB;AAAA,MACpD;AACA,iBAAW,CAAC,KAAK,KAAK,GAAG,KAAK,MAAM;AAClC,cAAM,QAAQ,MAAM,GAAG;AACvB,YAAI,OAAO,UAAU,YAAY,QAAQ,WAAW;AAClD,cAAI;AAAA,YACF,YAAY;AAAA,cACV,YAAY;AAAA,cACZ;AAAA,cACA,SAAS;AAAA,cACT,OAAO;AAAA,cACP,WAAW,GAAG,GAAG,IAAI,MAAM,QAAQ,CAAC,CAAC,oBAAoB,SAAS;AAAA,cAClE,UAAU;AAAA,cACV,YAAY;AAAA,cACZ,eAAe,CAAC;AAAA,cAChB,UAAU,EAAE,WAAW,KAAK,OAAO,WAAW,QAAQ,MAAM,IAAI,MAAM;AAAA,YACxE,CAAC;AAAA,UACH;AAAA,QACF;AAAA,MACF;AAEA,UAAI,MAAM,eAAe,IAAI,WAAW;AACtC,YAAI;AAAA,UACF,YAAY;AAAA,YACV,YAAY;AAAA,YACZ;AAAA,YACA,SAAS;AAAA,YACT,OAAO;AAAA,YACP,WAAW,gBAAgB,MAAM,aAAa,QAAQ,CAAC,CAAC;AAAA,YACxD,UAAU;AAAA,YACV,YAAY;AAAA,YACZ,eAAe,CAAC;AAAA,YAChB,UAAU,EAAE,eAAe,MAAM,cAAc,OAAO,MAAM,MAAM;AAAA,UACpE,CAAC;AAAA,QACH;AAAA,MACF;AACA,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAgBO,SAAS,mBAAmB,MAA6C;AAC9E,QAAM,KAAK,KAAK,MAAM;AACtB,QAAM,OAAO,KAAK,QAAQ;AAC1B,QAAM,YAAY,KAAK,aAAa;AACpC,SAAO;AAAA,IACL;AAAA,IACA,aACE;AAAA,IACF,WAAW;AAAA,IACX,MAAM,KAAK,QAAQ,EAAE,MAAM,MAAM;AAAA,IACjC,SAAS,SAAS,WAAW;AAAA,IAC7B,MAAM,QAAQ,OAAO;AACnB,YAAM,SAAS,MAAM,KAAK,MAAM,KAAK,QAAQ,KAAK;AAClD,aAAO,OACJ,OAAO,CAAC,MAAM,YAAY,EAAE,KAAK,IAAI,SAAS,EAC9C,IAAI,CAAC,MAAM,eAAe,IAAI,MAAM,CAAC,CAAC;AAAA,IAC3C;AAAA,EACF;AACF;AAEA,SAAS,YAAY,GAAmB;AAEtC,SAAO,KAAK,IAAI,IAAI,KAAK;AAC3B;AAEA,SAAS,eAAe,YAAoB,MAAc,GAA+B;AACvF,QAAM,UAAU,YAAY,EAAE,KAAK;AACnC,QAAM,WACJ,UAAU,IAAI,aAAa,UAAU,IAAI,SAAS,UAAU,IAAI,WAAW;AAC7E,SAAO,YAAY;AAAA,IACjB;AAAA,IACA;AAAA,IACA,SAAS,EAAE;AAAA,IACX,OAAO,GAAG,EAAE,SAAS,IAAI,EAAE,SAAS,WAAW,QAAQ,QAAQ,CAAC,CAAC;AAAA,IACjE,WAAW,EAAE;AAAA,IACb;AAAA,IACA,YAAY;AAAA,IACZ,eAAe,EAAE,WACb,CAAC,EAAE,MAAM,YAAY,KAAK,mBAAmB,SAAS,EAAE,SAAS,CAAC,IAClE,CAAC;AAAA;AAAA;AAAA;AAAA;AAAA,IAKL,oBAAoB;AAAA,IACpB,UAAU,EAAE,YAAY,EAAE,WAAW,WAAW,EAAE,WAAW,UAAU,QAAQ;AAAA,EACjF,CAAC;AACH;AAaO,SAAS,kCACd,OAAwC,CAAC,GACL;AACpC,QAAM,KAAK,KAAK,MAAM;AACtB,QAAM,OAAO,KAAK,QAAQ;AAC1B,QAAM,sBAAsB,+BAA+B,KAAK,mBAAmB;AACnF,SAAO;AAAA,IACL;AAAA,IACA,aACE;AAAA,IACF,WAAW;AAAA,IACX,MAAM;AAAA,MACJ,MAAM;AAAA,MACN,QAAQ,KAAK,SAAS,QAAQ,CAAC,KAAK,QAAQ,KAAK,IAAI;AAAA,MACrD,uBAAuB;AAAA,IACzB;AAAA,IACA,SAAS,GAAG,8BAA8B,YAAY,WAAW;AAAA,IACjE,MAAM,QAAQ,OAAO,KAAK;AACxB,YAAM,aAAa,IAAI,WAAW,IAAI,SAAS;AAC/C,UAAI;AACJ,UAAI;AACF,iBAAS,MAAM,wBAAwB,OAAO;AAAA,UAC5C,GAAG,KAAK;AAAA,UACR;AAAA,UACA,QAAQ,IAAI;AAAA,QACd,CAAC;AAAA,MACH,UAAE;AACA,cAAM,QAAQ,MAAM,iCAAiC,YAAY;AAAA,UAC/D,SAAS;AAAA,UACT,WAAW;AAAA,QACb,CAAC;AACD,YAAI,CAAC,MAAM,SAAS;AAClB,cAAI,MAAM,wDAAwD;AAAA,YAChE,eAAe,MAAM;AAAA,YACrB,YAAY;AAAA,UACd,CAAC;AAAA,QACH;AACA,YAAI,cAAc,MAAM,OAAO;AAAA,MACjC;AACA,UAAI,CAAC,OAAO,WAAW;AACrB,eAAO;AAAA,UACL,YAAY;AAAA,YACV,YAAY;AAAA,YACZ;AAAA,YACA,OAAO;AAAA,YACP,WAAW,OAAO;AAAA,YAClB,UAAU;AAAA,YACV,YAAY;AAAA,YACZ,eAAe,CAAC;AAAA,YAChB,UAAU,EAAE,QAAQ,OAAO,MAAM;AAAA,UACnC,CAAC;AAAA,QACH;AAAA,MACF;AACA,YAAM,MAAwB,CAAC;AAC/B,iBAAW,KAAK,OAAO,UAAU;AAG/B,YAAI,EAAE,WAAW,EAAE,SAAS,EAAG;AAC/B,YAAI;AAAA,UACF,YAAY;AAAA,YACV,YAAY;AAAA,YACZ;AAAA,YACA,SAAS,EAAE;AAAA,YACX,OAAO,EAAE,UACL,YAAY,EAAE,OAAO,cAAc,EAAE,KAAK,SAC1C,YAAY,EAAE,OAAO;AAAA,YACzB,WAAW,EAAE;AAAA,YACb,UAAU,aAAa,EAAE,QAAQ;AAAA,YACjC,YAAY;AAAA,YACZ,eAAe,CAAC,EAAE,MAAM,YAAY,KAAK,mBAAmB,SAAS,EAAE,SAAS,CAAC;AAAA,YACjF,UAAU;AAAA,cACR,SAAS,EAAE;AAAA,cACX,SAAS,EAAE;AAAA,cACX,UAAU,EAAE;AAAA,YACd;AAAA,UACF,CAAC;AAAA,QACH;AAAA,MACF;AACA,aAAO;AAAA,IACT;AAAA,EACF;AACF;;;ACvVA,IAAM,mBAAqD,oBAAI,IAAyB;AAAA,EACtF;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAUM,SAAS,kBAAkB,SAAkC;AAClE,SAAO,QAAQ,cAAc,KAAK,CAAC,QAAQ,iBAAiB,IAAI,IAAI,IAAI,CAAC;AAC3E;AAKO,SAAS,eAAe,SAAkC;AAC/D,SAAO,QAAQ,uBAAuB;AACxC;AAqBO,SAAS,qBACd,UACA,UAAU,SACqB;AAC/B,QAAM,QAAQ,SAAS,OAAO,cAAc;AAC5C,MAAI,MAAM,SAAS,GAAG;AACpB,UAAM,IAAI;AAAA,MACR,GAAG,OAAO,sJACoE,MACzE,IAAI,CAAC,MAAM,EAAE,UAAU,EACvB,KAAK,IAAI,CAAC;AAAA,IACjB;AAAA,EACF;AACA,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../../src/analyst/adapters.ts","../../src/analyst/steer-firewall.ts"],"sourcesContent":["/**\n * Adapter factories — lift each existing agent-eval primitive into the\n * Analyst contract without re-implementing it.\n *\n * Five primitives, five factories. Each one:\n *   - Builds an Analyst with a stable id (caller chooses; defaults\n *     given), a sensible default `inputKind`, a version derived from\n *     the wrapped primitive's version + an adapter revision, and an\n *     `analyze()` that calls the primitive and lifts its output to\n *     AnalystFinding[] using `makeFinding()`.\n *   - Maps severities: the existing `Severity` ('critical' | 'major' |\n *     'minor' | 'info') projects onto AnalystSeverity ('critical' |\n *     'high' | 'medium' | 'low' | 'info'); 'major' → 'high', 'minor' →\n *     'medium'. Domain analysts that want finer-grained mapping override.\n *\n * Adapters never own state. Calling the same factory twice with the\n * same primitive instance is safe.\n */\n\nimport { CostLedger } from '../cost-ledger'\nimport type {\n  Finding as LayerFinding,\n  Severity as LayerSeverity,\n  MultiLayerVerifier,\n  VerifyOptions,\n} from '../multi-layer-verifier'\nimport { RunCritic, type RunTrace } from '../run-critic'\nimport {\n  runSemanticConceptJudge,\n  SEMANTIC_CONCEPT_JUDGE_VERSION,\n  type SemanticConceptJudgeInput,\n  type SemanticConceptJudgeOptions,\n  type SemanticConceptJudgeResult,\n} from '../semantic-concept-judge'\nimport type { JudgeFn, JudgeInput, JudgeScore } from '../types'\nimport type { ChatClient } from './chat-client'\nimport type { Analyst, AnalystFinding, AnalystSeverity } from './types'\nimport { makeFinding } from './types'\nimport { settleUsageReceiptFromCostLedger, validateUsageSettlementTimeout } from './usage-receipt'\n\nconst ADAPTER_REV = '1'\n\n// ── Severity bridges ───────────────────────────────────────────────\n\nexport function liftSeverity(s: LayerSeverity): AnalystSeverity {\n  switch (s) {\n    case 'critical':\n      return 'critical'\n    case 'major':\n      return 'high'\n    case 'minor':\n      return 'medium'\n    case 'info':\n      return 'info'\n  }\n}\n\n// ── 1. MultiLayerVerifier → Analyst ─────────────────────────────────\n\nexport interface VerifierAdapterOpts<Env> {\n  id?: string\n  area?: string\n  verifier: MultiLayerVerifier<Env>\n  /**\n   * The verifier expects an `env` per run. Adapters take it from\n   * `AnalystRunInputs.custom[<id>]` via the registry's 'custom' routing.\n   */\n  options?: Omit<VerifyOptions<Env>, 'env'>\n}\n\nexport function createVerifierAdapter<Env>(opts: VerifierAdapterOpts<Env>): Analyst<Env> {\n  const id = opts.id ?? 'multi-layer-verifier'\n  const area = opts.area ?? 'verification'\n  return {\n    id,\n    description:\n      \"Runs a MultiLayerVerifier and lifts each layer's findings into the analyst envelope.\",\n    inputKind: 'custom',\n    cost: { kind: 'deterministic' },\n    version: `verifier-${ADAPTER_REV}`,\n    async analyze(env, ctx) {\n      const report = await opts.verifier.run({ env, ...opts.options })\n      const out: AnalystFinding[] = []\n      for (const layer of report.layers) {\n        for (const finding of layer.findings) {\n          out.push(liftLayerFinding(id, area, layer.layer, finding))\n        }\n        // Layer-level signal: a failed/error layer is itself a finding\n        // even if it didn't emit per-finding rows.\n        if (layer.status === 'fail' || layer.status === 'error' || layer.status === 'timeout') {\n          out.push(\n            makeFinding({\n              analyst_id: id,\n              area,\n              subject: layer.layer,\n              claim: `layer \"${layer.layer}\" ${layer.status}: ${layer.reason ?? 'no reason given'}`,\n              severity:\n                layer.status === 'error' ? 'high' : layer.status === 'timeout' ? 'medium' : 'high',\n              confidence: 1,\n              evidence_refs: [],\n              metadata: {\n                layer_status: layer.status,\n                duration_ms: layer.durationMs,\n                score: layer.score,\n                diagnostics: layer.diagnostics,\n              },\n            }),\n          )\n        }\n      }\n      ctx.log?.('verifier complete', {\n        layers: report.layers.length,\n        blended: report.blendedScore,\n        all_pass: report.allPass,\n      })\n      return out\n    },\n  }\n}\n\nfunction liftLayerFinding(\n  analyst_id: string,\n  area: string,\n  layer: string,\n  f: LayerFinding,\n): AnalystFinding {\n  return makeFinding({\n    analyst_id,\n    area,\n    subject: f.layer ?? layer,\n    claim: f.message,\n    severity: liftSeverity(f.severity),\n    confidence: 0.85,\n    evidence_refs: f.evidence\n      ? [{ kind: 'artifact', uri: 'inline:evidence', excerpt: f.evidence }]\n      : [],\n    metadata: f.detail,\n  })\n}\n\n// ── 2. RunCritic → Analyst ──────────────────────────────────────────\n\nexport interface RunCriticAdapterOpts {\n  id?: string\n  area?: string\n  critic?: RunCritic\n  /** Optional threshold below which a dimension is reported as a finding. Default 0.5. */\n  threshold?: number\n}\n\nexport function createRunCriticAdapter(opts: RunCriticAdapterOpts = {}): Analyst<RunTrace> {\n  const id = opts.id ?? 'run-critic'\n  const area = opts.area ?? 'run-quality'\n  const critic = opts.critic ?? new RunCritic()\n  const threshold = opts.threshold ?? 0.5\n  return {\n    id,\n    description:\n      'Scores a single run across success / grounding / drift / tool-quality and surfaces below-threshold dimensions.',\n    inputKind: 'custom',\n    cost: { kind: 'deterministic' },\n    version: `run-critic-${ADAPTER_REV}`,\n    async analyze(trace) {\n      const score = critic.scoreTrace(trace)\n      const out: AnalystFinding[] = []\n      const dims: Array<[keyof typeof score, AnalystSeverity, string]> = [\n        ['success', 'critical', 'run did not complete successfully'],\n        ['goalProgress', 'high', 'goal progress is low'],\n        ['repoGroundedness', 'high', 'output is poorly grounded in the repository'],\n        ['toolUseQuality', 'medium', 'tool use quality is low'],\n        ['patchQuality', 'medium', 'no real patch/edit evidence'],\n        ['testReality', 'high', 'no real test/build evidence'],\n        ['finalGate', 'critical', 'final gate is blocking'],\n      ]\n      for (const [dim, sev, msg] of dims) {\n        const value = score[dim] as number\n        if (typeof value === 'number' && value < threshold) {\n          out.push(\n            makeFinding({\n              analyst_id: id,\n              area,\n              subject: dim,\n              claim: msg,\n              rationale: `${dim}=${value.toFixed(2)} below threshold ${threshold}`,\n              severity: sev,\n              confidence: 1,\n              evidence_refs: [],\n              metadata: { dimension: dim, value, threshold, run_id: trace.run.runId },\n            }),\n          )\n        }\n      }\n      // Drift penalty is high → surface as a finding (inverse threshold).\n      if (score.driftPenalty > 1 - threshold) {\n        out.push(\n          makeFinding({\n            analyst_id: id,\n            area,\n            subject: 'drift',\n            claim: 'agent output drifted from repository signal',\n            rationale: `driftPenalty=${score.driftPenalty.toFixed(2)}`,\n            severity: 'medium',\n            confidence: 0.9,\n            evidence_refs: [],\n            metadata: { drift_penalty: score.driftPenalty, notes: score.notes },\n          }),\n        )\n      }\n      return out\n    },\n  }\n}\n\n// ── 3. JudgeFn → Analyst ────────────────────────────────────────────\n\nexport interface JudgeAdapterOpts {\n  id?: string\n  area?: string\n  judge: JudgeFn\n  /** Chat client passed to the JudgeFn. */\n  chat: ChatClient\n  /** Optional cost classification — most judges call an LLM. */\n  cost?: Analyst['cost']\n  /** Optional threshold below which a JudgeScore becomes a finding. Default 6 (on 0-10 scale). */\n  threshold?: number\n}\n\nexport function createJudgeAdapter(opts: JudgeAdapterOpts): Analyst<JudgeInput> {\n  const id = opts.id ?? 'judge'\n  const area = opts.area ?? 'judge'\n  const threshold = opts.threshold ?? 6\n  return {\n    id,\n    description:\n      'Wraps an agent-eval JudgeFn into an analyst; below-threshold dimensions surface as findings.',\n    inputKind: 'judge-input',\n    cost: opts.cost ?? { kind: 'llm' },\n    version: `judge-${ADAPTER_REV}`,\n    async analyze(input) {\n      const scores = await opts.judge(opts.chat, input)\n      return scores\n        .filter((s) => normalize10(s.score) < threshold)\n        .map((s) => liftJudgeScore(id, area, s))\n    },\n  }\n}\n\nfunction normalize10(s: number): number {\n  // JudgeScore convention is 0-10 but some judges emit 0-1. Coerce to 0-10.\n  return s <= 1 ? s * 10 : s\n}\n\nfunction liftJudgeScore(analyst_id: string, area: string, s: JudgeScore): AnalystFinding {\n  const score10 = normalize10(s.score)\n  const severity: AnalystSeverity =\n    score10 < 3 ? 'critical' : score10 < 5 ? 'high' : score10 < 7 ? 'medium' : 'low'\n  return makeFinding({\n    analyst_id,\n    area,\n    subject: s.dimension,\n    claim: `${s.judgeName}/${s.dimension} scored ${score10.toFixed(1)}/10`,\n    rationale: s.reasoning,\n    severity,\n    confidence: 0.8,\n    evidence_refs: s.evidence\n      ? [{ kind: 'artifact', uri: 'inline:evidence', excerpt: s.evidence }]\n      : [],\n    // Provenance: this finding IS a judge verdict (an acceptance score), not an\n    // observation of behavior. The steer firewall (assertNoJudgeVerdict) rejects\n    // it from steering — even when it cites an artifact above — because letting a\n    // verdict steer the next attempt is the held-out judge leaking into the loop.\n    derived_from_judge: true,\n    metadata: { judge_name: s.judgeName, dimension: s.dimension, score_10: score10 },\n  })\n}\n\n// ── 4. SemanticConceptJudge → Analyst ──────────────────────────────\n\nexport interface SemanticConceptJudgeAdapterOpts {\n  id?: string\n  area?: string\n  /** Registry context owns cancellation and the per-analyst cost ledger. */\n  options?: Omit<SemanticConceptJudgeOptions, 'costLedger' | 'signal'>\n  /** Maximum post-cancellation wait for a provider receipt. Default 5 seconds. */\n  settlementTimeoutMs?: number\n}\n\nexport function createSemanticConceptJudgeAdapter(\n  opts: SemanticConceptJudgeAdapterOpts = {},\n): Analyst<SemanticConceptJudgeInput> {\n  const id = opts.id ?? 'semantic-concept-judge'\n  const area = opts.area ?? 'concept-coverage'\n  const settlementTimeoutMs = validateUsageSettlementTimeout(opts.settlementTimeoutMs)\n  return {\n    id,\n    description:\n      'Runs the semantic-concept judge and surfaces missing / weak concepts as findings.',\n    inputKind: 'custom',\n    cost: {\n      kind: 'llm',\n      models: opts.options?.model ? [opts.options.model] : undefined,\n      settlement_timeout_ms: settlementTimeoutMs,\n    },\n    version: `${SEMANTIC_CONCEPT_JUDGE_VERSION}-adapter-${ADAPTER_REV}`,\n    async analyze(input, ctx) {\n      const costLedger = new CostLedger(ctx.budgetUsd)\n      let result: SemanticConceptJudgeResult\n      try {\n        result = await runSemanticConceptJudge(input, {\n          ...opts.options,\n          costLedger,\n          signal: ctx.signal,\n        })\n      } finally {\n        const usage = await settleUsageReceiptFromCostLedger(costLedger, {\n          channel: 'judge',\n          timeoutMs: settlementTimeoutMs,\n        })\n        if (!usage.settled) {\n          ctx.log?.('semantic-concept judge provider settlement timed out', {\n            pending_calls: usage.pendingCalls,\n            timeout_ms: settlementTimeoutMs,\n          })\n        }\n        ctx.recordUsage?.(usage.receipt)\n      }\n      if (!result.available) {\n        return [\n          makeFinding({\n            analyst_id: id,\n            area,\n            claim: 'semantic-concept judge unavailable',\n            rationale: result.error,\n            severity: 'info',\n            confidence: 1,\n            evidence_refs: [],\n            metadata: { reason: result.error },\n          }),\n        ]\n      }\n      const out: AnalystFinding[] = []\n      for (const f of result.findings) {\n        // Only surface gaps: missing concepts or low scores. Concepts at\n        // 7+/10 with present=true are not findings — they're successes.\n        if (f.present && f.score >= 7) continue\n        out.push(\n          makeFinding({\n            analyst_id: id,\n            area,\n            subject: f.concept,\n            claim: f.present\n              ? `concept \"${f.concept}\" is weak (${f.score}/10)`\n              : `concept \"${f.concept}\" is missing`,\n            rationale: f.evidence,\n            severity: liftSeverity(f.severity),\n            confidence: 0.85,\n            evidence_refs: [{ kind: 'artifact', uri: 'inline:evidence', excerpt: f.evidence }],\n            metadata: {\n              concept: f.concept,\n              present: f.present,\n              score_10: f.score,\n            },\n          }),\n        )\n      }\n      return out\n    },\n  }\n}\n","// The realness-oracle firewall (docs/learning-flywheel.md, \"The steer is f(trace)\").\n//\n// A realness/authenticity signal has TWO legitimate roles that must stay\n// separated by a firewall:\n//   (a) anchor judge J — write-only: scores the chosen output, gates promotion,\n//       NEVER seen by the worker/optimizer mid-run (else the loop games it).\n//   (b) steer f(trace) — an analyst observes the agent's OWN behavior in the\n//       trace (\"imported a stub\", \"used a non-crypto PRNG where encryption was\n//       required\") and steers the next attempt. Legitimate, because it is derived\n//       from OBSERVABLE BEHAVIOR, not from J's held-out verdict.\n//\n// The correct discriminator is PROVENANCE, not evidence presence. A judge verdict\n// lifted into a finding (createJudgeAdapter → liftJudgeScore) is a verdict even\n// when it cites an artifact; an evidence-less trace-analyst bullet is an\n// observation even though it cites nothing. So the firewall keys on\n// `AnalystFinding.derived_from_judge` (set at the judge lift site), NOT on whether\n// evidence_refs is populated. The instant a verdict steers the next attempt it is\n// a back-channel for J and the loop Goodharts realness exactly as it would\n// Goodhart pass-rate.\n\nimport type { AnalystFinding, EvidenceRef } from './types'\n\n/** Evidence grounded in the agent's OWN execution: OTLP trace elements\n *  (`span`/`event`) or the artifact it produced (`artifact`). */\nconst OBSERVABLE_KINDS: ReadonlySet<EvidenceRef['kind']> = new Set<EvidenceRef['kind']>([\n  'span',\n  'event',\n  'artifact',\n])\n\n/** DESCRIPTIVE predicate: does the finding cite at least one observable\n *  (span/event/artifact) evidence ref. Useful for ranking evidence quality or\n *  rendering — it is NOT the steer gate. Evidence presence is the WRONG\n *  discriminator for steering: a legitimate trace-analyst observation may cite\n *  nothing (it would be wrongly rejected), and a judge verdict may cite an\n *  artifact (it would be wrongly admitted). Use `assertNoJudgeVerdict` to gate\n *  steering; use this only where \"is this grounded in observable evidence\" is the\n *  literal question. */\nexport function isTraceObservable(finding: AnalystFinding): boolean {\n  return finding.evidence_refs.some((ref) => OBSERVABLE_KINDS.has(ref.kind))\n}\n\n/** True iff the finding is a JUDGE VERDICT (an acceptance score lifted into a\n *  finding), identified by provenance set at the lift site — independent of\n *  whatever evidence it cites. */\nexport function isJudgeVerdict(finding: AnalystFinding): boolean {\n  return finding.derived_from_judge === true\n}\n\n/**\n * THE steer firewall. Fail-loud guard for any path that admits analyst findings\n * as STEERING input (the `f(trace)` role): rejects — naming the offenders — any\n * finding whose provenance is a judge verdict, rather than let `J` leak into the\n * loop. Returns the findings unchanged for chaining.\n *\n * Call this at the chokepoint where a detector that ALSO scores/gates has its\n * findings turned into a steer (the judge-and-steer dual-role case). It keys on\n * provenance, so it correctly admits evidence-less trace-analyst observations and\n * correctly rejects an artifact-citing judge verdict — the cases an evidence\n * check gets backwards.\n *\n * It is necessary, not sufficient: it stops PROVENANCE-tagged verdicts. A judge\n * whose output is laundered through a hand-built finding with no provenance flag\n * is out of its reach — provenance must be honestly set at every judge→finding\n * lift (today: createJudgeAdapter). That is why the integrity rule lives at the\n * lift site, and why ProposeContext.judgeScores?: never is the complementary\n * compile-time tripwire on the obvious direct channel.\n */\nexport function assertNoJudgeVerdict(\n  findings: ReadonlyArray<AnalystFinding>,\n  context = 'steer',\n): ReadonlyArray<AnalystFinding> {\n  const leaks = findings.filter(isJudgeVerdict)\n  if (leaks.length > 0) {\n    throw new Error(\n      `${context}: a judge verdict cannot be admitted as steering input — that is the ` +\n        `held-out judge leaking into the loop. Offending judge-derived findings: [${leaks\n          .map((f) => f.finding_id)\n          .join(', ')}]. Steering consumes observations of behavior, never acceptance verdicts.`,\n    )\n  }\n  return findings\n}\n"],"mappings":"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","names":[]}

package/dist/belief-state/index.d.ts

@@ -329,20 +329,12 @@ interface OffPolicyTrajectory {
      * values must come from a model cross-fitted or trained outside this row.
      */
     vHatTarget?: number | null;
-    /**
-     * @deprecated Use `qHatChosen` and `vHatTarget` together. When the new pair
-     * is absent, this scalar is used as both terms to preserve existing results.
-     * When the new pair is present, this field is ignored.
-     */
-    qHat?: number | null;
 }
 interface OffPolicyContributionCounts {
     /** Contributions using the contextual-bandit doubly-robust formula. */
     dr: number;
     /** Contributions using exact IPS because no reward-model estimate was supplied. */
     ipsFallback: number;
-    /** Contributions using the deprecated single-scalar formula. */
-    legacyScalar: number;
 }
 interface OffPolicyEstimate {
     /** Estimated value of the target policy. */
@@ -473,8 +465,6 @@ interface BeliefDecisionPoint {
     targetProb?: number;
     qHatChosen?: number | null;
     vHatTarget?: number | null;
-    /** @deprecated Use `qHatChosen` and `vHatTarget` together. */
-    qHat?: number | null;
     costUsd?: number;
     evidence: BeliefEvidenceRef[];
     outcome?: BeliefDecisionOutcome;
@@ -498,8 +488,6 @@ interface BeliefPolicyDecision {
     targetProb?: number;
     qHatChosen?: number | null;
     vHatTarget?: number | null;
-    /** @deprecated Use `qHatChosen` and `vHatTarget` together. */
-    qHat?: number | null;
     reason?: string;
     reasons?: BeliefDecisionReason[];
 }
@@ -512,8 +500,6 @@ interface BeliefOpeTargetPolicy {
     targetProbOf(point: BeliefDecisionPoint): number | null | undefined;
     qHatChosenOf?(point: BeliefDecisionPoint): number | null | undefined;
     vHatTargetOf?(point: BeliefDecisionPoint): number | null | undefined;
-    /** @deprecated Use `qHatChosenOf` and `vHatTargetOf` together. */
-    qHatOf?(point: BeliefDecisionPoint): number | null | undefined;
 }
 interface BeliefUtilityOptions {
     successUtility?: number;
@@ -1110,7 +1096,8 @@ interface BeliefShadowProbeResponse {
     evidenceRefs?: string[];
     wouldChangeMindIf?: string[];
     targetProb?: number;
-    qHat?: number | null;
+    qHatChosen?: number | null;
+    vHatTarget?: number | null;
     metadata?: Record<string, unknown>;
 }
 interface BeliefShadowProbeRecord extends BeliefShadowProbeResponse {
@@ -1220,8 +1207,6 @@ interface RuntimeBeliefDecisionPointOptions {
     targetProb?: number;
     qHatChosen?: number | null;
     vHatTarget?: number | null;
-    /** @deprecated Use `qHatChosen` and `vHatTarget` together. */
-    qHat?: number | null;
     costUsd?: number;
     outcome?: BeliefDecisionOutcome;
     metadata?: Record<string, unknown>;
@@ -1264,8 +1249,6 @@ interface RuntimeBeliefDecisionLabel {
     targetProb?: number;
     qHatChosen?: number | null;
     vHatTarget?: number | null;
-    /** @deprecated Use `qHatChosen` and `vHatTarget` together. */
-    qHat?: number | null;
     costUsd?: number;
     splitTag?: RunSplitTag;
     metadata?: Record<string, unknown>;