@warmdrift/kgauto-compiler 2.0.0-alpha.3 → 2.0.0-alpha.30

package/dist/index.mjs

@@ -9,13 +9,47 @@ import {
   isArchetype,
   learningKey
 } from "./chunk-5TI6PNSK.mjs";
+import {
+  ABSOLUTE_FLOOR,
+  ARCHETYPE_FLOOR_DEFAULT,
+  PROVIDER_ENV_KEYS,
+  configureBrainQuery,
+  createBrainQueryCache,
+  ensureCrossProviderTail,
+  getAllStarterChains,
+  getAllStarterChainsWithGrounding,
+  getDefaultFallbackChain,
+  getDefaultFallbackChainWithGrounding,
+  getModelCompatibility,
+  getPerAxisMetrics,
+  getReachabilityDiagnostic,
+  getSequentialStarterChain,
+  getSequentialStarterChainWithGrounding,
+  getStarterChain,
+  getStarterChainWithGrounding,
+  isBrainQueryActiveFor,
+  isModelReachable,
+  isProviderReachable,
+  loadChainsFromBrain,
+  resolveProviderKey
+} from "./chunk-WXCFWUCN.mjs";
 import {
   ALIASES,
+  _setProfileBrainHook,
   allProfiles,
+  allProfilesRaw,
   getProfile,
   profilesByProvider,
   tryGetProfile
-} from "./chunk-MBEI5UOM.mjs";
+} from "./chunk-JQGRWJZO.mjs";
+import {
+  emitAdvisoryFired,
+  emitCompileDone,
+  emitCompileStart,
+  emitExecuteAttempt,
+  emitExecuteSuccess,
+  emitFallbackWalked
+} from "./chunk-NBO4R5PC.mjs";
 
 // src/tokenizer.ts
 var tokenizerImpl = defaultCharBasedCounter;
@@ -120,38 +154,96 @@ function passToolRelevance(ir, opts = {}) {
     ]
   };
 }
