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

package/README.md

@@ -26,10 +26,11 @@ What this package delivers today, and nothing it doesn't:
 
 **What it does not do (yet):** routing does not change itself from measured
 outcomes. There is no automatic learning loop in the shipped package — model
-promotion is evidence-*informed* but operator-*driven*. The eval-driven
-quality-floor-guarded swap architecture is specced (2026-07-17) and is the
-current engineering arc; the learning claims return to this README when they
-are code, not before.
+promotion is evidence-*informed* but operator-*driven*. What DOES ship as of
+alpha.62 is the eval spine (Stage 1 of that architecture): golden-set capture,
+a pairwise judge, and a non-inferiority eval whose verdict lands as evidence
+on the advisory surface — the eval runs, a human clicks promote. Automatic
+promotion (Stages 2–3) returns to this README when it is code, not before.
 
 Greenfield rewrite of `@warmdrift/kgauto` v1 (a behavioral patcher with
 telemetry).
@@ -324,16 +325,33 @@ For staging without a dedicated brain, point consumers at the same Supabase
 they already use — the schema is identical and migration to a dedicated brain
 is a `pg_dump` away.
 
+## Golden-set eval (alpha.62 — Stage 1, shipped)
+
+The eval-driven quality-floor-guarded swap architecture (specced 2026-07-17
+after an adversarial promise review) began shipping in alpha.62:
+
+- **Capture:** set `KGAUTO_GOLDEN_CAPTURE=0.1` on a consumer and successful
+  `call()`s sample their full IR + served output into a per-surface replay
+  corpus. Explicit opt-in — golden rows carry raw prompts (documented posture
+  change; consent provenance on every row; reads strictly app-scoped). Or
+  hand-curate with `scripts/seed-golden-set.mjs`.
+- **Eval:** `scripts/run-golden-eval.mjs --app X --archetype Y --candidate M`
+  replays the corpus on incumbent AND candidate (fresh outputs both sides),
+  applies mechanical hard floors (empty / schema / candidate-error / latency),
+  and runs an order-swapped pairwise judge (`judge` archetype, per-archetype
+  rubrics). Non-inferiority rule: wins-or-ties ≥ 80% + zero floor violations
+  → `promote-ready`.
+- **Evidence:** every run lands as brain rows (`kgauto_golden_eval_runs` +
+  per-case `probe_outcomes` `golden-replay` rows) and a `golden-eval-verdict`
+  advisory on the consumer's advisory surface.
+
 ## What's next
 
-The current arc (specced 2026-07-17, after an adversarial promise review)
-is **eval-driven quality-floor-guarded model swap**: golden sets of real
-IRs per consumer surface, a pairwise judge archetype, a non-inferiority
-promotion rule, and a rollback guard — evidence generated on demand instead
-of waiting for organic traffic volume that doesn't exist. A model replaces
-another on a surface only by demonstrating same-or-better quality on that
-surface's real workload. Each stage lands in this README **when it ships**,
-with its gate evidence — the promise follows the code.
+Stages 2–3 of the trust ladder (auto-promote downswaps behind a 7-day
+rollback guard, then upswaps) and trigger wiring (model-release-watch /
+price-truth-watch / live-telemetry drift → auto-eval), then the same harness
+pointed at compile variants (Tier D). Each stage lands in this README **when
+it ships**, with its gate evidence — the promise follows the code.
 
 ## Why this exists
 

package/dist/brain-proxy.js

@@ -27,7 +27,11 @@ var SEGMENT_TO_TABLE = {
   outcomes: "compile_outcomes",
   compile_outcome_advisories: "compile_outcome_advisories",
   compile_outcome_quality: "compile_outcome_quality",
-  probe_outcomes: "probe_outcomes"
+  probe_outcomes: "probe_outcomes",
+  // alpha.62 (eval spine): golden-set capture. Only receives rows when the
+  // consumer has explicitly opted in via KGAUTO_GOLDEN_CAPTURE — the segment
+  // existing here does not by itself store anything.
+  golden_irs: "kgauto_golden_irs"
 };
 var KNOWN_SEGMENTS = Object.keys(SEGMENT_TO_TABLE);
 var JSON_HEADERS = { "Content-Type": "application/json" };

