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

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import {
   createBrainForwardRoutes
-} from "./chunk-IUWFML6Z.mjs";
+} from "./chunk-65ZMX5OT.mjs";
 import {
   ALL_ARCHETYPES,
   DIALECT_VERSION,
@@ -11,11 +11,11 @@ import {
   hashShape,
   isArchetype,
   learningKey
-} from "./chunk-5TI6PNSK.mjs";
+} from "./chunk-3KQAID63.mjs";
 import {
   LIBRARY_VERSION,
   createKeyHealthRoute
-} from "./chunk-RQ3BUUB6.mjs";
+} from "./chunk-ABFXMO73.mjs";
 import {
   ABSOLUTE_FLOOR,
   ARCHETYPE_FLOOR_DEFAULT,
@@ -40,7 +40,7 @@ import {
   loadChainsFromBrain,
   readBrainReadEnv,
   resolveProviderKey
-} from "./chunk-IIMPJZNH.mjs";
+} from "./chunk-YZRPNSSQ.mjs";
 import {
   ALIASES,
   LATENCY_TIER_MS,
@@ -2626,6 +2626,134 @@ function clearBrain() {
   configureBrainQuery(void 0);
   configureExclusionFindingsBrain(void 0);
 }
+var DEAD_LETTER_MAX_ENTRIES = 50;
+var DEAD_LETTER_MAX_ATTEMPTS = 3;
+var ledger = {
+  sent: 0,
+  acked: 0,
+  failed: 0,
+  redirected: 0,
+  lastAckAt: void 0,
+  lastFailureAt: void 0,
+  lastFailure: void 0
+};
+var deadLetter = [];
+var flushing = false;
+function noteSent() {
+  ledger.sent += 1;
+}
+function noteAck() {
+  ledger.acked += 1;
+  ledger.lastAckAt = (/* @__PURE__ */ new Date()).toISOString();
+}
+function noteFailure(err) {
+  ledger.failed += 1;
+  ledger.lastFailureAt = (/* @__PURE__ */ new Date()).toISOString();
+  const msg = err instanceof Error ? err.message : String(err);
+  ledger.lastFailure = msg.length > 300 ? `${msg.slice(0, 300)}\u2026` : msg;
+}
+function assertNotRedirected(res, route) {
+  if (!res.redirected) return;
+  ledger.redirected += 1;
+  throw new Error(
+    `brain ${route} POST was redirected to ${res.url} \u2014 the write did NOT land. Likely cause: consumer middleware (auth/login allowlist) intercepts the brain proxy path. Add your kgauto proxy routes to the middleware public paths (the 2026-07-02 tt-intel/IC middleware-drift class).`
+  );
+}
+function pushDeadLetter(route, endpoint, payload, err) {
+  if (deadLetter.length >= DEAD_LETTER_MAX_ENTRIES) deadLetter.shift();
+  deadLetter.push({
+    route,
+    endpoint,
+    payload,
+    failedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    attempts: 1,
+    lastError: err instanceof Error ? err.message : String(err)
+  });
+}
+function maybeAutoFlush() {
+  if (deadLetter.length === 0 || flushing) return;
+  void flushBrainDeadLetter();
+}
+function brainHealth() {
+  let endpointHost;
+  if (activeConfig) {
+    try {
+      endpointHost = new URL(activeConfig.endpoint).host;
+    } catch {
+      endpointHost = void 0;
+    }
+  }
+  return {
+    configState: activeConfig ? "configured" : "not_configured",
+    endpointHost,
+    sync: activeConfig?.sync === true,
+    sent: ledger.sent,
+    acked: ledger.acked,
+    failed: ledger.failed,
+    redirected: ledger.redirected,
+    lastAckAt: ledger.lastAckAt,
+    lastFailureAt: ledger.lastFailureAt,
+    lastFailure: ledger.lastFailure,
+    deadLetterCount: deadLetter.length
+  };
+}
+function peekBrainDeadLetter() {
+  return deadLetter.slice();
+}
+async function flushBrainDeadLetter() {
+  if (!activeConfig || flushing || deadLetter.length === 0) {
+    return { attempted: 0, delivered: 0, remaining: deadLetter.length };
+  }
+  flushing = true;
+  const config = activeConfig;
+  const fetchFn = brainWriteFetch(config);
+  let attempted = 0;
+  let delivered = 0;
+  try {
+    const batch = deadLetter.filter((e) => e.endpoint === config.endpoint);
+    for (const entry of batch) {
+      attempted += 1;
+      noteSent();
+      try {
+        const res = await fetchFn(`${config.endpoint}/${entry.route}`, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            // Replay never chains a secondary — minimal is correct for all routes.
+            Prefer: "return=minimal",
+            ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}
+          },
+          body: JSON.stringify(entry.payload)
+        });
+        assertNotRedirected(res, entry.route);
+        if (!res.ok) {
+          const text = await res.text().catch(() => "<no body>");
+          throw new Error(describeBrainWriteFailure(res.status, entry.route, text));
+        }
+        noteAck();
+        delivered += 1;
+        const idx = deadLetter.indexOf(entry);
+        if (idx !== -1) deadLetter.splice(idx, 1);
+      } catch (err) {
+        noteFailure(err);
+        entry.attempts += 1;
+        entry.lastError = err instanceof Error ? err.message : String(err);
+        if (entry.attempts >= DEAD_LETTER_MAX_ATTEMPTS) {
+          const idx = deadLetter.indexOf(entry);
+          if (idx !== -1) deadLetter.splice(idx, 1);
+          (config.onError ?? defaultOnError4)(
+            new Error(
+              `brain dead-letter: dropping ${entry.route} payload after ${entry.attempts} attempts \u2014 last error: ${entry.lastError}`
+            )
+          );
+        }
+      }
+    }
+  } finally {
+    flushing = false;
+  }
+  return { attempted, delivered, remaining: deadLetter.length };
+}
 var compileRegistry = /* @__PURE__ */ new Map();
 var REGISTRY_MAX_ENTRIES = 1e4;
 function registerCompile(appId, archetype, ir, result) {
@@ -2733,6 +2861,7 @@ async function record(input) {
   const fetchFn = brainWriteFetch(config);
   const send = async () => {
     let outcomeId;
+    noteSent();
     try {
       const res = await fetchFn(`${config.endpoint}/outcomes`, {
         method: "POST",
@@ -2752,20 +2881,26 @@ async function record(input) {
         },
         body: JSON.stringify(payload)
       });
+      assertNotRedirected(res, "outcomes");
       if (!res.ok) {
         const text = await res.text().catch(() => "<no body>");
         throw new Error(describeBrainWriteFailure(res.status, "outcomes", text));
       }
+      noteAck();
       outcomeId = await tryExtractOutcomeId(res);
     } catch (err) {
+      noteFailure(err);
+      pushDeadLetter("outcomes", config.endpoint, payload, err);
       (config.onError ?? defaultOnError4)(err);
       return;
     }
+    maybeAutoFlush();
     const advisories = input.advisories ?? reg?.advisoriesFromCompile;
     if (!advisories || advisories.length === 0) return;
     if (outcomeId === void 0) return;
+    const advisoryPayload = advisories.map((a) => buildAdvisoryRow(outcomeId, a));
+    noteSent();
     try {
-      const advisoryPayload = advisories.map((a) => buildAdvisoryRow(outcomeId, a));
       const res = await fetchFn(`${config.endpoint}/compile_outcome_advisories`, {
         method: "POST",
         headers: {
@@ -2775,11 +2910,15 @@ async function record(input) {
         },
         body: JSON.stringify(advisoryPayload)
       });
+      assertNotRedirected(res, "compile_outcome_advisories");
       if (!res.ok) {
         const text = await res.text().catch(() => "<no body>");
         throw new Error(`brain advisories ${res.status}: ${text}`);
       }
+      noteAck();
     } catch (err) {
+      noteFailure(err);
+      pushDeadLetter("compile_outcome_advisories", config.endpoint, advisoryPayload, err);
       (config.onError ?? defaultOnError4)(err);
     }
   };
@@ -2918,6 +3057,7 @@ async function recordOutcome(input) {
     observed_confidence: input.observedConfidence ?? null
   };
   const send = async () => {
+    noteSent();
     try {
       const res = await fetchFn(`${config.endpoint}/compile_outcome_quality`, {
         method: "POST",
@@ -2927,16 +3067,19 @@ async function recordOutcome(input) {
         },
         body: JSON.stringify(payload)
       });
+      assertNotRedirected(res, "compile_outcome_quality");
       if (!res.ok) {
         const text = await res.text().catch(() => "<no body>");
-        const err = new Error(
+        throw new Error(
           describeBrainWriteFailure(res.status, "compile_outcome_quality", text)
         );
-        (config.onError ?? defaultOnError4)(err);
-        return { ok: false, reason: "persistence_failed" };
       }
+      noteAck();
+      maybeAutoFlush();
       return { ok: true };
     } catch (err) {
+      noteFailure(err);
+      pushDeadLetter("compile_outcome_quality", config.endpoint, payload, err);
       (config.onError ?? defaultOnError4)(err);
       return { ok: false, reason: "persistence_failed" };
     }
@@ -2945,7 +3088,7 @@ async function recordOutcome(input) {
     return send();
   }
   void send();
-  return { ok: true };
+  return { ok: "queued" };
 }
 function isBrainSync() {
   return activeConfig?.sync === true;
@@ -2987,6 +3130,7 @@ async function recordShadowProbe(input) {
   const fetchFn = brainWriteFetch(config);
   const row = buildShadowProbeRow(input);
   const send = async () => {
+    noteSent();
     try {
       const res = await fetchFn(`${config.endpoint}/probe_outcomes`, {
         method: "POST",
@@ -2997,11 +3141,71 @@ async function recordShadowProbe(input) {
         },
         body: JSON.stringify(row)
       });
+      assertNotRedirected(res, "probe_outcomes");
       if (!res.ok) {
         const text = await res.text().catch(() => "<no body>");
         throw new Error(describeBrainWriteFailure(res.status, "probe_outcomes", text));
       }
+      noteAck();
+      maybeAutoFlush();
     } catch (err) {
+      noteFailure(err);
+      pushDeadLetter("probe_outcomes", config.endpoint, row, err);
+      (config.onError ?? defaultOnError4)(err);
+    }
+  };
+  if (config.sync) {
+    await send();
+  } else {
+    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 ?? defaultOnError4)(err);
     }
   };
@@ -3026,6 +3230,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/streaming.ts
 var ANTHROPIC_URL = "https://api.anthropic.com/v1/messages";
 async function streamAnthropic(request, apiKey, opts) {
@@ -3737,6 +3980,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,
@@ -3789,6 +4034,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,
@@ -4128,6 +4390,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) {
@@ -4227,6 +4501,515 @@ 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 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") {
+        await new Promise((r) => setTimeout(r, 2e3));
+        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/oracle.ts
 var DEFAULT_DIMENSIONS = ["correctness", "completeness", "conciseness", "format"];
 var judgeCallTimes = [];
@@ -4664,6 +5447,7 @@ export {
   DIALECT_VERSION,
   FamilyResolutionError,
   INTENT_ARCHETYPES,
+  JUDGE_RUBRICS,
   LATENCY_TIER_MS,
   LIBRARY_VERSION,
   MEASURED_GROUNDING_MIN_N,
@@ -4675,13 +5459,18 @@ export {
   applyArchetypeConvention,
   applySectionRewrites,
   attachCacheControlToStreamTextInput,
+  brainHealth,
   bucketContext,
   bucketHistory,
   bucketToolCount,
+  buildGoldenIrRow,
   buildLLMJudge,
+  buildPairwiseJudgePrompt,
   buildShadowProbeRow,
   call,
+  captureGoldenIr,
   clearBrain,
+  combineOrderSwappedVerdicts,
   compile2 as compile,
   compileForAISDKv6,
   configureBrain,
@@ -4692,6 +5481,7 @@ export {
   deriveOwnership,
   execute,
   findBetterFit,
+  flushBrainDeadLetter,
   getActionableAdvisories,
   getAllStarterChains,
   getAllStarterChainsWithGrounding,
@@ -4726,18 +5516,27 @@ export {
   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
 };