@warmdrift/kgauto-compiler 2.0.0-alpha.61 → 2.0.0-alpha.62

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, S as SystemModelMessage, e as CompileResult, B as BestPracticeAdvisory, f as SectionRewrite, R as RecordInput, g as RecordOutcomeInput, O as OutcomeResult, h as OracleScore, i as Adapter, j as PerAxisMetrics, k as Provider, l as ChainEntry, G as Grounding } from './ir-DmUuJsWc.js';
-export { m as CallAttempt, n as CallError, o as ChainModelEntry, p as ChainWithGrounding, q as Constraints, E as EffortLevel, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, r as MutationApplied, s as NormalizedTokens, t as OutcomeKind, u as PerAxisMetricsByModel, v as PromptSection, w as SectionKind, x as ShadowProbeConfig, T as ToolCall, y as ToolDefinition } from './ir-DmUuJsWc.js';
+import { C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, S as SystemModelMessage, e as CompileResult, B as BestPracticeAdvisory, f as SectionRewrite, R as RecordInput, g as RecordOutcomeInput, O as OutcomeResult, h as OracleScore, i as Adapter, j as PerAxisMetrics, k as Provider, l as ChainEntry, G as Grounding } from './ir-ClU56aBc.js';
+export { m as CallAttempt, n as CallError, o as ChainModelEntry, p as ChainWithGrounding, q as Constraints, E as EffortLevel, F as FallbackReason, r as GoldenCaptureOptions, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, s as MutationApplied, t as NormalizedTokens, u as OutcomeKind, v as PerAxisMetricsByModel, w as PromptSection, x as SectionKind, y as ShadowProbeConfig, T as ToolCall, z as ToolDefinition, D as captureGoldenIr, J as parseGoldenCaptureRate, K as resolveGoldenCaptureRate, L as shouldCaptureGolden } from './ir-ClU56aBc.js';
 import { ModelProfile, ArchetypeConvention } from './profiles.js';
 export { ALIASES, CacheStrategy, CliffRule, LATENCY_TIER_MS, LatencyTier, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, latencyTierOf, profilesByProvider, tryGetProfile } from './profiles.js';
 export { BrainForwardConfig, BrainForwardRoutes, createBrainForwardRoutes } from './brain-proxy.js';
