@warmdrift/kgauto-compiler 2.0.0-alpha.20 → 2.0.0-alpha.22

package/dist/index.js

@@ -25,6 +25,7 @@ __export(index_exports, {
   CallError: () => CallError,
   DIALECT_VERSION: () => DIALECT_VERSION,
   INTENT_ARCHETYPES: () => INTENT_ARCHETYPES,
+  MEASURED_GROUNDING_MIN_N: () => MEASURED_GROUNDING_MIN_N,
   PROVIDER_ENV_KEYS: () => PROVIDER_ENV_KEYS,
   allProfiles: () => allProfiles,
   bucketContext: () => bucketContext,
@@ -38,18 +39,25 @@ __export(index_exports, {
   countTokens: () => countTokens,
   execute: () => execute,
   getAllStarterChains: () => getAllStarterChains,
+  getAllStarterChainsWithGrounding: () => getAllStarterChainsWithGrounding,
   getArchetypePerfScore: () => getArchetypePerfScore,
   getDefaultFallbackChain: () => getDefaultFallbackChain,
+  getDefaultFallbackChainWithGrounding: () => getDefaultFallbackChainWithGrounding,
   getProfile: () => getProfile,
   getReachabilityDiagnostic: () => getReachabilityDiagnostic,
+  getSequentialStarterChain: () => getSequentialStarterChain,
+  getSequentialStarterChainWithGrounding: () => getSequentialStarterChainWithGrounding,
   getStarterChain: () => getStarterChain,
+  getStarterChainWithGrounding: () => getStarterChainWithGrounding,
   hashShape: () => hashShape,
   isArchetype: () => isArchetype,
+  isBrainQueryActiveFor: () => isBrainQueryActiveFor,
   isModelReachable: () => isModelReachable,
   isProviderReachable: () => isProviderReachable,
   learningKey: () => learningKey,
   loadAliasesFromBrain: () => loadAliasesFromBrain,
   loadArchetypePerfFromBrain: () => loadArchetypePerfFromBrain,
+  loadArchetypePerfNFromBrain: () => loadArchetypePerfNFromBrain,
   loadChainsFromBrain: () => loadChainsFromBrain,
   loadModelsFromBrain: () => loadModelsFromBrain,
   loadPricingFromBrain: () => loadPricingFromBrain,
@@ -1937,14 +1945,160 @@ function profilesByProvider(provider) {
   return PROFILES_RAW.filter((p) => p.provider === provider);
 }
 
+// src/brain-query.ts
+var FRESH_SNAPSHOT = {
+  data: null,
+  expiresAt: 0,
+  refreshing: false,
+  warned: false
+};
+var snapshot = { ...FRESH_SNAPSHOT };
+var runtime;
+function configureBrainQuery(rt) {
+  runtime = rt;
+  snapshot = { ...FRESH_SNAPSHOT };
+}
+function createBrainQueryCache(opts) {
+  return () => {
+    const rt = runtime;
+    if (!rt || !rt.enabledTables.has(opts.table)) {
+      return opts.bundledFallback();
+    }
+    const now = Date.now();
+    const stale = snapshot.expiresAt <= now;
+    if (stale && !snapshot.refreshing) {
+      snapshot.refreshing = true;
+      void asyncRefresh(rt);
+    }
+    if (snapshot.data) {
+      const rows = snapshot.data[opts.table];
+      if (Array.isArray(rows) && rows.length > 0) {
+        try {
+          return opts.mapRows(rows);
+        } catch {
+          return opts.bundledFallback();
+        }
+      }
+    }
+    return opts.bundledFallback();
+  };
+}
+var pendingRefresh;
+async function asyncRefresh(rt) {
+  const promise = doRefresh(rt);
+  pendingRefresh = promise;
+  try {
+    await promise;
+  } finally {
+    if (pendingRefresh === promise) pendingRefresh = void 0;
+  }
+}
+var DEFAULT_CONFIG_URL = "https://kgauto-dashboard.vercel.app/api/kgauto-v2/config";
+async function doRefresh(rt) {
+  const url = rt.configEndpoint ?? DEFAULT_CONFIG_URL;
+  try {
+    const res = await rt.fetchImpl(url, { method: "GET" });
+    if (!res.ok) {
+      throw new Error(`brain-query ${res.status}: ${res.statusText}`);
+    }
+    const body = await res.json();
+    if (runtime !== rt) return;
+    snapshot = {
+      data: body,
+      expiresAt: Date.now() + rt.ttlMs,
+      refreshing: false,
+      warned: snapshot.warned
+    };
+  } catch (err) {
+    if (runtime !== rt) return;
+    snapshot.refreshing = false;
+    snapshot.expiresAt = Date.now() + rt.ttlMs;
+    if (!snapshot.warned) {
+      snapshot.warned = true;
+      (rt.onError ?? defaultOnError)(err);
+    }
+  }
+}
+function defaultOnError(err) {
+  console.warn("[kgauto] brain-query failed (using bundled fallback):", err);
+}
+function isBrainQueryActiveFor(table) {
+  return runtime !== void 0 && runtime.enabledTables.has(table);
+}
+
+// src/archetype-perf-brain.ts
+function isPerfRow(x) {
+  if (!x || typeof x !== "object") return false;
+  const r = x;
+  return typeof r.model_id === "string" && typeof r.archetype === "string" && typeof r.perf_score === "number";
+}
+function mapRowsToPerfMap(rows) {
+  const out = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    if (!isPerfRow(row)) continue;
+    const existing = out.get(row.model_id) ?? {};
+    existing[row.archetype] = row.perf_score;
+    out.set(row.model_id, existing);
+  }
+  return out;
+}
+function mapRowsToNMap(rows) {
+  const out = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    if (!isPerfRow(row)) continue;
+    if (typeof row.n !== "number") continue;
+    const existing = out.get(row.model_id) ?? {};
+    existing[row.archetype] = row.n;
+    out.set(row.model_id, existing);
+  }
+  return out;
+}
+function bundledArchetypePerf() {
+  const out = /* @__PURE__ */ new Map();
+  for (const profile of allProfiles()) {
+    if (profile.archetypePerf) out.set(profile.id, profile.archetypePerf);
+  }
+  return out;
+}
+function bundledArchetypePerfN() {
+  return /* @__PURE__ */ new Map();
+}
+var loadArchetypePerfFromBrain = createBrainQueryCache({
+  table: "kgauto_archetype_perf",
+  mapRows: mapRowsToPerfMap,
+  bundledFallback: bundledArchetypePerf
+});
+var loadArchetypePerfNFromBrain = createBrainQueryCache(
+  {
+    table: "kgauto_archetype_perf",
+    mapRows: mapRowsToNMap,
+    bundledFallback: bundledArchetypePerfN
+  }
+);
+var MEASURED_GROUNDING_MIN_N = 10;
+function getArchetypePerfScore(modelId, archetype) {
+  const score = loadArchetypePerfFromBrain().get(modelId)?.[archetype] ?? 5;
+  const n = loadArchetypePerfNFromBrain().get(modelId)?.[archetype] ?? 0;
+  const grounding = n >= MEASURED_GROUNDING_MIN_N ? "measured" : "judgment";
+  return { score, n, grounding };
+}
+
 // src/advisor.ts
-function runAdvisor(ir, result, profile, policy) {
+var QUALITY_FLOOR_FOR_RECOMMENDATION = 6;
+var TIER_DOWN_COST_RATIO = 0.5;
+var COST_MISMATCHED_CHOSEN_SCORE_CEILING = 7;
+function runAdvisor(ir, result, profile, policy, phase2) {
   const out = [];
   out.push(...detectCachingOff(ir, profile));
   out.push(...detectSingleChunkSystem(ir, profile));
   out.push(...detectToolBloat(ir, result));
   out.push(...detectHistoryUncached(ir, profile));
   out.push(...detectSingleModelArray(ir, policy));
+  if (policy?.posture !== "locked") {
+    out.push(...detectCostMismatchedArchetype(ir, profile, phase2));
+    out.push(...detectModelStaleEvidence(ir, profile));
+    out.push(...detectTierDown(ir, profile, phase2));
+  }
   return out;
 }
 function detectCachingOff(ir, profile) {
@@ -2030,6 +2184,91 @@ function detectSingleModelArray(ir, policy) {
     }
   ];
 }
+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"
+    }
+  ];
+}
 
 // src/compile.ts
 var counter = 0;
