@warmdrift/kgauto-compiler 2.0.0-alpha.39 → 2.0.0-alpha.41

package/dist/index.js

@@ -27,6 +27,7 @@ __export(index_exports, {
   CallError: () => CallError,
   DEFAULT_FINDINGS_ENDPOINT: () => DEFAULT_FINDINGS_ENDPOINT,
   DIALECT_VERSION: () => DIALECT_VERSION,
+  FamilyResolutionError: () => FamilyResolutionError,
   INTENT_ARCHETYPES: () => INTENT_ARCHETYPES,
   MEASURED_GROUNDING_MIN_N: () => MEASURED_GROUNDING_MIN_N,
   PROVIDER_ENV_KEYS: () => PROVIDER_ENV_KEYS,
@@ -44,6 +45,7 @@ __export(index_exports, {
   compile: () => compile2,
   configureBrain: () => configureBrain,
   countTokens: () => countTokens,
+  deriveFamilyFromModelId: () => deriveFamilyFromModelId,
   execute: () => execute,
   getActionableAdvisories: () => getActionableAdvisories,
   getAllStarterChains: () => getAllStarterChains,
@@ -55,6 +57,7 @@ __export(index_exports, {
   getPerAxisMetrics: () => getPerAxisMetrics,
   getProfile: () => getProfile,
   getReachabilityDiagnostic: () => getReachabilityDiagnostic,
+  getRecommendedPrimary: () => getRecommendedPrimary,
   getSequentialStarterChain: () => getSequentialStarterChain,
   getSequentialStarterChainWithGrounding: () => getSequentialStarterChainWithGrounding,
   getStaleExclusionFindings: () => getStaleExclusionFindings,
@@ -75,6 +78,7 @@ __export(index_exports, {
   loadPricingFromBrain: () => loadPricingFromBrain,
   markAdvisoryResolved: () => markAdvisoryResolved,
   markExclusionFindingHandled: () => markExclusionFindingHandled,
+  markPromoteReadyHandled: () => markPromoteReadyHandled,
   profileToRow: () => profileToRow,
   profilesByProvider: () => profilesByProvider,
   record: () => record,
@@ -463,7 +467,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);
@@ -507,7 +512,7 @@ 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;
@@ -2523,6 +2528,393 @@ function defaultOnError2(err) {
   );
 }
 
+// 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 runtime3;
+var warnedOnce2 = false;
+function isPromoteReadyBrainActive() {
+  return runtime3 !== void 0;
+}
+function loadPromoteReadyFindings(opts) {
+  const rt = runtime3;
+  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 asyncRefresh3(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 asyncRefresh3(rt, appId) {
+  const promise = doRefresh3(rt, appId);
+  pendingRefreshes2.set(appId, promise);
+  try {
+    await promise;
+  } finally {
+    if (pendingRefreshes2.get(appId) === promise) {
+      pendingRefreshes2.delete(appId);
+    }
+  }
+}
+async function doRefresh3(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 (runtime3 !== rt) return;
+    const rows = Array.isArray(body) ? mapRowsToFindings2(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 (!warnedOnce2) {
+      warnedOnce2 = true;
+      (rt.onError ?? defaultOnError3)(err);
+    }
+  }
+}
+function defaultOnError3(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 runtime4;
+var warnedOnce3 = false;
+var pendingRefreshes3 = /* @__PURE__ */ new Map();
+function isStaleModelFindingsBrainActive() {
+  return runtime4 !== void 0;
+}
+function getStaleModelFindings(opts) {
+  const rt = runtime4;
+  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 asyncRefresh4(rt, appId);
+  }
+  if (opts.archetype) {
+    return snap.data.filter((f) => f.archetype === opts.archetype);
+  }
+  return snap.data;
+}
+async function asyncRefresh4(rt, appId) {
+  const promise = doRefresh4(rt, appId);
+  pendingRefreshes3.set(appId, promise);
+  try {
+    await promise;
+  } finally {
+    if (pendingRefreshes3.get(appId) === promise) {
+      pendingRefreshes3.delete(appId);
+    }
+  }
+}
+async function doRefresh4(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 (runtime4 !== rt) return;
+    const rows = Array.isArray(body) ? mapRowsToFindings3(body) : [];
+    snap.data = rows;
+    snap.expiresAt = Date.now() + rt.ttlMs;
+    snap.refreshing = false;
+  } catch (err) {
+    if (runtime4 !== rt) return;
+    snap.refreshing = false;
+    snap.expiresAt = Date.now() + rt.ttlMs;
+    if (!warnedOnce3) {
+      warnedOnce3 = true;
+      (rt.onError ?? defaultOnError4)(err);
+    }
+  }
+}
+function defaultOnError4(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/advisor.ts
 var QUALITY_FLOOR_FOR_RECOMMENDATION = 6;
 var TIER_DOWN_COST_RATIO = 0.5;
@@ -2545,6 +2937,16 @@ function runAdvisor(ir, result, profile, policy, phase2) {
   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));
+  }
   return out;
 }
 function translatorClearedToolCallCliff(phase2) {
@@ -2856,6 +3258,261 @@ ${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() {
@@ -2865,6 +3522,7 @@ function makeHandle() {
 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, {
@@ -3051,6 +3709,29 @@ function validateIR(ir) {
     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);
@@ -3277,7 +3958,7 @@ async function record(input) {
       }
       outcomeId = await tryExtractOutcomeId(res);
     } catch (err) {
-      (config.onError ?? defaultOnError3)(err);
+      (config.onError ?? defaultOnError5)(err);
       return;
     }
     const advisories = input.advisories ?? reg?.advisoriesFromCompile;
@@ -3299,7 +3980,7 @@ async function record(input) {
         throw new Error(`brain advisories ${res.status}: ${text}`);
       }
     } catch (err) {
-      (config.onError ?? defaultOnError3)(err);
+      (config.onError ?? defaultOnError5)(err);
     }
   };
   if (config.sync) {
@@ -3308,7 +3989,7 @@ async function record(input) {
     void send();
   }
 }
-function defaultOnError3(err) {
+function defaultOnError5(err) {
   console.warn("[kgauto] brain record failed:", err);
 }
 function buildPayload(input, reg) {
@@ -3440,12 +4121,12 @@ async function recordOutcome(input) {
       if (!res.ok) {
         const text = await res.text().catch(() => "<no body>");
         const err = new Error(`brain ${res.status}: ${text}`);
-        (config.onError ?? defaultOnError3)(err);
+        (config.onError ?? defaultOnError5)(err);
         return { ok: false, reason: "persistence_failed" };
       }
       return { ok: true };
     } catch (err) {
-      (config.onError ?? defaultOnError3)(err);
+      (config.onError ?? defaultOnError5)(err);
       return { ok: false, reason: "persistence_failed" };
     }
   };
@@ -4705,7 +5386,13 @@ async function call(ir, opts = {}) {
     () => emitCompileStart(traceId, ir.appId, {
       appId: ir.appId,
       archetype: ir.intent.archetype,
-      models: ir.models
+      // 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);
@@ -5171,7 +5858,7 @@ var RESOLUTION_SOURCE_SET = /* @__PURE__ */ new Set([
   "consumer-marked",
   "declined"
 ]);
-function asString(v) {
+function asString2(v) {
   return typeof v === "string" && v.length > 0 ? v : void 0;
 }
 function asSeverity(v) {
@@ -5193,10 +5880,10 @@ function asResolutionSource(v) {
   return void 0;
 }
 function rowToAdvisory(row) {
-  const archetype = asString(row.applies_to_archetype);
-  const model = asString(row.applies_to_model);
-  const docsLink = asString(row.docs_url);
-  const suggestion = asString(row.suggestion);
+  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" };
@@ -5220,18 +5907,18 @@ function rowToAdvisory(row) {
     // reserved — alpha.30+
     status: asStatus(row.status)
   };
-  const resolvedAt = asString(row.resolved_at);
+  const resolvedAt = asString2(row.resolved_at);
   if (resolvedAt) out.resolvedAt = resolvedAt;
   const resolutionSource = asResolutionSource(row.resolution_source);
   if (resolutionSource) out.resolutionSource = resolutionSource;
-  const resolutionNote = asString(row.resolution_note);
+  const resolutionNote = asString2(row.resolution_note);
   if (resolutionNote) out.resolutionNote = resolutionNote;
   return out;
 }
 function resolveFetch(injected) {
   return injected ?? ((...args) => globalThis.fetch(...args));
 }
-function normalizeEndpoint(endpoint) {
+function normalizeEndpoint2(endpoint) {
   return endpoint.replace(/\/+$/, "");
 }
 async function getActionableAdvisories(opts) {
@@ -5248,7 +5935,7 @@ async function getActionableAdvisories(opts) {
     throw new Error("getActionableAdvisories: appId is required");
   }
   const doFetch = resolveFetch(injectedFetch);
-  const base = normalizeEndpoint(brainEndpoint);
+  const base = normalizeEndpoint2(brainEndpoint);
   const qs = new URLSearchParams();
   qs.set("app_id", `eq.${appId}`);
   if (severity) qs.set("severity", `eq.${severity}`);
@@ -5311,7 +5998,7 @@ async function markAdvisoryResolved(opts) {
     return { ok: false, reason: "id_required" };
   }
   const doFetch = resolveFetch(injectedFetch);
-  const base = normalizeEndpoint(brainEndpoint);
+  const base = normalizeEndpoint2(brainEndpoint);
   const lookupUrl = `${base}/rest/v1/actionable_advisories_v?id=eq.${encodeURIComponent(id)}&select=app_id,rule`;
   let lookupRes;
   try {
@@ -5455,7 +6142,7 @@ async function markExclusionFindingHandled(opts) {
     return { ok: false, reason: "resolution_invalid" };
   }
   const doFetch = resolveFetch(injectedFetch);
-  const base = normalizeEndpoint(brainEndpoint);
+  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(),
@@ -5495,125 +6182,6 @@ async function markExclusionFindingHandled(opts) {
   return { ok: true };
 }
 
-// src/models-brain.ts
-function isModelRow(x) {
-  if (!x || typeof x !== "object") return false;
-  const r = x;
-  return typeof r.model_id === "string" && typeof r.provider === "string";
-}
-function isAliasRow(x) {
-  if (!x || typeof x !== "object") return false;
-  const r = x;
-  return typeof r.alias_id === "string" && typeof r.canonical_id === "string";
-}
-function rowToProfile(row) {
-  try {
-    if (row.cliffs !== void 0 && row.cliffs !== null && !Array.isArray(row.cliffs)) {
-      return null;
-    }
-    if (row.recovery !== void 0 && row.recovery !== null && !Array.isArray(row.recovery)) {
-      return null;
-    }
-    if (row.lowering !== void 0 && row.lowering !== null && (typeof row.lowering !== "object" || Array.isArray(row.lowering))) {
-      return null;
-    }
-    return {
-      id: row.model_id,
-      provider: row.provider,
-      status: row.status ?? "current",
-      maxContextTokens: row.max_context_tokens ?? 0,
-      maxOutputTokens: row.max_output_tokens ?? 0,
-      maxTools: row.max_tools ?? 0,
-      parallelToolCalls: row.parallel_tool_calls ?? false,
-      structuredOutput: row.structured_output ?? "none",
-      systemPromptMode: row.system_prompt_mode ?? "inline",
-      streaming: row.streaming ?? true,
-      cliffs: row.cliffs ?? [],
-      costInputPer1m: row.cost_input_per_1m ?? 0,
-      costOutputPer1m: row.cost_output_per_1m ?? 0,
-      lowering: row.lowering ?? { system: { mode: "inline" }, cache: { strategy: "unsupported" } },
-      recovery: row.recovery ?? [],
-      strengths: row.strengths ?? [],
-      weaknesses: row.weaknesses ?? [],
-      notes: row.notes ?? void 0,
-      verifiedAgainstDocs: row.verified_against_docs ?? void 0,
-      archetypePerf: row.archetype_perf ?? void 0
-    };
-  } catch {
-    return null;
-  }
-}
-function profileToRow(profile, opts = {}) {
-  const row = {
-    model_id: profile.id,
-    provider: profile.provider,
-    status: profile.status,
-    max_context_tokens: profile.maxContextTokens,
-    max_output_tokens: profile.maxOutputTokens,
-    max_tools: profile.maxTools,
-    parallel_tool_calls: profile.parallelToolCalls,
-    structured_output: profile.structuredOutput,
-    system_prompt_mode: profile.systemPromptMode,
-    streaming: profile.streaming,
-    cliffs: profile.cliffs,
-    cost_input_per_1m: profile.costInputPer1m,
-    cost_output_per_1m: profile.costOutputPer1m,
-    lowering: profile.lowering,
-    recovery: profile.recovery,
-    strengths: profile.strengths,
-    weaknesses: profile.weaknesses,
-    notes: profile.notes ?? null,
-    archetype_perf: profile.archetypePerf ?? null,
-    active: opts.active ?? true
-  };
-  if (opts.verifiedAgainstDocs !== void 0) {
-    row.verified_against_docs = opts.verifiedAgainstDocs;
-  } else if (profile.verifiedAgainstDocs !== void 0) {
-    const v = profile.verifiedAgainstDocs;
-    row.verified_against_docs = /^\d{4}-\d{2}-\d{2}/.test(v) ? v : null;
-  }
-  if (opts.versionAdded !== void 0) row.version_added = opts.versionAdded;
-  if (opts.versionRemoved !== void 0) row.version_removed = opts.versionRemoved;
-  return row;
-}
-function mapRowsToModels(rows) {
-  const out = /* @__PURE__ */ new Map();
-  for (const row of rows) {
-    if (!isModelRow(row)) continue;
-    const profile = rowToProfile(row);
-    if (profile) out.set(profile.id, profile);
-  }
-  return out;
-}
-function mapRowsToAliases(rows) {
-  const out = {};
-  for (const row of rows) {
-    if (!isAliasRow(row)) continue;
-    out[row.alias_id] = row.canonical_id;
-  }
-  return out;
-}
-function bundledModels() {
-  return new Map(allProfilesRaw().map((p) => [p.id, p]));
-}
-function bundledAliases() {
-  return { ...ALIASES };
-}
-var loadModelsFromBrain = createBrainQueryCache({
-  table: "kgauto_models",
-  mapRows: mapRowsToModels,
-  bundledFallback: bundledModels
-});
-var loadAliasesFromBrain = createBrainQueryCache({
-  table: "kgauto_aliases",
-  mapRows: mapRowsToAliases,
-  bundledFallback: bundledAliases
-});
-_setProfileBrainHook({
-  getProfile: (canonical) => loadModelsFromBrain().get(canonical),
-  resolveAlias: (id) => loadAliasesFromBrain()[id]
-});
-
 // src/index.ts
 function compile2(ir, opts) {
   const result = compile(ir, opts);
@@ -5629,6 +6197,7 @@ function compile2(ir, opts) {
   CallError,
   DEFAULT_FINDINGS_ENDPOINT,
   DIALECT_VERSION,
+  FamilyResolutionError,
   INTENT_ARCHETYPES,
   MEASURED_GROUNDING_MIN_N,
   PROVIDER_ENV_KEYS,
@@ -5646,6 +6215,7 @@ function compile2(ir, opts) {
   compile,
   configureBrain,
   countTokens,
+  deriveFamilyFromModelId,
   execute,
   getActionableAdvisories,
   getAllStarterChains,
@@ -5657,6 +6227,7 @@ function compile2(ir, opts) {
   getPerAxisMetrics,
   getProfile,
   getReachabilityDiagnostic,
+  getRecommendedPrimary,
   getSequentialStarterChain,
   getSequentialStarterChainWithGrounding,
   getStaleExclusionFindings,
@@ -5677,6 +6248,7 @@ function compile2(ir, opts) {
   loadPricingFromBrain,
   markAdvisoryResolved,
   markExclusionFindingHandled,
+  markPromoteReadyHandled,
   profileToRow,
   profilesByProvider,
   record,