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

package/dist/index.js

@@ -30,6 +30,7 @@ __export(index_exports, {
   DIALECT_VERSION: () => DIALECT_VERSION,
   FamilyResolutionError: () => FamilyResolutionError,
   INTENT_ARCHETYPES: () => INTENT_ARCHETYPES,
+  JUDGE_RUBRICS: () => JUDGE_RUBRICS,
   LATENCY_TIER_MS: () => LATENCY_TIER_MS,
   LIBRARY_VERSION: () => LIBRARY_VERSION,
   MEASURED_GROUNDING_MIN_N: () => MEASURED_GROUNDING_MIN_N,
@@ -45,10 +46,14 @@ __export(index_exports, {
   bucketContext: () => bucketContext,
   bucketHistory: () => bucketHistory,
   bucketToolCount: () => bucketToolCount,
+  buildGoldenIrRow: () => buildGoldenIrRow,
   buildLLMJudge: () => buildLLMJudge,
+  buildPairwiseJudgePrompt: () => buildPairwiseJudgePrompt,
   buildShadowProbeRow: () => buildShadowProbeRow,
   call: () => call,
+  captureGoldenIr: () => captureGoldenIr,
   clearBrain: () => clearBrain,
+  combineOrderSwappedVerdicts: () => combineOrderSwappedVerdicts,
   compile: () => compile2,
   compileForAISDKv6: () => compileForAISDKv6,
   configureBrain: () => configureBrain,
@@ -94,20 +99,28 @@ __export(index_exports, {
   markAdvisoryResolved: () => markAdvisoryResolved,
   markExclusionFindingHandled: () => markExclusionFindingHandled,
   markPromoteReadyHandled: () => markPromoteReadyHandled,
+  parseGoldenCaptureRate: () => parseGoldenCaptureRate,
+  parseJudgeVerdict: () => parseJudgeVerdict,
   peekBrainDeadLetter: () => peekBrainDeadLetter,
   probeShadow: () => probeShadow,
   profileToRow: () => profileToRow,
   profilesByProvider: () => profilesByProvider,
   readBrainReadEnv: () => readBrainReadEnv,
   record: () => record,
+  recordGoldenIr: () => recordGoldenIr,
   recordOutcome: () => recordOutcome,
   recordShadowProbe: () => recordShadowProbe,
+  renderIrForJudge: () => renderIrForJudge,
   resetTokenizer: () => resetTokenizer,
   resolveConventionsForProfile: () => resolveConventionsForProfile,
+  resolveGoldenCaptureRate: () => resolveGoldenCaptureRate,
   resolvePricingAt: () => resolvePricingAt,
   resolveProviderKey: () => resolveProviderKey,
+  rubricFor: () => rubricFor,
   runAdvisor: () => runAdvisor,
+  runGoldenEval: () => runGoldenEval,
   setTokenizer: () => setTokenizer,
+  shouldCaptureGolden: () => shouldCaptureGolden,
   tryGetProfile: () => tryGetProfile
 });
 module.exports = __toCommonJS(index_exports);
@@ -2295,6 +2308,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);
@@ -5005,6 +5023,61 @@ async function recordShadowProbe(input) {
     void send();
   }
 }
+function peekRegisteredShapeKey(handle) {
+  return compileRegistry.get(handle)?.shapeKey;
+}
+function buildGoldenIrRow(input) {
+  return {
+    app_id: input.appId,
+    intent_archetype: input.archetype,
+    shape_key: input.shapeKey ?? null,
+    ir: input.ir,
+    incumbent_model: input.incumbentModel,
+    incumbent_output: input.incumbentOutput ?? null,
+    incumbent_latency_ms: input.incumbentLatencyMs ?? null,
+    incumbent_tokens_in: input.incumbentTokensIn ?? null,
+    incumbent_tokens_out: input.incumbentTokensOut ?? null,
+    source: input.source,
+    consent: input.consent,
+    outcome_handle: input.outcomeHandle ?? null
+  };
+}
+async function recordGoldenIr(input) {
+  if (!activeConfig) return;
+  const config = activeConfig;
+  const fetchFn = brainWriteFetch(config);
+  const row = buildGoldenIrRow(input);
+  const send = async () => {
+    noteSent();
+    try {
+      const res = await fetchFn(`${config.endpoint}/golden_irs`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Prefer: "return=minimal",
+          ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}
+        },
+        body: JSON.stringify(row)
+      });
+      assertNotRedirected(res, "golden_irs");
+      if (!res.ok) {
+        const text = await res.text().catch(() => "<no body>");
+        throw new Error(describeBrainWriteFailure(res.status, "golden_irs", text));
+      }
+      noteAck();
+      maybeAutoFlush();
+    } catch (err) {
+      noteFailure(err);
+      pushDeadLetter("golden_irs", config.endpoint, row, err);
+      (config.onError ?? defaultOnError5)(err);
+    }
+  };
+  if (config.sync) {
+    await send();
+  } else {
+    void send();
+  }
+}
 
 // src/ir.ts
 var CallError = class extends Error {
@@ -5020,6 +5093,45 @@ var CallError = class extends Error {
   }
 };
 
