@warmdrift/kgauto-compiler 2.0.0-alpha.5 → 2.0.0-alpha.51

package/dist/index.mjs

@@ -9,13 +9,441 @@ 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,
+  readBrainReadEnv,
+  resolveProviderKey
+} from "./chunk-HHWBB46W.mjs";
 import {
   ALIASES,
+  LATENCY_TIER_MS,
+  _setProfileBrainHook,
   allProfiles,
+  allProfilesRaw,
   getProfile,
+  latencyTierOf,
   profilesByProvider,
   tryGetProfile
-} from "./chunk-MBEI5UOM.mjs";
+} from "./chunk-CXH7KC4D.mjs";
+import {
+  emitAdvisoryFired,
+  emitCompileDone,
+  emitCompileStart,
+  emitExecuteAttempt,
+  emitExecuteSuccess,
+  emitFallbackWalked
+} from "./chunk-NBO4R5PC.mjs";
+
+// 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;
+    }
+    if (row.archetype_conventions !== void 0 && row.archetype_conventions !== null && !Array.isArray(row.archetype_conventions)) {
+      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,
+      // alpha.41 — family-resolution fields. `family` may be null pre-
+      // migration 024; runtime falls back to deriveFamilyFromModelId at
+      // resolution time (see family-resolution.ts, G1).
+      family: row.family ?? void 0,
+      versionAdded: row.version_added ?? void 0,
+      active: row.active ?? void 0,
+      // alpha.49 — executable-knowledge fields (migration 028). Invalid
+      // latency_tier → undefined (latencyTierOf derives from tags; not
+      // safety-critical). archetype_conventions already array-validated above.
+      latencyTier: normalizeLatencyTier(row.latency_tier),
+      archetypeConventions: row.archetype_conventions ?? void 0
+    };
+  } catch {
+    return null;
+  }
+}
+var VALID_LATENCY_TIERS = /* @__PURE__ */ new Set(["fast", "medium", "slow"]);
+function normalizeLatencyTier(v) {
+  return typeof v === "string" && VALID_LATENCY_TIERS.has(v) ? v : void 0;
+}
+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 ?? profile.active ?? true,
+    // alpha.41 — round-trip family + version_added when present on profile.
+    // version_added is operator-controlled via opts; profile-side value is
+    // used only when opts didn't override.
+    family: profile.family ?? null,
+    // alpha.49 — round-trip the executable-knowledge fields (migration 028)
+    // so a reseed from bundled profiles makes the latency lever + schema
+    // conventions live warm. Closes the silently-dropped-field gap.
+    latency_tier: profile.latencyTier ?? null,
+    archetype_conventions: profile.archetypeConventions ?? null
+  };
+  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;
+  else if (profile.versionAdded !== void 0) row.version_added = profile.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/exclusion-findings-brain.ts
+function isValidVerdict(v) {
+  return v === "recommend-probe" || v === "unblock" || v === "stay-excluded" || v === "inconclusive";
+}
+function isValidConfidence(v) {
+  return v === "high" || v === "medium" || v === "low";
+}
+function isRawFindingRow(x) {
+  if (!x || typeof x !== "object") return false;
+  const r = x;
+  return typeof r.intent_archetype === "string" && typeof r.excluded_model === "string" && typeof r.excluded_provider === "string" && typeof r.verdict === "string" && typeof r.message === "string" && typeof r.suggestion === "string" && typeof r.confidence === "string";
+}
+function mapRowsToFindings(rows) {
+  const out = [];
+  for (const row of rows) {
+    if (!isRawFindingRow(row)) continue;
+    if (!isValidVerdict(row.verdict)) continue;
+    if (!isValidConfidence(row.confidence)) continue;
+    let savings = null;
+    if (typeof row.estimated_savings_usd_30d === "number") {
+      savings = Number.isFinite(row.estimated_savings_usd_30d) ? row.estimated_savings_usd_30d : null;
+    } else if (typeof row.estimated_savings_usd_30d === "string") {
+      const n = Number(row.estimated_savings_usd_30d);
+      savings = Number.isFinite(n) ? n : null;
+    }
+    out.push({
+      archetype: row.intent_archetype,
+      excludedModel: row.excluded_model,
+      excludedProvider: row.excluded_provider,
+      verdict: row.verdict,
+      estimatedSavingsUsd30d: savings,
+      message: row.message,
+      suggestion: row.suggestion,
+      confidence: row.confidence,
+      evidence: row.evidence && typeof row.evidence === "object" ? row.evidence : void 0
+    });
+  }
+  return out;
+}
+var snapshots = /* @__PURE__ */ new Map();
+var runtime;
+var warnedOnce = false;
+var DEFAULT_FINDINGS_ENDPOINT = "https://kgauto-dashboard.vercel.app/api/kgauto-v2/findings/exclusions";
+function configureExclusionFindingsBrain(rt) {
+  runtime = rt;
+  snapshots.clear();
+  warnedOnce = false;
+}
+function isExclusionFindingsBrainActive() {
+  return runtime !== void 0;
+}
+function getStaleExclusionFindings(opts) {
+  const rt = runtime;
+  if (!rt) return [];
+  const appId = opts.appId;
+  if (!appId) return [];
+  let snap = snapshots.get(appId);
+  if (!snap) {
+    snap = { data: [], expiresAt: 0, refreshing: false };
+    snapshots.set(appId, snap);
+  }
+  const now = Date.now();
+  const stale = snap.expiresAt <= now;
+  if (stale && !snap.refreshing) {
+    snap.refreshing = true;
+    void asyncRefresh(rt, appId);
+  }
+  if (opts.archetype) {
+    return snap.data.filter((f) => f.archetype === opts.archetype);
+  }
+  return snap.data;
+}
+var pendingRefreshes = /* @__PURE__ */ new Map();
+async function asyncRefresh(rt, appId) {
+  const promise = doRefresh(rt, appId);
+  pendingRefreshes.set(appId, promise);
+  try {
+    await promise;
+  } finally {
+    if (pendingRefreshes.get(appId) === promise) {
+      pendingRefreshes.delete(appId);
+    }
+  }
+}
+async function doRefresh(rt, appId) {
+  const url = `${rt.endpoint}?app_id=${encodeURIComponent(appId)}`;
+  let snap = snapshots.get(appId);
+  if (!snap) {
+    snap = { data: [], expiresAt: 0, refreshing: false };
+    snapshots.set(appId, snap);
+  }
+  try {
+    const res = await rt.fetchImpl(url, { method: "GET" });
+    if (!res.ok) {
+      throw new Error(`findings ${res.status}: ${res.statusText}`);
+    }
+    const body = await res.json();
+    if (runtime !== rt) return;
+    const rows = Array.isArray(body) ? mapRowsToFindings(body) : [];
+    snap.data = rows;
+    snap.expiresAt = Date.now() + rt.ttlMs;
+    snap.refreshing = false;
+  } catch (err) {
+    if (runtime !== rt) return;
+    snap.refreshing = false;
+    snap.expiresAt = Date.now() + rt.ttlMs;
+    if (!warnedOnce) {
+      warnedOnce = true;
+      (rt.onError ?? defaultOnError)(err);
+    }
+  }
+}
+function defaultOnError(err) {
+  console.warn(
+    "[kgauto] exclusion-findings fetch failed (using empty fallback):",
+    err
+  );
+}
+
+// src/family-resolution.ts
+var FamilyResolutionError = class extends Error {
+  family;
+  cause;
+  constructor(family, cause) {
+    super(
+      `Family "${family}" did not resolve to any current+active model. ${cause}. Pass a literal model id in ir.models, or call getRecommendedPrimary({ family, fallback }) at IR-construction time.`
+    );
+    this.name = "FamilyResolutionError";
+    this.family = family;
+    this.cause = cause;
+  }
+};
+function deriveFamilyFromModelId(modelId) {
+  if (typeof modelId !== "string" || modelId.length === 0) return null;
+  if (modelId.startsWith("claude-opus-")) return "claude-opus";
+  if (modelId.startsWith("claude-sonnet-")) return "claude-sonnet";
+  if (modelId.startsWith("claude-haiku-")) return "claude-haiku";
+  if (modelId.startsWith("gemini-") && modelId.includes("flash-lite")) {
+    return "gemini-flash-lite";
+  }
+  if (modelId.startsWith("gemini-") && modelId.includes("flash")) {
+    return "gemini-flash";
+  }
+  if (modelId.startsWith("gemini-") && modelId.includes("pro")) {
+    return "gemini-pro";
+  }
+  if (modelId.startsWith("deepseek-") && modelId.includes("pro")) {
+    return "deepseek-reasoner";
+  }
+  if (modelId.startsWith("deepseek-")) return "deepseek-chat";
+  if (modelId.startsWith("gpt-")) return "openai-gpt";
+  return null;
+}
+function familyOf(profile) {
+  return profile.family ?? deriveFamilyFromModelId(profile.id);
+}
+function archetypePerfFor(profile, archetype) {
+  if (!archetype) return 0;
+  const score = profile.archetypePerf?.[archetype];
+  return typeof score === "number" ? score : 5;
+}
+function selectCandidates(registry, family, archetype, appId) {
+  const out = [];
+  const excluded = /* @__PURE__ */ new Set();
+  if (appId && archetype) {
+    const findings = getStaleExclusionFindings({ appId, archetype });
+    for (const f of findings) {
+      if (f.verdict === "stay-excluded") excluded.add(f.excludedModel);
+    }
+  }
+  for (const profile of registry.values()) {
+    if (familyOf(profile) !== family) continue;
+    if (profile.status !== "current") continue;
+    if (profile.active === false) continue;
+    if (archetype) {
+      if (archetypePerfFor(profile, archetype) < ARCHETYPE_FLOOR_DEFAULT) continue;
+    }
+    if (excluded.has(profile.id)) continue;
+    out.push(profile);
+  }
+  return out;
+}
+function sortCandidates(candidates, archetype) {
+  const sorted = [...candidates];
+  sorted.sort((a, b) => {
+    const perfA = archetypePerfFor(a, archetype);
+    const perfB = archetypePerfFor(b, archetype);
+    if (perfA !== perfB) return perfB - perfA;
+    const vA = a.versionAdded ?? "";
+    const vB = b.versionAdded ?? "";
+    if (vA !== vB) return vA < vB ? 1 : -1;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+  });
+  return sorted;
+}
+function getRecommendedPrimary(opts) {
+  if (opts.posture === "locked") return opts.fallback;
+  const registry = loadModelsFromBrain();
+  const candidates = selectCandidates(
+    registry,
+    opts.family,
+    opts.archetype,
+    opts.appId
+  );
+  if (candidates.length === 0) return opts.fallback;
+  const sorted = sortCandidates(candidates, opts.archetype);
+  return sorted[0]?.id ?? opts.fallback;
+}
+function resolveFamilyEntry(family, ctx) {
+  if (typeof family !== "string" || family.length === 0) {
+    throw new FamilyResolutionError(
+      String(family),
+      "Family tag must be a non-empty string"
+    );
+  }
+  const registry = loadModelsFromBrain();
+  const candidates = selectCandidates(
+    registry,
+    family,
+    ctx.archetype,
+    ctx.appId
+  );
+  if (candidates.length === 0) {
+    let anyInFamily = false;
+    for (const profile of registry.values()) {
+      if (familyOf(profile) === family) {
+        anyInFamily = true;
+        break;
+      }
+    }
+    const cause = anyInFamily ? `Family has registered models but none are current+active${ctx.archetype ? ` at archetype-perf >= ${ARCHETYPE_FLOOR_DEFAULT} for "${ctx.archetype}"` : ""}${ctx.appId ? ` and not excluded for app "${ctx.appId}"` : ""}` : `No models in brain registry carry family="${family}". Check the taxonomy table in family-resolution.ts or migration 024`;
+    throw new FamilyResolutionError(family, cause);
+  }
+  const sorted = sortCandidates(candidates, ctx.archetype);
+  const winner = sorted[0];
+  if (!winner) {
+    throw new FamilyResolutionError(
+      family,
+      "Candidates non-empty but sort returned undefined \u2014 internal invariant violation"
+    );
+  }
+  return winner.id;
+}
 
 // src/tokenizer.ts
 var tokenizerImpl = defaultCharBasedCounter;
