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

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,11 +39,16 @@ __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,
   isModelReachable: () => isModelReachable,
@@ -50,6 +56,7 @@ __export(index_exports, {
   learningKey: () => learningKey,
   loadAliasesFromBrain: () => loadAliasesFromBrain,
   loadArchetypePerfFromBrain: () => loadArchetypePerfFromBrain,
+  loadArchetypePerfNFromBrain: () => loadArchetypePerfNFromBrain,
   loadChainsFromBrain: () => loadChainsFromBrain,
   loadModelsFromBrain: () => loadModelsFromBrain,
   loadPricingFromBrain: () => loadPricingFromBrain,
@@ -2898,101 +2905,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 +3079,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 };
@@ -3806,6 +3939,17 @@ function mapRowsToPerfMap(rows) {
   }
   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()) {
@@ -3813,13 +3957,27 @@ function bundledArchetypePerf() {
   }
   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) {
-  return loadArchetypePerfFromBrain().get(modelId)?.[archetype] ?? 5;
+  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/models-brain.ts
@@ -3954,6 +4112,7 @@ function compile2(ir, opts) {
   CallError,
   DIALECT_VERSION,
   INTENT_ARCHETYPES,
+  MEASURED_GROUNDING_MIN_N,
   PROVIDER_ENV_KEYS,
   allProfiles,
   bucketContext,
@@ -3967,11 +4126,16 @@ function compile2(ir, opts) {
   countTokens,
   execute,
   getAllStarterChains,
+  getAllStarterChainsWithGrounding,
   getArchetypePerfScore,
   getDefaultFallbackChain,
+  getDefaultFallbackChainWithGrounding,
   getProfile,
   getReachabilityDiagnostic,
+  getSequentialStarterChain,
+  getSequentialStarterChainWithGrounding,
   getStarterChain,
+  getStarterChainWithGrounding,
   hashShape,
   isArchetype,
   isModelReachable,
@@ -3979,6 +4143,7 @@ function compile2(ir, opts) {
   learningKey,
   loadAliasesFromBrain,
   loadArchetypePerfFromBrain,
+  loadArchetypePerfNFromBrain,
   loadChainsFromBrain,
   loadModelsFromBrain,
   loadPricingFromBrain,