@@ -2105,6 +2344,13 @@ function compile(ir, opts = {}) {
       description: "ir.constraints.toolOrchestration='sequential' selected the DeepSeek-tier-0 hunt chain overlay (L-040 parallel-tool cliff doesn't apply at single-step granularity)."
     });
   }
+  const phase2ProfileResolver = opts.profileResolver ? (id) => {
+    try {
+      return opts.profileResolver(id);
+    } catch {
+      return void 0;
+    }
+  } : tryGetProfile;
   const advisories = runAdvisor(
     ir,
     {
@@ -2114,7 +2360,11 @@ function compile(ir, opts = {}) {
       diagnostics
     },
     profile,
-    opts.policy
+    opts.policy,
+    {
+      fallbackChain,
+      profileResolver: phase2ProfileResolver
+    }
   );
   return {
     handle,
@@ -2167,84 +2417,6 @@ function validateFinalFit(ir, profile, tokens) {
   }
 }
 
-// src/brain-query.ts
-var FRESH_SNAPSHOT = {
-  data: null,
-  expiresAt: 0,
-  refreshing: false,
-  warned: false
-};
-var snapshot = { ...FRESH_SNAPSHOT };
-var runtime;
-function configureBrainQuery(rt) {
-  runtime = rt;
-  snapshot = { ...FRESH_SNAPSHOT };
-}
-function createBrainQueryCache(opts) {
-  return () => {
-    const rt = runtime;
-    if (!rt || !rt.enabledTables.has(opts.table)) {
-      return opts.bundledFallback();
-    }
-    const now = Date.now();
-    const stale = snapshot.expiresAt <= now;
-    if (stale && !snapshot.refreshing) {
-      snapshot.refreshing = true;
-      void asyncRefresh(rt);
-    }
-    if (snapshot.data) {
-      const rows = snapshot.data[opts.table];
-      if (Array.isArray(rows) && rows.length > 0) {
-        try {
-          return opts.mapRows(rows);
-        } catch {
-          return opts.bundledFallback();
-        }
-      }
-    }
-    return opts.bundledFallback();
-  };
-}
-var pendingRefresh;
-async function asyncRefresh(rt) {
-  const promise = doRefresh(rt);
-  pendingRefresh = promise;
-  try {
-    await promise;
-  } finally {
-    if (pendingRefresh === promise) pendingRefresh = void 0;
-  }
-}
-var DEFAULT_CONFIG_URL = "https://kgauto-dashboard.vercel.app/api/kgauto-v2/config";
-async function doRefresh(rt) {
-  const url = rt.configEndpoint ?? DEFAULT_CONFIG_URL;
-  try {
-    const res = await rt.fetchImpl(url, { method: "GET" });
-    if (!res.ok) {
-      throw new Error(`brain-query ${res.status}: ${res.statusText}`);
-    }
-    const body = await res.json();
-    if (runtime !== rt) return;
-    snapshot = {
-      data: body,
-      expiresAt: Date.now() + rt.ttlMs,
-      refreshing: false,
-      warned: snapshot.warned
-    };
-  } catch (err) {
-    if (runtime !== rt) return;
-    snapshot.refreshing = false;
-    snapshot.expiresAt = Date.now() + rt.ttlMs;
-    if (!snapshot.warned) {
-      snapshot.warned = true;
-      (rt.onError ?? defaultOnError)(err);
-    }
-  }
-}
-function defaultOnError(err) {
-  console.warn("[kgauto] brain-query failed (using bundled fallback):", err);
-}
-
 // src/pricing-brain.ts
 function isPricingRow(x) {
   if (!x || typeof x !== "object") return false;
@@ -2898,101 +3070,119 @@ var loadChainsFromBrain = createBrainQueryCache({
 });
 
 // src/fallback.ts
-var STARTER_CHAINS = {
+var STARTER_CHAINS_GROUNDED = {
   // Reasoning floor — never degrade. Walk UP on 429 to Opus → cross-provider.
-  // alpha.16: gpt-5.5 appended as third-provider critique floor (frontier-tier,
-  // archetypePerf=9). Cross-provider-tail invariant has somewhere to land when
-  // both Anthropic + Google are unreachable (consumer adds only OpenAI key).
   critique: [
-    "claude-opus-4-7",
-    "claude-sonnet-4-6",
-    "gemini-2.5-pro",
-    "gpt-5.5"
+    { id: "claude-opus-4-7", grounding: "judgment", reason: "Highest reasoning bar, no degradation tier \u2014 engineer pick, awaiting measured backing" },
+    { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Same-provider walk-down from Opus on 429" },
+    { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor in similar quality bracket" },
+    { id: "gpt-5.5", grounding: "judgment", reason: "alpha.16: third-provider frontier-tier floor (archetypePerf=9)" }
   ],
-  // Reasoning matters — Sonnet primary; walk UP to Opus on 429 (rare exception
-  // to "always cheaper"); cross-provider via Pro; DeepSeek Pro as tier 3 floor.
+  // Reasoning matters — Sonnet primary; walk UP to Opus on 429.
   plan: [
-    "claude-sonnet-4-6",
-    "claude-opus-4-7",
-    "gemini-2.5-pro",
-    "deepseek-v4-pro"
+    { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Reasoning + cost balance \u2014 engineer pick" },
+    { id: "claude-opus-4-7", grounding: "judgment", reason: 'Same-provider walk-UP on 429 (rare exception to "always cheaper")' },
+    { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor" },
+    { id: "deepseek-v4-pro", grounding: "judgment", reason: "Tier 3 cost floor \u2014 no brain evidence yet" }
   ],
-  // Quality + cost match. Walk Sonnet → Haiku same-provider, Pro cross,
-  // gpt-5.4-mini as third-provider tail (alpha.16 — closes the mono-Anthropic
-  // gap when consumer has only ANTHROPIC + OPENAI keys; archetypePerf=7).
+  // Quality + cost match.
   generate: [
-    "claude-sonnet-4-6",
-    "claude-haiku-4-5",
-    "gemini-2.5-pro",
-    "gpt-5.4-mini"
+    { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Quality + cost match \u2014 engineer pick" },
+    { id: "claude-haiku-4-5", grounding: "judgment", reason: "Same-provider step-down" },
+    { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor" },
+    { id: "gpt-5.4-mini", grounding: "judgment", reason: "alpha.16: third-provider tail (archetypePerf=7) \u2014 closes mono-Anthropic gap" }
   ],
+  // ask::sonnet — STARTER_CHAINS calls this "Quality + cost match" but
+  // tt-intel s78 prod data showed 27% empty rate. Labeled 'judgment' until
+  // evidence either validates or refutes the placement.
   ask: [
-    "claude-sonnet-4-6",
-    "claude-haiku-4-5",
-    "gemini-2.5-pro",
-    "gpt-5.4-mini"
+    { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Quality + cost match \u2014 engineer pick. NOTE: tt-intel s78 prod showed 27% empty rate; placement awaits measurement validation" },
+    { id: "claude-haiku-4-5", grounding: "judgment", reason: "Same-provider step-down" },
+    { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor" },
+    { id: "gpt-5.4-mini", grounding: "judgment", reason: "alpha.16: third-provider tail (archetypePerf=7)" }
   ],
-  // Structured-output archetype — Flash skipped (alpha.8 MAX_TOKENS cliff),
-  // DeepSeek skipped (no brain evidence). Floor at Haiku. alpha.16: gpt-5.4
-  // appended as third-provider extract floor (archetypePerf=8, native
-  // structured-output support).
+  // Structured-output archetype — Flash skipped (alpha.8 MAX_TOKENS cliff,
+  // capability-fact); DeepSeek skipped (no brain evidence).
   extract: [
-    "claude-sonnet-4-6",
-    "claude-haiku-4-5",
-    "gemini-2.5-pro",
-    "gpt-5.4"
+    { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Reliable structured-output anchor \u2014 engineer pick" },
+    { id: "claude-haiku-4-5", grounding: "judgment", reason: "Same-provider step-down with native structured output" },
+    { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor with structured-output support" },
+    { id: "gpt-5.4", grounding: "capability-fact", reason: "alpha.16: third-provider floor \u2014 native structured-output capability (archetypePerf=8)" }
   ],
   // Forgiving archetype — Sonnet primary but Flash safely floors it.
   transform: [
-    "claude-sonnet-4-6",
-    "claude-haiku-4-5",
-    "gemini-2.5-pro",
-    "gemini-2.5-flash"
+    { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Quality anchor \u2014 engineer pick" },
+    { id: "claude-haiku-4-5", grounding: "judgment", reason: "Same-provider step-down" },
+    { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor" },
+    { id: "gemini-2.5-flash", grounding: "judgment", reason: "Cost floor \u2014 forgiving archetype tolerates Flash" }
   ],
-  // Parallel-tool throughput champion (Flash, L-040). Tier 1 cross-provider
-  // Pro; tier 2 Sonnet (quality safety net for blocked-Flash case); tier 3
-  // Haiku (reduced tool budget — cliff at 16 fires). This is the
-  // `toolOrchestration: 'parallel'` (default) hunt chain. The sequential
-  // variant lives in STARTER_CHAINS_BY_MODE.hunt.sequential below — see
-  // alpha.20 E3 / interfaces/kgauto.md `sequential-agentic-hunt-mode`.
+  // Parallel-tool throughput champion — Flash leads on the L-040 cliff
+  // (capability-fact: Flash 15-75 parallel calls/step vs DeepSeek 7-8).
   hunt: [
-    "gemini-2.5-flash",
-    "gemini-2.5-pro",
-    "claude-sonnet-4-6",
-    "claude-haiku-4-5"
+    { id: "gemini-2.5-flash", grounding: "capability-fact", reason: "L-040 parallel-tool throughput champion (15-75 calls/step)" },
+    { id: "gemini-2.5-pro", grounding: "capability-fact", reason: "Cross-provider tier 1 with strong parallel-tool support" },
+    { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Quality safety net for blocked-Flash case" },
+    { id: "claude-haiku-4-5", grounding: "judgment", reason: "Reduced tool budget \u2014 cliff at 16 fires" }
   ],
-  // Cost-sensitive + tolerant. DeepSeek brain-evidence tier 1; Haiku tier 2
-  // for quality safety; Flash-Lite emergency floor (onboarded s22).
+  // Cost-sensitive + tolerant. DeepSeek brain-evidence tier 1.
   summarize: [
-    "gemini-2.5-flash",
-    "deepseek-v4-flash",
-    "claude-haiku-4-5",
-    "gemini-2.5-flash-lite"
+    { id: "gemini-2.5-flash", grounding: "judgment", reason: "Cost-sensitive primary \u2014 engineer pick" },
+    { id: "deepseek-v4-flash", grounding: "measured", reason: "Brain-validated tier 1 for cost-sensitive summarize workloads", n: 169 },
+    { id: "claude-haiku-4-5", grounding: "judgment", reason: "Quality safety net" },
+    { id: "gemini-2.5-flash-lite", grounding: "judgment", reason: "Emergency floor \u2014 onboarded s22, no brain evidence yet" }
   ],
-  // Brain-validated DeepSeek tier 1 (169 rows, 0% empty); Haiku tier 2;
-  // Flash-Lite floor for repeat-prompt workloads (cache-discount 10×).
+  // Brain-validated DeepSeek tier 1 (169 rows, 0% empty rate).
   classify: [
-    "gemini-2.5-flash",
-    "deepseek-v4-flash",
-    "claude-haiku-4-5",
-    "gemini-2.5-flash-lite"
+    { id: "gemini-2.5-flash", grounding: "judgment", reason: "Cost-sensitive primary \u2014 engineer pick" },
+    { id: "deepseek-v4-flash", grounding: "measured", reason: "Brain-validated tier 1 (169 rows, 0% empty rate)", n: 169 },
+    { id: "claude-haiku-4-5", grounding: "judgment", reason: "Quality safety net" },
+    { id: "gemini-2.5-flash-lite", grounding: "judgment", reason: "Cache-discount 10\xD7 floor for repeat-prompt workloads" }
   ]
 };
-var STARTER_CHAINS_BY_MODE = {
+var STARTER_CHAINS = (() => {
+  const out = {};
+  for (const [archetype, entries] of Object.entries(STARTER_CHAINS_GROUNDED)) {
+    out[archetype] = entries.map((e) => e.id);
+  }
+  return out;
+})();
+var STARTER_CHAINS_BY_MODE_GROUNDED = {
   hunt: {
     sequential: [
-      // V4-Pro: cheap + good reasoning at single-step granularity; no
-      // L-040 cliff applies when consumer commits to sequential.
-      "deepseek-v4-pro",
-      // V4-Flash: cheapest viable; sibling-provider fallback.
-      "deepseek-v4-flash",
-      // Cross-provider safety net — Sonnet handles sequential agentic loops
-      // cleanly; Pro as third-provider tail when no DeepSeek key reachable.
-      "claude-sonnet-4-6",
-      "gemini-2.5-pro"
+      {
+        id: "deepseek-v4-pro",
+        grounding: "judgment",
+        reason: "alpha.20 E3: cheap + good reasoning at single-step granularity; L-040 cliff silenced when sequential \u2014 hypothesis not yet measured"
+      },
+      {
+        id: "deepseek-v4-flash",
+        grounding: "judgment",
+        reason: "Cheapest viable; sibling-provider fallback"
+      },
+      {
+        id: "claude-sonnet-4-6",
+        grounding: "judgment",
+        reason: "Cross-provider safety net \u2014 Sonnet handles sequential agentic loops cleanly"
+      },
+      {
+        id: "gemini-2.5-pro",
+        grounding: "judgment",
+        reason: "Third-provider tail when no DeepSeek key reachable"
+      }
     ]
   }
 };
+var STARTER_CHAINS_BY_MODE = (() => {
+  const out = {};
+  for (const [archetype, modes] of Object.entries(STARTER_CHAINS_BY_MODE_GROUNDED)) {
+    if (modes?.sequential) {
+      out[archetype] = {
+        sequential: modes.sequential.map((e) => e.id)
+      };
+    }
+  }
+  return out;
+})();
 function resolveStarterForMode(archetype, toolOrchestration, allChains) {
   if (toolOrchestration === "sequential") {
     const overlay = STARTER_CHAINS_BY_MODE[archetype]?.sequential;
@@ -3054,6 +3244,114 @@ function getAllStarterChains() {
   }
   return out;
 }
+function getSequentialStarterChain(archetype) {
+  const overlay = STARTER_CHAINS_BY_MODE[archetype]?.sequential;
+  return overlay ? [...overlay] : void 0;
+}
+function copyEntry(e) {
+  const out = { id: e.id, grounding: e.grounding };
+  if (e.reason !== void 0) out.reason = e.reason;
+  if (e.n !== void 0) out.n = e.n;
+  return out;
+}
+function lookupStaticEntry(id, archetype) {
+  const archetypeEntries = STARTER_CHAINS_GROUNDED[archetype];
+  if (archetypeEntries) {
+    const hit = archetypeEntries.find((e) => e.id === id);
+    if (hit) return hit;
+  }
+  const seqOverlay = STARTER_CHAINS_BY_MODE_GROUNDED[archetype]?.sequential;
+  if (seqOverlay) {
+    const hit = seqOverlay.find((e) => e.id === id);
+    if (hit) return hit;
+  }
+  return void 0;
+}
+function resolveGroundedChainForArchetype(archetype, toolOrchestration) {
+  if (toolOrchestration === "sequential") {
+    const overlay = STARTER_CHAINS_BY_MODE_GROUNDED[archetype]?.sequential;
+    if (overlay) return overlay.map(copyEntry);
+  }
+  const allChains = loadChainsFromBrain();
+  const ids = allChains[archetype];
+  if (!ids) return void 0;
+  return ids.map((id) => {
+    const known = lookupStaticEntry(id, archetype);
+    if (known) return copyEntry(known);
+    return { id, grounding: "judgment" };
+  });
+}
+function getDefaultFallbackChainWithGrounding(opts) {
+  const {
+    archetype,
+    primary,
+    maxDepth = 3,
+    policy,
+    reachability,
+    toolOrchestration
+  } = opts;
+  if (maxDepth < 1) {
+    throw new Error(
+      `getDefaultFallbackChainWithGrounding: maxDepth must be >= 1, got ${maxDepth}`
+    );
+  }
+  const starter = resolveGroundedChainForArchetype(archetype, toolOrchestration);
+  if (!starter) {
+    throw new Error(
+      `getDefaultFallbackChainWithGrounding: unknown archetype "${archetype}". Known: ${Object.keys(STARTER_CHAINS_GROUNDED).join(", ")}`
+    );
+  }
+  let chain;
+  if (primary) {
+    const primaryEntry = (() => {
+      const inStarter = starter.find((e) => e.id === primary);
+      if (inStarter) return copyEntry(inStarter);
+      const knownAnywhere = lookupStaticEntry(primary, archetype);
+      if (knownAnywhere) return { ...copyEntry(knownAnywhere), id: primary };
+      return { id: primary, grounding: "judgment" };
+    })();
+    chain = [primaryEntry, ...starter.filter((e) => e.id !== primary)];
+  } else {
+    chain = [...starter];
+  }
+  if (policy?.blockedModels && policy.blockedModels.length > 0) {
+    const blocked = new Set(policy.blockedModels);
+    chain = chain.filter((e) => !blocked.has(e.id));
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const deduped = [];
+  for (const e of chain) {
+    if (!seen.has(e.id)) {
+      seen.add(e.id);
+      deduped.push(e);
+    }
+  }
+  let filtered = deduped;
+  if (reachability) {
+    filtered = deduped.filter((e) => isModelReachable(e.id, reachability));
+  }
+  return filtered.slice(0, maxDepth);
+}
+function getStarterChainWithGrounding(archetype) {
+  const entries = STARTER_CHAINS_GROUNDED[archetype];
+  if (!entries) {
+    throw new Error(
+      `getStarterChainWithGrounding: unknown archetype "${archetype}"`
+    );
+  }
+  return entries.map(copyEntry);
+}
+function getAllStarterChainsWithGrounding() {
+  const out = {};
+  for (const [archetype, entries] of Object.entries(STARTER_CHAINS_GROUNDED)) {
+    out[archetype] = entries.map(copyEntry);
+  }
+  return out;
+}
+function getSequentialStarterChainWithGrounding(archetype) {
+  const overlay = STARTER_CHAINS_BY_MODE_GROUNDED[archetype]?.sequential;
+  return overlay ? overlay.map(copyEntry) : void 0;
+}
 function ensureCrossProviderTail(opts) {
   const { chain, archetype, apiKeys, envSource } = opts;
   if (chain.length < 1) return { chain };
@@ -3790,38 +4088,6 @@ function clamp(n) {
   return Math.max(0, Math.min(1, n));
 }
 
-// src/archetype-perf-brain.ts
-function isPerfRow(x) {
-  if (!x || typeof x !== "object") return false;
-  const r = x;
-  return typeof r.model_id === "string" && typeof r.archetype === "string" && typeof r.perf_score === "number";
-}
-function mapRowsToPerfMap(rows) {
-  const out = /* @__PURE__ */ new Map();
-  for (const row of rows) {
-    if (!isPerfRow(row)) continue;
-    const existing = out.get(row.model_id) ?? {};
-    existing[row.archetype] = row.perf_score;
-    out.set(row.model_id, existing);
-  }
-  return out;
-}
-function bundledArchetypePerf() {
-  const out = /* @__PURE__ */ new Map();
-  for (const profile of allProfiles()) {
-    if (profile.archetypePerf) out.set(profile.id, profile.archetypePerf);
-  }
-  return out;
-}
-var loadArchetypePerfFromBrain = createBrainQueryCache({
-  table: "kgauto_archetype_perf",
-  mapRows: mapRowsToPerfMap,
-  bundledFallback: bundledArchetypePerf
-});
-function getArchetypePerfScore(modelId, archetype) {
-  return loadArchetypePerfFromBrain().get(modelId)?.[archetype] ?? 5;
-}
-
 // src/models-brain.ts
 function isModelRow(x) {
   if (!x || typeof x !== "object") return false;
@@ -3954,6 +4220,7 @@ function compile2(ir, opts) {
   CallError,
   DIALECT_VERSION,
   INTENT_ARCHETYPES,
+  MEASURED_GROUNDING_MIN_N,
   PROVIDER_ENV_KEYS,
   allProfiles,
   bucketContext,
@@ -3967,18 +4234,25 @@ function compile2(ir, opts) {
   countTokens,
   execute,
   getAllStarterChains,
+  getAllStarterChainsWithGrounding,
   getArchetypePerfScore,
   getDefaultFallbackChain,
+  getDefaultFallbackChainWithGrounding,
   getProfile,
   getReachabilityDiagnostic,
+  getSequentialStarterChain,
+  getSequentialStarterChainWithGrounding,
   getStarterChain,
+  getStarterChainWithGrounding,
   hashShape,
   isArchetype,
+  isBrainQueryActiveFor,
   isModelReachable,
   isProviderReachable,
   learningKey,
   loadAliasesFromBrain,
   loadArchetypePerfFromBrain,
+  loadArchetypePerfNFromBrain,
   loadChainsFromBrain,
   loadModelsFromBrain,
   loadPricingFromBrain,