@@ -120,38 +548,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":
@@ -243,6 +729,19 @@ function passApplyCliffs(ir, profile, estimatedInputTokens) {
   }
   return { value: { ir: nextIR, loweringHints: hints }, mutations };
 }
+var LATENCY_OVERAGE_WEIGHT = 0.6;
+var LATENCY_PENALTY_CAP = 1;
+var QUALITY_GATE_PENALTY = 4;
+function effectiveConventions(profile) {
+  const own = profile.archetypeConventions ?? [];
+  if (own.length > 0) return own;
+  const family = profile.family ?? deriveFamilyFromModelId(profile.id);
+  if (!family) return [];
+  const repId = familyRepId(family);
+  if (!repId || repId === profile.id) return [];
+  const rep = tryGetProfile(repId);
+  return rep?.archetypeConventions ?? [];
+}
 function passScoreTargets(ir, opts) {
   const constraints = ir.constraints ?? {};
   const policy = opts.policy ?? {};
@@ -250,7 +749,8 @@ function passScoreTargets(ir, opts) {
   const preferredSet = new Set(policy.preferredModels ?? []);
   const scores = [];
   const policyMutations = [];
-  for (const modelId of ir.models) {
+  const modelIds = ir.models.filter((m) => typeof m === "string");
+  for (const modelId of modelIds) {
     let profile;
     try {
       profile = opts.profilesById(modelId);
@@ -294,10 +794,26 @@ function passScoreTargets(ir, opts) {
     }
     const baseQuality = profile.strengths.includes("reasoning") ? 0.85 : profile.strengths.includes("quality") ? 0.8 : 0.6;
     const qualityScore = Math.max(0, baseQuality - qualityPenalty);
-    const callerOrderBoost = (ir.models.length - ir.models.indexOf(modelId)) * 0.1;
+    const callerOrderBoost = (modelIds.length - modelIds.indexOf(modelId)) * 0.1;
     const costPenalty = estimatedCostUsd * 5;
     const preferredBoost = preferredSet.has(modelId) ? 0.5 : 0;
-    const rank = qualityScore + callerOrderBoost - costPenalty - reasons.length * 10 + preferredBoost;
+    let latencyPenalty = 0;
+    const maxLatencyMs = constraints.maxLatencyMs;
+    if (typeof maxLatencyMs === "number" && maxLatencyMs > 0) {
+      const tierMs = LATENCY_TIER_MS[latencyTierOf(profile)];
+      if (tierMs > maxLatencyMs) {
+        const overage = (tierMs - maxLatencyMs) / maxLatencyMs;
+        latencyPenalty = Math.min(LATENCY_OVERAGE_WEIGHT * overage, LATENCY_PENALTY_CAP);
+      }
+    }
+    let qualityGatePenalty = 0;
+    if (constraints.structuredOutput) {
+      const schemaWeak = effectiveConventions(profile).some(
+        (c) => c.archetype === ir.intent.archetype && c.structuredOutputHint === "avoid"
+      );
+      if (schemaWeak) qualityGatePenalty = QUALITY_GATE_PENALTY;
+    }
+    const rank = qualityScore + callerOrderBoost - costPenalty - reasons.length * 10 + preferredBoost - latencyPenalty - qualityGatePenalty;
     scores.push({
       modelId,
       estimatedCostUsd,
@@ -330,6 +846,23 @@ function passScoreTargets(ir, opts) {
         description: `Model ${modelId} rank boosted by CompilePolicy.preferredModels`
       });
     }
+    if (latencyPenalty > 0) {
+      const tier = latencyTierOf(profile);
+      policyMutations.push({
+        id: `latency-downrank-${modelId}`,
+        source: "latency_guard",
+        passName: "score_targets",
+        description: `Model ${modelId} rank down ${latencyPenalty.toFixed(2)} \u2014 latency tier '${tier}' (~${LATENCY_TIER_MS[tier]}ms) exceeds constraints.maxLatencyMs (${maxLatencyMs}ms)`
+      });
+    }
+    if (qualityGatePenalty > 0) {
+      policyMutations.push({
+        id: `quality-gate-structured-${modelId}`,
+        source: "quality_gate",
+        passName: "score_targets",
+        description: `Model ${modelId} gated below the quality floor for archetype '${ir.intent.archetype}' \u2014 declared structuredOutput + kgauto convention flags it schema-weak for this contract (structuredOutputHint:'avoid'). Down-ranked out of leadership; retained as graceful fallback only.`
+      });
+    }
   }
   return { value: scores, mutations: policyMutations };
 }
@@ -356,6 +889,175 @@ function simpleHash(s) {
   }
   return (h >>> 0).toString(36);
 }
+function resolveConventionsForProfile(profile) {
+  const own = profile.archetypeConventions ?? [];
+  const family = profile.family ?? deriveFamilyFromModelId(profile.id);
+  if (!family) return own;
+  return own;
+}
+function applyArchetypeConvention(promptText, archetype, family) {
+  if (typeof promptText !== "string" || promptText.length === 0) return promptText;
+  const repId = familyRepId(family);
+  if (!repId) return promptText;
+  const profile = tryGetProfile(repId);
+  if (!profile || !profile.archetypeConventions) return promptText;
+  const conventions = profile.archetypeConventions.filter((c) => c.archetype === archetype);
+  if (conventions.length === 0) return promptText;
+  let next = promptText;
+  for (const c of conventions) {
+    if (c.promptPrefix) {
+      if (!next.startsWith(c.promptPrefix)) {
+        next = c.promptPrefix + next;
+      }
+    }
+    if (c.promptSuffix) {
+      if (!next.endsWith(c.promptSuffix)) {
+        next = next + c.promptSuffix;
+      }
+    }
+  }
+  return next;
+}
+function familyRepId(family) {
+  switch (family) {
+    case "deepseek-reasoner":
+      return "deepseek-v4-pro";
+    case "deepseek-chat":
+      return "deepseek-v4-flash";
+    default:
+      return void 0;
+  }
+}
+function passApplyConventions(ir, profile) {
+  const mutations = [];
+  const cliffWarnings = [];
+  const structuredOutputHints = [];
+  const own = profile.archetypeConventions ?? [];
+  let effective = own;
+  if (effective.length === 0) {
+    const family2 = profile.family ?? deriveFamilyFromModelId(profile.id);
+    if (family2) {
+      const repId = familyRepId(family2);
+      if (repId && repId !== profile.id) {
+        const repProfile = tryGetProfile(repId);
+        if (repProfile && repProfile.archetypeConventions) {
+          effective = repProfile.archetypeConventions;
+        }
+      }
+    }
+  }
+  if (effective.length === 0) {
+    return {
+      value: { ir, cliffWarnings, structuredOutputHints },
+      mutations
+    };
+  }
+  const archetype = ir.intent.archetype;
+  const matching = effective.filter((c) => c.archetype === archetype);
+  if (matching.length === 0) {
+    return {
+      value: { ir, cliffWarnings, structuredOutputHints },
+      mutations
+    };
+  }
+  const family = profile.family ?? deriveFamilyFromModelId(profile.id) ?? "unknown";
+  let nextIR = ir;
+  for (const convention of matching) {
+    let touched = false;
+    if (convention.promptPrefix) {
+      const sections = nextIR.sections ?? [];
+      const alreadyPresent = sections.some(
+        (s) => s.text.includes(convention.promptPrefix)
+      );
+      if (!alreadyPresent) {
+        const prefixSection = {
+          id: `convention-prefix-${family}-${archetype}`,
+          text: convention.promptPrefix
+        };
+        nextIR = { ...nextIR, sections: [prefixSection, ...sections] };
+        touched = true;
+      }
+    }
+    if (convention.promptSuffix) {
+      const history = nextIR.history ?? [];
+      let lastUserIdx = -1;
+      for (let i = history.length - 1; i >= 0; i--) {
+        if (history[i]?.role === "user") {
+          lastUserIdx = i;
+          break;
+        }
+      }
+      if (lastUserIdx >= 0) {
+        const target = history[lastUserIdx];
+        if (!target.content.endsWith(convention.promptSuffix)) {
+          const newHistory = history.slice();
+          newHistory[lastUserIdx] = {
+            ...target,
+            content: target.content + convention.promptSuffix
+          };
+          nextIR = { ...nextIR, history: newHistory };
+          touched = true;
+        }
+      } else if (nextIR.currentTurn && nextIR.currentTurn.role === "user") {
+        const target = nextIR.currentTurn;
+        if (!target.content.endsWith(convention.promptSuffix)) {
+          nextIR = {
+            ...nextIR,
+            currentTurn: {
+              ...target,
+              content: target.content + convention.promptSuffix
+            }
+          };
+          touched = true;
+        }
+      } else {
+        nextIR = {
+          ...nextIR,
+          currentTurn: {
+            role: "user",
+            content: convention.promptSuffix.trim()
+          }
+        };
+        touched = true;
+      }
+    }
+    if (convention.structuredOutputHint) {
+      const wantsStructured = !!nextIR.constraints?.structuredOutput;
+      const shouldSurface = convention.structuredOutputHint === "avoid" && wantsStructured || convention.structuredOutputHint === "enforce" && !wantsStructured;
+      if (shouldSurface) {
+        structuredOutputHints.push({
+          archetype,
+          hint: convention.structuredOutputHint,
+          reason: convention.reason
+        });
+        if (convention.cliffWarning) {
+          cliffWarnings.push(`${profile.id}: ${convention.cliffWarning}`);
+        }
+        touched = true;
+      }
+    }
+    if (convention.cliffWarning && !convention.structuredOutputHint) {
+      const toolCount = nextIR.tools?.length ?? 0;
+      const thresholdOk = convention.whenToolCountAtLeast === void 0 || toolCount >= convention.whenToolCountAtLeast;
+      if (thresholdOk) {
+        cliffWarnings.push(`${profile.id}: ${convention.cliffWarning}`);
+        touched = true;
+      }
+    }
+    if (touched) {
+      mutations.push({
+        id: `apply-convention-${family}-${archetype}`,
+        source: "archetype_convention",
+        passName: "apply_conventions",
+        description: `${profile.id}: applied ${family}-family convention for archetype=${archetype} \u2014 ${convention.reason}`
+      });
+    }
+  }
+  return {
+    value: { ir: nextIR, cliffWarnings, structuredOutputHints },
+    mutations
+  };
+}
 
 // src/lower.ts
 function lower(ir, profile, hints = {}) {
@@ -374,7 +1076,7 @@ function lower(ir, profile, hints = {}) {
 }
 function lowerAnthropic(ir, profile, hints) {
   const systemBlocks = buildAnthropicSystemBlocks(ir.sections, profile);
-  const history = ir.history ?? [];
+  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);
@@ -383,6 +1085,7 @@ function lowerAnthropic(ir, profile, hints) {
   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",
@@ -390,7 +1093,12 @@ 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,
@@ -519,7 +1227,7 @@ 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 ?? [];
+  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 {
@@ -581,9 +1289,10 @@ function lowerOpenAI(ir, profile, hints) {
       content: ir.currentTurn.parts ?? ir.currentTurn.content
     });
   }
-  const history = ir.history ?? [];
+  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",
@@ -591,7 +1300,8 @@ 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,
@@ -624,7 +1334,7 @@ function lowerDeepSeek(ir, profile) {
       content: ir.currentTurn.parts ?? ir.currentTurn.content
     });
   }
-  const history = ir.history ?? [];
+  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 {
@@ -668,102 +1378,1126 @@ function setNestedField(obj, path, value) {
   cursor[parts[parts.length - 1]] = value;
 }
 
-// src/compile.ts
-var counter = 0;
-function makeHandle() {
-  counter = (counter + 1) % 1e6;
-  return `c${Date.now().toString(36)}-${counter.toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+// 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 compile(ir, opts = {}) {
-  const resolver = opts.profileResolver ?? getProfile;
-  validateIR(ir);
-  const sliced = passSlice(ir);
-  const deduped = passDedupe(sliced.value);
-  const toolFiltered = passToolRelevance(deduped.value, {
-    threshold: opts.toolRelevanceThreshold
-  });
-  const compressed = passCompressHistory(toolFiltered.value, {
-    summarizeOlderThan: opts.compressHistoryAfter
-  });
-  let workingIR = compressed.value;
-  const accumulatedMutations = [
-    ...sliced.mutations,
-    ...deduped.mutations,
-    ...toolFiltered.mutations,
-    ...compressed.mutations
-  ];
-  const inputTokens = estimateInputTokens(workingIR);
-  const scores = passScoreTargets(workingIR, {
-    estimatedInputTokens: inputTokens,
-    profilesById: resolver,
-    policy: opts.policy
-  });
-  accumulatedMutations.push(...scores.mutations);
-  const target = pickTarget(workingIR, scores.value);
-  if (!target) {
-    throw new Error(
-      `compile(): no allowed model fits the request. Scores: ${JSON.stringify(scores.value, null, 2)}`
-    );
+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);
   }
-  const profile = resolver(target.modelId);
-  const fallbackChain = scores.value.filter((s) => s.modelId !== target.modelId && s.fits).sort((a, b) => b.rank - a.rank).map((s) => s.modelId);
-  const cliffs = passApplyCliffs(workingIR, profile, inputTokens);
-  workingIR = cliffs.value.ir;
-  accumulatedMutations.push(...cliffs.mutations);
-  const lowered = lower(workingIR, profile, {
-    forceThinkingZero: cliffs.value.loweringHints.forceThinkingZero,
-    forceTerseOutput: cliffs.value.loweringHints.forceTerseOutput
-  });
-  validateFinalFit(workingIR, profile, inputTokens);
-  const handle = makeHandle();
-  const finalShape = computeShape(workingIR, inputTokens);
-  const _learningKey = learningKey(ir.intent.archetype, profile.id, finalShape);
-  return {
-    handle,
-    target: profile.id,
-    provider: profile.provider,
-    request: lowered.request,
-    tokensIn: inputTokens,
-    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,
-      historyCacheableTokens: lowered.diagnostics.historyCacheableTokens
-    }
-  };
+  return out;
 }
-function validateIR(ir) {
-  if (!ir.appId) throw new Error("compile(): ir.appId is required");
-  if (!ir.intent || !ir.intent.archetype) {
-    throw new Error("compile(): ir.intent.archetype is required (use a dialect-v1 archetype)");
-  }
-  if (!Array.isArray(ir.models) || ir.models.length === 0) {
-    throw new Error("compile(): ir.models must be a non-empty array");
-  }
-  if (!Array.isArray(ir.sections)) {
-    throw new Error("compile(): ir.sections must be an array");
+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 pickTarget(ir, scores) {
-  if (ir.constraints?.forceModel) {
-    const forced = scores.find((s) => s.modelId === ir.constraints.forceModel);
-    if (forced && forced.fits) return forced;
-    if (forced) {
-      throw new Error(
-        `compile(): forceModel="${ir.constraints.forceModel}" does not fit: ${forced.rejectReasons.join("; ")}`
-      );
-    }
+function bundledArchetypePerf() {
+  const out = /* @__PURE__ */ new Map();
+  for (const profile of allProfiles()) {
+    if (profile.archetypePerf) out.set(profile.id, profile.archetypePerf);
   }
-  const fitting = scores.filter((s) => s.fits).sort((a, b) => b.rank - a.rank);
-  return fitting[0];
+  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/promote-ready-brain.ts
+function isRawPromoteReadyRow(x) {
+  if (!x || typeof x !== "object") return false;
+  const r = x;
+  return typeof r.intent_archetype === "string" && typeof r.family === "string" && typeof r.candidate_model === "string" && typeof r.current_model === "string" && typeof r.detected_at === "string";
+}
+function coerceNumber(v) {
+  if (typeof v === "number") return Number.isFinite(v) ? v : null;
+  if (typeof v === "string") {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+function mapRowsToFindings2(rows) {
+  const out = [];
+  for (const row of rows) {
+    if (!isRawPromoteReadyRow(row)) continue;
+    const sampleN = coerceNumber(row.sample_n);
+    const passRate = coerceNumber(row.judge_pass_rate);
+    const avgScore = coerceNumber(row.judge_avg_score);
+    if (sampleN === null || passRate === null || avgScore === null) continue;
+    out.push({
+      archetype: row.intent_archetype,
+      family: row.family,
+      candidateModel: row.candidate_model,
+      currentModel: row.current_model,
+      sampleN,
+      judgePassRate: passRate,
+      judgeAvgScore: avgScore,
+      costDeltaPct: coerceNumber(row.cost_delta_pct),
+      detectedAt: row.detected_at
+    });
+  }
+  return out;
+}
+var snapshots2 = /* @__PURE__ */ new Map();
+var runtime2;
+var warnedOnce2 = false;
+function isPromoteReadyBrainActive() {
+  return runtime2 !== void 0;
+}
+function loadPromoteReadyFindings(opts) {
+  const rt = runtime2;
+  if (!rt) return [];
+  const appId = opts.appId;
+  if (!appId) return [];
+  let snap = snapshots2.get(appId);
+  if (!snap) {
+    snap = { data: [], expiresAt: 0, refreshing: false };
+    snapshots2.set(appId, snap);
+  }
+  const now = Date.now();
+  const stale = snap.expiresAt <= now;
+  if (stale && !snap.refreshing) {
+    snap.refreshing = true;
+    void asyncRefresh2(rt, appId);
+  }
+  let rows = snap.data;
+  if (opts.archetype) {
+    rows = rows.filter((f) => f.archetype === opts.archetype);
+  }
+  if (opts.family) {
+    rows = rows.filter((f) => f.family === opts.family);
+  }
+  return rows;
+}
+var pendingRefreshes2 = /* @__PURE__ */ new Map();
+async function asyncRefresh2(rt, appId) {
+  const promise = doRefresh2(rt, appId);
+  pendingRefreshes2.set(appId, promise);
+  try {
+    await promise;
+  } finally {
+    if (pendingRefreshes2.get(appId) === promise) {
+      pendingRefreshes2.delete(appId);
+    }
+  }
+}
+async function doRefresh2(rt, appId) {
+  const url = `${rt.endpoint}?app_id=${encodeURIComponent(appId)}`;
+  let snap = snapshots2.get(appId);
+  if (!snap) {
+    snap = { data: [], expiresAt: 0, refreshing: false };
+    snapshots2.set(appId, snap);
+  }
+  try {
+    const res = await rt.fetchImpl(url, { method: "GET" });
+    if (!res.ok) {
+      throw new Error(`promote-ready ${res.status}: ${res.statusText}`);
+    }
+    const body = await res.json();
+    if (runtime2 !== rt) return;
+    const rows = Array.isArray(body) ? mapRowsToFindings2(body) : [];
+    snap.data = rows;
+    snap.expiresAt = Date.now() + rt.ttlMs;
+    snap.refreshing = false;
+  } catch (err) {
+    if (runtime2 !== rt) return;
+    snap.refreshing = false;
+    snap.expiresAt = Date.now() + rt.ttlMs;
+    if (!warnedOnce2) {
+      warnedOnce2 = true;
+      (rt.onError ?? defaultOnError2)(err);
+    }
+  }
+}
+function defaultOnError2(err) {
+  console.warn(
+    "[kgauto] promote-ready fetch failed (using empty fallback):",
+    err
+  );
+}
+function resolveFetchImpl(injected) {
+  return injected ?? ((...args) => globalThis.fetch(...args));
+}
+function normalizeEndpoint(endpoint) {
+  return endpoint.replace(/\/+$/, "");
+}
+async function markPromoteReadyHandled(opts) {
+  const {
+    appId,
+    archetype,
+    family,
+    resolution,
+    resolutionNote,
+    brainEndpoint,
+    brainJwt,
+    brainAnonKey,
+    fetch: injectedFetch
+  } = opts;
+  if (!appId) return { ok: false, reason: "app_id_required" };
+  if (!archetype) return { ok: false, reason: "archetype_required" };
+  if (!family) return { ok: false, reason: "family_required" };
+  if (resolution !== "promoted" && resolution !== "declined" && resolution !== "still-evaluating") {
+    return { ok: false, reason: "resolution_invalid" };
+  }
+  const doFetch = resolveFetchImpl(injectedFetch);
+  const base = normalizeEndpoint(brainEndpoint);
+  const url = `${base}/rest/v1/promote_ready_findings?app_id=eq.${encodeURIComponent(appId)}&intent_archetype=eq.${encodeURIComponent(archetype)}&family=eq.${encodeURIComponent(family)}&resolved_at=is.null`;
+  const patchBody = {
+    resolved_at: (/* @__PURE__ */ new Date()).toISOString(),
+    resolution
+  };
+  if (resolutionNote !== void 0) {
+    patchBody.resolution_note = resolutionNote;
+  }
+  let res;
+  try {
+    res = await doFetch(url, {
+      method: "PATCH",
+      headers: {
+        Authorization: `Bearer ${brainJwt}`,
+        apikey: brainAnonKey,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        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 (res.status === 401 || res.status === 403) {
+    return { ok: false, reason: "brain_auth_misconfig" };
+  }
+  if (res.status >= 500) {
+    return { ok: false, reason: "brain_unavailable" };
+  }
+  if (!res.ok) {
+    return { ok: false, reason: `patch_failed:${res.status}` };
+  }
+  return { ok: true };
+}
+
+// src/advisor-rules/promote-ready.ts
+var PROMOTE_READY_THRESHOLDS = {
+  minPassRate: 0.8,
+  minAvgScore: 4
+};
+function shouldFirePromoteReady(finding, resolvedPrimary) {
+  if (finding.currentModel !== resolvedPrimary) return false;
+  if (finding.judgePassRate < PROMOTE_READY_THRESHOLDS.minPassRate) return false;
+  if (finding.judgeAvgScore < PROMOTE_READY_THRESHOLDS.minAvgScore) return false;
+  return true;
+}
+function deriveFamilyLocal(modelId) {
+  if (modelId.startsWith("claude-opus-")) return "claude-opus";
+  if (modelId.startsWith("claude-sonnet-")) return "claude-sonnet";
+  if (modelId.startsWith("claude-haiku-")) return "claude-haiku";
+  if (/^gemini-.*-flash-lite/.test(modelId)) return "gemini-flash-lite";
+  if (/^gemini-.*-flash/.test(modelId)) return "gemini-flash";
+  if (/^gemini-.*-pro/.test(modelId)) return "gemini-pro";
+  if (/^deepseek-.*-pro/.test(modelId)) return "deepseek-reasoner";
+  if (modelId.startsWith("deepseek-")) return "deepseek-chat";
+  if (modelId.startsWith("gpt-")) return "openai-gpt";
+  return null;
+}
+function advisorRulePromoteReady(ctx) {
+  if (!isPromoteReadyBrainActive()) return [];
+  if (!ctx.appId) return [];
+  if (!ctx.resolvedPrimary) return [];
+  const family = deriveFamilyLocal(ctx.resolvedPrimary);
+  if (!family) return [];
+  const findings = loadPromoteReadyFindings({
+    appId: ctx.appId,
+    archetype: ctx.archetype,
+    family
+  });
+  if (findings.length === 0) return [];
+  const qualifying = findings.filter(
+    (f) => shouldFirePromoteReady(f, ctx.resolvedPrimary)
+  );
+  if (qualifying.length === 0) return [];
+  qualifying.sort((a, b) => {
+    if (a.judgeAvgScore !== b.judgeAvgScore) {
+      return b.judgeAvgScore - a.judgeAvgScore;
+    }
+    return b.judgePassRate - a.judgePassRate;
+  });
+  const top = qualifying[0];
+  const pctPass = Math.round(top.judgePassRate * 100);
+  const score = top.judgeAvgScore.toFixed(2);
+  let costClause = "";
+  if (top.costDeltaPct !== null) {
+    const sign = top.costDeltaPct < 0 ? "cheaper" : "more expensive";
+    const magnitude = Math.abs(top.costDeltaPct * 100).toFixed(1);
+    costClause = `, cost ${magnitude}% ${sign}`;
+  }
+  const message = `Probe found ${top.candidateModel} produces equivalent-or-better outputs vs ${top.currentModel} on ${top.sampleN} recent ${top.archetype} prompts (pass rate ${pctPass}%, avg score ${score}/5${costClause}). Consider promoting via markPromoteReadyHandled.`;
+  return [
+    {
+      level: "info",
+      code: "promote-ready",
+      message,
+      suggestion: `Migrate ${top.archetype} traffic from ${top.currentModel} to ${top.candidateModel}, then call markPromoteReadyHandled({ appId, archetype: '${top.archetype}', family: '${top.family}', resolution: 'promoted' }) to silence this advisory.`,
+      // alpha.36 architectural field — not a no-ai-needed case.
+      recommendedArchitecture: void 0,
+      docsUrl: "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#best-practice-advisories"
+    }
+  ];
+}
+
+// src/advisor-rules/consumer-on-stale-model.ts
+function isStaleStatus(v) {
+  return v === "legacy" || v === "deprecated";
+}
+function asString(v) {
+  return typeof v === "string" && v.length > 0 ? v : void 0;
+}
+function mapRowsToFindings3(rows) {
+  const out = [];
+  for (const raw of rows) {
+    if (!raw || typeof raw !== "object") continue;
+    const r = raw;
+    const archetype = asString(r.intent_archetype) ?? asString(r.applies_to_archetype);
+    const staleModel = asString(r.stale_model) ?? asString(r.applies_to_model);
+    const staleProvider = asString(r.stale_provider);
+    const recommendedModel = asString(r.recommended_model);
+    const family = asString(r.family);
+    const message = asString(r.message);
+    if (!archetype || !staleModel || !recommendedModel || !family || !message) {
+      continue;
+    }
+    if (!isStaleStatus(r.stale_status)) continue;
+    const row = {
+      archetype,
+      staleModel,
+      staleProvider: staleProvider ?? "unknown",
+      staleStatus: r.stale_status,
+      recommendedModel,
+      family,
+      message
+    };
+    const suggestion = asString(r.suggestion);
+    if (suggestion) row.suggestion = suggestion;
+    if (typeof r.observation_count === "number" && Number.isFinite(r.observation_count)) {
+      row.observationCount = r.observation_count;
+    }
+    out.push(row);
+  }
+  return out;
+}
+var snapshots3 = /* @__PURE__ */ new Map();
+var runtime3;
+var warnedOnce3 = false;
+var pendingRefreshes3 = /* @__PURE__ */ new Map();
+function isStaleModelFindingsBrainActive() {
+  return runtime3 !== void 0;
+}
+function getStaleModelFindings(opts) {
+  const rt = runtime3;
+  if (!rt) return [];
+  const appId = opts.appId;
+  if (!appId) return [];
+  let snap = snapshots3.get(appId);
+  if (!snap) {
+    snap = { data: [], expiresAt: 0, refreshing: false };
+    snapshots3.set(appId, snap);
+  }
+  const now = Date.now();
+  const stale = snap.expiresAt <= now;
+  if (stale && !snap.refreshing) {
+    snap.refreshing = true;
+    void asyncRefresh3(rt, appId);
+  }
+  if (opts.archetype) {
+    return snap.data.filter((f) => f.archetype === opts.archetype);
+  }
+  return snap.data;
+}
+async function asyncRefresh3(rt, appId) {
+  const promise = doRefresh3(rt, appId);
+  pendingRefreshes3.set(appId, promise);
+  try {
+    await promise;
+  } finally {
+    if (pendingRefreshes3.get(appId) === promise) {
+      pendingRefreshes3.delete(appId);
+    }
+  }
+}
+async function doRefresh3(rt, appId) {
+  const url = `${rt.endpoint}?app_id=${encodeURIComponent(appId)}`;
+  let snap = snapshots3.get(appId);
+  if (!snap) {
+    snap = { data: [], expiresAt: 0, refreshing: false };
+    snapshots3.set(appId, snap);
+  }
+  try {
+    const res = await rt.fetchImpl(url, { method: "GET" });
+    if (!res.ok) {
+      throw new Error(`stale-model findings ${res.status}: ${res.statusText}`);
+    }
+    const body = await res.json();
+    if (runtime3 !== rt) return;
+    const rows = Array.isArray(body) ? mapRowsToFindings3(body) : [];
+    snap.data = rows;
+    snap.expiresAt = Date.now() + rt.ttlMs;
+    snap.refreshing = false;
+  } catch (err) {
+    if (runtime3 !== rt) return;
+    snap.refreshing = false;
+    snap.expiresAt = Date.now() + rt.ttlMs;
+    if (!warnedOnce3) {
+      warnedOnce3 = true;
+      (rt.onError ?? defaultOnError3)(err);
+    }
+  }
+}
+function defaultOnError3(err) {
+  console.warn(
+    "[kgauto] stale-model findings fetch failed (using empty fallback):",
+    err
+  );
+}
+var CONSUMER_ON_STALE_MODEL_RULE_CODE = "consumer-on-stale-model";
+function advisorRuleConsumerOnStaleModel(ir) {
+  if (!isStaleModelFindingsBrainActive()) return [];
+  if (!ir.appId) return [];
+  const findings = getStaleModelFindings({
+    appId: ir.appId,
+    archetype: ir.intent.archetype
+  });
+  if (findings.length === 0) return [];
+  const ranked = [...findings].sort((a, b) => {
+    if (a.staleStatus !== b.staleStatus) {
+      return a.staleStatus === "deprecated" ? -1 : 1;
+    }
+    return a.staleModel.localeCompare(b.staleModel);
+  });
+  const top = ranked[0];
+  const extraCount = findings.length - 1;
+  const extraNote = extraCount > 0 ? ` (+ ${extraCount} more stale model${extraCount === 1 ? "" : "s"} for this archetype)` : "";
+  return [
+    {
+      level: "warn",
+      code: CONSUMER_ON_STALE_MODEL_RULE_CODE,
+      message: `${top.message}${extraNote}`,
+      suggestion: top.suggestion ?? `Migrate ${top.staleModel} \u2192 ${top.recommendedModel} for archetype "${top.archetype}". The newer model is the current latest in the "${top.family}" family; the stale one is ${top.staleStatus}.`,
+      recommendationType: "model-swap",
+      docsUrl: "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#best-practice-advisories"
+    }
+  ];
+}
+
+// src/archetype-fits.ts
+var ARCHETYPE_FAMILY_FITS = Object.freeze([
+  {
+    archetype: "plan",
+    betterFitFamily: "deepseek-reasoner",
+    reason: "Plan archetype is reasoning-shaped (multi-step chains, hypothesis-and-check, sub-goal decomposition) \u2014 exactly where reasoner-family models excel. Sonnet/Opus produce plans but at higher cost; reasoners produce equivalent-or-better plans at 7-17x lower cost at current promo pricing (deepseek-v4-pro $0.435/$0.87 per 1M promo through 2026-05-31 vs sonnet $3/$15).",
+    costGuidance: "substantially cheaper at current pricing (deepseek-v4-pro promo: ~7-17x cheaper than sonnet)"
+  },
+  {
+    archetype: "critique",
+    betterFitFamily: "deepseek-reasoner",
+    reason: "Critique archetype rewards epistemic humility and explicit reasoning \u2014 reasoner-family default behavior. Sonnet/Opus over-confident on critique tasks; reasoners surface uncertainty productively.",
+    costGuidance: "comparable or cheaper at current pricing"
+  }
+]);
+function findBetterFit(archetype, currentFamily) {
+  for (const fit of ARCHETYPE_FAMILY_FITS) {
+    if (fit.archetype !== archetype) continue;
+    if (fit.betterFitFamily === currentFamily) return null;
+    return fit;
+  }
+  return null;
+}
+
+// src/advisor-rules/cross-family-fit.ts
+function familyHasCurrentActiveModel(family) {
+  for (const profile of allProfiles()) {
+    const profileFamily = profile.family ?? deriveFamilyFromModelId(profile.id);
+    if (profileFamily !== family) continue;
+    if (profile.status !== "current") continue;
+    if (profile.active === false) continue;
+    return true;
+  }
+  return false;
+}
+function listCandidatesInFamily(family) {
+  const candidates = [];
+  for (const profile of allProfiles()) {
+    const profileFamily = profile.family ?? deriveFamilyFromModelId(profile.id);
+    if (profileFamily !== family) continue;
+    if (profile.status !== "current") continue;
+    if (profile.active === false) continue;
+    candidates.push(profile.id);
+    if (candidates.length >= 3) break;
+  }
+  return candidates;
+}
+function advisorRuleCrossFamilyFit(ctx) {
+  if (!ctx.resolvedPrimary) return [];
+  const currentFamily = deriveFamilyFromModelId(ctx.resolvedPrimary);
+  if (!currentFamily) return [];
+  const fit = findBetterFit(ctx.archetype, currentFamily);
+  if (!fit) return [];
+  if (!familyHasCurrentActiveModel(fit.betterFitFamily)) return [];
+  const candidates = listCandidatesInFamily(fit.betterFitFamily);
+  if (candidates.length === 0) return [];
+  const candidateStr = candidates.join(", ");
+  const message = `Your ${currentFamily} call on ${ctx.archetype} could shift to ${fit.betterFitFamily} \u2014 typically better quality + ${fit.costGuidance}. Suggested candidates: ${candidateStr}.`;
+  return [
+    {
+      level: "info",
+      code: "cross-family-fit-candidate",
+      ownership: "consumer-actionable",
+      message,
+      suggestion: `Swap the model literal in \`ir.models\` to one of: ${candidateStr}. Or call \`getRecommendedPrimary({ family: '${fit.betterFitFamily}', archetype: '${ctx.archetype}', fallback: { id: '${candidates[0]}', reason: 'cross-family-fit-recommendation' } })\` to let kgauto resolve to the current+active family member.`,
+      recommendationType: "model-swap",
+      docsUrl: "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#best-practice-advisories"
+    }
+  ];
+}
+
+// src/advisor.ts
+var QUALITY_FLOOR_FOR_RECOMMENDATION = 6;
+var TIER_DOWN_COST_RATIO = 0.5;
+var COST_MISMATCHED_CHOSEN_SCORE_CEILING = 7;
+var PRODUCER_OWNED_RULE_CODES = Object.freeze(
+  /* @__PURE__ */ new Set(["model-stale-evidence", "promote-ready"])
+);
+function deriveOwnership(code, selfDeclared) {
+  if (selfDeclared) return selfDeclared;
+  return PRODUCER_OWNED_RULE_CODES.has(code) ? "producer-owned" : "consumer-actionable";
+}
+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));
+  }
+  if (policy?.posture !== "locked") {
+    out.push(...detectStaleExclusionCandidate(ir));
+  }
+  if (policy?.posture !== "locked" && ir.appId) {
+    out.push(
+      ...advisorRulePromoteReady({
+        appId: ir.appId,
+        archetype: ir.intent.archetype,
+        resolvedPrimary: profile.id
+      })
+    );
+    out.push(...advisorRuleConsumerOnStaleModel(ir));
+  }
+  if (policy?.posture !== "locked") {
+    out.push(
+      ...advisorRuleCrossFamilyFit({
+        archetype: ir.intent.archetype,
+        resolvedPrimary: profile.id
+      })
+    );
+  }
+  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"
+    }
+  ];
+}
+function detectStaleExclusionCandidate(ir) {
+  if (!isExclusionFindingsBrainActive()) return [];
+  if (!ir.appId) return [];
+  const findings = getStaleExclusionFindings({
+    appId: ir.appId,
+    archetype: ir.intent.archetype
+  });
+  if (findings.length === 0) return [];
+  const ranked = [...findings].sort((a, b) => {
+    const sa = a.estimatedSavingsUsd30d ?? -Infinity;
+    const sb = b.estimatedSavingsUsd30d ?? -Infinity;
+    if (sa !== sb) return sb - sa;
+    return confidenceRank(b.confidence) - confidenceRank(a.confidence);
+  });
+  const top = ranked[0];
+  const extraCount = findings.length - 1;
+  const extraNote = extraCount > 0 ? ` (+ ${extraCount} more excluded model${extraCount === 1 ? "" : "s"} for this archetype)` : "";
+  return [
+    {
+      level: "info",
+      code: "stale-exclusion-candidate",
+      message: `${top.message}${extraNote}`,
+      suggestion: top.suggestion,
+      recommendationType: "tier-down",
+      docsUrl: "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#best-practice-advisories"
+    }
+  ];
+}
+function confidenceRank(c) {
+  if (c === "high") return 3;
+  if (c === "medium") return 2;
+  return 1;
+}
+
+// src/translator.ts
+var TRANSLATOR_FLOOR = ARCHETYPE_FLOOR_DEFAULT;
+var RULE_SEQUENTIAL_TOOL_CLIFF = "sequential-tool-cliff-below-floor";
+var RULE_NARRATION_DRIFT_ANTHROPIC = "narration-drift-anthropic";
+var RULE_NARRATION_THINKING_LEAK_DEEPSEEK = "narration-thinking-leak-deepseek";
+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.";
+var NARRATION_DRIFT_ANTHROPIC_PREAMBLE = "Output ONLY the requested content. Do not narrate your thought process. Each line \u2264 12 words.";
+var NARRATION_THINKING_LEAK_DEEPSEEK_PREAMBLE = "Reasoning is internal. Output ONLY the requested content; do not emit <thinking> blocks or internal monologue as user-facing text.";
+function matchRule(kind, profile, archetype) {
+  if (kind === "tool_call_contract") {
+    if (!profile.archetypePerf) return null;
+    const archetypeScore = profile.archetypePerf[archetype];
+    if (typeof archetypeScore !== "number" || archetypeScore >= TRANSLATOR_FLOOR) {
+      return null;
+    }
+    return {
+      id: RULE_SEQUENTIAL_TOOL_CLIFF,
+      preamble: SEQUENTIAL_TOOL_PREAMBLE,
+      wireOverrides: { parallelToolCalls: false }
+    };
+  }
+  if (kind === "narration_contract") {
+    if (profile.provider === "anthropic") {
+      return {
+        id: RULE_NARRATION_DRIFT_ANTHROPIC,
+        preamble: NARRATION_DRIFT_ANTHROPIC_PREAMBLE
+      };
+    }
+    if (profile.provider === "deepseek") {
+      return {
+        id: RULE_NARRATION_THINKING_LEAK_DEEPSEEK,
+        preamble: NARRATION_THINKING_LEAK_DEEPSEEK_PREAMBLE
+      };
+    }
+    return null;
+  }
+  return null;
+}
+function applySectionRewrites(args) {
+  const { ir, profile, archetype } = args;
+  if (!Array.isArray(ir.sections) || ir.sections.length === 0) {
+    return { rewrittenIR: ir, rewrites: [] };
+  }
+  const rewrites = [];
+  const newSections = ir.sections.map((section) => {
+    if (!section.kind || section.kind === "arbitrary") return section;
+    const rule = matchRule(section.kind, profile, archetype);
+    if (!rule) return section;
+    const originalText = section.text;
+    const transformedText = `${rule.preamble}
+
+${originalText}`;
+    rewrites.push({
+      sectionId: section.id,
+      kind: section.kind,
+      rule: rule.id,
+      originalText,
+      transformedText,
+      ...rule.wireOverrides ? { wireOverrides: rule.wireOverrides } : {}
+    });
+    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() {
+  counter = (counter + 1) % 1e6;
+  return `c${Date.now().toString(36)}-${counter.toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+}
+function compile(ir, opts = {}) {
+  const resolver = opts.profileResolver ?? getProfile;
+  validateIR(ir);
+  ir = resolveModelEntries(ir);
+  const sliced = passSlice(ir);
+  const deduped = passDedupe(sliced.value);
+  const toolFiltered = passToolRelevance(deduped.value, {
+    threshold: opts.toolRelevanceThreshold
+  });
+  const compressed = passCompressHistory(toolFiltered.value, {
+    summarizeOlderThan: opts.compressHistoryAfter,
+    summarizeAboveTokens: opts.compressHistoryAboveTokens
+  });
+  let workingIR = compressed.value;
+  const accumulatedMutations = [
+    ...sliced.mutations,
+    ...deduped.mutations,
+    ...toolFiltered.mutations,
+    ...compressed.mutations
+  ];
+  const inputTokens = estimateInputTokens(workingIR);
+  const scores = passScoreTargets(workingIR, {
+    estimatedInputTokens: inputTokens,
+    profilesById: resolver,
+    policy: opts.policy
+  });
+  accumulatedMutations.push(...scores.mutations);
+  const target = pickTarget(workingIR, scores.value);
+  if (!target) {
+    throw new Error(
+      `compile(): no allowed model fits the request. Scores: ${JSON.stringify(scores.value, null, 2)}`
+    );
+  }
+  const profile = resolver(target.modelId);
+  const fallbackChain = scores.value.filter((s) => s.modelId !== target.modelId && s.fits).sort((a, b) => b.rank - a.rank).map((s) => s.modelId);
+  const cliffs = passApplyCliffs(workingIR, profile, inputTokens);
+  workingIR = cliffs.value.ir;
+  accumulatedMutations.push(...cliffs.mutations);
+  const conventions = passApplyConventions(workingIR, profile);
+  workingIR = conventions.value.ir;
+  accumulatedMutations.push(...conventions.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,
+    wireOverrides
+  });
+  validateFinalFit(workingIR, profile, inputTokens);
+  const handle = makeHandle();
+  const finalShape = computeShape(workingIR, inputTokens);
+  const _learningKey = learningKey(ir.intent.archetype, profile.id, finalShape);
+  const historyCacheMarkIndex = computeHistoryCacheMarkIndex(workingIR);
+  const systemMessages = buildSystemMessages(workingIR, profile.provider);
+  const systemCacheMarkIndex = lastCacheableSystemIndex(systemMessages);
+  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,
+    // alpha.33 — see top-of-block comment.
+    historyCacheMarkIndex,
+    systemCacheMarkIndex,
+    // alpha.43 — cliff-style warnings emitted by passApplyConventions.
+    // Merge convention-pass cliffWarnings with any cliff-guard quality
+    // warnings the cliff pass surfaced (the same shape — informational
+    // text the consumer can route on without changing behavior).
+    cliffWarnings: [
+      ...cliffs.value.loweringHints.qualityWarning ?? [],
+      ...conventions.value.cliffWarnings
+    ]
+  };
+  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 rawAdvisories = 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
+    }
+  );
+  const advisories = rawAdvisories.map((a) => ({
+    ...a,
+    kgautoRequestId: handle,
+    ownership: deriveOwnership(a.code, a.ownership)
+  }));
+  return {
+    handle,
+    target: profile.id,
+    provider: profile.provider,
+    request: lowered.request,
+    tokensIn: inputTokens,
+    estimatedCostUsd: target.estimatedCostUsd,
+    mutationsApplied: accumulatedMutations,
+    fallbackChain,
+    advisories,
+    diagnostics,
+    sectionRewritesApplied,
+    wireOverrides,
+    systemMessages
+  };
+}
+function computeHistoryCacheMarkIndex(ir) {
+  const policy = ir.historyCachePolicy;
+  if (!policy || policy.strategy === "none") return void 0;
+  const historyLen = ir.history?.length ?? 0;
+  if (historyLen === 0) return void 0;
+  if (policy.strategy === "all-but-latest") {
+    return historyLen - 1;
+  }
+  if (policy.strategy === "fixed-suffix") {
+    const idx = historyLen - 1 - policy.suffix;
+    if (idx < 0) return void 0;
+    return idx;
+  }
+  return void 0;
+}
+function buildSystemMessages(ir, provider) {
+  const sections = ir.sections;
+  if (!sections || sections.length === 0) return [];
+  return sections.map((s) => {
+    const base = { role: "system", content: s.text };
+    if (provider === "anthropic" && s.cacheable) {
+      base.providerOptions = { anthropic: { cacheControl: { type: "ephemeral" } } };
+    }
+    return base;
+  });
+}
+function lastCacheableSystemIndex(systemMessages) {
+  for (let i = systemMessages.length - 1; i >= 0; i--) {
+    const entry = systemMessages[i];
+    if (entry && entry.providerOptions?.anthropic?.cacheControl) {
+      return i;
+    }
+  }
+  return void 0;
+}
+function validateIR(ir) {
+  if (!ir.appId) throw new Error("compile(): ir.appId is required");
+  if (!ir.intent || !ir.intent.archetype) {
+    throw new Error("compile(): ir.intent.archetype is required (use a dialect-v1 archetype)");
+  }
+  if (!Array.isArray(ir.models) || ir.models.length === 0) {
+    throw new Error("compile(): ir.models must be a non-empty array");
+  }
+  if (!Array.isArray(ir.sections)) {
+    throw new Error("compile(): ir.sections must be an array");
+  }
+}
+function resolveModelEntries(ir) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of ir.models) {
+    let id;
+    if (typeof entry === "string") {
+      id = entry;
+    } else if (entry && typeof entry === "object" && "family" in entry) {
+      id = resolveFamilyEntry(entry.family, {
+        archetype: ir.intent.archetype,
+        appId: ir.appId
+      });
+    } else {
+      throw new Error(
+        `compile(): ir.models entry must be a string or { family: string }; got ${JSON.stringify(entry)}`
+      );
+    }
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.push(id);
+  }
+  return { ...ir, models: out };
+}
+function pickTarget(ir, scores) {
+  if (ir.constraints?.forceModel) {
+    const forced = scores.find((s) => s.modelId === ir.constraints.forceModel);
+    if (forced && forced.fits) return forced;
+    if (forced) {
+      throw new Error(
+        `compile(): forceModel="${ir.constraints.forceModel}" does not fit: ${forced.rejectReasons.join("; ")}`
+      );
+    }
+  }
+  const fitting = scores.filter((s) => s.fits).sort((a, b) => b.rank - a.rank);
+  return fitting[0];
 }
 function validateFinalFit(ir, profile, tokens) {
   if (tokens > profile.maxContextTokens) {
@@ -778,14 +2512,103 @@ 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);
+  } else {
+    configureBrainQuery({
+      endpoint,
+      configEndpoint: bq.configEndpoint,
+      ttlMs: bq.cacheTtlMs ?? 3e5,
+      fetchImpl: config.fetchImpl ?? fetch,
+      enabledTables,
+      onError: config.onError
+    });
+  }
+  if (bq.findingsExclusions !== false) {
+    configureExclusionFindingsBrain({
+      endpoint: bq.findingsEndpoint ?? DEFAULT_FINDINGS_ENDPOINT,
+      ttlMs: bq.cacheTtlMs ?? 3e5,
+      fetchImpl: config.fetchImpl ?? fetch,
+      onError: config.onError
+    });
+  } else {
+    configureExclusionFindingsBrain(void 0);
+  }
 }
 function clearBrain() {
   activeConfig = void 0;
+  configureBrainQuery(void 0);
+  configureExclusionFindingsBrain(void 0);
 }
 var compileRegistry = /* @__PURE__ */ new Map();
 var REGISTRY_MAX_ENTRIES = 1e4;
@@ -812,6 +2635,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,
@@ -821,10 +2647,35 @@ function registerCompile(appId, archetype, ir, result) {
     learningKey: learningKey(archetype, result.target, shape),
     estimatedTokensIn: tokens,
     mutationsApplied: result.mutationsApplied.map((m) => m.id),
+    // 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
+    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);
@@ -835,11 +2686,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)
@@ -848,8 +2710,31 @@ 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 ?? defaultOnError4)(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);
+      (config.onError ?? defaultOnError4)(err);
     }
   };
   if (config.sync) {
@@ -858,7 +2743,7 @@ async function record(input) {
     void send();
   }
 }
-function defaultOnError(err) {
+function defaultOnError4(err) {
   console.warn("[kgauto] brain record failed:", err);
 }
 function buildPayload(input, reg) {
@@ -868,6 +2753,8 @@ function buildPayload(input, reg) {
   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,
@@ -896,34 +2783,477 @@ function buildPayload(input, reg) {
     cache_creation_input_tokens: input.cacheCreationInputTokens,
     cost_usd_actual: costUsdActual,
     ttft_ms: input.ttftMs,
-    history_cacheable_tokens: reg?.historyCacheableTokens
+    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;
 }
-
-// src/ir.ts
-var CallError = class extends Error {
-  attempts;
-  lastErrorCode;
-  lastStatus;
-  constructor(message, attempts, lastStatus, lastErrorCode) {
-    super(message);
-    this.name = "CallError";
-    this.attempts = attempts;
-    this.lastStatus = lastStatus;
-    this.lastErrorCode = lastErrorCode;
+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 ?? defaultOnError4)(err);
+        return { ok: false, reason: "persistence_failed" };
+      }
+      return { ok: true };
+    } catch (err) {
+      (config.onError ?? defaultOnError4)(err);
+      return { ok: false, reason: "persistence_failed" };
+    }
+  };
+  if (config.sync) {
+    return send();
+  }
+  void send();
+  return { ok: true };
+}
+function isBrainSync() {
+  return activeConfig?.sync === true;
+}
+function buildShadowProbeRow(input) {
+  return {
+    app_id: input.appId,
+    intent_archetype: input.archetype,
+    family: input.family,
+    candidate_model: input.candidateModel,
+    current_model: input.currentModel,
+    prompt_hash: input.promptHash,
+    current_response: input.currentResponsePreview ?? null,
+    candidate_response: input.candidateResponsePreview ?? null,
+    judge_verdict: null,
+    judge_score: null,
+    tokens_current_in: input.tokensCurrentIn ?? null,
+    tokens_current_out: input.tokensCurrentOut ?? null,
+    tokens_candidate_in: input.tokensCandidateIn ?? null,
+    tokens_candidate_out: input.tokensCandidateOut ?? null,
+    latency_current_ms: input.latencyCurrentMs ?? null,
+    latency_candidate_ms: input.latencyCandidateMs ?? null,
+    // Full IR was replayed (not a truncated preview), so fidelity is 1.0 — the
+    // prompt-fidelity guard never fires on these rows.
+    prompt_fidelity: 1,
+    replay_source: "inline-full-ir",
+    // alpha — migration 029. 'completed' is the default completed-probe shape;
+    // diagnostic rows (aborted/skipped) pass the explicit class.
+    outcome: input.outcome ?? "completed"
+  };
+}
+async function recordShadowProbe(input) {
+  if (!activeConfig) return;
+  const config = activeConfig;
+  const fetchFn = config.fetchImpl ?? fetch;
+  const row = buildShadowProbeRow(input);
+  const send = async () => {
+    try {
+      const res = await fetchFn(`${config.endpoint}/probe_outcomes`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Prefer: "return=minimal",
+          ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}
+        },
+        body: JSON.stringify(row)
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "<no body>");
+        throw new Error(`brain probe_outcomes ${res.status}: ${text}`);
+      }
+    } catch (err) {
+      (config.onError ?? defaultOnError4)(err);
+    }
+  };
+  if (config.sync) {
+    await send();
+  } else {
+    void send();
+  }
+}
+
+// src/ir.ts
+var CallError = class extends Error {
+  attempts;
+  lastErrorCode;
+  lastStatus;
+  constructor(message, attempts, lastStatus, lastErrorCode) {
+    super(message);
+    this.name = "CallError";
+    this.attempts = attempts;
+    this.lastStatus = lastStatus;
+    this.lastErrorCode = lastErrorCode;
+  }
+};
+
+// src/streaming.ts
+var ANTHROPIC_URL = "https://api.anthropic.com/v1/messages";
+async function streamAnthropic(request, apiKey, opts) {
+  const { provider: _provider, ...body } = request;
+  const fetchFn = opts.fetchImpl ?? fetch;
+  let res;
+  try {
+    res = await fetchFn(ANTHROPIC_URL, {
+      method: "POST",
+      headers: {
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01",
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({ ...body, stream: true })
+    });
+  } catch (err) {
+    return retryableError(0, "network_error", String(err), null);
+  }
+  if (!res.ok) {
+    const errBody = await res.json().catch(() => ({}));
+    return classifyHttpError(res.status, errBody);
+  }
+  let text = "";
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cacheReadTokens;
+  let cacheCreatedTokens;
+  let stopReason;
+  const toolBlocks = /* @__PURE__ */ new Map();
+  try {
+    await parseSSEStream(res, (event) => {
+      if (!event.data) return;
+      let payload;
+      try {
+        payload = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+      const type = payload.type;
+      if (type === "message_start") {
+        const msg = payload.message;
+        const usage = msg?.usage;
+        if (usage) {
+          inputTokens = usage.input_tokens ?? 0;
+          outputTokens = usage.output_tokens ?? 0;
+          if (typeof usage.cache_read_input_tokens === "number")
+            cacheReadTokens = usage.cache_read_input_tokens;
+          if (typeof usage.cache_creation_input_tokens === "number")
+            cacheCreatedTokens = usage.cache_creation_input_tokens;
+        }
+        return;
+      }
+      if (type === "content_block_start") {
+        const p = payload;
+        const idx = p.index ?? 0;
+        const block = p.content_block;
+        if (block?.type === "tool_use" && block.id && block.name) {
+          toolBlocks.set(idx, { id: block.id, name: block.name, argsJson: "" });
+        }
+        return;
+      }
+      if (type === "content_block_delta") {
+        const p = payload;
+        const delta = p.delta;
+        if (!delta) return;
+        if (delta.type === "text_delta" && typeof delta.text === "string") {
+          text += delta.text;
+          opts.onChunk(delta.text);
+        } else if (delta.type === "input_json_delta" && typeof delta.partial_json === "string") {
+          const idx = p.index ?? 0;
+          const tool = toolBlocks.get(idx);
+          if (tool) tool.argsJson += delta.partial_json;
+        }
+        return;
+      }
+      if (type === "message_delta") {
+        const p = payload;
+        if (p.delta?.stop_reason) stopReason = p.delta.stop_reason;
+        if (typeof p.usage?.output_tokens === "number") outputTokens = p.usage.output_tokens;
+        return;
+      }
+    });
+  } catch (err) {
+    return retryableError(0, "stream_interrupted", String(err), null);
+  }
+  const toolCalls = Array.from(toolBlocks.values()).map((b) => ({
+    id: b.id,
+    name: b.name,
+    args: tryParseJson(b.argsJson) ?? {}
+  }));
+  const tokens = {
+    input: inputTokens,
+    output: outputTokens,
+    total: inputTokens + outputTokens,
+    cached: cacheReadTokens,
+    cacheCreated: cacheCreatedTokens
+  };
+  const response = {
+    text,
+    structuredOutput: null,
+    toolCalls,
+    tokens,
+    finishReason: stopReason,
+    raw: { streamed: true, provider: "anthropic" }
+  };
+  return { ok: true, status: res.status, response };
+}
+async function streamOpenAILike(url, request, apiKey, providerLabel, opts) {
+  const { provider: _provider, ...body } = request;
+  const fetchFn = opts.fetchImpl ?? fetch;
+  const reqBody = {
+    ...body,
+    stream: true,
+    stream_options: {
+      ...body.stream_options ?? {},
+      include_usage: true
+    }
+  };
+  let res;
+  try {
+    res = await fetchFn(url, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${apiKey}`,
+        "content-type": "application/json"
+      },
+      body: JSON.stringify(reqBody)
+    });
+  } catch (err) {
+    return retryableError(0, "network_error", String(err), null);
+  }
+  if (!res.ok) {
+    const errBody = await res.json().catch(() => ({}));
+    return classifyHttpError(res.status, errBody);
+  }
+  let text = "";
+  let finishReason;
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let totalTokens;
+  let cachedTokens;
+  const toolBuffers = /* @__PURE__ */ new Map();
+  try {
+    await parseSSEStream(res, (event) => {
+      if (!event.data) return;
+      if (event.data === "[DONE]") return;
+      let payload;
+      try {
+        payload = JSON.parse(event.data);
+      } catch {
+        return;
+      }
+      const choices = payload.choices;
+      if (choices && choices.length > 0) {
+        const choice = choices[0];
+        const deltaContent = choice.delta?.content;
+        if (typeof deltaContent === "string" && deltaContent.length > 0) {
+          text += deltaContent;
+          opts.onChunk(deltaContent);
+        }
+        const toolDeltas = choice.delta?.tool_calls;
+        if (toolDeltas) {
+          for (const tcDelta of toolDeltas) {
+            const idx = tcDelta.index ?? 0;
+            let buf = toolBuffers.get(idx);
+            if (!buf) {
+              buf = { id: tcDelta.id ?? `tc-${idx}`, name: "", argsJson: "" };
+              toolBuffers.set(idx, buf);
+            }
+            if (tcDelta.id) buf.id = tcDelta.id;
+            if (tcDelta.function?.name) buf.name += tcDelta.function.name;
+            if (tcDelta.function?.arguments) buf.argsJson += tcDelta.function.arguments;
+          }
+        }
+        if (choice.finish_reason) finishReason = choice.finish_reason;
+      }
+      const usage = payload.usage;
+      if (usage) {
+        if (typeof usage.prompt_tokens === "number") inputTokens = usage.prompt_tokens;
+        if (typeof usage.completion_tokens === "number") outputTokens = usage.completion_tokens;
+        if (typeof usage.total_tokens === "number") totalTokens = usage.total_tokens;
+        const details = usage.prompt_tokens_details;
+        if (typeof details?.cached_tokens === "number") cachedTokens = details.cached_tokens;
+      }
+    });
+  } catch (err) {
+    return retryableError(0, "stream_interrupted", String(err), null);
+  }
+  const toolCalls = Array.from(toolBuffers.values()).filter((b) => b.name.length > 0).map((b) => ({
+    id: b.id,
+    name: b.name,
+    args: tryParseJson(b.argsJson) ?? {}
+  }));
+  const tokens = {
+    input: inputTokens,
+    output: outputTokens,
+    total: totalTokens ?? inputTokens + outputTokens,
+    cached: cachedTokens
+  };
+  const response = {
+    text,
+    structuredOutput: null,
+    toolCalls,
+    tokens,
+    finishReason,
+    raw: { streamed: true, provider: providerLabel }
+  };
+  return { ok: true, status: res.status, response };
+}
+async function parseSSEStream(response, handler) {
+  const body = response.body;
+  if (!body) throw new Error("Response has no body for SSE parse");
+  const reader = body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let buffer = "";
+  for (; ; ) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    let sep;
+    while (sep = buffer.indexOf("\n\n"), sep !== -1) {
+      const block = buffer.slice(0, sep);
+      buffer = buffer.slice(sep + 2);
+      const event = parseSSEBlock(block);
+      if (event) handler(event);
+    }
+  }
+  if (buffer.length > 0) {
+    const event = parseSSEBlock(buffer);
+    if (event) handler(event);
+  }
+}
+function parseSSEBlock(block) {
+  const lines = block.split(/\r?\n/);
+  let eventName;
+  const dataLines = [];
+  for (const line of lines) {
+    if (line.startsWith(":")) continue;
+    if (line.startsWith("event:")) {
+      eventName = line.slice(6).trim();
+    } else if (line.startsWith("data:")) {
+      dataLines.push(line.slice(5).trim());
+    }
+  }
+  if (dataLines.length === 0) return void 0;
+  return { event: eventName, data: dataLines.join("\n") };
+}
+function tryParseJson(s) {
+  if (typeof s !== "string" || s.length === 0) return void 0;
+  try {
+    const parsed = JSON.parse(s);
+    return typeof parsed === "object" && parsed !== null ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function classifyHttpError(status, body) {
+  const message = extractErrorMessage(body) ?? `HTTP ${status}`;
+  if (status === 429)
+    return { ok: false, status, errorType: "retryable", errorCode: "rate_limit", message, raw: body };
+  if (status === 408)
+    return { ok: false, status, errorType: "retryable", errorCode: "timeout", message, raw: body };
+  if (status >= 500)
+    return { ok: false, status, errorType: "retryable", errorCode: "server_error", message, raw: body };
+  if (status === 404)
+    return { ok: false, status, errorType: "retryable", errorCode: "model_not_found", message, raw: body };
+  if (status === 401 || status === 403)
+    return { ok: false, status, errorType: "terminal", errorCode: "auth", message, raw: body };
+  if (status === 400)
+    return { ok: false, status, errorType: "terminal", errorCode: "invalid_request", message, raw: body };
+  return { ok: false, status, errorType: "terminal", errorCode: "unknown", message, raw: body };
+}
+function extractErrorMessage(body) {
+  if (!body || typeof body !== "object") return void 0;
+  const b = body;
+  if (b.error && typeof b.error === "object") {
+    const e = b.error;
+    if (typeof e.message === "string") return e.message;
   }
-};
+  if (typeof b.message === "string") return b.message;
+  return void 0;
+}
+function retryableError(status, code, message, raw) {
+  return { ok: false, status, errorType: "retryable", errorCode: code, message, raw };
+}
 
 // src/execute.ts
-var ANTHROPIC_URL = "https://api.anthropic.com/v1/messages";
+var ANTHROPIC_URL2 = "https://api.anthropic.com/v1/messages";
 var OPENAI_URL = "https://api.openai.com/v1/chat/completions";
 var DEEPSEEK_URL = "https://api.deepseek.com/chat/completions";
 async function execute(request, opts = {}) {
@@ -944,16 +3274,22 @@ 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");
   }
+  if (opts.onChunk) {
+    return streamAnthropic(request, apiKey, {
+      onChunk: opts.onChunk,
+      fetchImpl: opts.fetchImpl
+    });
+  }
   const { provider: _provider, ...body } = request;
   const fetchFn = opts.fetchImpl ?? fetch;
   let res;
   let json;
   try {
-    res = await fetchFn(ANTHROPIC_URL, {
+    res = await fetchFn(ANTHROPIC_URL2, {
       method: "POST",
       headers: {
         "x-api-key": apiKey,
@@ -964,9 +3300,9 @@ async function executeAnthropic(request, opts) {
     });
     json = await res.json().catch(() => ({}));
   } catch (err) {
-    return retryableError(0, "network_error", String(err), null);
+    return retryableError2(0, "network_error", String(err), null);
   }
-  if (!res.ok) return classifyHttpError(res.status, json);
+  if (!res.ok) return classifyHttpError2(res.status, json);
   return { ok: true, status: res.status, response: normalizeAnthropic(json) };
 }
 function normalizeAnthropic(raw) {
@@ -983,7 +3319,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");
   }
@@ -1000,9 +3336,9 @@ async function executeGoogle(request, opts) {
     });
     json = await res.json().catch(() => ({}));
   } catch (err) {
-    return retryableError(0, "network_error", String(err), null);
+    return retryableError2(0, "network_error", String(err), null);
   }
-  if (!res.ok) return classifyHttpError(res.status, json);
+  if (!res.ok) return classifyHttpError2(res.status, json);
   return { ok: true, status: res.status, response: normalizeGoogle(json) };
 }
 function normalizeGoogle(raw) {
@@ -1025,10 +3361,16 @@ 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");
   }
+  if (opts.onChunk) {
+    return streamOpenAILike(OPENAI_URL, request, apiKey, "openai", {
+      onChunk: opts.onChunk,
+      fetchImpl: opts.fetchImpl
+    });
+  }
   const { provider: _provider, ...body } = request;
   const fetchFn = opts.fetchImpl ?? fetch;
   let res;
@@ -1041,16 +3383,22 @@ async function executeOpenAI(request, opts) {
     });
     json = await res.json().catch(() => ({}));
   } catch (err) {
-    return retryableError(0, "network_error", String(err), null);
+    return retryableError2(0, "network_error", String(err), null);
   }
