@warmdrift/kgauto-compiler 2.0.0-alpha.42 → 2.0.0-alpha.44

package/dist/index.mjs

@@ -33,7 +33,7 @@ import {
   loadChainsFromBrain,
   readBrainReadEnv,
   resolveProviderKey
-} from "./chunk-KCNQUMHN.mjs";
+} from "./chunk-6MSJQCAP.mjs";
 import {
   ALIASES,
   _setProfileBrainHook,
@@ -42,7 +42,7 @@ import {
   getProfile,
   profilesByProvider,
   tryGetProfile
-} from "./chunk-JQGRWJZO.mjs";
+} from "./chunk-ZHUD3I52.mjs";
 import {
   emitAdvisoryFired,
   emitCompileDone,
@@ -52,6 +52,380 @@ import {
   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;
+    }
+    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
+    };
+  } catch {
+    return null;
+  }
+}
+function profileToRow(profile, opts = {}) {
+  const row = {
+    model_id: profile.id,
+    provider: profile.provider,
+    status: profile.status,
+    max_context_tokens: profile.maxContextTokens,
+    max_output_tokens: profile.maxOutputTokens,
+    max_tools: profile.maxTools,
+    parallel_tool_calls: profile.parallelToolCalls,
+    structured_output: profile.structuredOutput,
+    system_prompt_mode: profile.systemPromptMode,
+    streaming: profile.streaming,
+    cliffs: profile.cliffs,
+    cost_input_per_1m: profile.costInputPer1m,
+    cost_output_per_1m: profile.costOutputPer1m,
+    lowering: profile.lowering,
+    recovery: profile.recovery,
+    strengths: profile.strengths,
+    weaknesses: profile.weaknesses,
+    notes: profile.notes ?? null,
+    archetype_perf: profile.archetypePerf ?? null,
+    active: opts.active ?? 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
+  };
+  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;
 function defaultCharBasedCounter(text) {
@@ -450,6 +824,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 = {}) {
@@ -827,125 +1370,6 @@ function getArchetypePerfScore(modelId, archetype) {
   return { score, n, grounding };
 }
 
-// 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/promote-ready-brain.ts
 function isRawPromoteReadyRow(x) {
   if (!x || typeof x !== "object") return false;
@@ -1333,6 +1757,77 @@ function advisorRuleConsumerOnStaleModel(ir) {
   ];
 }
 
+// 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;
@@ -1372,6 +1867,14 @@ function runAdvisor(ir, result, profile, policy, phase2) {
     );
     out.push(...advisorRuleConsumerOnStaleModel(ir));
   }
+  if (policy?.posture !== "locked") {
+    out.push(
+      ...advisorRuleCrossFamilyFit({
+        archetype: ir.intent.archetype,
+        resolvedPrimary: profile.id
+      })
+    );
+  }
   return out;
 }
 function translatorClearedToolCallCliff(phase2) {
@@ -1683,261 +2186,6 @@ ${originalText}`;
   return { rewrittenIR, rewrites };
 }
 
-// src/models-brain.ts
-function isModelRow(x) {
-  if (!x || typeof x !== "object") return false;
-  const r = x;
-  return typeof r.model_id === "string" && typeof r.provider === "string";
-}
-function isAliasRow(x) {
-  if (!x || typeof x !== "object") return false;
-  const r = x;
-  return typeof r.alias_id === "string" && typeof r.canonical_id === "string";
-}
-function rowToProfile(row) {
-  try {
-    if (row.cliffs !== void 0 && row.cliffs !== null && !Array.isArray(row.cliffs)) {
-      return null;
-    }
-    if (row.recovery !== void 0 && row.recovery !== null && !Array.isArray(row.recovery)) {
-      return null;
-    }
-    if (row.lowering !== void 0 && row.lowering !== null && (typeof row.lowering !== "object" || Array.isArray(row.lowering))) {
-      return null;
-    }
-    return {
-      id: row.model_id,
-      provider: row.provider,
-      status: row.status ?? "current",
-      maxContextTokens: row.max_context_tokens ?? 0,
-      maxOutputTokens: row.max_output_tokens ?? 0,
-      maxTools: row.max_tools ?? 0,
-      parallelToolCalls: row.parallel_tool_calls ?? false,
-      structuredOutput: row.structured_output ?? "none",
-      systemPromptMode: row.system_prompt_mode ?? "inline",
-      streaming: row.streaming ?? true,
-      cliffs: row.cliffs ?? [],
-      costInputPer1m: row.cost_input_per_1m ?? 0,
-      costOutputPer1m: row.cost_output_per_1m ?? 0,
-      lowering: row.lowering ?? { system: { mode: "inline" }, cache: { strategy: "unsupported" } },
-      recovery: row.recovery ?? [],
-      strengths: row.strengths ?? [],
-      weaknesses: row.weaknesses ?? [],
-      notes: row.notes ?? void 0,
-      verifiedAgainstDocs: row.verified_against_docs ?? void 0,
-      archetypePerf: row.archetype_perf ?? void 0,
-      // 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
-    };
-  } catch {
-    return null;
-  }
-}
-function profileToRow(profile, opts = {}) {
-  const row = {
-    model_id: profile.id,
-    provider: profile.provider,
-    status: profile.status,
-    max_context_tokens: profile.maxContextTokens,
-    max_output_tokens: profile.maxOutputTokens,
-    max_tools: profile.maxTools,
-    parallel_tool_calls: profile.parallelToolCalls,
-    structured_output: profile.structuredOutput,
-    system_prompt_mode: profile.systemPromptMode,
-    streaming: profile.streaming,
-    cliffs: profile.cliffs,
-    cost_input_per_1m: profile.costInputPer1m,
-    cost_output_per_1m: profile.costOutputPer1m,
-    lowering: profile.lowering,
-    recovery: profile.recovery,
-    strengths: profile.strengths,
-    weaknesses: profile.weaknesses,
-    notes: profile.notes ?? null,
-    archetype_perf: profile.archetypePerf ?? null,
-    active: opts.active ?? 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
-  };
-  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/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/compile.ts
 var counter = 0;
 function makeHandle() {
@@ -1982,6 +2230,9 @@ function compile(ir, opts = {}) {
   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,
@@ -2033,7 +2284,15 @@ function compile(ir, opts = {}) {
     toolOrchestration: ir.constraints?.toolOrchestration,
     // alpha.33 — see top-of-block comment.
     historyCacheMarkIndex,
-    systemCacheMarkIndex
+    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({
@@ -3344,7 +3603,12 @@ async function call(ir, opts = {}) {
         fallbackReason,
         unreachableFiltered,
         policyBlockedFiltered,
-        traceId
+        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({
@@ -3917,6 +4181,7 @@ export {
   ABSOLUTE_FLOOR,
   ALIASES,
   ALL_ARCHETYPES,
+  ARCHETYPE_FAMILY_FITS,
   ARCHETYPE_FLOOR_DEFAULT,
   CallError,
   DEFAULT_FINDINGS_ENDPOINT,
@@ -3929,6 +4194,7 @@ export {
   RULE_SEQUENTIAL_TOOL_CLIFF,
   TRANSLATOR_FLOOR,
   allProfiles,
+  applyArchetypeConvention,
   applySectionRewrites,
   attachCacheControlToStreamTextInput,
   bucketContext,
@@ -3943,6 +4209,7 @@ export {
   deriveFamilyFromModelId,
   deriveOwnership,
   execute,
+  findBetterFit,
   getActionableAdvisories,
   getAllStarterChains,
   getAllStarterChainsWithGrounding,
@@ -3981,6 +4248,7 @@ export {
   record,
   recordOutcome,
   resetTokenizer,
+  resolveConventionsForProfile,
   resolvePricingAt,
   resolveProviderKey,
   runAdvisor,