package/dist/brain-proxy.mjs

@@ -1,6 +1,6 @@
 import {
   createBrainForwardRoutes
-} from "./chunk-IUWFML6Z.mjs";
+} from "./chunk-65ZMX5OT.mjs";
 export {
   createBrainForwardRoutes
 };

package/dist/{chunk-5TI6PNSK.mjs → chunk-3KQAID63.mjs}

@@ -45,6 +45,11 @@ var INTENT_ARCHETYPES = {
     name: "transform",
     description: "Change format or style while preserving content",
     examples: ["markdown \u2192 html", "formal \u2192 casual", "translate"]
+  },
+  judge: {
+    name: "judge",
+    description: "Pairwise comparison of two candidate outputs for the same input",
+    examples: ["golden-set eval A/B verdict", "model-swap non-inferiority check", "response bake-off"]
   }
 };
 var ALL_ARCHETYPES = Object.keys(INTENT_ARCHETYPES);

package/dist/{chunk-IUWFML6Z.mjs → chunk-65ZMX5OT.mjs}

@@ -3,7 +3,11 @@ var SEGMENT_TO_TABLE = {
   outcomes: "compile_outcomes",
   compile_outcome_advisories: "compile_outcome_advisories",
   compile_outcome_quality: "compile_outcome_quality",
-  probe_outcomes: "probe_outcomes"
+  probe_outcomes: "probe_outcomes",
+  // alpha.62 (eval spine): golden-set capture. Only receives rows when the
+  // consumer has explicitly opted in via KGAUTO_GOLDEN_CAPTURE — the segment
+  // existing here does not by itself store anything.
+  golden_irs: "kgauto_golden_irs"
 };
 var KNOWN_SEGMENTS = Object.keys(SEGMENT_TO_TABLE);
 var JSON_HEADERS = { "Content-Type": "application/json" };

package/dist/{chunk-3RMLZCUK.mjs → chunk-ABFXMO73.mjs}

@@ -1,5 +1,5 @@
 // src/version.ts
-var LIBRARY_VERSION = "2.0.0-alpha.61";
+var LIBRARY_VERSION = "2.0.0-alpha.62";
 
 // src/key-health.ts
 var JSON_HEADERS = { "Content-Type": "application/json" };

package/dist/{chunk-IIMPJZNH.mjs → chunk-YZRPNSSQ.mjs}