@@ -462,7 +462,7 @@ interface BrainHealthSnapshot {
 }
 interface BrainDeadLetterEntry {
     /** Brain route segment the payload was bound for. */
-    route: 'outcomes' | 'compile_outcome_quality' | 'probe_outcomes' | 'compile_outcome_advisories';
+    route: 'outcomes' | 'compile_outcome_quality' | 'probe_outcomes' | 'compile_outcome_advisories' | 'golden_irs';
     /**
      * Endpoint the payload was originally bound for. Flush replays ONLY entries
      * matching the currently-configured endpoint — a reconfigure must never
@@ -686,6 +686,193 @@ declare function buildShadowProbeRow(input: ShadowProbeRecordInput): {
  * `/probe_outcomes` the same way they forward `/outcomes`.
  */
 declare function recordShadowProbe(input: ShadowProbeRecordInput): Promise<void>;
+/**
+ * Golden-IR capture input. UNLIKE every other brain write, this row carries the
+ * RAW full PromptIR — an explicit, documented posture change from the s51
+ * "brain holds no raw consumer prompts" rule, gated on consumer opt-in
+ * (`KGAUTO_GOLDEN_CAPTURE` env / `CallOptions.goldenCapture`). The `consent`
+ * field records the provenance of that opt-in at capture time.
+ */
+interface GoldenIrRecordInput {
+    appId: string;
+    archetype: string;
+    /** hashShape() of the call at compile time (peek before record() pops). */
+    shapeKey?: string;
+    /** The full PromptIR, verbatim. Plain JSON by construction (ir.ts). */
+    ir: unknown;
+    incumbentModel: string;
+    incumbentOutput?: string;
+    incumbentLatencyMs?: number;
+    incumbentTokensIn?: number;
+    incumbentTokensOut?: number;
+    /** 'sampled' (capture flag fired on live traffic) | 'curated' (operator). */
+    source: 'sampled' | 'curated';
+    /** Consent provenance, e.g. 'KGAUTO_GOLDEN_CAPTURE=0.1 (consumer env opt-in)'. */
+    consent: string;
+    /** Optional link back to the compile handle of the captured call. */
+    outcomeHandle?: string;
+}
+/** Pure builder for the `kgauto_golden_irs` row (snake_case wire shape). */
+declare function buildGoldenIrRow(input: GoldenIrRecordInput): {
+    app_id: string;
+    intent_archetype: string;
+    shape_key: string | null;
+    ir: unknown;
+    incumbent_model: string;
+    incumbent_output: string | null;
+    incumbent_latency_ms: number | null;
+    incumbent_tokens_in: number | null;
+    incumbent_tokens_out: number | null;
+    source: 'sampled' | 'curated';
+    consent: string;
+    outcome_handle: string | null;
+};
+/**
+ * Persist one golden IR to `kgauto_golden_irs`. Same G1 write-leg discipline as
+ * every other brain route (redirect check, ledger, dead-letter); fire-and-forget
+ * by default, honors `BrainConfig.sync`. Never throws.
+ */
+declare function recordGoldenIr(input: GoldenIrRecordInput): Promise<void>;
+
+/**
+ * Golden-set eval engine (alpha.62, eval spine — design brief 2026-07-17).
+ *
+ * Implements the quality-floor-guarded model-swap contract:
+ *
+ *   > A model replaces another on a surface only by demonstrating
+ *   > same-or-better quality on that surface's real workload — never by
+ *   > price, recency, or judgment alone.
+ *
+ * One eval run: load the active golden set for (app, archetype), replay every
+ * IR on BOTH the incumbent and the candidate (fresh outputs on both sides —
+ * fair comparison, no stale stored output), apply mechanical hard floors,
+ * then a pairwise LLM judge (order-swapped to cancel position bias), and
+ * aggregate under the non-inferiority rule:
+ *
+ *   promote-ready  ⇔  wins-or-ties ≥ threshold (default 80%)
+ *                     AND zero hard-floor violations
+ *                     AND candidate p50 latency ≤ ratio × incumbent p50
+ *
+ * Evidence lands as brain rows: one `kgauto_golden_eval_runs` aggregate + one
+ * `probe_outcomes` row per case (`replay_source='golden-replay'`, full
+ * fidelity by construction) + an evidence-attached advisory on the consumer's
+ * advisory surface (trust-ladder Stage 1: eval runs, human clicks promote).
+ *
+ * Judging is PAIRWISE, not absolute — it operationalizes the quality-floor
+ * Common Pattern directly ("same or better, never less"). Each pair is judged
+ * twice with A/B order swapped; disagreement between the two orders is scored
+ * a tie (the honest reading of positional noise).
+ *
+ * This module is operator-grade: it talks to the brain via direct PostgREST
+ * with a service key (the watchers' convention), never through consumer
+ * proxies, and it deliberately does NOT call record() — eval traffic must not
+ * pollute compile_outcomes.
+ */
+
+/**
+ * What "better" means per archetype. Fed verbatim into the pairwise judge
+ * prompt. Kept deliberately short — the judge sees the full request, so the
+ * rubric only needs to name the failure modes that matter for the archetype.
+ */
+declare const JUDGE_RUBRICS: Record<string, string>;
+declare function rubricFor(archetype: string): string;
+/** Render the golden IR's request for the judge (system sections + user turn). */
+declare function renderIrForJudge(ir: PromptIR): string;
+declare function buildPairwiseJudgePrompt(args: {
+    archetype: string;
+    renderedInput: string;
+    outputA: string;
+    outputB: string;
+}): string;
+type PairwiseWinner = 'A' | 'B' | 'tie';
+/** Parse the judge's JSON verdict. Returns undefined when unparseable. */
+declare function parseJudgeVerdict(raw: string): {
+    winner: PairwiseWinner;
+    rationale?: string;
+} | undefined;
+/**
+ * Combine the two order-swapped verdicts into a case verdict. Both verdicts
+ * are expressed in incumbent/candidate terms BEFORE this call (the caller
+ * un-swaps run 2). Agreement → that verdict; disagreement → 'tied' (positional
+ * noise reads as a tie, never as a win).
+ */
+declare function combineOrderSwappedVerdicts(run1: 'candidate-better' | 'current-better' | 'tied', run2: 'candidate-better' | 'current-better' | 'tied'): 'candidate-better' | 'current-better' | 'tied';
+interface GoldenEvalOptions {
+    appId: string;
+    archetype: string;
+    candidateModel: string;
+    /**
+     * Incumbent to compare against. Default: the most frequent incumbent_model
+     * across the loaded golden set (the surface's de-facto leader).
+     */
+    incumbentModel?: string;
+    /** Judge model id. Default 'claude-opus-4-8' (judge chain tier 0). */
+    judgeModel?: string;
+    /** Max golden cases to load (newest first). Default 50. */
+    limit?: number;
+    /** Non-inferiority threshold on wins-or-ties. Default 0.8. */
+    winOrTieThreshold?: number;
+    /** Latency hard floor: candidate p50 ≤ ratio × incumbent p50. Default 3. */
+    latencyFloorRatio?: number;
+    /** Minimum judged cases for a non-inconclusive verdict. Default 5. */
+    minJudgeableCases?: number;
+    /** What fired the eval. Default 'manual' (Stage 1). */
+    triggerSource?: 'manual' | 'supply' | 'price' | 'demand';
+    /** Brain access — direct PostgREST (operator convention). */
+    supabaseUrl: string;
+    serviceKey: string;
+    /** Provider keys for the replay + judge calls. Default: process.env. */
+    apiKeys?: ApiKeys;
+    fetchImpl?: typeof fetch;
+    /** Replay + judge but write NOTHING to the brain. */
+    dryRun?: boolean;
+    onProgress?: (message: string) => void;
+}
+interface GoldenEvalCase {
+    goldenIrId: number;
+    verdict: 'candidate-better' | 'tied' | 'current-better' | 'inconclusive';
+    judgeRationale?: string;
+    /** Hard-floor violations on the candidate side for this case. */
+    floorViolations: Array<'empty' | 'schema' | 'candidate_error'>;
+    errorClass?: string;
+    incumbent?: {
+        latencyMs: number;
+        tokensIn: number;
+        tokensOut: number;
+        text: string;
+    };
+    candidate?: {
+        latencyMs: number;
+        tokensIn: number;
+        tokensOut: number;
+        text: string;
+    };
+    /** Case excluded from the denominator (incumbent replay/judge failed). */
+    excludedReason?: string;
+}
+interface GoldenEvalRunResult {
+    verdict: 'promote-ready' | 'not-inferior' | 'inconclusive';
+    runId?: number;
+    appId: string;
+    archetype: string;
+    incumbentModel: string;
+    candidateModel: string;
+    judgeModel: string;
+    nCases: number;
+    wins: number;
+    ties: number;
+    losses: number;
+    floorViolations: number;
+    floorDetail: Record<string, number>;
+    winOrTieRatio: number | null;
+    latencyRatio: number | null;
+    costIncumbentUsd: number | null;
+    costCandidateUsd: number | null;
+    advisoryOutcomeId?: number;
+    cases: GoldenEvalCase[];
+    notes: string[];
+}
+declare function runGoldenEval(opts: GoldenEvalOptions): Promise<GoldenEvalRunResult>;
 
 /**
  * alpha.60 — the library's own version, baked as a constant so Edge/Worker
@@ -700,7 +887,7 @@ declare function recordShadowProbe(input: ShadowProbeRecordInput): Promise<void>
  * guard in `tests/version.test.ts` fails the suite (and therefore
  * `prepublishOnly`) when they diverge — a stale constant cannot reach npm.
  */
-declare const LIBRARY_VERSION = "2.0.0-alpha.61";
+declare const LIBRARY_VERSION = "2.0.0-alpha.62";
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -1886,7 +2073,7 @@ declare function getSequentialStarterChainWithGrounding(archetype: IntentArchety
  * Sync reader for the brain-driven chains map. Returns bundled
  * STARTER_CHAINS when brain-query is disabled, cold, or unreachable.
  */
-declare const loadChainsFromBrain: () => Record<"ask" | "hunt" | "classify" | "summarize" | "generate" | "extract" | "plan" | "critique" | "transform", string[]>;
+declare const loadChainsFromBrain: () => Record<"ask" | "hunt" | "classify" | "summarize" | "generate" | "extract" | "plan" | "critique" | "transform" | "judge", string[]>;
 
 /**
  * archetype-perf-brain — alpha.11 KG-12 adapter.
@@ -2489,4 +2676,4 @@ declare function markPromoteReadyHandled(opts: MarkPromoteReadyHandledOptions):
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, ArchetypeConvention, type ArchetypeFamilyFit, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainDeadLetterEntry, type BrainHealthSnapshot, type BrainQueryConfig, type BrainReadEnv, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, DEFAULT_FINDINGS_ENDPOINT, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, Grounding, IntentArchetypeName, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type ShadowProbeRecordInput, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, brainHealth, buildLLMJudge, buildShadowProbeRow, call, clearBrain, compile, compileForAISDKv6, configureBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, flushBrainDeadLetter, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, peekBrainDeadLetter, probeShadow, profileToRow, readBrainReadEnv, record, recordOutcome, recordShadowProbe, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, ArchetypeConvention, type ArchetypeFamilyFit, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainDeadLetterEntry, type BrainHealthSnapshot, type BrainQueryConfig, type BrainReadEnv, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, DEFAULT_FINDINGS_ENDPOINT, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, type GoldenEvalCase, type GoldenEvalOptions, type GoldenEvalRunResult, type GoldenIrRecordInput, Grounding, IntentArchetypeName, JUDGE_RUBRICS, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type ShadowProbeRecordInput, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, brainHealth, buildGoldenIrRow, buildLLMJudge, buildPairwiseJudgePrompt, buildShadowProbeRow, call, clearBrain, combineOrderSwappedVerdicts, compile, compileForAISDKv6, configureBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, flushBrainDeadLetter, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, parseJudgeVerdict, peekBrainDeadLetter, probeShadow, profileToRow, readBrainReadEnv, record, recordGoldenIr, recordOutcome, recordShadowProbe, renderIrForJudge, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, rubricFor, runAdvisor, runGoldenEval, setTokenizer };