+// src/golden.ts
+function parseGoldenCaptureRate(raw) {
+  if (raw === void 0 || raw.trim() === "") return 0;
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return 0;
+  return Math.max(0, Math.min(1, n));
+}
+function resolveGoldenCaptureRate(optRate) {
+  if (optRate !== void 0 && Number.isFinite(optRate)) {
+    return Math.max(0, Math.min(1, optRate));
+  }
+  const env = typeof process !== "undefined" && process.env ? process.env.KGAUTO_GOLDEN_CAPTURE : void 0;
+  return parseGoldenCaptureRate(env);
+}
+function shouldCaptureGolden(rate, rng = Math.random) {
+  if (rate <= 0) return false;
+  if (rate >= 1) return true;
+  return rng() < rate;
+}
+async function captureGoldenIr(ctx) {
+  try {
+    await recordGoldenIr({
+      appId: ctx.ir.appId,
+      archetype: ctx.ir.intent.archetype,
+      shapeKey: ctx.shapeKey,
+      ir: ctx.ir,
+      incumbentModel: ctx.servedModel,
+      incumbentOutput: ctx.response.text,
+      incumbentLatencyMs: ctx.latencyMs,
+      incumbentTokensIn: ctx.response.tokens.input,
+      incumbentTokensOut: ctx.response.tokens.output,
+      source: "sampled",
+      consent: ctx.consent,
+      outcomeHandle: ctx.handle
+    });
+  } catch {
+  }
+}
+
 // src/env.ts
 var SUPPORTED_PROVIDERS = Object.freeze([
   "anthropic",
@@ -5654,6 +5766,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" },
@@ -6446,6 +6568,8 @@ async function call(ir, opts = {}) {
       );
       const fellOver = targetModel !== initial.target;
       const fallbackReason = fellOver ? normalizeFallbackReason(attempts) : void 0;
+      const goldenRate = resolveGoldenCaptureRate(opts.goldenCapture?.sampleRate);
+      const goldenShapeKey = goldenRate > 0 ? peekRegisteredShapeKey(initial.handle) : void 0;
       await record({
         handle: initial.handle,
         tokensIn: validated.response.tokens.input,
@@ -6498,6 +6622,23 @@ async function call(ir, opts = {}) {
           void probe;
         }
       }
+      if (goldenRate > 0 && validated.response.tokens.output > 0 && shouldCaptureGolden(goldenRate)) {
+        const consent = opts.goldenCapture?.sampleRate !== void 0 ? `CallOptions.goldenCapture.sampleRate=${goldenRate} (consumer code opt-in)` + (opts.goldenCapture.consentNote ? ` \u2014 ${opts.goldenCapture.consentNote}` : "") : `KGAUTO_GOLDEN_CAPTURE=${goldenRate} (consumer env opt-in)`;
+        const capture = captureGoldenIr({
+          ir,
+          servedModel: targetModel,
+          response: validated.response,
+          latencyMs: latencyMs2,
+          handle: initial.handle,
+          shapeKey: goldenShapeKey,
+          consent
+        });
+        if (isBrainSync()) {
+          await capture;
+        } else {
+          void capture;
+        }
+      }
       return {
         handle: initial.handle,
         actualModel: targetModel,
@@ -6837,6 +6978,18 @@ function safeEmit(fn) {
   } catch {
   }
 }
+var _internal = {
+  compileAndRegister,
+  validateStructuredContract,
+  extractPromptPreview,
+  normalizeFallbackReason,
+  generateTraceId,
+  safeEmit,
+  shouldSampleProbe,
+  normalizeProbeCandidates,
+  runShadowProbe,
+  runProbeCandidates
+};
 
 // src/streamtext-helpers.ts
 function attachCacheControlToStreamTextInput(result, convertedMessages) {
@@ -6936,12 +7089,529 @@ function extractKeptToolNames(result) {
   return names;
 }
 
+// src/golden-eval.ts
+var GENERIC_RUBRIC = "overall correctness, completeness against the request, clarity, and adherence to any requested format";
+var JUDGE_RUBRICS = {
+  summarize: "faithfulness to the source (no fabricated facts), coverage of the key points, concision, and adherence to the requested output format",
+  classify: "assignment of the correct category from the allowed set, and nothing outside the allowed set",
+  generate: "relevance to the brief, quality and coherence of the writing, and adherence to the requested format and tone",
+  extract: "completeness of extraction (nothing relevant missed), precision (no invented fields or values), and exact schema adherence",
+  ask: "correctness of the answer with respect to the provided data, relevance, and absence of fabrication",
+  hunt: "relevance and novelty of the discovered entities, and absence of duplicates or fabricated entries",
+  plan: "quality of the decomposition (complete, ordered, actionable steps) and realism of the sequencing",
+  critique: "specificity and correctness of the assessment, and actionability of the feedback",
+  transform: "preservation of the source content and correctness of the target format or style"
+};
+function rubricFor(archetype) {
+  return JUDGE_RUBRICS[archetype] ?? GENERIC_RUBRIC;
+}
+var INPUT_TRUNCATE_CHARS = 24e3;
+var OUTPUT_TRUNCATE_CHARS = 12e3;
+function renderIrForJudge(ir) {
+  const sections = (ir.sections ?? []).map((s) => s.text).filter(Boolean).join("\n\n");
+  const turn = typeof ir.currentTurn?.content === "string" ? ir.currentTurn.content : "";
+  const combined = [
+    sections ? `[system]
+${sections}` : "",
+    turn ? `[user]
+${turn}` : ""
+  ].filter(Boolean).join("\n\n");
+  return combined.length > INPUT_TRUNCATE_CHARS ? `${combined.slice(0, INPUT_TRUNCATE_CHARS)}
+\u2026[truncated]` : combined;
+}
+function buildPairwiseJudgePrompt(args) {
+  const clip = (s) => s.length > OUTPUT_TRUNCATE_CHARS ? `${s.slice(0, OUTPUT_TRUNCATE_CHARS)}
+\u2026[truncated]` : s;
+  return `You are a strict pairwise judge comparing two AI responses to the SAME request.
+
+The request (archetype: ${args.archetype}):
+<request>
+${args.renderedInput}
+</request>
+
+Response A:
+<response_a>
+${clip(args.outputA)}
+</response_a>
+
+Response B:
+<response_b>
+${clip(args.outputB)}
+</response_b>
+
+Judge which response better satisfies the request. Rubric for ${args.archetype}: ${rubricFor(args.archetype)}.
+
+A tie is a legitimate verdict \u2014 declare it when the responses are of genuinely comparable quality. Do NOT prefer a response merely for being longer.
+
+Output ONLY this JSON, no other text:
+{"winner": "A" | "B" | "tie", "rationale": "<one sentence>"}`;
+}
+function parseJudgeVerdict(raw) {
+  const cleaned = raw.replace(/^```(?:json)?\s*/i, "").replace(/\s*```\s*$/, "").trim();
+  let parsed;
+  try {
+    parsed = JSON.parse(cleaned);
+  } catch {
+    const match = cleaned.match(/\{[\s\S]*\}/);
+    if (!match) return void 0;
+    try {
+      parsed = JSON.parse(match[0]);
+    } catch {
+      return void 0;
+    }
+  }
+  if (!parsed || typeof parsed !== "object") return void 0;
+  const obj = parsed;
+  const winner = obj.winner;
+  if (winner !== "A" && winner !== "B" && winner !== "tie") return void 0;
+  return {
+    winner,
+    rationale: typeof obj.rationale === "string" ? obj.rationale : void 0
+  };
+}
+function combineOrderSwappedVerdicts(run1, run2) {
+  if (run1 === run2) return run1;
+  return "tied";
+}
+function replayRetryDelayMs(errorCode) {
+  return errorCode === "rate_limit" ? 65e3 : 2e3;
+}
+function p50(values) {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.floor(sorted.length / 2)] ?? null;
+}
+function costUsd(model, tokensIn, tokensOut) {
+  const profile = tryGetProfile(model);
+  if (!profile) return null;
+  return tokensIn / 1e6 * profile.costInputPer1m + tokensOut / 1e6 * profile.costOutputPer1m;
+}
+function hashForGolden(s) {
+  let h = 5381;
+  for (let i = 0; i < s.length; i += 1) {
+    h = (h << 5) + h + s.charCodeAt(i) >>> 0;
+  }
+  return `g${h.toString(36)}`;
+}
+async function runGoldenEval(opts) {
+  const fetchFn = opts.fetchImpl ?? fetch;
+  const progress = opts.onProgress ?? (() => {
+  });
+  const limit = opts.limit ?? 50;
+  const threshold = opts.winOrTieThreshold ?? 0.8;
+  const latencyFloorRatio = opts.latencyFloorRatio ?? 3;
+  const minJudgeable = opts.minJudgeableCases ?? 5;
+  const judgeModel = opts.judgeModel ?? "claude-opus-4-8";
+  const notes = [];
+  const restHeaders = {
+    apikey: opts.serviceKey,
+    Authorization: `Bearer ${opts.serviceKey}`
+  };
+  const rest = (path) => `${opts.supabaseUrl}/rest/v1/${path}`;
+  const setUrl = rest(
+    `kgauto_golden_irs?app_id=eq.${encodeURIComponent(opts.appId)}&intent_archetype=eq.${encodeURIComponent(opts.archetype)}&active=is.true&select=id,app_id,intent_archetype,ir,incumbent_model&order=captured_at.desc&limit=${limit}`
+  );
+  const setRes = await fetchFn(setUrl, { headers: restHeaders });
+  if (!setRes.ok) {
+    throw new Error(
+      `golden-eval: failed to load golden set (${setRes.status}): ${await setRes.text().catch(() => "<no body>")}`
+    );
+  }
+  const goldenRows = await setRes.json();
+  if (goldenRows.length === 0) {
+    throw new Error(
+      `golden-eval: no active golden IRs for (${opts.appId}, ${opts.archetype}) \u2014 seed via KGAUTO_GOLDEN_CAPTURE or scripts/seed-golden-set.mjs first.`
+    );
+  }
+  progress(`Loaded ${goldenRows.length} golden case(s).`);
+  let incumbentModel = opts.incumbentModel;
+  if (!incumbentModel) {
+    const counts = /* @__PURE__ */ new Map();
+    for (const row of goldenRows) {
+      counts.set(row.incumbent_model, (counts.get(row.incumbent_model) ?? 0) + 1);
+    }
+    const top = [...counts.entries()].sort((a, b) => b[1] - a[1])[0];
+    if (!top) throw new Error("golden-eval: could not resolve an incumbent from the golden set.");
+    incumbentModel = top[0];
+    notes.push(`incumbent defaulted to most-captured model: ${incumbentModel}`);
+  }
+  if (incumbentModel === opts.candidateModel) {
+    throw new Error("golden-eval: candidate and incumbent are the same model.");
+  }
+  const judgeProfile = tryGetProfile(judgeModel);
+  if (!judgeProfile) {
+    throw new Error(`golden-eval: judge model '${judgeModel}' is not in the roster.`);
+  }
+  if (judgeProfile.family && [incumbentModel, opts.candidateModel].some(
+    (m) => tryGetProfile(m)?.family === judgeProfile.family
+  )) {
+    notes.push(
+      `WARNING: judge family (${judgeProfile.family}) overlaps a compared model \u2014 self-preference risk; consider --judge from another provider.`
+    );
+  }
+  const replay = async (ir, model) => {
+    try {
+      const evalIr = {
+        ...ir,
+        models: [model],
+        constraints: { ...ir.constraints ?? {}, forceModel: model }
+      };
+      const compiled = compile(evalIr);
+      const attempt = () => execute(compiled.request, { apiKeys: opts.apiKeys, fetchImpl: opts.fetchImpl });
+      let started = Date.now();
+      let exec = await attempt();
+      if (!exec.ok && exec.errorType === "retryable") {
+        const delayMs = replayRetryDelayMs(exec.errorCode);
+        await new Promise((r) => setTimeout(r, delayMs));
+        started = Date.now();
+        exec = await attempt();
+      }
+      const latencyMs = Date.now() - started;
+      if (!exec.ok) {
+        return {
+          ok: false,
+          text: "",
+          structuredOutput: null,
+          tokensIn: 0,
+          tokensOut: 0,
+          latencyMs,
+          errorClass: exec.errorCode
+        };
+      }
+      const validated = _internal.validateStructuredContract(exec, evalIr);
+      if (!validated.ok) {
+        return {
+          ok: true,
+          text: exec.response.text,
+          structuredOutput: null,
+          tokensIn: exec.response.tokens.input,
+          tokensOut: exec.response.tokens.output,
+          latencyMs,
+          contractViolation: validated.errorCode
+        };
+      }
+      return {
+        ok: true,
+        text: validated.response.text,
+        structuredOutput: validated.response.structuredOutput,
+        parseError: validated.response.parseError,
+        tokensIn: validated.response.tokens.input,
+        tokensOut: validated.response.tokens.output,
+        latencyMs
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        text: "",
+        structuredOutput: null,
+        tokensIn: 0,
+        tokensOut: 0,
+        latencyMs: 0,
+        errorClass: err instanceof Error ? `execute_rejected:${err.message}` : "execute_rejected"
+      };
+    }
+  };
+  const judgeOnce = async (ir, outputA, outputB) => {
+    const judgeIr = {
+      appId: opts.appId,
+      intent: { name: "golden-eval-judge", archetype: "judge" },
+      sections: [
+        {
+          id: "role",
+          text: "You are a strict, impartial pairwise judge. You output only JSON.",
+          weight: 10
+        }
+      ],
+      currentTurn: {
+        role: "user",
+        content: buildPairwiseJudgePrompt({
+          archetype: opts.archetype,
+          renderedInput: renderIrForJudge(ir),
+          outputA,
+          outputB
+        })
+      },
+      models: [judgeModel],
+      constraints: { forceModel: judgeModel }
+    };
+    try {
+      const compiled = compile(judgeIr);
+      const exec = await execute(compiled.request, {
+        apiKeys: opts.apiKeys,
+        fetchImpl: opts.fetchImpl
+      });
+      if (!exec.ok) return void 0;
+      return parseJudgeVerdict(exec.response.text);
+    } catch {
+      return void 0;
+    }
+  };
+  const cases = [];
+  const floorDetail = {};
+  const bumpFloor = (k) => {
+    floorDetail[k] = (floorDetail[k] ?? 0) + 1;
+  };
+  for (const [i, row] of goldenRows.entries()) {
+    progress(
+      `Case ${i + 1}/${goldenRows.length} (golden #${row.id}): replaying ${incumbentModel} + ${opts.candidateModel}\u2026`
+    );
+    const [inc, cand] = await Promise.all([
+      replay(row.ir, incumbentModel),
+      replay(row.ir, opts.candidateModel)
+    ]);
+    if (!inc.ok || inc.contractViolation) {
+      const why = !inc.ok ? `incumbent replay failed (${inc.errorClass ?? "unknown"})` : `incumbent contract violation (${inc.contractViolation})`;
+      cases.push({
+        goldenIrId: row.id,
+        verdict: "inconclusive",
+        floorViolations: [],
+        excludedReason: why
+      });
+      notes.push(`case #${row.id}: ${why} \u2014 excluded`);
+      continue;
+    }
+    const incumbentLeg = {
+      latencyMs: inc.latencyMs,
+      tokensIn: inc.tokensIn,
+      tokensOut: inc.tokensOut,
+      text: inc.text
+    };
+    const violations = [];
+    if (!cand.ok) {
+      violations.push("candidate_error");
+      bumpFloor("candidate_error");
+    } else if (cand.tokensOut === 0 || cand.text.trim() === "" && !cand.structuredOutput) {
+      violations.push("empty");
+      bumpFloor("empty");
+    } else if (cand.contractViolation) {
+      violations.push("schema");
+      bumpFloor("schema");
+    }
+    if (violations.length > 0) {
+      cases.push({
+        goldenIrId: row.id,
+        verdict: "current-better",
+        floorViolations: violations,
+        errorClass: cand.errorClass ?? cand.contractViolation,
+        incumbent: incumbentLeg,
+        candidate: cand.ok ? { latencyMs: cand.latencyMs, tokensIn: cand.tokensIn, tokensOut: cand.tokensOut, text: cand.text } : void 0
+      });
+      continue;
+    }
+    const [order1, order2] = await Promise.all([
+      judgeOnce(row.ir, inc.text, cand.text),
+      judgeOnce(row.ir, cand.text, inc.text)
+    ]);
+    if (!order1 || !order2) {
+      cases.push({
+        goldenIrId: row.id,
+        verdict: "inconclusive",
+        floorViolations: [],
+        incumbent: incumbentLeg,
+        candidate: { latencyMs: cand.latencyMs, tokensIn: cand.tokensIn, tokensOut: cand.tokensOut, text: cand.text },
+        excludedReason: "judge call failed or unparseable"
+      });
+      notes.push(`case #${row.id}: judge failed \u2014 excluded`);
+      continue;
+    }
+    const v1 = order1.winner === "tie" ? "tied" : order1.winner === "B" ? "candidate-better" : "current-better";
+    const v2 = order2.winner === "tie" ? "tied" : order2.winner === "A" ? "candidate-better" : "current-better";
+    const verdict2 = combineOrderSwappedVerdicts(v1, v2);
+    cases.push({
+      goldenIrId: row.id,
+      verdict: verdict2,
+      judgeRationale: order1.rationale ?? order2.rationale,
+      floorViolations: [],
+      incumbent: incumbentLeg,
+      candidate: { latencyMs: cand.latencyMs, tokensIn: cand.tokensIn, tokensOut: cand.tokensOut, text: cand.text }
+    });
+  }
+  const evaluable = cases.filter((c) => !c.excludedReason);
+  const wins = evaluable.filter((c) => c.verdict === "candidate-better").length;
+  const ties = evaluable.filter((c) => c.verdict === "tied").length;
+  const losses = evaluable.filter((c) => c.verdict === "current-better").length;
+  const floorViolations = evaluable.reduce((n, c) => n + c.floorViolations.length, 0);
+  const winOrTieRatio = evaluable.length > 0 ? (wins + ties) / evaluable.length : null;
+  const incP50 = p50(evaluable.map((c) => c.incumbent?.latencyMs ?? NaN).filter(Number.isFinite));
+  const candP50 = p50(evaluable.map((c) => c.candidate?.latencyMs ?? NaN).filter(Number.isFinite));
+  const latencyRatio = incP50 && candP50 ? candP50 / incP50 : null;
+  const sum = (xs) => xs.some((x) => x === null) ? null : xs.reduce((a, b) => a + b, 0);
+  const costIncumbentUsd = sum(
+    evaluable.map(
+      (c) => c.incumbent ? costUsd(incumbentModel, c.incumbent.tokensIn, c.incumbent.tokensOut) : null
+    )
+  );
+  const costCandidateUsd = sum(
+    evaluable.map(
+      (c) => c.candidate ? costUsd(opts.candidateModel, c.candidate.tokensIn, c.candidate.tokensOut) : null
+    )
+  );
+  const latencyFloorOk = latencyRatio === null || latencyRatio <= latencyFloorRatio;
+  if (!latencyFloorOk) bumpFloor("latency");
+  let verdict;
+  if (evaluable.length < minJudgeable) {
+    verdict = "inconclusive";
+    notes.push(
+      `only ${evaluable.length} evaluable case(s) < minJudgeableCases=${minJudgeable}`
+    );
+  } else if (winOrTieRatio !== null && winOrTieRatio >= threshold && floorViolations === 0 && latencyFloorOk) {
+    verdict = "promote-ready";
+  } else {
+    verdict = "not-inferior";
+  }
+  const result = {
+    verdict,
+    appId: opts.appId,
+    archetype: opts.archetype,
+    incumbentModel,
+    candidateModel: opts.candidateModel,
+    judgeModel,
+    nCases: evaluable.length,
+    wins,
+    ties,
+    losses,
+    floorViolations: floorViolations + (latencyFloorOk ? 0 : 1),
+    floorDetail,
+    winOrTieRatio,
+    latencyRatio,
+    costIncumbentUsd,
+    costCandidateUsd,
+    cases,
+    notes
+  };
+  if (opts.dryRun) {
+    notes.push("dry-run: no brain rows written");
+    return result;
+  }
+  progress("Writing eval evidence to the brain\u2026");
+  const runRes = await fetchFn(rest("kgauto_golden_eval_runs"), {
+    method: "POST",
+    headers: {
+      ...restHeaders,
+      "Content-Type": "application/json",
+      Prefer: "return=representation"
+    },
+    body: JSON.stringify({
+      app_id: opts.appId,
+      intent_archetype: opts.archetype,
+      incumbent_model: incumbentModel,
+      candidate_model: opts.candidateModel,
+      trigger_source: opts.triggerSource ?? "manual",
+      judge_model: judgeModel,
+      n_cases: result.nCases,
+      wins,
+      ties,
+      losses,
+      floor_violations: result.floorViolations,
+      floor_detail: floorDetail,
+      win_or_tie_ratio: winOrTieRatio,
+      latency_ratio: latencyRatio,
+      verdict,
+      win_or_tie_threshold: threshold,
+      notes: notes.join(" | ") || null
+    })
+  });
+  if (!runRes.ok) {
+    throw new Error(
+      `golden-eval: run-row write failed (${runRes.status}): ${await runRes.text().catch(() => "<no body>")}`
+    );
+  }
+  const runRows = await runRes.json();
+  result.runId = runRows[0]?.id;
+  const caseRows = cases.filter((c) => !c.excludedReason).map((c) => {
+    const row = goldenRows.find((g) => g.id === c.goldenIrId);
+    const turn = typeof row?.ir.currentTurn?.content === "string" ? row.ir.currentTurn.content : "";
+    return {
+      app_id: opts.appId,
+      intent_archetype: opts.archetype,
+      family: tryGetProfile(opts.candidateModel)?.family ?? "unknown",
+      candidate_model: opts.candidateModel,
+      current_model: incumbentModel,
+      prompt_hash: hashForGolden(turn),
+      current_response: c.incumbent?.text.slice(0, 500) ?? null,
+      candidate_response: c.candidate?.text.slice(0, 500) ?? null,
+      judge_verdict: c.floorViolations.length > 0 ? null : c.verdict,
+      judge_rationale: c.floorViolations.length > 0 ? `hard-floor violation: ${c.floorViolations.join(",")}` : c.judgeRationale ?? null,
+      judge_model: judgeModel,
+      tokens_current_in: c.incumbent?.tokensIn ?? null,
+      tokens_current_out: c.incumbent?.tokensOut ?? null,
+      tokens_candidate_in: c.candidate?.tokensIn ?? null,
+      tokens_candidate_out: c.candidate?.tokensOut ?? null,
+      latency_current_ms: c.incumbent?.latencyMs ?? null,
+      latency_candidate_ms: c.candidate?.latencyMs ?? null,
+      prompt_fidelity: 1,
+      replay_source: "golden-replay",
+      outcome: c.floorViolations.includes("candidate_error") ? "candidate_error" : "completed",
+      // migration-032 taxonomy: error_class only on candidate_error rows;
+      // schema-floor detail rides in judge_rationale + the run's floor_detail.
+      error_class: c.floorViolations.includes("candidate_error") ? c.errorClass ?? null : null,
+      golden_run_id: result.runId ?? null,
+      golden_ir_id: c.goldenIrId
+    };
+  });
+  if (caseRows.length > 0) {
+    const casesRes = await fetchFn(rest("probe_outcomes"), {
+      method: "POST",
+      headers: { ...restHeaders, "Content-Type": "application/json", Prefer: "return=minimal" },
+      body: JSON.stringify(caseRows)
+    });
+    if (!casesRes.ok) {
+      notes.push(
+        `case-row write failed (${casesRes.status}): ${await casesRes.text().catch(() => "<no body>")}`
+      );
+    }
+  }
+  const latestRes = await fetchFn(
+    rest(
+      `compile_outcomes?app_id=eq.${encodeURIComponent(opts.appId)}&select=id&order=id.desc&limit=1`
+    ),
+    { headers: restHeaders }
+  );
+  const latest = latestRes.ok ? await latestRes.json() : [];
+  const latestOutcomeId = latest[0]?.id;
+  if (latestOutcomeId !== void 0) {
+    const costLine = costIncumbentUsd !== null && costCandidateUsd !== null ? ` Eval cost basis: incumbent $${costIncumbentUsd.toFixed(4)} vs candidate $${costCandidateUsd.toFixed(4)} across the set.` : "";
+    const message = `Golden-set eval (run #${result.runId}): ${opts.candidateModel} vs ${incumbentModel} on ${opts.appId}/${opts.archetype} \u2014 verdict ${verdict.toUpperCase()}. ${wins}W/${ties}T/${losses}L over ${result.nCases} real workload case(s), wins-or-ties ${(100 * (winOrTieRatio ?? 0)).toFixed(0)}% (threshold ${(100 * threshold).toFixed(0)}%), ${result.floorViolations} hard-floor violation(s), latency ratio ${latencyRatio?.toFixed(2) ?? "n/a"}.` + costLine;
+    const suggestion = verdict === "promote-ready" ? `Candidate passed the non-inferiority rule on your real workload. To promote: node v2/scripts/promote-model.mjs --model ${opts.candidateModel} (or ask kgauto-Cairn). Evidence: kgauto_golden_eval_runs #${result.runId} + probe_outcomes golden_run_id=${result.runId}.` : `Candidate did NOT clear the non-inferiority rule \u2014 no action needed; the incumbent stays. Evidence rows: golden_run_id=${result.runId}.`;
+    const advRes = await fetchFn(rest("compile_outcome_advisories"), {
+      method: "POST",
+      headers: { ...restHeaders, "Content-Type": "application/json", Prefer: "return=minimal" },
+      body: JSON.stringify({
+        outcome_id: latestOutcomeId,
+        code: "golden-eval-verdict",
+        level: "info",
+        recommendation_type: "model-swap",
+        message,
+        suggestion
+      })
+    });
+    if (advRes.ok) {
+      result.advisoryOutcomeId = latestOutcomeId;
+      await fetchFn(rest(`kgauto_golden_eval_runs?id=eq.${result.runId}`), {
+        method: "PATCH",
+        headers: { ...restHeaders, "Content-Type": "application/json", Prefer: "return=minimal" },
+        body: JSON.stringify({ advisory_outcome_id: latestOutcomeId })
+      }).catch(() => {
+      });
+    } else {
+      notes.push(`advisory write failed (${advRes.status})`);
+    }
+  } else {
+    notes.push("no compile_outcomes row for app \u2014 evidence advisory skipped (view needs a real outcome_id)");
+  }
+  return result;
+}
+
 // src/brain-proxy.ts
 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" };
@@ -7099,7 +7769,7 @@ function createBrainForwardRoutes(config) {
 }
 
 // src/version.ts
-var LIBRARY_VERSION = "2.0.0-alpha.61";
+var LIBRARY_VERSION = "2.0.0-alpha.63";
 
 // src/key-health.ts
 var JSON_HEADERS2 = { "Content-Type": "application/json" };
@@ -7722,6 +8392,7 @@ function compile2(ir, opts) {
   DIALECT_VERSION,
   FamilyResolutionError,
   INTENT_ARCHETYPES,
+  JUDGE_RUBRICS,
   LATENCY_TIER_MS,
   LIBRARY_VERSION,
   MEASURED_GROUNDING_MIN_N,
@@ -7737,10 +8408,14 @@ function compile2(ir, opts) {
   bucketContext,
   bucketHistory,
   bucketToolCount,
+  buildGoldenIrRow,
   buildLLMJudge,
+  buildPairwiseJudgePrompt,
   buildShadowProbeRow,
   call,
+  captureGoldenIr,
   clearBrain,
+  combineOrderSwappedVerdicts,
   compile,
   compileForAISDKv6,
   configureBrain,
@@ -7786,19 +8461,27 @@ function compile2(ir, opts) {
   markAdvisoryResolved,
   markExclusionFindingHandled,
   markPromoteReadyHandled,
+  parseGoldenCaptureRate,
+  parseJudgeVerdict,
   peekBrainDeadLetter,
   probeShadow,
   profileToRow,
   profilesByProvider,
   readBrainReadEnv,
   record,
+  recordGoldenIr,
   recordOutcome,
   recordShadowProbe,
+  renderIrForJudge,
   resetTokenizer,
   resolveConventionsForProfile,
+  resolveGoldenCaptureRate,
   resolvePricingAt,
   resolveProviderKey,
+  rubricFor,
   runAdvisor,
+  runGoldenEval,
   setTokenizer,
+  shouldCaptureGolden,
   tryGetProfile
 });