@@ -333,6 +333,16 @@ var STARTER_CHAINS_GROUNDED = {
     { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor in similar quality bracket" },
     { id: "gpt-5.5", grounding: "judgment", reason: "alpha.16: third-provider frontier-tier floor (archetypePerf=9)" }
   ],
+  // alpha.62 (eval spine) — pairwise output comparison. Same reasoning-floor
+  // posture as critique (a verdict from a weak judge is worse than no
+  // verdict); tier 0 anchored on the CURRENT opus (4-8, s64 roster). Strict
+  // JSON output, so every tier declares native structured output.
+  judge: [
+    { id: "claude-opus-4-8", grounding: "judgment", reason: "Highest reasoning bar for pairwise verdicts \u2014 current opus (s64 roster)" },
+    { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Same-provider walk-down on 429" },
+    { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor in similar quality bracket" },
+    { id: "gpt-5.5", grounding: "judgment", reason: "Third-provider frontier-tier floor" }
+  ],
   // Reasoning matters — Sonnet primary; walk UP to Opus on 429.
   plan: [
     { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Reasoning + cost balance \u2014 engineer pick" },

package/dist/dialect.d.mts

@@ -12,8 +12,15 @@
  * The brain learns by `(archetype, model, shape)` tuples. Apps that declare
  * the same tuple inherit each other's mutations.
  *
- * v1 is intentionally small (9 archetypes, 5 shape dimensions). New entries
- * arrive in v2/v3 from real usage signals — never speculatively.
+ * v1 is intentionally small (10 archetypes, 5 shape dimensions). New entries
+ * arrive from real usage signals — never speculatively.
+ *
+ * Versioning note (alpha.62): `judge` was added as an ADDITIVE 10th entry
+ * under dialect-v1 rather than bumping to v2. Bumping the version string
+ * would fragment every existing learning key (`v1::…` → `v2::…`) for a
+ * purely additive vocabulary change; existing keys are untouched and judge
+ * keys are new, so no collision is possible. A v2 bump is reserved for
+ * changes that alter the MEANING of existing entries or the shape hash.
  */
 declare const DIALECT_VERSION: "v1";
 declare const INTENT_ARCHETYPES: {
@@ -62,6 +69,11 @@ declare const INTENT_ARCHETYPES: {
         readonly description: "Change format or style while preserving content";
         readonly examples: ["markdown → html", "formal → casual", "translate"];
     };
+    readonly judge: {
+        readonly name: "judge";
+        readonly description: "Pairwise comparison of two candidate outputs for the same input";
+        readonly examples: ["golden-set eval A/B verdict", "model-swap non-inferiority check", "response bake-off"];
+    };
 };
 type IntentArchetypeName = keyof typeof INTENT_ARCHETYPES;
 declare const ALL_ARCHETYPES: IntentArchetypeName[];

package/dist/dialect.d.ts

@@ -12,8 +12,15 @@
  * The brain learns by `(archetype, model, shape)` tuples. Apps that declare
  * the same tuple inherit each other's mutations.
  *
- * v1 is intentionally small (9 archetypes, 5 shape dimensions). New entries
- * arrive in v2/v3 from real usage signals — never speculatively.
+ * v1 is intentionally small (10 archetypes, 5 shape dimensions). New entries
+ * arrive from real usage signals — never speculatively.
+ *
+ * Versioning note (alpha.62): `judge` was added as an ADDITIVE 10th entry
+ * under dialect-v1 rather than bumping to v2. Bumping the version string
+ * would fragment every existing learning key (`v1::…` → `v2::…`) for a
+ * purely additive vocabulary change; existing keys are untouched and judge
+ * keys are new, so no collision is possible. A v2 bump is reserved for
+ * changes that alter the MEANING of existing entries or the shape hash.
  */
 declare const DIALECT_VERSION: "v1";
 declare const INTENT_ARCHETYPES: {
@@ -62,6 +69,11 @@ declare const INTENT_ARCHETYPES: {
         readonly description: "Change format or style while preserving content";
         readonly examples: ["markdown → html", "formal → casual", "translate"];
     };
+    readonly judge: {
+        readonly name: "judge";
+        readonly description: "Pairwise comparison of two candidate outputs for the same input";
+        readonly examples: ["golden-set eval A/B verdict", "model-swap non-inferiority check", "response bake-off"];
+    };
 };
 type IntentArchetypeName = keyof typeof INTENT_ARCHETYPES;
 declare const ALL_ARCHETYPES: IntentArchetypeName[];

package/dist/dialect.js

@@ -77,6 +77,11 @@ var INTENT_ARCHETYPES = {
     name: "transform",
     description: "Change format or style while preserving content",
     examples: ["markdown \u2192 html", "formal \u2192 casual", "translate"]
+  },
+  judge: {
+    name: "judge",
+    description: "Pairwise comparison of two candidate outputs for the same input",
+    examples: ["golden-set eval A/B verdict", "model-swap non-inferiority check", "response bake-off"]
   }
 };
 var ALL_ARCHETYPES = Object.keys(INTENT_ARCHETYPES);

package/dist/dialect.mjs

@@ -8,7 +8,7 @@ import {
   hashShape,
   isArchetype,
   learningKey
-} from "./chunk-5TI6PNSK.mjs";
+} from "./chunk-3KQAID63.mjs";
 export {
   ALL_ARCHETYPES,
   DIALECT_VERSION,

package/dist/glassbox/index.d.mts

@@ -1,6 +1,6 @@
-import { G as GlassboxEvent } from '../types-CssWqd0X.mjs';
-export { A as AdvisoryFiredData, C as CompileDoneData, a as CompileStartData, E as ExecuteAttemptData, b as ExecuteSuccessData, F as FallbackWalkedData, c as GLASSBOX_STREAM_TTL_MS, d as GlassboxEventKind, e as GlassboxPubSub } from '../types-CssWqd0X.mjs';
-import '../ir-DAKlQsVb.mjs';
+import { G as GlassboxEvent } from '../types-axAX1Bg0.mjs';
+export { A as AdvisoryFiredData, C as CompileDoneData, a as CompileStartData, E as ExecuteAttemptData, b as ExecuteSuccessData, F as FallbackWalkedData, c as GLASSBOX_STREAM_TTL_MS, d as GlassboxEventKind, e as GlassboxPubSub } from '../types-axAX1Bg0.mjs';
+import '../ir-B2dRyJXO.mjs';
 import '../dialect.mjs';
 
 /**

package/dist/glassbox/index.d.ts

@@ -1,6 +1,6 @@
-import { G as GlassboxEvent } from '../types-DR62iPcO.js';
-export { A as AdvisoryFiredData, C as CompileDoneData, a as CompileStartData, E as ExecuteAttemptData, b as ExecuteSuccessData, F as FallbackWalkedData, c as GLASSBOX_STREAM_TTL_MS, d as GlassboxEventKind, e as GlassboxPubSub } from '../types-DR62iPcO.js';
-import '../ir-DmUuJsWc.js';
+import { G as GlassboxEvent } from '../types-C-Wp7HpI.js';
+export { A as AdvisoryFiredData, C as CompileDoneData, a as CompileStartData, E as ExecuteAttemptData, b as ExecuteSuccessData, F as FallbackWalkedData, c as GLASSBOX_STREAM_TTL_MS, d as GlassboxEventKind, e as GlassboxPubSub } from '../types-C-Wp7HpI.js';
+import '../ir-ClU56aBc.js';
 import '../dialect.js';
 
 /**

package/dist/glassbox-routes/format.d.mts

@@ -1,5 +1,5 @@
-import { T as TraceHealth } from '../types-MRMBUqzY.mjs';
-import '../ir-DAKlQsVb.mjs';
+import { T as TraceHealth } from '../types-CSDweZsl.mjs';
+import '../ir-B2dRyJXO.mjs';
 import '../dialect.mjs';
 
 /**

package/dist/glassbox-routes/format.d.ts

@@ -1,5 +1,5 @@
-import { T as TraceHealth } from '../types-B8X1Pyhx.js';
-import '../ir-DmUuJsWc.js';
+import { T as TraceHealth } from '../types-ByN3r0_7.js';
+import '../ir-ClU56aBc.js';
 import '../dialect.js';
 
 /**

package/dist/glassbox-routes/index.d.mts

@@ -1,7 +1,7 @@
-import { G as GlassboxEvent } from '../types-CssWqd0X.mjs';
-import { a as TraceDetail, b as TraceSummary, c as TraceCounterfactual } from '../types-MRMBUqzY.mjs';
-export { A as AdvisoryRecord, T as TraceHealth, d as TraceSectionRewrite } from '../types-MRMBUqzY.mjs';
-import '../ir-DAKlQsVb.mjs';
+import { G as GlassboxEvent } from '../types-axAX1Bg0.mjs';
+import { a as TraceDetail, b as TraceSummary, c as TraceCounterfactual } from '../types-CSDweZsl.mjs';
+export { A as AdvisoryRecord, T as TraceHealth, d as TraceSectionRewrite } from '../types-CSDweZsl.mjs';
+import '../ir-B2dRyJXO.mjs';
 import '../dialect.mjs';
 
 /**

package/dist/glassbox-routes/index.d.ts

@@ -1,7 +1,7 @@
-import { G as GlassboxEvent } from '../types-DR62iPcO.js';
-import { a as TraceDetail, b as TraceSummary, c as TraceCounterfactual } from '../types-B8X1Pyhx.js';
-export { A as AdvisoryRecord, T as TraceHealth, d as TraceSectionRewrite } from '../types-B8X1Pyhx.js';
-import '../ir-DmUuJsWc.js';
+import { G as GlassboxEvent } from '../types-C-Wp7HpI.js';
+import { a as TraceDetail, b as TraceSummary, c as TraceCounterfactual } from '../types-ByN3r0_7.js';
+export { A as AdvisoryRecord, T as TraceHealth, d as TraceSectionRewrite } from '../types-ByN3r0_7.js';
+import '../ir-ClU56aBc.js';
 import '../dialect.js';
 
 /**

package/dist/glassbox-routes/index.js

@@ -1650,6 +1650,16 @@ var STARTER_CHAINS_GROUNDED = {
     { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor in similar quality bracket" },
     { id: "gpt-5.5", grounding: "judgment", reason: "alpha.16: third-provider frontier-tier floor (archetypePerf=9)" }
   ],
+  // alpha.62 (eval spine) — pairwise output comparison. Same reasoning-floor
+  // posture as critique (a verdict from a weak judge is worse than no
+  // verdict); tier 0 anchored on the CURRENT opus (4-8, s64 roster). Strict
+  // JSON output, so every tier declares native structured output.
+  judge: [
+    { id: "claude-opus-4-8", grounding: "judgment", reason: "Highest reasoning bar for pairwise verdicts \u2014 current opus (s64 roster)" },
+    { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Same-provider walk-down on 429" },
+    { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor in similar quality bracket" },
+    { id: "gpt-5.5", grounding: "judgment", reason: "Third-provider frontier-tier floor" }
+  ],
   // Reasoning matters — Sonnet primary; walk UP to Opus on 429.
   plan: [
     { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Reasoning + cost balance \u2014 engineer pick" },

package/dist/glassbox-routes/index.mjs

@@ -1,7 +1,7 @@
 import {
   ARCHETYPE_FLOOR_DEFAULT,
   getDefaultFallbackChain
-} from "../chunk-IIMPJZNH.mjs";
+} from "../chunk-YZRPNSSQ.mjs";
 import {
   tryGetProfile
 } from "../chunk-QKXTMVCT.mjs";

package/dist/glassbox-routes/react/index.d.mts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { a as TraceDetail } from '../../types-MRMBUqzY.mjs';
-import '../../ir-DAKlQsVb.mjs';
+import { a as TraceDetail } from '../../types-CSDweZsl.mjs';
+import '../../ir-B2dRyJXO.mjs';
 import '../../dialect.mjs';
 
 /**

package/dist/glassbox-routes/react/index.d.ts

@@ -1,6 +1,6 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { a as TraceDetail } from '../../types-B8X1Pyhx.js';
-import '../../ir-DmUuJsWc.js';
+import { a as TraceDetail } from '../../types-ByN3r0_7.js';
+import '../../ir-ClU56aBc.js';
 import '../../dialect.js';
 
 /**

package/dist/index.d.mts

@@ -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-DAKlQsVb.mjs';
-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-DAKlQsVb.mjs';
+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-B2dRyJXO.mjs';
+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-B2dRyJXO.mjs';
 import { ModelProfile, ArchetypeConvention } from './profiles.mjs';
 export { ALIASES, CacheStrategy, CliffRule, LATENCY_TIER_MS, LatencyTier, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, latencyTierOf, profilesByProvider, tryGetProfile } from './profiles.mjs';
 export { BrainForwardConfig, BrainForwardRoutes, createBrainForwardRoutes } from './brain-proxy.mjs';
@@ -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 };