-  if (!res.ok) return classifyHttpError(res.status, json);
+  if (!res.ok) return classifyHttpError2(res.status, json);
   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");
   }
+  if (opts.onChunk) {
+    return streamOpenAILike(DEEPSEEK_URL, request, apiKey, "deepseek", {
+      onChunk: opts.onChunk,
+      fetchImpl: opts.fetchImpl
+    });
+  }
   const { provider: _provider, ...body } = request;
   const fetchFn = opts.fetchImpl ?? fetch;
   let res;
@@ -1063,9 +3411,9 @@ async function executeDeepSeek(request, opts) {
     });
     json = await res.json().catch(() => ({}));
   } catch (err) {
-    return retryableError(0, "network_error", String(err), null);
+    return retryableError2(0, "network_error", String(err), null);
   }
-  if (!res.ok) return classifyHttpError(res.status, json);
+  if (!res.ok) return classifyHttpError2(res.status, json);
   return { ok: true, status: res.status, response: normalizeOpenAILike(json) };
 }
 function normalizeOpenAILike(raw) {
@@ -1075,7 +3423,7 @@ function normalizeOpenAILike(raw) {
   const toolCalls = (choice?.message?.tool_calls ?? []).filter((tc) => tc.function?.name).map((tc, i) => ({
     id: tc.id ?? `tc-${i}`,
     name: tc.function.name,
-    args: tryParseJson(tc.function?.arguments) ?? {}
+    args: tryParseJson2(tc.function?.arguments) ?? {}
   }));
   const u = r.usage ?? {};
   const tokens = {
@@ -1092,8 +3440,8 @@ function applyOverrides(request, overrides) {
   if (!layer) return request;
   return { ...request, ...layer };
 }
-function classifyHttpError(status, body) {
-  const message = extractErrorMessage(body) ?? `HTTP ${status}`;
+function classifyHttpError2(status, body) {
+  const message = extractErrorMessage2(body) ?? `HTTP ${status}`;
   if (status === 429) {
     return { ok: false, status, errorType: "retryable", errorCode: "rate_limit", message, raw: body };
   }
@@ -1114,7 +3462,7 @@ function classifyHttpError(status, body) {
   }
   return { ok: false, status, errorType: "terminal", errorCode: "unknown", message, raw: body };
 }
-function extractErrorMessage(body) {
+function extractErrorMessage2(body) {
   if (!body || typeof body !== "object") return void 0;
   const b = body;
   if (b.error && typeof b.error === "object") {
@@ -1127,10 +3475,10 @@ function extractErrorMessage(body) {
 function terminalError(status, code, message) {
   return { ok: false, status, errorType: "terminal", errorCode: code, message, raw: null };
 }
-function retryableError(status, code, message, raw) {
+function retryableError2(status, code, message, raw) {
   return { ok: false, status, errorType: "retryable", errorCode: code, message, raw };
 }
-function tryParseJson(s) {
+function tryParseJson2(s) {
   if (typeof s !== "string" || s.length === 0) return void 0;
   try {
     const parsed = JSON.parse(s);
@@ -1142,15 +3490,148 @@ 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,
+      // alpha.41: ir.models is ChainModelEntry[] (string | { family }).
+      // Glass-Box renderer carries string ids only; surface family entries
+      // as their family tag prefixed so the panel still shows them in the
+      // pre-resolution log.
+      models: ir.models.map(
+        (m) => typeof m === "string" ? m : `family:${m.family}`
+      )
+    })
+  );
   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(
           {
@@ -1170,49 +3651,117 @@ async function call(ir, opts = {}) {
         continue;
       }
     }
+    safeEmit(
+      () => emitExecuteAttempt(traceId, ir.appId, { model: targetModel, attemptIndex: i })
+    );
+    const targetSupportsStreaming = targetProfile?.streaming === true;
+    const streamingOnChunk = opts.onChunk && !opts.noStream && targetSupportsStreaming ? opts.onChunk : void 0;
     const exec = await execute(activeCompile.request, {
       apiKeys: opts.apiKeys,
       fetchImpl: opts.fetchImpl,
-      providerOverrides: opts.providerOverrides
+      providerOverrides: opts.providerOverrides,
+      onChunk: streamingOnChunk
     });
-    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);
+      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,
         mutationsApplied: targetModel !== initial.target ? activeCompile.mutationsApplied.map((m) => m.id) : void 0,
         promptPreview: extractPromptPreview(ir),
-        responsePreview: responseWithStructured.text.slice(0, 200),
-        cacheReadInputTokens: responseWithStructured.tokens.cached,
-        cacheCreationInputTokens: responseWithStructured.tokens.cacheCreated
+        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
+            })
+          );
+        }
+      }
+      if (opts.shadowProbe) {
+        const probe = runShadowProbe({
+          ir,
+          opts,
+          servedModel: targetModel,
+          servedResponse: validated.response,
+          servedLatencyMs: latencyMs2
+        });
+        if (isBrainSync()) {
+          await probe;
+        } else {
+          void probe;
+        }
+      }
       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,
+        // alpha.44: surface the served compile's advisories so call()
+        // consumers (agent paths) can logAdvisories() like compile()
+        // consumers (chat/intake) do. activeCompile, not initial — parity
+        // with mutationsApplied above on fallback. Closes IC's side-finding.
+        advisories: activeCompile.advisories
       };
     }
     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;
     }
   }