+function totalHistoryTokens(history) {
+  let total = 0;
+  for (const m of history) {
+    if (typeof m.content === "string") total += countTokens(m.content);
+  }
+  return total;
+}
 function passCompressHistory(ir, opts = {}) {
   const history = ir.history;
-  if (!history || history.length === 0) return { value: ir, mutations: [] };
+  if (!history || history.length === 0) {
+    return { value: ir, mutations: [], historyTokensTotal: 0 };
+  }
   const keepRecent = opts.keepRecent ?? 4;
   const summarizeOlderThan = opts.summarizeOlderThan ?? 8;
-  if (history.length <= summarizeOlderThan) return { value: ir, mutations: [] };
-  const cutIndex = history.length - keepRecent;
-  const old = history.slice(0, cutIndex);
-  const recent = history.slice(cutIndex);
-  const userTurns = old.filter((m) => m.role === "user");
-  const firstUserLine = userTurns[0]?.content.split("\n")[0]?.slice(0, 200) ?? "";
-  const summary = {
-    role: "system",
-    content: `[Earlier conversation: ${old.length} turns omitted. First user message: "${firstUserLine}"]`
-  };
-  return {
-    value: { ...ir, history: [summary, ...recent] },
-    mutations: [
-      {
-        id: `compress-history-${old.length}`,
-        source: "static_pass",
-        passName: "compress_history",
-        description: `Compressed ${old.length} old turns into 1 summary line (kept ${keepRecent} recent)`
+  const summarizeAboveTokens = opts.summarizeAboveTokens;
+  const historyTokensTotal = totalHistoryTokens(history);
+  const countThresholdHit = history.length > summarizeOlderThan;
+  const tokenThresholdHit = summarizeAboveTokens !== void 0 && historyTokensTotal > summarizeAboveTokens;
+  if (!countThresholdHit && !tokenThresholdHit) {
+    return { value: ir, mutations: [], historyTokensTotal };
+  }
+  if (history.length > keepRecent) {
+    const cutIndex = history.length - keepRecent;
+    const old = history.slice(0, cutIndex);
+    const recent = history.slice(cutIndex);
+    const userTurns = old.filter((m) => m.role === "user");
+    const firstUserLine = userTurns[0]?.content.split("\n")[0]?.slice(0, 200) ?? "";
+    const oldTokens = totalHistoryTokens(old);
+    const trigger = tokenThresholdHit && !countThresholdHit ? "tokens" : "count";
+    const summary = {
+      role: "system",
+      content: `[Earlier conversation: ${old.length} turns omitted (~${oldTokens} tokens). First user message: "${firstUserLine}"]`
+    };
+    return {
+      value: { ...ir, history: [summary, ...recent] },
+      mutations: [
+        {
+          id: `compress-history-${old.length}`,
+          source: "static_pass",
+          passName: "compress_history",
+          description: trigger === "tokens" ? `Compressed ${old.length} old turns (~${oldTokens} tokens) into 1 summary \u2014 token threshold ${summarizeAboveTokens} exceeded (kept ${keepRecent} recent)` : `Compressed ${old.length} old turns into 1 summary (kept ${keepRecent} recent)`
+        }
+      ],
+      historyTokensTotal
+    };
+  }
+  if (tokenThresholdHit) {
+    let fattestIdx = -1;
+    let fattestTokens = 0;
+    for (let i = 0; i < history.length; i++) {
+      const m = history[i];
+      if (!m || typeof m.content !== "string") continue;
+      const t = countTokens(m.content);
+      if (t > fattestTokens) {
+        fattestTokens = t;
+        fattestIdx = i;
       }
-    ]
-  };
+    }
+    const FAT_DOMINANCE_FLOOR = 0.3;
+    const fattest = fattestIdx >= 0 ? history[fattestIdx] : void 0;
+    if (fattest && historyTokensTotal > 0 && fattestTokens / historyTokensTotal >= FAT_DOMINANCE_FLOOR) {
+      const firstLine = fattest.content.split("\n")[0]?.slice(0, 200) ?? "";
+      const newContent = `[Earlier ${fattest.role} message content omitted: ~${fattestTokens} tokens. Preview: "${firstLine}"]`;
+      const newHistory = history.slice();
+      newHistory[fattestIdx] = { ...fattest, content: newContent };
+      return {
+        value: { ...ir, history: newHistory },
+        mutations: [
+          {
+            id: `compress-fat-message-${fattestIdx}`,
+            source: "static_pass",
+            passName: "compress_history",
+            description: `Replaced fat ${fattest.role} message #${fattestIdx} content (~${fattestTokens} of ${historyTokensTotal} tokens, ${Math.round(fattestTokens / historyTokensTotal * 100)}% of history) with summary stub \u2014 token threshold ${summarizeAboveTokens} exceeded (history.length ${history.length} <= keepRecent ${keepRecent}, slice not possible)`
+          }
+        ],
+        historyTokensTotal
+      };
+    }
+  }
+  return { value: ir, mutations: [], historyTokensTotal };
 }
 function passApplyCliffs(ir, profile, estimatedInputTokens) {
   const mutations = [];
   const hints = { qualityWarning: [] };
   let nextIR = ir;
+  const sequentialMode = nextIR.constraints?.toolOrchestration === "sequential";
   for (const cliff of profile.cliffs) {
+    if (sequentialMode && cliff.reason.includes("L-040")) {
+      continue;
+    }
     let triggered = false;
     switch (cliff.metric) {
       case "input_tokens":
@@ -374,10 +466,16 @@ function lower(ir, profile, hints = {}) {
 }
 function lowerAnthropic(ir, profile, hints) {
   const systemBlocks = buildAnthropicSystemBlocks(ir.sections, profile);
-  const messages = buildAnthropicMessages(ir.history ?? [], ir.currentTurn);
+  const history = (ir.history ?? []).filter((m) => m.role !== "system");
+  const policy = ir.historyCachePolicy;
+  const markIndex = resolveHistoryMarkIndex(history.length, policy);
+  const messages = buildAnthropicMessages(history, ir.currentTurn, markIndex);
   const tools = ir.tools ? toAnthropicTools(ir.tools) : void 0;
   const cacheableTokens = computeCacheableTokens(systemBlocks);
-  const cacheSavings = cacheableTokens / 1e6 * profile.costInputPer1m * (1 - (profile.lowering.cache.discount ?? 0.1));
+  const historyCacheableTokens = markIndex >= 0 ? sumHistoryTokens(history, markIndex) : 0;
+  const totalCacheableTokens = cacheableTokens + historyCacheableTokens;
+  const cacheSavings = totalCacheableTokens / 1e6 * profile.costInputPer1m * (1 - (profile.lowering.cache.discount ?? 0.1));
+  const toolChoice = hints.wireOverrides?.parallelToolCalls === false && tools && tools.length > 0 ? { type: "auto", disable_parallel_tool_use: true } : void 0;
   return {
     request: {
       provider: "anthropic",
@@ -385,10 +483,16 @@ function lowerAnthropic(ir, profile, hints) {
       system: systemBlocks,
       messages,
       tools,
-      max_tokens: hints.forceTerseOutput ? 200 : Math.min(profile.maxOutputTokens, 4096)
+      // alpha.8: trust profile.maxOutputTokens. The historical Math.min(_, 4096)
+      // floor surprised every consumer once (PB-Cairn contract-gaps brief, Gap 3).
+      // Profile is the single source of truth; consumers wanting a tighter
+      // budget can pass providerOverrides.anthropic.max_tokens explicitly.
+      max_tokens: hints.forceTerseOutput ? 200 : profile.maxOutputTokens,
+      tool_choice: toolChoice
     },
     diagnostics: {
       cacheableTokens,
+      historyCacheableTokens,
       estimatedCacheSavingsUsd: cacheSavings
     }
   };
@@ -421,17 +525,64 @@ function buildAnthropicSystemBlocks(sections, profile) {
   }
   return blocks;
 }
-function buildAnthropicMessages(history, currentTurn) {
+function buildAnthropicMessages(history, currentTurn, markIndex) {
   const out = [];
-  for (const m of history) {
+  for (let i = 0; i < history.length; i++) {
+    const m = history[i];
     if (m.role === "system") continue;
-    out.push({ role: m.role, content: m.parts ?? m.content });
+    const shouldMark = i === markIndex;
+    out.push({
+      role: m.role,
+      content: shouldMark ? attachAnthropicCacheControl(m) : m.parts ?? m.content
+    });
   }
   if (currentTurn && currentTurn.role !== "system") {
     out.push({ role: currentTurn.role, content: currentTurn.parts ?? currentTurn.content });
   }
   return out;
 }
+function attachAnthropicCacheControl(m) {
+  if (Array.isArray(m.parts) && m.parts.length > 0) {
+    const blocks = m.parts;
+    const last = blocks[blocks.length - 1];
+    const withMarker = {
+      ...last,
+      cache_control: { type: "ephemeral" }
+    };
+    return [...blocks.slice(0, -1), withMarker];
+  }
+  return [
+    {
+      type: "text",
+      text: m.content,
+      cache_control: { type: "ephemeral" }
+    }
+  ];
+}
+function resolveHistoryMarkIndex(historyLen, policy) {
+  if (!policy || policy.strategy === "none") return -1;
+  if (historyLen === 0) return -1;
+  if (policy.strategy === "all-but-latest") {
+    return historyLen - 1;
+  }
+  const idx = historyLen - 1 - policy.suffix;
+  return idx >= 0 ? idx : -1;
+}
+function sumHistoryTokens(history, throughIndex) {
+  let total = 0;
+  for (let i = 0; i <= throughIndex && i < history.length; i++) {
+    const m = history[i];
+    if (m.role === "system") continue;
+    if (Array.isArray(m.parts)) {
+      for (const p of m.parts) {
+        if (typeof p.text === "string") total += countTokens(p.text);
+      }
+    } else if (typeof m.content === "string") {
+      total += countTokens(m.content);
+    }
+  }
+  return total;
+}
 function toAnthropicTools(tools) {
   return tools.map((t) => ({
     name: t.name,
@@ -466,6 +617,9 @@ function lowerGoogle(ir, profile, hints) {
   const minTokens = profile.lowering.cache.minTokens ?? 4096;
   const meetsMin = cacheableTokens >= minTokens;
   const cacheSavings = meetsMin ? cacheableTokens / 1e6 * profile.costInputPer1m * (1 - (profile.lowering.cache.discount ?? 0.25)) : 0;
+  const history = (ir.history ?? []).filter((m) => m.role !== "system");
+  const histMarkIndex = resolveHistoryMarkIndex(history.length, ir.historyCachePolicy);
+  const historyCacheableTokens = histMarkIndex >= 0 ? sumHistoryTokens(history, histMarkIndex) : 0;
   return {
     request: {
       provider: "google",
@@ -477,6 +631,7 @@ function lowerGoogle(ir, profile, hints) {
     },
     diagnostics: {
       cacheableTokens: meetsMin ? cacheableTokens : 0,
+      historyCacheableTokens,
       estimatedCacheSavingsUsd: cacheSavings
     }
   };
@@ -524,6 +679,10 @@ function lowerOpenAI(ir, profile, hints) {
       content: ir.currentTurn.parts ?? ir.currentTurn.content
     });
   }
+  const history = (ir.history ?? []).filter((m) => m.role !== "system");
+  const histMarkIndex = resolveHistoryMarkIndex(history.length, ir.historyCachePolicy);
+  const historyCacheableTokens = histMarkIndex >= 0 ? sumHistoryTokens(history, histMarkIndex) : 0;
+  const openaiParallelToolCalls = hints.wireOverrides?.parallelToolCalls === false && ir.tools && ir.tools.length > 0 ? false : void 0;
   return {
     request: {
       provider: "openai",
@@ -531,9 +690,14 @@ function lowerOpenAI(ir, profile, hints) {
       messages,
       tools: ir.tools && ir.tools.length > 0 ? toOpenAITools(ir.tools) : void 0,
       response_format: ir.constraints?.structuredOutput ? { type: "json_object" } : void 0,
-      reasoning_effort: hints.forceTerseOutput ? "low" : void 0
+      reasoning_effort: hints.forceTerseOutput ? "low" : void 0,
+      parallel_tool_calls: openaiParallelToolCalls
     },
-    diagnostics: { cacheableTokens: 0, estimatedCacheSavingsUsd: 0 }
+    diagnostics: {
+      cacheableTokens: 0,
+      historyCacheableTokens,
+      estimatedCacheSavingsUsd: 0
+    }
   };
 }
 function toOpenAITools(tools) {
@@ -560,6 +724,9 @@ function lowerDeepSeek(ir, profile) {
       content: ir.currentTurn.parts ?? ir.currentTurn.content
     });
   }
+  const history = (ir.history ?? []).filter((m) => m.role !== "system");
+  const histMarkIndex = resolveHistoryMarkIndex(history.length, ir.historyCachePolicy);
+  const historyCacheableTokens = histMarkIndex >= 0 ? sumHistoryTokens(history, histMarkIndex) : 0;
   return {
     request: {
       provider: "deepseek",
@@ -574,7 +741,11 @@ function lowerDeepSeek(ir, profile) {
         }
       })) : void 0
     },
-    diagnostics: { cacheableTokens: 0, estimatedCacheSavingsUsd: 0 }
+    diagnostics: {
+      cacheableTokens: 0,
+      historyCacheableTokens,
+      estimatedCacheSavingsUsd: 0
+    }
   };
 }
 function sortSections(sections) {
@@ -597,6 +768,332 @@ function setNestedField(obj, path, value) {
   cursor[parts[parts.length - 1]] = value;
 }
 
+// src/archetype-perf-brain.ts
+function isPerfRow(x) {
+  if (!x || typeof x !== "object") return false;
+  const r = x;
+  return typeof r.model_id === "string" && typeof r.archetype === "string" && typeof r.perf_score === "number";
+}
+function mapRowsToPerfMap(rows) {
+  const out = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    if (!isPerfRow(row)) continue;
+    const existing = out.get(row.model_id) ?? {};
+    existing[row.archetype] = row.perf_score;
+    out.set(row.model_id, existing);
+  }
+  return out;
+}
+function mapRowsToNMap(rows) {
+  const out = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    if (!isPerfRow(row)) continue;
+    if (typeof row.n !== "number") continue;
+    const existing = out.get(row.model_id) ?? {};
+    existing[row.archetype] = row.n;
+    out.set(row.model_id, existing);
+  }
+  return out;
+}
+function bundledArchetypePerf() {
+  const out = /* @__PURE__ */ new Map();
+  for (const profile of allProfiles()) {
+    if (profile.archetypePerf) out.set(profile.id, profile.archetypePerf);
+  }
+  return out;
+}
+function bundledArchetypePerfN() {
+  return /* @__PURE__ */ new Map();
+}
+var loadArchetypePerfFromBrain = createBrainQueryCache({
+  table: "kgauto_archetype_perf",
+  mapRows: mapRowsToPerfMap,
+  bundledFallback: bundledArchetypePerf
+});
+var loadArchetypePerfNFromBrain = createBrainQueryCache(
+  {
+    table: "kgauto_archetype_perf",
+    mapRows: mapRowsToNMap,
+    bundledFallback: bundledArchetypePerfN
+  }
+);
+var MEASURED_GROUNDING_MIN_N = 10;
+function getArchetypePerfScore(modelId, archetype) {
+  const score = loadArchetypePerfFromBrain().get(modelId)?.[archetype] ?? 5;
+  const n = loadArchetypePerfNFromBrain().get(modelId)?.[archetype] ?? 0;
+  const grounding = n >= MEASURED_GROUNDING_MIN_N ? "measured" : "judgment";
+  return { score, n, grounding };
+}
+
+// src/advisor.ts
+var QUALITY_FLOOR_FOR_RECOMMENDATION = 6;
+var TIER_DOWN_COST_RATIO = 0.5;
+var COST_MISMATCHED_CHOSEN_SCORE_CEILING = 7;
+function runAdvisor(ir, result, profile, policy, phase2) {
+  const out = [];
+  out.push(...detectCachingOff(ir, profile));
+  out.push(...detectSingleChunkSystem(ir, profile));
+  out.push(...detectToolBloat(ir, result));
+  out.push(...detectHistoryUncached(ir, profile));
+  out.push(...detectSingleModelArray(ir, policy));
+  if (policy?.posture !== "locked") {
+    out.push(...detectCostMismatchedArchetype(ir, profile, phase2));
+    out.push(...detectModelStaleEvidence(ir, profile));
+    out.push(...detectTierDown(ir, profile, phase2));
+  }
+  if (!translatorClearedToolCallCliff(phase2)) {
+    out.push(...detectArchetypePerfFloorBreach(ir, profile));
+  }
+  return out;
+}
+function translatorClearedToolCallCliff(phase2) {
+  const rewrites = phase2?.sectionRewritesApplied;
+  if (!rewrites || rewrites.length === 0) return false;
+  for (const rw of rewrites) {
+    if (rw.kind === "tool_call_contract") return true;
+  }
+  return false;
+}
+function detectCachingOff(ir, profile) {
+  if (profile.provider !== "anthropic") return [];
+  const totalChars = ir.sections.reduce((s, sec) => s + sec.text.length, 0);
+  if (totalChars < 2e3) return [];
+  const anyCacheable = ir.sections.some((s) => s.cacheable === true);
+  if (anyCacheable) return [];
+  return [
+    {
+      level: "warn",
+      code: "caching-off-on-claude",
+      message: `System prompt is ${totalChars} chars on Anthropic but no PromptSection has cacheable=true. Anthropic prompt caching cuts cached-prefix input cost by ~90% on subsequent calls; without it, every turn re-pays full price for the static system context.`,
+      suggestion: "Mark stable system sections (role, persona, tool policy) with `cacheable: true`. The lowering pass concatenates cacheable sections into a single cache-controlled block before the dynamic ones.",
+      docsUrl: "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#best-practice-advisories"
+    }
+  ];
+}
+function detectSingleChunkSystem(ir, profile) {
+  if (profile.provider !== "anthropic") return [];
+  if (ir.sections.length !== 1) return [];
+  const only = ir.sections[0];
+  if (!only || only.text.length <= 1e3) return [];
+  return [
+    {
+      level: "info",
+      code: "single-chunk-system",
+      message: `System prompt is a single ${only.text.length}-char chunk. Splitting into NamedChunks (static role/persona vs dynamic context) gives the lowering pass a finer cache-marker boundary \u2014 only the static portion needs to be byte-stable for the cache to hit.`,
+      suggestion: "Refactor the system builder to return an array of `PromptSection` shaped { id, text, cacheable?: boolean }. Static chunks (role, persona, tool policy) get `cacheable: true`; dynamic ones (current context, today's date) don't.",
+      docsUrl: "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#best-practice-advisories"
+    }
+  ];
+}
+function detectToolBloat(ir, result) {
+  const SHORT_OUTPUT = /* @__PURE__ */ new Set([
+    "classify",
+    "extract",
+    "summarize",
+    "transform",
+    "critique"
+  ]);
+  if (!ir.tools || ir.tools.length === 0) return [];
+  const toolsKept = result.diagnostics.toolsKept;
+  if (toolsKept <= 10) return [];
+  if (!SHORT_OUTPUT.has(ir.intent.archetype)) return [];
+  return [
+    {
+      level: "warn",
+      code: "tool-bloat",
+      message: `${toolsKept} tools kept after the relevance pass for archetype="${ir.intent.archetype}" (consumer declared ${ir.tools.length}). This archetype is short-output and rarely needs more than 3 tools; each tool definition eats ~350 tokens of context budget.`,
+      suggestion: "Tighten `relevanceByIntent: { [archetype]: 0..1 }` per ToolDefinition. Tools below `toolRelevanceThreshold` (default 0.2) get dropped. Without `relevanceByIntent`, every tool defaults to neutral (0.5) and stays.",
+      docsUrl: "https://github.com/stue/kgauto/blob/main/v2/README.md#tools"
+    }
+  ];
+}
+function detectHistoryUncached(ir, profile) {
+  if (profile.provider !== "anthropic") return [];
+  if (!ir.history || ir.history.length < 2) return [];
+  if (ir.historyCachePolicy && ir.historyCachePolicy.strategy !== "none") {
+    return [];
+  }
+  return [
+    {
+      level: "warn",
+      code: "history-uncached-on-claude",
+      message: `${ir.history.length} history messages on Anthropic with no historyCachePolicy. Every turn re-pays for the full conversation context; with caching, subsequent turns hit the cache at ~10% the input cost.`,
+      suggestion: "Set `historyCachePolicy: { strategy: 'all-but-latest' }` on this IR. The lowering pass marks the message immediately preceding currentTurn with cache_control; subsequent turns whose history prefix matches byte-for-byte hit the cache.",
+      docsUrl: "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#best-practice-advisories"
+    }
+  ];
+}
+function detectSingleModelArray(ir, policy) {
+  if (ir.models.length !== 1) return [];
+  if (policy?.posture === "locked") return [];
+  const only = ir.models[0];
+  return [
+    {
+      level: "warn",
+      code: "single-model-array",
+      message: `\`ir.models\` has length 1 (only "${only}") and posture is not 'locked'. A single-model chain has no safety net \u2014 the first 429 / 5xx / cliff hits the user as a failure. Master plan \xA71.2 closes the reliability gap with a 2-step minimum.`,
+      suggestion: "Use `getDefaultFallbackChain({ archetype: ir.intent.archetype, primary: '" + only + "', posture: 'preferred' })` for a user-anchored chain, or `getDefaultFallbackChain({ archetype, posture: 'open' })` for library-picked. If single-model is intentional (compliance/brand promise), set `policy.posture = 'locked'` to silence this rule.",
+      docsUrl: "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#single-model-array"
+    }
+  ];
+}
+function detectCostMismatchedArchetype(ir, profile, phase2) {
+  if (!phase2 || phase2.fallbackChain.length === 0) return [];
+  if (!phase2.profileResolver) return [];
+  const archetype = ir.intent.archetype;
+  const chosenScore = getArchetypePerfScore(profile.id, archetype);
+  const chosenHasRoomToGrow = chosenScore.grounding === "judgment" || chosenScore.score < COST_MISMATCHED_CHOSEN_SCORE_CEILING;
+  if (!chosenHasRoomToGrow) return [];
+  let bestAlt = null;
+  for (const altId of phase2.fallbackChain) {
+    const altProfile = phase2.profileResolver(altId);
+    if (!altProfile) continue;
+    if (altProfile.id === profile.id) continue;
+    const altScore = getArchetypePerfScore(altProfile.id, archetype);
+    if (altScore.score < QUALITY_FLOOR_FOR_RECOMMENDATION) continue;
+    if (altScore.score < chosenScore.score) continue;
+    if (altProfile.costInputPer1m >= profile.costInputPer1m) continue;
+    if (!bestAlt || altScore.score > bestAlt.score.score || altScore.score === bestAlt.score.score && altProfile.costInputPer1m < bestAlt.profile.costInputPer1m) {
+      bestAlt = { id: altId, profile: altProfile, score: altScore };
+    }
+  }
+  if (!bestAlt) return [];
+  const tierDownWouldFire = bestAlt.score.grounding === "measured" && bestAlt.profile.costInputPer1m <= profile.costInputPer1m * TIER_DOWN_COST_RATIO;
+  if (tierDownWouldFire) return [];
+  const chosenGrounding = chosenScore.grounding === "judgment" ? `archetypePerf.${archetype}=judgment` : `archetypePerf.${archetype}=${chosenScore.score}`;
+  const altGrounding = bestAlt.score.grounding === "measured" ? `archetypePerf.${archetype}=${bestAlt.score.score}, measured, n=${bestAlt.score.n}` : `archetypePerf.${archetype}=${bestAlt.score.score}, judgment`;
+  return [
+    {
+      level: "warn",
+      code: "cost-mismatched-archetype",
+      message: `Cost-mismatched-archetype: target=${profile.id} (${chosenGrounding}) selected for ${archetype}. Alternative ${bestAlt.id} (${altGrounding}) is cheaper ($${bestAlt.profile.costInputPer1m}/$${bestAlt.profile.costOutputPer1m} vs $${profile.costInputPer1m}/$${profile.costOutputPer1m} per 1M) at equal-or-better quality.`,
+      suggestion: `Consider declaring \`${bestAlt.id}\` as the primary model for this archetype, or relax to posture='open' to let kgauto select among the chain. If the chosen model is required for compliance/brand reasons, set \`policy.posture = 'locked'\` to silence this rule.`,
+      recommendationType: profile.provider === bestAlt.profile.provider ? "tier-down" : "model-swap",
+      docsUrl: "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#best-practice-advisories"
+    }
+  ];
+}
+function detectModelStaleEvidence(ir, profile) {
+  if (!isBrainQueryActiveFor("kgauto_archetype_perf")) return [];
+  const archetype = ir.intent.archetype;
+  const chosen = getArchetypePerfScore(profile.id, archetype);
+  if (chosen.grounding !== "judgment") return [];
+  return [
+    {
+      level: "info",
+      code: "model-stale-evidence",
+      message: `Model-stale-evidence: target=${profile.id} archetype=${archetype} is judgment-grounded (n=${chosen.n}) despite brain-query mode being active. Measurement substrate is wired but the brain hasn't accumulated >=10 outcomes for this (model, archetype) tuple yet \u2014 routing decisions remain pre-measured for this slot.`,
+      suggestion: "Verify that `record()` is being called on every call() outcome with the appropriate `actualModel` and `mutationsApplied` fields. Once the brain accumulates n>=10 rows on this tuple, the score promotes from judgment to measured automatically (5-min SWR cache). No code change required from your side \u2014 this is the substrate signaling the gap.",
+      recommendationType: "prompt-fix",
+      docsUrl: "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#best-practice-advisories"
+    }
+  ];
+}
+function detectTierDown(ir, profile, phase2) {
+  if (!phase2 || phase2.fallbackChain.length === 0) return [];
+  if (!phase2.profileResolver) return [];
+  const archetype = ir.intent.archetype;
+  const chosenScore = getArchetypePerfScore(profile.id, archetype);
+  const chosenCost = profile.costInputPer1m;
+  let bestAlt = null;
+  for (const altId of phase2.fallbackChain) {
+    const altProfile = phase2.profileResolver(altId);
+    if (!altProfile) continue;
+    if (altProfile.id === profile.id) continue;
+    const altScore = getArchetypePerfScore(altProfile.id, archetype);
+    if (altScore.grounding !== "measured") continue;
+    if (altScore.score < QUALITY_FLOOR_FOR_RECOMMENDATION) continue;
+    if (altScore.score < chosenScore.score) continue;
+    if (altProfile.costInputPer1m > chosenCost * TIER_DOWN_COST_RATIO) continue;
+    if (!bestAlt || altProfile.costInputPer1m < bestAlt.profile.costInputPer1m || altProfile.costInputPer1m === bestAlt.profile.costInputPer1m && altScore.score > bestAlt.score.score) {
+      bestAlt = { id: altId, profile: altProfile, score: altScore };
+    }
+  }
+  if (!bestAlt) return [];
+  const chosenDesc = chosenScore.grounding === "measured" ? `archetypePerf.${archetype}=${chosenScore.score} (measured, n=${chosenScore.n})` : `archetypePerf.${archetype}=${chosenScore.score} (${chosenScore.grounding})`;
+  return [
+    {
+      level: "warn",
+      code: "tier-down",
+      message: `Tier-down: target=${profile.id} (${chosenDesc}) selected for ${archetype}. Brain shows ${bestAlt.id} delivers equal-or-better quality (archetypePerf.${archetype}=${bestAlt.score.score}, measured, n=${bestAlt.score.n}) at $${bestAlt.profile.costInputPer1m}/$${bestAlt.profile.costOutputPer1m} per 1M vs $${profile.costInputPer1m}/$${profile.costOutputPer1m} \u2014 a measured tier-down opportunity.`,
+      suggestion: `Move \`${bestAlt.id}\` to primary for this archetype. The brain has n=${bestAlt.score.n} measured outcomes backing the recommendation; this is data, not opinion. If posture='locked' is required (compliance/brand promise), set it explicitly to silence this rule.`,
+      recommendationType: "tier-down",
+      docsUrl: "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#best-practice-advisories"
+    }
+  ];
+}
+function detectArchetypePerfFloorBreach(ir, profile) {
+  const compat = getModelCompatibility(profile.id, {
+    archetype: ir.intent.archetype,
+    toolOrchestration: ir.constraints?.toolOrchestration
+  });
+  if (compat.status === "compatible") return [];
+  if (compat.status === "requires-adapter") {
+    return [
+      {
+        level: "warn",
+        code: "archetype-perf-floor-breach",
+        message: `${profile.id} sits below the archetype floor for ${ir.intent.archetype} (score ${compat.archetypePerf}/10, floor ${6}). A known adapter would lift it: ${compat.adapter.parameter}=${compat.adapter.value}. ${compat.adapter.consequence}`,
+        suggestion: `Pass \`ir.constraints.${compat.adapter.parameter} = '${compat.adapter.value}'\` for this call, OR pick a model whose archetypePerf for ${ir.intent.archetype} already clears the floor (call \`getModelCompatibility(modelId, { archetype: '${ir.intent.archetype}' })\` to check). Estimated post-adapter score: ${compat.archetypePerfWithAdapter}/10.`,
+        recommendationType: "prompt-fix",
+        suggestedAdaptation: compat.adapter,
+        docsUrl: "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#best-practice-advisories"
+      }
+    ];
+  }
+  return [
+    {
+      level: "critical",
+      code: "archetype-perf-floor-breach",
+      message: `${profile.id} sits below the archetype floor for ${ir.intent.archetype} (score ${compat.archetypePerf}/10, floor ${6}) and no known adapter would lift it. ${compat.reason}`,
+      suggestion: `Swap to a model whose archetypePerf for ${ir.intent.archetype} clears the floor. Use \`getModelCompatibility(candidateId, { archetype: '${ir.intent.archetype}' })\` to vet candidates, or \`getDefaultFallbackChain({ archetype: '${ir.intent.archetype}', posture: 'open' })\` for a library-picked chain that respects the floor by construction.`,
+      recommendationType: "model-swap",
+      docsUrl: "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#best-practice-advisories"
+    }
+  ];
+}
+
+// src/translator.ts
+var TRANSLATOR_FLOOR = ARCHETYPE_FLOOR_DEFAULT;
+var RULE_SEQUENTIAL_TOOL_CLIFF = "sequential-tool-cliff-below-floor";
+var SEQUENTIAL_TOOL_PREAMBLE = "IMPORTANT: Use one tool call per response. Wait for the tool result before deciding the next tool. Do NOT batch tool calls in parallel.";
+function applySectionRewrites(args) {
+  const { ir, profile, archetype } = args;
+  if (!Array.isArray(ir.sections) || ir.sections.length === 0) {
+    return { rewrittenIR: ir, rewrites: [] };
+  }
+  if (!profile.archetypePerf) {
+    return { rewrittenIR: ir, rewrites: [] };
+  }
+  const archetypeScore = profile.archetypePerf[archetype];
+  const cliffFires = typeof archetypeScore === "number" && archetypeScore < TRANSLATOR_FLOOR;
+  if (!cliffFires) {
+    return { rewrittenIR: ir, rewrites: [] };
+  }
+  const rewrites = [];
+  const newSections = ir.sections.map((section) => {
+    if (section.kind !== "tool_call_contract") return section;
+    const originalText = section.text;
+    const transformedText = `${SEQUENTIAL_TOOL_PREAMBLE}
+
+${originalText}`;
+    rewrites.push({
+      sectionId: section.id,
+      kind: "tool_call_contract",
+      rule: RULE_SEQUENTIAL_TOOL_CLIFF,
+      originalText,
+      transformedText,
+      wireOverrides: { parallelToolCalls: false }
+    });
+    return { ...section, text: transformedText };
+  });
+  if (rewrites.length === 0) {
+    return { rewrittenIR: ir, rewrites: [] };
+  }
+  const rewrittenIR = { ...ir, sections: newSections };
+  return { rewrittenIR, rewrites };
+}
+
 // src/compile.ts
 var counter = 0;
 function makeHandle() {
@@ -612,7 +1109,8 @@ function compile(ir, opts = {}) {
     threshold: opts.toolRelevanceThreshold
   });
   const compressed = passCompressHistory(toolFiltered.value, {
-    summarizeOlderThan: opts.compressHistoryAfter
+    summarizeOlderThan: opts.compressHistoryAfter,
+    summarizeAboveTokens: opts.compressHistoryAboveTokens
   });
   let workingIR = compressed.value;
   const accumulatedMutations = [
@@ -639,14 +1137,89 @@ function compile(ir, opts = {}) {
   const cliffs = passApplyCliffs(workingIR, profile, inputTokens);
   workingIR = cliffs.value.ir;
   accumulatedMutations.push(...cliffs.mutations);
+  const translated = applySectionRewrites({
+    ir: workingIR,
+    profile,
+    archetype: ir.intent.archetype
+  });
+  workingIR = translated.rewrittenIR;
+  const sectionRewritesApplied = translated.rewrites;
+  let wireOverrides;
+  for (const rw of sectionRewritesApplied) {
+    if (!rw.wireOverrides) continue;
+    if (!wireOverrides) wireOverrides = {};
+    if (rw.wireOverrides.parallelToolCalls !== void 0) {
+      wireOverrides.parallelToolCalls = rw.wireOverrides.parallelToolCalls;
+    }
+  }
+  for (const rw of sectionRewritesApplied) {
+    accumulatedMutations.push({
+      id: `translator:${rw.rule}:${rw.sectionId}`,
+      source: "translator",
+      passName: "translator",
+      description: `Rewrote section "${rw.sectionId}" (kind=${rw.kind}) via rule "${rw.rule}".`
+    });
+  }
   const lowered = lower(workingIR, profile, {
     forceThinkingZero: cliffs.value.loweringHints.forceThinkingZero,
-    forceTerseOutput: cliffs.value.loweringHints.forceTerseOutput
+    forceTerseOutput: cliffs.value.loweringHints.forceTerseOutput,
+    wireOverrides
   });
   validateFinalFit(workingIR, profile, inputTokens);
   const handle = makeHandle();
   const finalShape = computeShape(workingIR, inputTokens);
   const _learningKey = learningKey(ir.intent.archetype, profile.id, finalShape);
+  const diagnostics = {
+    sectionsKept: workingIR.sections.length,
+    sectionsDropped: ir.sections.length - workingIR.sections.length,
+    toolsKept: workingIR.tools?.length ?? 0,
+    toolsDropped: (ir.tools?.length ?? 0) - (workingIR.tools?.length ?? 0),
+    historyKept: workingIR.history?.length ?? 0,
+    historyDropped: (ir.history?.length ?? 0) - (workingIR.history?.length ?? 0),
+    cacheableTokens: lowered.diagnostics.cacheableTokens,
+    estimatedCacheSavingsUsd: lowered.diagnostics.estimatedCacheSavingsUsd,
+    historyCacheableTokens: lowered.diagnostics.historyCacheableTokens,
+    historyTokensTotal: compressed.historyTokensTotal,
+    // alpha.20 E3: mirror the consumer's declared mode for Glass-Box +
+    // brain observability. Undefined when not declared (pre-alpha.20).
+    toolOrchestration: ir.constraints?.toolOrchestration
+  };
+  if (ir.intent.archetype === "hunt" && ir.constraints?.toolOrchestration === "sequential") {
+    accumulatedMutations.push({
+      id: "sequential-mode-chain-selected",
+      source: "tool_orchestration",
+      passName: "compile",
+      description: "ir.constraints.toolOrchestration='sequential' selected the DeepSeek-tier-0 hunt chain overlay (L-040 parallel-tool cliff doesn't apply at single-step granularity)."
+    });
+  }
+  const phase2ProfileResolver = opts.profileResolver ? (id) => {
+    try {
+      return opts.profileResolver(id);
+    } catch {
+      return void 0;
+    }
+  } : tryGetProfile;
+  const advisories = runAdvisor(
+    ir,
+    {
+      target: profile.id,
+      provider: profile.provider,
+      tokensIn: inputTokens,
+      diagnostics
+    },
+    profile,
+    opts.policy,
+    {
+      fallbackChain,
+      profileResolver: phase2ProfileResolver,
+      // alpha.29 — feed translator rewrites to the advisor so the
+      // `archetype-perf-floor-breach` rule can suppress when the translator
+      // already cleared the cliff for the same archetype. Without this,
+      // both the rewrite AND the advisory fire — noisy, and the advisory
+      // would mislead consumers into thinking the cliff is unaddressed.
+      sectionRewritesApplied
+    }
+  );
   return {
     handle,
     target: profile.id,
@@ -656,16 +1229,10 @@ function compile(ir, opts = {}) {
     estimatedCostUsd: target.estimatedCostUsd,
     mutationsApplied: accumulatedMutations,
     fallbackChain,
-    diagnostics: {
-      sectionsKept: workingIR.sections.length,
-      sectionsDropped: ir.sections.length - workingIR.sections.length,
-      toolsKept: workingIR.tools?.length ?? 0,
-      toolsDropped: (ir.tools?.length ?? 0) - (workingIR.tools?.length ?? 0),
-      historyKept: workingIR.history?.length ?? 0,
-      historyDropped: (ir.history?.length ?? 0) - (workingIR.history?.length ?? 0),
-      cacheableTokens: lowered.diagnostics.cacheableTokens,
-      estimatedCacheSavingsUsd: lowered.diagnostics.estimatedCacheSavingsUsd
-    }
+    advisories,
+    diagnostics,
+    sectionRewritesApplied,
+    wireOverrides
   };
 }
 function validateIR(ir) {
@@ -706,14 +1273,92 @@ function validateFinalFit(ir, profile, tokens) {
   }
 }
 
+// src/pricing-brain.ts
+function isPricingRow(x) {
+  if (!x || typeof x !== "object") return false;
+  const r = x;
+  return typeof r.model_id === "string" && typeof r.cost_input_per_1m === "number" && typeof r.cost_output_per_1m === "number" && typeof r.valid_from === "string";
+}
+function mapRowsToPricing(rows) {
+  const out = [];
+  for (const row of rows) {
+    if (!isPricingRow(row)) continue;
+    out.push({
+      modelId: row.model_id,
+      costInputPer1m: row.cost_input_per_1m,
+      costOutputPer1m: row.cost_output_per_1m,
+      cacheInputPer1m: row.cache_input_per_1m ?? void 0,
+      cacheCreationPer1m: row.cache_creation_per_1m ?? void 0,
+      validFrom: Date.parse(row.valid_from),
+      validUntil: row.valid_until == null ? void 0 : Date.parse(row.valid_until),
+      source: row.source ?? void 0
+    });
+  }
+  return out;
+}
+function bundledPricing() {
+  const out = [];
+  for (const profile of allProfiles()) {
+    out.push({
+      modelId: profile.id,
+      costInputPer1m: profile.costInputPer1m,
+      costOutputPer1m: profile.costOutputPer1m,
+      cacheInputPer1m: profile.lowering.cache.discount !== void 0 && profile.lowering.cache.discount > 0 ? profile.costInputPer1m * profile.lowering.cache.discount : void 0,
+      validFrom: 0,
+      validUntil: void 0,
+      source: "profile_seed"
+    });
+  }
+  return out;
+}
+var loadPricingFromBrain = createBrainQueryCache({
+  table: "kgauto_pricing",
+  mapRows: mapRowsToPricing,
+  bundledFallback: bundledPricing
+});
+function resolvePricingAt(modelId, at = /* @__PURE__ */ new Date()) {
+  const ts = at.getTime();
+  const all = loadPricingFromBrain();
+  let best;
+  for (const row of all) {
+    if (row.modelId !== modelId) continue;
+    if (row.validFrom > ts) continue;
+    if (row.validUntil !== void 0 && row.validUntil <= ts) continue;
+    if (!best || row.validFrom > best.validFrom) best = row;
+  }
+  return best;
+}
+
 // src/brain.ts
 var activeConfig;
 function configureBrain(config) {
   const endpoint = config.endpoint.replace(/\/outcomes\/?$/, "");
   activeConfig = { ...config, endpoint };
+  const bq = config.brainQuery ?? {};
+  const enabledTables = /* @__PURE__ */ new Set();
+  if (bq.chains !== false) enabledTables.add("kgauto_chains");
+  if (bq.perf !== false) enabledTables.add("kgauto_archetype_perf");
+  if (bq.pricing !== false) enabledTables.add("kgauto_pricing");
+  if (bq.models !== false) {
+    enabledTables.add("kgauto_models");
+    enabledTables.add("kgauto_aliases");
+  }
+  if (enabledTables.size === 0) {
+    configureBrainQuery(void 0);
+    return;
+  }
+  configureBrainQuery({
+    endpoint,
+    configEndpoint: bq.configEndpoint,
+    ttlMs: bq.cacheTtlMs ?? 3e5,
+    fetchImpl: config.fetchImpl ?? fetch,
+    enabledTables,
+    onError: config.onError
+  });
 }
 function clearBrain() {
   activeConfig = void 0;
+  configureBrainQuery(void 0);
 }
 var compileRegistry = /* @__PURE__ */ new Map();
 var REGISTRY_MAX_ENTRIES = 1e4;
@@ -740,6 +1385,9 @@ function registerCompile(appId, archetype, ir, result) {
     tokens
   );
   const shapeKey = `${shape.contextBucket}-${shape.toolCountBucket}-${shape.historyDepth}-${shape.outputMode}`;
+  const toolsCount = result.diagnostics.toolsKept;
+  const historyDepth = Array.isArray(ir.history) ? ir.history.length : 0;
+  const systemPromptChars = estimateSystemPromptChars(ir.sections);
   compileRegistry.set(result.handle, {
     appId,
     archetype,
@@ -749,9 +1397,35 @@ function registerCompile(appId, archetype, ir, result) {
     learningKey: learningKey(archetype, result.target, shape),
     estimatedTokensIn: tokens,
     mutationsApplied: result.mutationsApplied.map((m) => m.id),
-    startedAt: Date.now()
+    // alpha.30: cache the in-memory advisories so record() can auto-persist
+    // to `compile_outcome_advisories` without consumer-side threading.
+    advisoriesFromCompile: result.advisories ?? [],
+    startedAt: Date.now(),
+    historyCacheableTokens: result.diagnostics.historyCacheableTokens,
+    historyTokensTotal: result.diagnostics.historyTokensTotal,
+    // alpha.20 E3: capture consumer's declared mode for the brain payload.
+    toolOrchestration: result.diagnostics.toolOrchestration,
+    // alpha.28: shape fields for Glass-Box renderer.
+    toolsCount,
+    historyDepth,
+    systemPromptChars,
+    // alpha.29: translator activity — persisted on the brain row so
+    // cross-app aggregates can answer "Sonnet narration rule fired N times,
+    // outcome quality lifted to M."
+    sectionRewritesApplied: result.sectionRewritesApplied
   });
 }
+function estimateSystemPromptChars(sections) {
+  if (!Array.isArray(sections) || sections.length === 0) return void 0;
+  let total = 0;
+  for (const s of sections) {
+    if (s && typeof s === "object") {
+      const content = s.content;
+      if (typeof content === "string") total += content.length;
+    }
+  }
+  return total > 0 ? total : void 0;
+}
 async function record(input) {
   const reg = compileRegistry.get(input.handle);
   if (reg) compileRegistry.delete(input.handle);
@@ -762,11 +1436,22 @@ async function record(input) {
   const config = activeConfig;
   const fetchFn = config.fetchImpl ?? fetch;
   const send = async () => {
+    let outcomeId;
     try {
       const res = await fetchFn(`${config.endpoint}/outcomes`, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
+          // alpha.20: request the inserted row back so we can JOIN advisories
+          // to it via outcome_id. PostgREST returns the row when
+          // `Prefer: return=representation` is set; proxies that pass the
+          // header through (the recommended `const row = { ...body }` shape
+          // from OutcomePayload's forward-compat rule) will surface
+          // the row id. Proxies that don't (legacy / hand-rolled shapes)
+          // simply produce no parseable id → secondary advisory POST is
+          // skipped silently. Best-effort — primary outcome row is the
+          // load-bearing write.
+          Prefer: "return=representation",
           ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}
         },
         body: JSON.stringify(payload)
@@ -775,6 +1460,29 @@ async function record(input) {
         const text = await res.text().catch(() => "<no body>");
         throw new Error(`brain ${res.status}: ${text}`);
       }
+      outcomeId = await tryExtractOutcomeId(res);
+    } catch (err) {
+      (config.onError ?? defaultOnError)(err);
+      return;
+    }
+    const advisories = input.advisories ?? reg?.advisoriesFromCompile;
+    if (!advisories || advisories.length === 0) return;
+    if (outcomeId === void 0) return;
+    try {
+      const advisoryPayload = advisories.map((a) => buildAdvisoryRow(outcomeId, a));
+      const res = await fetchFn(`${config.endpoint}/compile_outcome_advisories`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Prefer: "return=minimal",
+          ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}
+        },
+        body: JSON.stringify(advisoryPayload)
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "<no body>");
+        throw new Error(`brain advisories ${res.status}: ${text}`);
+      }
     } catch (err) {
       (config.onError ?? defaultOnError)(err);
     }
@@ -792,6 +1500,11 @@ function buildPayload(input, reg) {
   const compileTarget = reg?.model;
   const actual = input.actualModel ?? compileTarget;
   const requested = input.actualModel && compileTarget && input.actualModel !== compileTarget ? compileTarget : void 0;
+  const mutationsApplied = input.mutationsApplied ?? reg?.mutationsApplied ?? [];
+  const costModel = actual;
+  const costUsdActual = costModel ? computeCostUsd(costModel, input.tokensIn, input.tokensOut) : void 0;
+  const fellOverFrom = input.fellOverFrom ?? requested;
+  const fallbackReason = fellOverFrom ? input.fallbackReason : void 0;
   return {
     handle: input.handle,
     app_id: reg?.appId,
@@ -801,7 +1514,7 @@ function buildPayload(input, reg) {
     provider: reg?.provider,
     shape_key: reg?.shapeKey,
     learning_key: reg?.learningKey,
-    mutations_applied: reg?.mutationsApplied ?? [],
+    mutations_applied: mutationsApplied,
     tokens_in: input.tokensIn,
     tokens_out: input.tokensOut,
     estimated_tokens_in: reg?.estimatedTokensIn,
@@ -815,9 +1528,118 @@ function buildPayload(input, reg) {
     oracle_rationale: input.oracleScore?.rationale,
     prompt_preview: input.promptPreview,
     response_preview: input.responsePreview,
-    dialect_version: "v1"
+    dialect_version: "v1",
+    cache_read_input_tokens: input.cacheReadInputTokens,
+    cache_creation_input_tokens: input.cacheCreationInputTokens,
+    cost_usd_actual: costUsdActual,
+    ttft_ms: input.ttftMs,
+    history_cacheable_tokens: reg?.historyCacheableTokens,
+    history_tokens_at_compile: reg?.historyTokensTotal,
+    // alpha.20 E3: mirror consumer's declared tool-orchestration mode so
+    // the brain can measure per-mode model perf separately (DeepSeek in
+    // sequential vs parallel mode is two different stories — L-040).
+    // Null when consumer hadn't adopted the constraint yet.
+    tool_orchestration: reg?.toolOrchestration ?? null,
+    // alpha.28 — Glass-Box renderer substrate (migration 018). All optional;
+    // omitted-undefined PostgREST inserts store NULL → renderer renders "—".
+    finish_reason: input.finishReason,
+    total_ms: input.totalMs ?? input.latencyMs,
+    tools_count: input.toolsCount ?? reg?.toolsCount,
+    history_depth: input.historyDepth ?? reg?.historyDepth,
+    system_prompt_chars: input.systemPromptChars ?? reg?.systemPromptChars,
+    fell_over_from: fellOverFrom,
+    fallback_reason: fallbackReason,
+    // alpha.29 — translator activity (migration 019). Send NULL when no
+    // rewrites fired so the brain's "did the translator do anything?"
+    // queries can use `IS NOT NULL` cleanly.
+    section_rewrites_applied: reg?.sectionRewritesApplied && reg.sectionRewritesApplied.length > 0 ? reg.sectionRewritesApplied : null
+  };
+}
+function computeCostUsd(modelId, tokensIn, tokensOut) {
+  if (tokensIn === 0 && tokensOut === 0) return void 0;
+  const brainRow = resolvePricingAt(modelId);
+  if (brainRow && (brainRow.costInputPer1m > 0 || brainRow.costOutputPer1m > 0)) {
+    const inUsd2 = tokensIn / 1e6 * brainRow.costInputPer1m;
+    const outUsd2 = tokensOut / 1e6 * brainRow.costOutputPer1m;
+    return Math.round((inUsd2 + outUsd2) * 1e6) / 1e6;
+  }
+  const profile = tryGetProfile(modelId);
+  if (!profile) return void 0;
+  const inUsd = tokensIn / 1e6 * profile.costInputPer1m;
+  const outUsd = tokensOut / 1e6 * profile.costOutputPer1m;
+  return Math.round((inUsd + outUsd) * 1e6) / 1e6;
+}
+async function tryExtractOutcomeId(res) {
+  try {
+    const ct = res.headers?.get?.("content-type") ?? "";
+    if (ct && !ct.includes("application/json")) return void 0;
+    if (typeof res.json !== "function") return void 0;
+    const body = await res.json();
+    if (Array.isArray(body) && body.length > 0) {
+      const first = body[0];
+      const id = first?.id;
+      if (typeof id === "number") return id;
+    } else if (body && typeof body === "object") {
+      const id = body.id;
+      if (typeof id === "number") return id;
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+function buildAdvisoryRow(outcomeId, a) {
+  return {
+    outcome_id: outcomeId,
+    code: a.code,
+    level: a.level,
+    message: a.message,
+    ...a.recommendationType ? { recommendation_type: a.recommendationType } : {},
+    ...a.suggestion ? { suggestion: a.suggestion } : {},
+    ...a.docsUrl ? { docs_url: a.docsUrl } : {}
   };
 }
+async function recordOutcome(input) {
+  if (!activeConfig) {
+    return { ok: false, reason: "brain_not_configured" };
+  }
+  const config = activeConfig;
+  const fetchFn = config.fetchImpl ?? fetch;
+  const payload = {
+    outcome_id: input.outcomeId,
+    outcome: input.outcome,
+    rating: input.rating ?? null,
+    reason: input.reason ?? null,
+    observed_confidence: input.observedConfidence ?? null
+  };
+  const send = async () => {
+    try {
+      const res = await fetchFn(`${config.endpoint}/compile_outcome_quality`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}
+        },
+        body: JSON.stringify(payload)
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "<no body>");
+        const err = new Error(`brain ${res.status}: ${text}`);
+        (config.onError ?? defaultOnError)(err);
+        return { ok: false, reason: "persistence_failed" };
+      }
+      return { ok: true };
+    } catch (err) {
+      (config.onError ?? defaultOnError)(err);
+      return { ok: false, reason: "persistence_failed" };
+    }
+  };
+  if (config.sync) {
+    return send();
+  }
+  void send();
+  return { ok: true };
+}
 
 // src/ir.ts
 var CallError = class extends Error {
@@ -855,7 +1677,7 @@ async function execute(request, opts = {}) {
   }
 }
 async function executeAnthropic(request, opts) {
-  const apiKey = opts.apiKeys?.anthropic ?? process.env.ANTHROPIC_API_KEY;
+  const apiKey = resolveProviderKey("anthropic", { apiKeys: opts.apiKeys });
   if (!apiKey) {
     return terminalError(401, "auth", "ANTHROPIC_API_KEY missing");
   }
@@ -894,7 +1716,7 @@ function normalizeAnthropic(raw) {
   return { text, structuredOutput: null, toolCalls, tokens, finishReason: r.stop_reason, raw };
 }
 async function executeGoogle(request, opts) {
-  const apiKey = opts.apiKeys?.google ?? process.env.GOOGLE_API_KEY ?? process.env.GEMINI_API_KEY;
+  const apiKey = resolveProviderKey("google", { apiKeys: opts.apiKeys });
   if (!apiKey) {
     return terminalError(401, "auth", "GOOGLE_API_KEY/GEMINI_API_KEY missing");
   }
@@ -936,7 +1758,7 @@ function normalizeGoogle(raw) {
   return { text, structuredOutput: null, toolCalls, tokens, finishReason: candidate?.finishReason, raw };
 }
 async function executeOpenAI(request, opts) {
-  const apiKey = opts.apiKeys?.openai ?? process.env.OPENAI_API_KEY;
+  const apiKey = resolveProviderKey("openai", { apiKeys: opts.apiKeys });
   if (!apiKey) {
     return terminalError(401, "auth", "OPENAI_API_KEY missing");
   }
@@ -958,7 +1780,7 @@ async function executeOpenAI(request, opts) {
   return { ok: true, status: res.status, response: normalizeOpenAILike(json) };
 }
 async function executeDeepSeek(request, opts) {
-  const apiKey = opts.apiKeys?.deepseek ?? process.env.DEEPSEEK_API_KEY;
+  const apiKey = resolveProviderKey("deepseek", { apiKeys: opts.apiKeys });
   if (!apiKey) {
     return terminalError(401, "auth", "DEEPSEEK_API_KEY missing");
   }
@@ -1053,15 +1875,142 @@ function tryParseJson(s) {
 
 // src/call.ts
 async function call(ir, opts = {}) {
+  const traceId = generateTraceId();
+  safeEmit(
+    () => emitCompileStart(traceId, ir.appId, {
+      appId: ir.appId,
+      archetype: ir.intent.archetype,
+      models: ir.models
+    })
+  );
   const initial = compileAndRegister(ir, opts);
+  safeEmit(
+    () => emitCompileDone(traceId, ir.appId, {
+      target: initial.target,
+      provider: initial.provider,
+      fallbackChain: initial.fallbackChain,
+      tokensIn: initial.tokensIn,
+      estimatedCostUsd: initial.estimatedCostUsd,
+      mutationsApplied: initial.mutationsApplied,
+      advisories: initial.advisories
+    })
+  );
+  for (const adv of initial.advisories) {
+    safeEmit(
+      () => emitAdvisoryFired(traceId, ir.appId, { code: adv.code, message: adv.message })
+    );
+  }
   const start = Date.now();
   const attempts = [];
-  const targetsToTry = [initial.target, ...initial.fallbackChain];
+  const rawTargets = [initial.target, ...initial.fallbackChain];
+  let unreachableFiltered;
+  let targetsToTry;
+  if (opts.noAutoFilter) {
+    targetsToTry = rawTargets;
+  } else {
+    const dropped = [];
+    targetsToTry = [];
+    for (const t of rawTargets) {
+      if (isModelReachable(t, { apiKeys: opts.apiKeys })) {
+        targetsToTry.push(t);
+      } else {
+        dropped.push(t);
+      }
+    }
+    unreachableFiltered = dropped;
+    if (targetsToTry.length === 0) {
+      const latencyMs2 = Date.now() - start;
+      await record({
+        handle: initial.handle,
+        tokensIn: 0,
+        tokensOut: 0,
+        latencyMs: latencyMs2,
+        success: false,
+        errorType: "no_reachable_models",
+        promptPreview: extractPromptPreview(ir)
+      });
+      const noReachableAttempts = dropped.map((m) => ({
+        model: m,
+        status: "terminal",
+        errorCode: "unreachable_provider",
+        message: `No API key for ${m}'s provider \u2014 set one of PROVIDER_ENV_KEYS or pass apiKeys`
+      }));
+      throw new CallError(
+        `call(): no reachable models in chain. Filtered: [${dropped.join(", ")}]. Add a key for one provider, or pass apiKeys.`,
+        noReachableAttempts,
+        void 0,
+        "no_reachable_models"
+      );
+    }
+    const archetypeName = ir.intent?.archetype;
+    if (archetypeName) {
+      const ensured = ensureCrossProviderTail({
+        chain: targetsToTry,
+        archetype: archetypeName,
+        apiKeys: opts.apiKeys
+      });
+      if (ensured.appended) {
+        targetsToTry = ensured.chain;
+      }
+    }
+  }
+  let policyBlockedFiltered;
+  if (opts.policy?.blockedModels && opts.policy.blockedModels.length > 0) {
+    const blocked = new Set(opts.policy.blockedModels);
+    const filtered = [];
+    const dropped = [];
+    for (const t of targetsToTry) {
+      if (blocked.has(t)) {
+        dropped.push(t);
+      } else {
+        filtered.push(t);
+      }
+    }
+    if (dropped.length > 0) {
+      policyBlockedFiltered = dropped;
+      targetsToTry = filtered;
+    }
+    if (targetsToTry.length === 0) {
+      const latencyMs2 = Date.now() - start;
+      await record({
+        handle: initial.handle,
+        tokensIn: 0,
+        tokensOut: 0,
+        latencyMs: latencyMs2,
+        success: false,
+        errorType: "all_blocked_by_policy",
+        promptPreview: extractPromptPreview(ir)
+      });
+      const blockedAttempts = dropped.map((m) => ({
+        model: m,
+        status: "terminal",
+        errorCode: "blocked_by_policy",
+        message: `Skipped \u2014 model ${m} is in CompilePolicy.blockedModels`
+      }));
+      throw new CallError(
+        `call(): all chain targets blocked by CompilePolicy.blockedModels: [${dropped.join(", ")}]`,
+        blockedAttempts,
+        void 0,
+        "all_blocked_by_policy"
+      );
+    }
+  }
   let activeCompile = initial;
   let lastErr;
+  const failedProviders = /* @__PURE__ */ new Set();
   for (let i = 0; i < targetsToTry.length; i++) {
     const targetModel = targetsToTry[i];
-    if (i > 0) {
+    const targetProfile = tryGetProfile(targetModel);
+    if (targetProfile && failedProviders.has(targetProfile.provider) && !opts.noFallback) {
+      attempts.push({
+        model: targetModel,
+        status: "terminal",
+        errorCode: "auth_inferred",
+        message: `Skipped \u2014 provider ${targetProfile.provider} returned 401/403 earlier in this call; same key inferred to fail`
+      });
+      continue;
+    }
+    if (targetModel !== initial.target) {
       try {
         activeCompile = compileAndRegister(
           {
@@ -1081,59 +2030,112 @@ async function call(ir, opts = {}) {
         continue;
       }
     }
+    safeEmit(
+      () => emitExecuteAttempt(traceId, ir.appId, { model: targetModel, attemptIndex: i })
+    );
     const exec = await execute(activeCompile.request, {
       apiKeys: opts.apiKeys,
       fetchImpl: opts.fetchImpl,
       providerOverrides: opts.providerOverrides
     });
-    if (exec.ok) {
+    const validated = exec.ok ? validateStructuredContract(exec, ir) : exec;
+    if (validated.ok) {
       attempts.push({ model: targetModel, status: "success" });
       const latencyMs2 = Date.now() - start;
-      const responseWithStructured = withStructuredOutput(exec.response, ir);
-      void record({
+      safeEmit(
+        () => emitExecuteSuccess(traceId, ir.appId, {
+          model: targetModel,
+          tokensIn: validated.response.tokens.input,
+          tokensOut: validated.response.tokens.output,
+          latencyMs: latencyMs2
+        })
+      );
+      const fellOver = targetModel !== initial.target;
+      const fallbackReason = fellOver ? normalizeFallbackReason(attempts) : void 0;
+      await record({
         handle: initial.handle,
-        tokensIn: responseWithStructured.tokens.input,
-        tokensOut: responseWithStructured.tokens.output,
+        tokensIn: validated.response.tokens.input,
+        tokensOut: validated.response.tokens.output,
         latencyMs: latencyMs2,
         success: true,
-        emptyResponse: responseWithStructured.tokens.output === 0,
-        toolsCalled: responseWithStructured.toolCalls.map((tc) => tc.name),
+        emptyResponse: validated.response.tokens.output === 0,
+        toolsCalled: validated.response.toolCalls.map((tc) => tc.name),
         actualModel: targetModel !== initial.target ? targetModel : void 0,
-        responsePreview: responseWithStructured.text.slice(0, 200)
+        mutationsApplied: targetModel !== initial.target ? activeCompile.mutationsApplied.map((m) => m.id) : void 0,
+        promptPreview: extractPromptPreview(ir),
+        responsePreview: validated.response.text.slice(0, 200),
+        cacheReadInputTokens: validated.response.tokens.cached,
+        cacheCreationInputTokens: validated.response.tokens.cacheCreated,
+        // alpha.28 — Glass-Box renderer substrate (migration 018). call()
+        // owns the lifecycle so it has direct visibility into finishReason
+        // (from the normalized provider response), totalMs (mirrors latencyMs
+        // for non-streaming; future streaming variant may diverge), and the
+        // fell-over-from / fallback-reason pair (already computed above for
+        // the CallResult return shape).
+        finishReason: validated.response.finishReason,
+        totalMs: latencyMs2,
+        fellOverFrom: fellOver ? initial.target : void 0,
+        fallbackReason
       });
+      if (fellOver) {
+        const firstFailed = attempts.find((a) => a.status !== "success");
+        if (firstFailed) {
+          safeEmit(
+            () => emitFallbackWalked(traceId, ir.appId, {
+              from: initial.target,
+              to: targetModel,
+              reason: fallbackReason ?? "unknown",
+              attempt: firstFailed
+            })
+          );
+        }
+      }
       return {
         handle: initial.handle,
         actualModel: targetModel,
         requestedModel: initial.target,
         provider: activeCompile.provider,
-        response: responseWithStructured,
+        response: validated.response,
         latencyMs: latencyMs2,
         mutationsApplied: activeCompile.mutationsApplied,
-        attempts
+        attempts,
+        servedBy: targetModel,
+        fellOverFrom: fellOver ? initial.target : void 0,
+        fallbackReason,
+        unreachableFiltered,
+        policyBlockedFiltered,
+        traceId
       };
     }
     attempts.push({
       model: targetModel,
-      status: exec.errorType,
-      errorCode: exec.errorCode,
-      message: exec.message
+      status: validated.errorType,
+      errorCode: validated.errorCode,
+      message: validated.message
     });
-    lastErr = exec;
-    if (exec.errorType === "terminal" || opts.noFallback) {
+    lastErr = validated;
+    if (validated.errorType === "terminal" || opts.noFallback) {
+      if (validated.errorCode === "auth" && !opts.noFallback && activeCompile.provider) {
+        failedProviders.add(activeCompile.provider);
+        continue;
+      }
       break;
     }
   }
   const latencyMs = Date.now() - start;
-  void record({
+  await record({
     handle: initial.handle,
     tokensIn: 0,
     tokensOut: 0,
     latencyMs,
     success: false,
-    errorType: lastErr?.errorCode
+    errorType: lastErr?.errorCode,
+    promptPreview: extractPromptPreview(ir)
   });
+  const filteredNote = unreachableFiltered && unreachableFiltered.length > 0 ? ` (also auto-filtered: [${unreachableFiltered.join(", ")}] \u2014 no API key)` : "";
+  const blockedNote = policyBlockedFiltered && policyBlockedFiltered.length > 0 ? ` (also policy-blocked: [${policyBlockedFiltered.join(", ")}])` : "";
   throw new CallError(
-    `call(): all attempts failed${lastErr ? ` \u2014 ${lastErr.errorCode}: ${lastErr.message}` : ""}`,
+    `call(): all attempts failed${lastErr ? ` \u2014 ${lastErr.errorCode}: ${lastErr.message}` : ""}${filteredNote}${blockedNote}`,
     attempts,
     lastErr?.status,
     lastErr?.errorCode
@@ -1148,20 +2150,74 @@ function compileAndRegister(ir, opts) {
   registerCompile(ir.appId, ir.intent.archetype, ir, result);
   return result;
 }
-function withStructuredOutput(response, ir) {
-  if (!ir.constraints?.structuredOutput) return response;
-  if (!response.text) return response;
+function extractPromptPreview(ir) {
+  const turn = ir.currentTurn?.content;
+  if (turn) return turn.slice(0, 200);
+  const lastHist = ir.history?.[ir.history.length - 1]?.content;
+  if (lastHist) return lastHist.slice(0, 200);
+  return void 0;
+}
+function validateStructuredContract(exec, ir) {
+  if (!ir.constraints?.structuredOutput) {
+    return { ok: true, response: exec.response };
+  }
+  const finish = (exec.response.finishReason ?? "").toLowerCase();
+  if (finish === "max_tokens" || finish === "length") {
+    return {
+      ok: false,
+      status: exec.status,
+      errorType: "retryable",
+      errorCode: "max_tokens_on_structured_output",
+      message: `Provider returned finishReason="${exec.response.finishReason}" on a structured-output call \u2014 output truncated mid-token, JSON cannot be valid`,
+      raw: exec.response.raw
+    };
+  }
+  if (!exec.response.text) {
+    return { ok: true, response: exec.response };
+  }
   try {
-    const parsed = JSON.parse(response.text);
-    return { ...response, structuredOutput: parsed };
+    const parsed = JSON.parse(exec.response.text);
+    return { ok: true, response: { ...exec.response, structuredOutput: parsed } };
   } catch (err) {
     return {
-      ...response,
-      structuredOutput: null,
-      parseError: err instanceof Error ? err.message : String(err)
+      ok: false,
+      status: exec.status,
+      errorType: "retryable",
+      errorCode: "structured_output_parse_failed",
+      message: err instanceof Error ? err.message : String(err),
+      raw: exec.response.raw
     };
   }
 }
+function normalizeFallbackReason(attempts) {
+  const first = attempts.find((a) => a.status !== "success");
+  if (!first) return void 0;
+  const code = first.errorCode ?? "";
+  if (code === "rate_limit_429" || code === "rate_limit") return "rate_limit";
+  if (code === "max_tokens_on_structured_output" || code === "structured_output_parse_failed") {
+    return "cliff";
+  }
+  if (code === "cost_cap_exceeded") return "cost_cap";
+  if (code === "auth" || code === "auth_inferred") return "provider_auth_failed";
+  return "provider_error";
+}
+function generateTraceId() {
+  try {
+    const g = globalThis;
+    if (g.crypto && typeof g.crypto.randomUUID === "function") {
+      return g.crypto.randomUUID();
+    }
+  } catch {
+  }
+  const hex = (n) => Math.floor(Math.random() * Math.pow(16, n)).toString(16).padStart(n, "0");
+  return `${hex(8)}-${hex(4)}-${hex(4)}-${hex(4)}-${hex(12)}`;
+}
+function safeEmit(fn) {
+  try {
+    fn();
+  } catch {
+  }
+}
 
 // src/oracle.ts
 var DEFAULT_DIMENSIONS = ["correctness", "completeness", "conciseness", "format"];
@@ -1251,6 +2307,397 @@ function clamp(n) {
   return Math.max(0, Math.min(1, n));
 }
 
+// src/advisories-api.ts
+var SEVERITY_SET = /* @__PURE__ */ new Set(["info", "warn", "critical"]);
+var STATUS_SET = /* @__PURE__ */ new Set(["open", "snoozed", "resolved"]);
+var RESOLUTION_SOURCE_SET = /* @__PURE__ */ new Set([
+  "auto",
+  "consumer-marked",
+  "declined"
+]);
+function asString(v) {
+  return typeof v === "string" && v.length > 0 ? v : void 0;
+}
+function asSeverity(v) {
+  if (typeof v === "string" && SEVERITY_SET.has(v)) {
+    return v;
+  }
+  return "info";
+}
+function asStatus(v) {
+  if (typeof v === "string" && STATUS_SET.has(v)) {
+    return v;
+  }
+  return "open";
+}
+function asResolutionSource(v) {
+  if (typeof v === "string" && RESOLUTION_SOURCE_SET.has(v)) {
+    return v;
+  }
+  return void 0;
+}
+function rowToAdvisory(row) {
+  const archetype = asString(row.applies_to_archetype);
+  const model = asString(row.applies_to_model);
+  const docsLink = asString(row.docs_url);
+  const suggestion = asString(row.suggestion);
+  let suggestedFix = null;
+  if (docsLink || suggestion) {
+    suggestedFix = { type: "manual" };
+    if (docsLink) suggestedFix.docsLink = docsLink;
+    if (suggestion) suggestedFix.before = suggestion;
+  }
+  const out = {
+    id: typeof row.id === "string" ? row.id : "",
+    rule: typeof row.rule === "string" ? row.rule : "",
+    severity: asSeverity(row.severity),
+    openedAt: typeof row.opened_at === "string" ? row.opened_at : "",
+    lastObservedAt: typeof row.last_observed_at === "string" ? row.last_observed_at : "",
+    observationCount: typeof row.observation_count === "number" ? row.observation_count : 0,
+    appliesTo: {
+      ...archetype ? { archetype } : {},
+      ...model ? { model } : {}
+    },
+    message: typeof row.message === "string" ? row.message : "",
+    suggestedFix,
+    autoApplicable: false,
+    // reserved — alpha.30+
+    status: asStatus(row.status)
+  };
+  const resolvedAt = asString(row.resolved_at);
+  if (resolvedAt) out.resolvedAt = resolvedAt;
+  const resolutionSource = asResolutionSource(row.resolution_source);
+  if (resolutionSource) out.resolutionSource = resolutionSource;
+  const resolutionNote = asString(row.resolution_note);
+  if (resolutionNote) out.resolutionNote = resolutionNote;
+  return out;
+}
+function resolveFetch(injected) {
+  return injected ?? ((...args) => globalThis.fetch(...args));
+}
+function normalizeEndpoint(endpoint) {
+  return endpoint.replace(/\/+$/, "");
+}
+async function getActionableAdvisories(opts) {
+  const {
+    appId,
+    severity,
+    status,
+    brainEndpoint,
+    brainJwt,
+    brainAnonKey,
+    fetch: injectedFetch
+  } = opts;
+  if (!appId) {
+    throw new Error("getActionableAdvisories: appId is required");
+  }
+  const doFetch = resolveFetch(injectedFetch);
+  const base = normalizeEndpoint(brainEndpoint);
+  const qs = new URLSearchParams();
+  qs.set("app_id", `eq.${appId}`);
+  if (severity) qs.set("severity", `eq.${severity}`);
+  const effectiveStatus = status ?? "open";
+  if (effectiveStatus !== "all") {
+    qs.set("status", `eq.${effectiveStatus}`);
+  }
+  qs.set("order", "last_observed_at.desc");
+  const url = `${base}/rest/v1/actionable_advisories_v?${qs.toString()}`;
+  let res;
+  try {
+    res = await doFetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${brainJwt}`,
+        apikey: brainAnonKey,
+        Accept: "application/json"
+      }
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`getActionableAdvisories: network error: ${msg}`);
+  }
+  if (res.status === 401 || res.status === 403) {
+    throw new Error("getActionableAdvisories: brain auth misconfig");
+  }
+  if (res.status >= 500) {
+    throw new Error(`getActionableAdvisories: brain unavailable (${res.status})`);
+  }
+  if (!res.ok) {
+    throw new Error(`getActionableAdvisories: bad request (${res.status})`);
+  }
+  let rows;
+  try {
+    rows = await res.json();
+  } catch {
+    throw new Error("getActionableAdvisories: malformed brain response");
+  }
+  if (!Array.isArray(rows)) {
+    throw new Error("getActionableAdvisories: expected array from brain");
+  }
+  const out = [];
+  for (const raw of rows) {
+    if (raw && typeof raw === "object") {
+      out.push(rowToAdvisory(raw));
+    }
+  }
+  return out;
+}
+async function markAdvisoryResolved(opts) {
+  const {
+    id,
+    resolutionNote,
+    brainEndpoint,
+    brainJwt,
+    brainAnonKey,
+    fetch: injectedFetch
+  } = opts;
+  if (!id) {
+    return { ok: false, reason: "id_required" };
+  }
+  const doFetch = resolveFetch(injectedFetch);
+  const base = normalizeEndpoint(brainEndpoint);
+  const lookupUrl = `${base}/rest/v1/actionable_advisories_v?id=eq.${encodeURIComponent(id)}&select=app_id,rule`;
+  let lookupRes;
+  try {
+    lookupRes = await doFetch(lookupUrl, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${brainJwt}`,
+        apikey: brainAnonKey,
+        Accept: "application/json"
+      }
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, reason: `network_error:${msg}` };
+  }
+  if (lookupRes.status === 401 || lookupRes.status === 403) {
+    return { ok: false, reason: "brain_auth_misconfig" };
+  }
+  if (lookupRes.status >= 500) {
+    return { ok: false, reason: "brain_unavailable" };
+  }
+  if (!lookupRes.ok) {
+    return { ok: false, reason: `brain_lookup_failed:${lookupRes.status}` };
+  }
+  let lookupRows;
+  try {
+    lookupRows = await lookupRes.json();
+  } catch {
+    return { ok: false, reason: "brain_lookup_malformed" };
+  }
+  if (!Array.isArray(lookupRows) || lookupRows.length === 0) {
+    return { ok: false, reason: "advisory_not_found" };
+  }
+  const tuple = lookupRows[0];
+  const appId = typeof tuple.app_id === "string" ? tuple.app_id : "";
+  const code = typeof tuple.rule === "string" ? tuple.rule : "";
+  if (!appId || !code) {
+    return { ok: false, reason: "advisory_tuple_invalid" };
+  }
+  const outcomesUrl = `${base}/rest/v1/compile_outcomes?app_id=eq.${encodeURIComponent(appId)}&select=id`;
+  let outcomesRes;
+  try {
+    outcomesRes = await doFetch(outcomesUrl, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${brainJwt}`,
+        apikey: brainAnonKey,
+        Accept: "application/json"
+      }
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, reason: `network_error:${msg}` };
+  }
+  if (outcomesRes.status === 401 || outcomesRes.status === 403) {
+    return { ok: false, reason: "brain_auth_misconfig" };
+  }
+  if (outcomesRes.status >= 500) {
+    return { ok: false, reason: "brain_unavailable" };
+  }
+  if (!outcomesRes.ok) {
+    return { ok: false, reason: `brain_lookup_failed:${outcomesRes.status}` };
+  }
+  let outcomeRows;
+  try {
+    outcomeRows = await outcomesRes.json();
+  } catch {
+    return { ok: false, reason: "brain_lookup_malformed" };
+  }
+  if (!Array.isArray(outcomeRows)) {
+    return { ok: false, reason: "brain_lookup_malformed" };
+  }
+  const outcomeIds = [];
+  for (const row of outcomeRows) {
+    if (row && typeof row === "object") {
+      const idVal = row.id;
+      if (typeof idVal === "number" && Number.isFinite(idVal)) {
+        outcomeIds.push(idVal);
+      }
+    }
+  }
+  if (outcomeIds.length === 0) {
+    return { ok: true };
+  }
+  const inList = outcomeIds.join(",");
+  const patchUrl = `${base}/rest/v1/compile_outcome_advisories?outcome_id=in.(${inList})&code=eq.${encodeURIComponent(code)}&resolved_at=is.null`;
+  const patchBody = {
+    resolved_at: (/* @__PURE__ */ new Date()).toISOString(),
+    resolution_source: "consumer-marked"
+  };
+  if (resolutionNote !== void 0) {
+    patchBody.resolution_note = resolutionNote;
+  }
+  let patchRes;
+  try {
+    patchRes = await doFetch(patchUrl, {
+      method: "PATCH",
+      headers: {
+        Authorization: `Bearer ${brainJwt}`,
+        apikey: brainAnonKey,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        // PostgREST default is no return; we don't need the row back.
+        Prefer: "return=minimal"
+      },
+      body: JSON.stringify(patchBody)
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, reason: `network_error:${msg}` };
+  }
+  if (patchRes.status === 401 || patchRes.status === 403) {
+    return { ok: false, reason: "brain_auth_misconfig" };
+  }
+  if (patchRes.status >= 500) {
+    return { ok: false, reason: "brain_unavailable" };
+  }
+  if (!patchRes.ok) {
+    return { ok: false, reason: `patch_failed:${patchRes.status}` };
+  }
+  return { ok: true };
+}
+
+// src/models-brain.ts
+function isModelRow(x) {
+  if (!x || typeof x !== "object") return false;
+  const r = x;
+  return typeof r.model_id === "string" && typeof r.provider === "string";
+}
+function isAliasRow(x) {
+  if (!x || typeof x !== "object") return false;
+  const r = x;
+  return typeof r.alias_id === "string" && typeof r.canonical_id === "string";
+}
+function rowToProfile(row) {
+  try {
+    if (row.cliffs !== void 0 && row.cliffs !== null && !Array.isArray(row.cliffs)) {
+      return null;
+    }
+    if (row.recovery !== void 0 && row.recovery !== null && !Array.isArray(row.recovery)) {
+      return null;
+    }
+    if (row.lowering !== void 0 && row.lowering !== null && (typeof row.lowering !== "object" || Array.isArray(row.lowering))) {
+      return null;
+    }
+    return {
+      id: row.model_id,
+      provider: row.provider,
+      status: row.status ?? "current",
+      maxContextTokens: row.max_context_tokens ?? 0,
+      maxOutputTokens: row.max_output_tokens ?? 0,
+      maxTools: row.max_tools ?? 0,
+      parallelToolCalls: row.parallel_tool_calls ?? false,
+      structuredOutput: row.structured_output ?? "none",
+      systemPromptMode: row.system_prompt_mode ?? "inline",
+      streaming: row.streaming ?? true,
+      cliffs: row.cliffs ?? [],
+      costInputPer1m: row.cost_input_per_1m ?? 0,
+      costOutputPer1m: row.cost_output_per_1m ?? 0,
+      lowering: row.lowering ?? { system: { mode: "inline" }, cache: { strategy: "unsupported" } },
+      recovery: row.recovery ?? [],
+      strengths: row.strengths ?? [],
+      weaknesses: row.weaknesses ?? [],
+      notes: row.notes ?? void 0,
+      verifiedAgainstDocs: row.verified_against_docs ?? void 0,
+      archetypePerf: row.archetype_perf ?? void 0
+    };
+  } catch {
+    return null;
+  }
+}
+function profileToRow(profile, opts = {}) {
+  const row = {
+    model_id: profile.id,
+    provider: profile.provider,
+    status: profile.status,
+    max_context_tokens: profile.maxContextTokens,
+    max_output_tokens: profile.maxOutputTokens,
+    max_tools: profile.maxTools,
+    parallel_tool_calls: profile.parallelToolCalls,
+    structured_output: profile.structuredOutput,
+    system_prompt_mode: profile.systemPromptMode,
+    streaming: profile.streaming,
+    cliffs: profile.cliffs,
+    cost_input_per_1m: profile.costInputPer1m,
+    cost_output_per_1m: profile.costOutputPer1m,
+    lowering: profile.lowering,
+    recovery: profile.recovery,
+    strengths: profile.strengths,
+    weaknesses: profile.weaknesses,
+    notes: profile.notes ?? null,
+    archetype_perf: profile.archetypePerf ?? null,
+    active: opts.active ?? true
+  };
+  if (opts.verifiedAgainstDocs !== void 0) {
+    row.verified_against_docs = opts.verifiedAgainstDocs;
+  } else if (profile.verifiedAgainstDocs !== void 0) {
+    const v = profile.verifiedAgainstDocs;
+    row.verified_against_docs = /^\d{4}-\d{2}-\d{2}/.test(v) ? v : null;
+  }
+  if (opts.versionAdded !== void 0) row.version_added = opts.versionAdded;
+  if (opts.versionRemoved !== void 0) row.version_removed = opts.versionRemoved;
+  return row;
+}
+function mapRowsToModels(rows) {
+  const out = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    if (!isModelRow(row)) continue;
+    const profile = rowToProfile(row);
+    if (profile) out.set(profile.id, profile);
+  }
+  return out;
+}
+function mapRowsToAliases(rows) {
+  const out = {};
+  for (const row of rows) {
+    if (!isAliasRow(row)) continue;
+    out[row.alias_id] = row.canonical_id;
+  }
+  return out;
+}
+function bundledModels() {
+  return new Map(allProfilesRaw().map((p) => [p.id, p]));
+}
+function bundledAliases() {
+  return { ...ALIASES };
+}
+var loadModelsFromBrain = createBrainQueryCache({
+  table: "kgauto_models",
+  mapRows: mapRowsToModels,
+  bundledFallback: bundledModels
+});
+var loadAliasesFromBrain = createBrainQueryCache({
+  table: "kgauto_aliases",
+  mapRows: mapRowsToAliases,
+  bundledFallback: bundledAliases
+});
+_setProfileBrainHook({
+  getProfile: (canonical) => loadModelsFromBrain().get(canonical),
+  resolveAlias: (id) => loadAliasesFromBrain()[id]
+});
+
 // src/index.ts
 function compile2(ir, opts) {
   const result = compile(ir, opts);
@@ -1258,12 +2705,19 @@ function compile2(ir, opts) {
   return result;
 }
 export {
+  ABSOLUTE_FLOOR,
   ALIASES,
   ALL_ARCHETYPES,
+  ARCHETYPE_FLOOR_DEFAULT,
   CallError,
   DIALECT_VERSION,
   INTENT_ARCHETYPES,
+  MEASURED_GROUNDING_MIN_N,
+  PROVIDER_ENV_KEYS,
+  RULE_SEQUENTIAL_TOOL_CLIFF,
+  TRANSLATOR_FLOOR,
   allProfiles,
+  applySectionRewrites,
   bucketContext,
   bucketHistory,
   bucketToolCount,
@@ -1274,13 +2728,41 @@ export {
   configureBrain,
   countTokens,
   execute,
+  getActionableAdvisories,
+  getAllStarterChains,
+  getAllStarterChainsWithGrounding,
+  getArchetypePerfScore,
+  getDefaultFallbackChain,
+  getDefaultFallbackChainWithGrounding,
+  getModelCompatibility,
+  getPerAxisMetrics,
   getProfile,
+  getReachabilityDiagnostic,
+  getSequentialStarterChain,
+  getSequentialStarterChainWithGrounding,
+  getStarterChain,
+  getStarterChainWithGrounding,
   hashShape,
   isArchetype,
+  isBrainQueryActiveFor,
+  isModelReachable,
+  isProviderReachable,
   learningKey,
+  loadAliasesFromBrain,
+  loadArchetypePerfFromBrain,
+  loadArchetypePerfNFromBrain,
+  loadChainsFromBrain,
+  loadModelsFromBrain,
+  loadPricingFromBrain,
+  markAdvisoryResolved,
+  profileToRow,
   profilesByProvider,
   record,
+  recordOutcome,
   resetTokenizer,
+  resolvePricingAt,
+  resolveProviderKey,
+  runAdvisor,
   setTokenizer,
   tryGetProfile
 };