@@ -1226,8 +3775,10 @@ async function call(ir, opts = {}) {
     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
@@ -1249,20 +3800,281 @@ function extractPromptPreview(ir) {
   if (lastHist) return lastHist.slice(0, 200);
   return void 0;
 }
-function withStructuredOutput(response, ir) {
-  if (!ir.constraints?.structuredOutput) return response;
-  if (!response.text) return response;
+function shouldSampleProbe(sampleRate, rng = Math.random) {
+  if (!(sampleRate > 0)) return false;
+  if (sampleRate >= 1) return true;
+  return rng() < sampleRate;
+}
+function normalizeProbeCandidates(candidates) {
+  const arr = Array.isArray(candidates) ? candidates : [candidates];
+  return [...new Set(arr.filter((c) => typeof c === "string" && c.length > 0))];
+}
+function hashForProbe(s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) h = (h << 5) - h + s.charCodeAt(i) | 0;
+  return `h${(h >>> 0).toString(16)}`;
+}
+var DEFAULT_PROBE_MAX_LATENCY_MS = 15e3;
+function isSlowTierCandidate(candidate) {
+  const profile = tryGetProfile(candidate);
+  if (!profile) return false;
+  return latencyTierOf(profile) === "slow";
+}
+async function runProbeCandidates(args) {
+  try {
+    if (!shouldSampleProbe(args.cfg.sampleRate ?? 0.05)) return;
+    const candidates = normalizeProbeCandidates(args.cfg.candidates);
+    const promptHash = hashForProbe(args.ir.currentTurn?.content ?? "");
+    const budgetMs = args.cfg.maxLatencyMs ?? DEFAULT_PROBE_MAX_LATENCY_MS;
+    const deadline = args.sync ? Date.now() + budgetMs : Number.POSITIVE_INFINITY;
+    const skipSlow = args.sync && (args.cfg.skipSlowTierInSync ?? true);
+    const recordDiagnostic = async (candidate, outcome) => {
+      await recordShadowProbe({
+        appId: args.ir.appId,
+        archetype: args.ir.intent.archetype,
+        family: deriveFamilyFromModelId(candidate) ?? "unknown",
+        candidateModel: candidate,
+        currentModel: args.servedModel,
+        promptHash,
+        // Served leg only — the candidate never produced a comparable response.
+        currentResponsePreview: args.servedResponse.text.slice(0, 2e3),
+        tokensCurrentIn: args.servedResponse.tokens.input,
+        tokensCurrentOut: args.servedResponse.tokens.output,
+        latencyCurrentMs: args.servedLatencyMs,
+        outcome
+      });
+    };
+    for (const candidate of candidates) {
+      if (candidate === args.servedModel) continue;
+      if (deriveFamilyFromModelId(candidate) === "claude-opus") continue;
+      if (!isModelReachable(candidate, { apiKeys: args.exec.apiKeys })) continue;
+      if (skipSlow && isSlowTierCandidate(candidate)) {
+        try {
+          await recordDiagnostic(candidate, "skipped_slow_tier_sync");
+        } catch {
+        }
+        continue;
+      }
+      if (args.sync && Date.now() >= deadline) {
+        try {
+          await recordDiagnostic(candidate, "aborted_latency_budget");
+        } catch {
+        }
+        break;
+      }
+      try {
+        const candCompile = compileAndRegister(
+          {
+            ...args.ir,
+            models: args.ir.models.includes(candidate) ? args.ir.models : [candidate, ...args.ir.models],
+            constraints: { ...args.ir.constraints ?? {}, forceModel: candidate }
+          },
+          args.exec
+        );
+        const candStart = Date.now();
+        let timer;
+        const execPromise = execute(candCompile.request, {
+          apiKeys: args.exec.apiKeys,
+          fetchImpl: args.exec.fetchImpl,
+          providerOverrides: args.exec.providerOverrides
+        }).then((exec2) => ({ kind: "exec", exec: exec2 })).catch(() => ({ kind: "failed" }));
+        let raced;
+        if (args.sync) {
+          const remaining = Math.max(0, deadline - Date.now());
+          const timeoutPromise = new Promise((resolve) => {
+            timer = setTimeout(() => resolve({ kind: "timeout" }), remaining);
+          });
+          raced = await Promise.race([execPromise, timeoutPromise]);
+          if (timer) clearTimeout(timer);
+        } else {
+          raced = await execPromise;
+        }
+        if (raced.kind === "timeout") {
+          try {
+            await recordDiagnostic(candidate, "aborted_latency_budget");
+          } catch {
+          }
+          break;
+        }
+        if (raced.kind === "failed") continue;
+        const exec = raced.exec;
+        const candidateLatencyMs = Date.now() - candStart;
+        if (!exec.ok) continue;
+        await recordShadowProbe({
+          appId: args.ir.appId,
+          archetype: args.ir.intent.archetype,
+          family: deriveFamilyFromModelId(candidate) ?? candCompile.provider,
+          candidateModel: candidate,
+          currentModel: args.servedModel,
+          promptHash,
+          currentResponsePreview: args.servedResponse.text.slice(0, 2e3),
+          candidateResponsePreview: exec.response.text.slice(0, 2e3),
+          tokensCurrentIn: args.servedResponse.tokens.input,
+          tokensCurrentOut: args.servedResponse.tokens.output,
+          tokensCandidateIn: exec.response.tokens.input,
+          tokensCandidateOut: exec.response.tokens.output,
+          // alpha.46 — speed is the third swap-decision axis. Served latency
+          // mirrors the user's actual wait; candidate latency is measured only
+          // here and stored nowhere else (irrecoverable if not captured now).
+          latencyCurrentMs: args.servedLatencyMs,
+          latencyCandidateMs: candidateLatencyMs,
+          outcome: "completed"
+        });
+      } catch {
+      }
+    }
+  } catch {
+  }
+}
+async function runShadowProbe(args) {
+  const cfg = args.opts.shadowProbe;
+  if (!cfg) return;
+  await runProbeCandidates({
+    ir: args.ir,
+    cfg,
+    servedModel: args.servedModel,
+    servedResponse: args.servedResponse,
+    servedLatencyMs: args.servedLatencyMs,
+    // CallOptions is a structural superset of ProbeExecOpts.
+    exec: args.opts,
+    // alpha — the call()-inline path is on the user's critical path exactly when
+    // BrainConfig.sync is set (call() awaits the probe before returning). That's
+    // the only case where the latency budget + slow-tier skip must fire.
+    sync: isBrainSync()
+  });
+}
+async function probeShadow(ir, opts) {
+  try {
+    const servedResponse = {
+      text: opts.served.responseText,
+      structuredOutput: null,
+      toolCalls: [],
+      tokens: {
+        input: opts.served.tokensIn,
+        output: opts.served.tokensOut,
+        total: opts.served.tokensIn + opts.served.tokensOut
+      },
+      raw: null
+    };
+    await runProbeCandidates({
+      ir,
+      cfg: {
+        candidates: opts.candidates,
+        sampleRate: opts.sampleRate,
+        judge: opts.judge ?? "off"
+      },
+      servedModel: opts.served.model,
+      servedResponse,
+      servedLatencyMs: opts.served.latencyMs,
+      exec: {
+        policy: opts.policy,
+        toolRelevanceThreshold: opts.toolRelevanceThreshold,
+        compressHistoryAfter: opts.compressHistoryAfter,
+        apiKeys: opts.apiKeys,
+        fetchImpl: opts.fetchImpl,
+        providerOverrides: opts.providerOverrides
+      },
+      // alpha — probeShadow() is ALWAYS off the user-facing critical path: the
+      // consumer fires it from `onFinish` wrapped in `after()`/`waitUntil()`,
+      // after the response is flushed. So the sync-mode latency budget +
+      // slow-tier skip are no-ops here — slow candidates run to completion (this
+      // is in fact the right place to evaluate a slow reasoner). The
+      // maxLatencyMs/skipSlowTierInSync knobs aren't even exposed on
+      // ProbeShadowOptions for that reason.
+      sync: false
+    });
+  } catch {
+  }
+}
+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/streamtext-helpers.ts
+function attachCacheControlToStreamTextInput(result, convertedMessages) {
+  const messages = convertedMessages.map((m) => ({ ...m }));
+  const markIdx = result.diagnostics.historyCacheMarkIndex;
+  if (result.provider === "anthropic" && typeof markIdx === "number" && markIdx >= 0 && markIdx < messages.length) {
+    const target = messages[markIdx];
+    if (target) {
+      messages[markIdx] = {
+        role: target.role,
+        content: target.content,
+        providerOptions: {
+          ...target.providerOptions ?? {},
+          anthropic: {
+            ...target.providerOptions?.anthropic ?? {},
+            cacheControl: { type: "ephemeral" }
+          }
+        }
+      };
+    }
+  }
+  const systemMessages = result.systemMessages;
+  const hasStructuredSystemCacheControl = result.provider === "anthropic" && systemMessages.some(
+    (m) => m.providerOptions?.anthropic?.cacheControl !== void 0
+  );
+  const system = hasStructuredSystemCacheControl ? systemMessages : systemMessages.map((m) => m.content).join("\n\n");
+  return { system, messages };
+}
 
 // src/oracle.ts
 var DEFAULT_DIMENSIONS = ["correctness", "completeness", "conciseness", "format"];
@@ -1352,6 +4164,338 @@ 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 asString2(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 = asString2(row.applies_to_archetype);
+  const model = asString2(row.applies_to_model);
+  const docsLink = asString2(row.docs_url);
+  const suggestion = asString2(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 = asString2(row.resolved_at);
+  if (resolvedAt) out.resolvedAt = resolvedAt;
+  const resolutionSource = asResolutionSource(row.resolution_source);
+  if (resolutionSource) out.resolutionSource = resolutionSource;
+  const resolutionNote = asString2(row.resolution_note);
+  if (resolutionNote) out.resolutionNote = resolutionNote;
+  return out;
+}
+function resolveFetch(injected) {
+  return injected ?? ((...args) => globalThis.fetch(...args));
+}
+function normalizeEndpoint2(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 = normalizeEndpoint2(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 = normalizeEndpoint2(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 };
+}
+async function markExclusionFindingHandled(opts) {
+  const {
+    appId,
+    archetype,
+    excludedModel,
+    resolution,
+    resolutionNote,
+    brainEndpoint,
+    brainJwt,
+    brainAnonKey,
+    fetch: injectedFetch
+  } = opts;
+  if (!appId) return { ok: false, reason: "app_id_required" };
+  if (!archetype) return { ok: false, reason: "archetype_required" };
+  if (!excludedModel) {
+    return { ok: false, reason: "excluded_model_required" };
+  }
+  if (resolution !== "consumer-marked" && resolution !== "declined" && resolution !== "probed-unblock" && resolution !== "probed-stay-excluded") {
+    return { ok: false, reason: "resolution_invalid" };
+  }
+  const doFetch = resolveFetch(injectedFetch);
+  const base = normalizeEndpoint2(brainEndpoint);
+  const url = `${base}/rest/v1/exclusion_findings?app_id=eq.${encodeURIComponent(appId)}&intent_archetype=eq.${encodeURIComponent(archetype)}&excluded_model=eq.${encodeURIComponent(excludedModel)}&resolved_at=is.null`;
+  const patchBody = {
+    resolved_at: (/* @__PURE__ */ new Date()).toISOString(),
+    resolution_source: resolution
+  };
+  if (resolutionNote !== void 0) {
+    patchBody.resolution_note = resolutionNote;
+  }
+  let res;
+  try {
+    res = await doFetch(url, {
+      method: "PATCH",
+      headers: {
+        Authorization: `Bearer ${brainJwt}`,
+        apikey: brainAnonKey,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        // PATCH may match zero rows when already resolved — return=minimal
+        // keeps the response body empty so the success path is uniform.
+        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 (res.status === 401 || res.status === 403) {
+    return { ok: false, reason: "brain_auth_misconfig" };
+  }
+  if (res.status >= 500) {
+    return { ok: false, reason: "brain_unavailable" };
+  }
+  if (!res.ok) {
+    return { ok: false, reason: `patch_failed:${res.status}` };
+  }
+  return { ok: true };
+}
+
 // src/index.ts
 function compile2(ir, opts) {
   const result = compile(ir, opts);
@@ -1359,29 +4503,86 @@ function compile2(ir, opts) {
   return result;
 }
 export {
+  ABSOLUTE_FLOOR,
   ALIASES,
   ALL_ARCHETYPES,
+  ARCHETYPE_FAMILY_FITS,
+  ARCHETYPE_FLOOR_DEFAULT,
   CallError,
+  DEFAULT_FINDINGS_ENDPOINT,
   DIALECT_VERSION,
+  FamilyResolutionError,
   INTENT_ARCHETYPES,
+  LATENCY_TIER_MS,
+  MEASURED_GROUNDING_MIN_N,
+  PRODUCER_OWNED_RULE_CODES,
+  PROVIDER_ENV_KEYS,
+  RULE_SEQUENTIAL_TOOL_CLIFF,
+  TRANSLATOR_FLOOR,
   allProfiles,
+  applyArchetypeConvention,
+  applySectionRewrites,
+  attachCacheControlToStreamTextInput,
   bucketContext,
   bucketHistory,
   bucketToolCount,
   buildLLMJudge,
+  buildShadowProbeRow,
   call,
   clearBrain,
   compile2 as compile,
   configureBrain,
   countTokens,
+  deriveFamilyFromModelId,
+  deriveOwnership,
   execute,
+  findBetterFit,
+  getActionableAdvisories,
+  getAllStarterChains,
+  getAllStarterChainsWithGrounding,
+  getArchetypePerfScore,
+  getDefaultFallbackChain,
+  getDefaultFallbackChainWithGrounding,
+  getModelCompatibility,
+  getPerAxisMetrics,
   getProfile,
+  getReachabilityDiagnostic,
+  getRecommendedPrimary,
+  getSequentialStarterChain,
+  getSequentialStarterChainWithGrounding,
+  getStaleExclusionFindings,
+  getStarterChain,
+  getStarterChainWithGrounding,
   hashShape,
   isArchetype,
+  isBrainQueryActiveFor,
+  isBrainSync,
+  isExclusionFindingsBrainActive,
+  isModelReachable,
+  isProviderReachable,
+  latencyTierOf,
   learningKey,
+  loadAliasesFromBrain,
+  loadArchetypePerfFromBrain,
+  loadArchetypePerfNFromBrain,
+  loadChainsFromBrain,
+  loadModelsFromBrain,
+  loadPricingFromBrain,
+  markAdvisoryResolved,
+  markExclusionFindingHandled,
+  markPromoteReadyHandled,
+  probeShadow,
+  profileToRow,
   profilesByProvider,
+  readBrainReadEnv,
   record,
+  recordOutcome,
+  recordShadowProbe,
   resetTokenizer,
+  resolveConventionsForProfile,
+  resolvePricingAt,
+  resolveProviderKey,
+  runAdvisor,
   setTokenizer,
   tryGetProfile
 };