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

package/dist/index.mjs

@@ -1701,101 +1701,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;
@@ -1857,6 +1875,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 };
@@ -2321,6 +2447,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()) {
@@ -2328,13 +2465,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
@@ -2468,6 +2619,7 @@ export {
   CallError,
   DIALECT_VERSION,
   INTENT_ARCHETYPES,
+  MEASURED_GROUNDING_MIN_N,
   PROVIDER_ENV_KEYS,
   allProfiles,
   bucketContext,
@@ -2481,11 +2633,16 @@ export {
   countTokens,
   execute,
   getAllStarterChains,
+  getAllStarterChainsWithGrounding,
   getArchetypePerfScore,
   getDefaultFallbackChain,
+  getDefaultFallbackChainWithGrounding,
   getProfile,
   getReachabilityDiagnostic,
+  getSequentialStarterChain,
+  getSequentialStarterChainWithGrounding,
   getStarterChain,
+  getStarterChainWithGrounding,
   hashShape,
   isArchetype,
   isModelReachable,
@@ -2493,6 +2650,7 @@ export {
   learningKey,
   loadAliasesFromBrain,
   loadArchetypePerfFromBrain,
+  loadArchetypePerfNFromBrain,
   loadChainsFromBrain,
   loadModelsFromBrain,
   loadPricingFromBrain,

package/dist/{ir-DTMbSnyE.d.mts → ir-CruZBtpK.d.mts}

@@ -741,5 +741,60 @@ interface OutcomeResult {
     /** Stable reason code when ok=false. One of: 'brain_not_configured' | 'persistence_failed'. */
     reason?: string;
 }
+/**
+ * alpha.21 (s78 Entry 1): provenance label on a chain entry. Surfaces WHY
+ * an entry sits where it sits so consumers can distinguish:
+ *
+ *   - 'measured'         brain has N>=10 rows with a measurable quality
+ *                        outcome backing this placement. The number lives on
+ *                        `ChainEntry.n`.
+ *   - 'capability-fact'  inclusion or exclusion driven by a published or
+ *                        measured CAPABILITY (L-040 cliff, ctx window cap,
+ *                        structured-output support). Not an opinion — a
+ *                        fact about what the model can/can't do.
+ *   - 'judgment'         engineer's pick, no measured backing yet. Cold-start
+ *                        prior; entirely valid until evidence accumulates.
+ *
+ * "Judgment" is HONEST, not a downgrade. Most of `STARTER_CHAINS` lands here
+ * in alpha.21 — that's the point: consumers can SEE the grounding gap and
+ * prioritize the measurement work that would graduate them to 'measured'.
+ */
+type Grounding = 'measured' | 'capability-fact' | 'judgment';
+/**
+ * alpha.21 (s78 Entry 1): a single position in a fallback chain, carrying its
+ * provenance label and an optional human-readable reason. The shape replaces
+ * the old `string[]` representation everywhere chains are surfaced externally.
+ *
+ * `n` is REQUIRED when `grounding === 'measured'` — the runtime helper
+ * `makeMeasuredEntry()` enforces this. For 'capability-fact' and 'judgment'
+ * entries, `n` is undefined.
+ */
+interface ChainEntry {
+    /** Canonical model id (post-alias). */
+    id: string;
+    /** Why this entry sits in this position. */
+    grounding: Grounding;
+    /**
+     * Optional one-liner explaining the grounding decision. The inline comments
+     * that historically lived next to STARTER_CHAINS entries are now expressed
+     * here as machine-readable text.
+     */
+    reason?: string;
+    /**
+     * When `grounding === 'measured'`, the brain row count that backs this
+     * placement. Undefined for 'capability-fact' and 'judgment' entries.
+     */
+    n?: number;
+}
+/**
+ * alpha.21 introspection shape — a per-archetype chain with grounding on
+ * every position. Consumers reading this never see naked string ids;
+ * everything carries provenance.
+ */
+interface ChainWithGrounding {
+    archetype: IntentArchetypeName;
+    /** Ordered: position 0 = primary, rising index = fallback positions. */
+    entries: ChainEntry[];
+}
 
-export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type RecordOutcomeInput as e, type OracleScore as f, type CompileResult as g, type Provider as h, type CallAttempt as i, CallError as j, type Constraints as k, type MutationApplied as l, type NormalizedTokens as m, type OutcomeKind as n, type PromptSection as o, type ToolDefinition as p };
+export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type Grounding as G, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type RecordOutcomeInput as e, type OracleScore as f, type CompileResult as g, type Provider as h, type ChainEntry as i, type CallAttempt as j, CallError as k, type ChainWithGrounding as l, type Constraints as m, type MutationApplied as n, type NormalizedTokens as o, type OutcomeKind as p, type PromptSection as q, type ToolDefinition as r };

package/dist/{ir-CsTU4cMB.d.ts → ir-Wr5lc8Mi.d.ts}

@@ -741,5 +741,60 @@ interface OutcomeResult {
     /** Stable reason code when ok=false. One of: 'brain_not_configured' | 'persistence_failed'. */
     reason?: string;
 }
+/**
+ * alpha.21 (s78 Entry 1): provenance label on a chain entry. Surfaces WHY
+ * an entry sits where it sits so consumers can distinguish:
+ *
+ *   - 'measured'         brain has N>=10 rows with a measurable quality
+ *                        outcome backing this placement. The number lives on
+ *                        `ChainEntry.n`.
+ *   - 'capability-fact'  inclusion or exclusion driven by a published or
+ *                        measured CAPABILITY (L-040 cliff, ctx window cap,
+ *                        structured-output support). Not an opinion — a
+ *                        fact about what the model can/can't do.
+ *   - 'judgment'         engineer's pick, no measured backing yet. Cold-start
+ *                        prior; entirely valid until evidence accumulates.
+ *
+ * "Judgment" is HONEST, not a downgrade. Most of `STARTER_CHAINS` lands here
+ * in alpha.21 — that's the point: consumers can SEE the grounding gap and
+ * prioritize the measurement work that would graduate them to 'measured'.
+ */
+type Grounding = 'measured' | 'capability-fact' | 'judgment';
+/**
+ * alpha.21 (s78 Entry 1): a single position in a fallback chain, carrying its
+ * provenance label and an optional human-readable reason. The shape replaces
+ * the old `string[]` representation everywhere chains are surfaced externally.
+ *
+ * `n` is REQUIRED when `grounding === 'measured'` — the runtime helper
+ * `makeMeasuredEntry()` enforces this. For 'capability-fact' and 'judgment'
+ * entries, `n` is undefined.
+ */
+interface ChainEntry {
+    /** Canonical model id (post-alias). */
+    id: string;
+    /** Why this entry sits in this position. */
+    grounding: Grounding;
+    /**
+     * Optional one-liner explaining the grounding decision. The inline comments
+     * that historically lived next to STARTER_CHAINS entries are now expressed
+     * here as machine-readable text.
+     */
+    reason?: string;
+    /**
+     * When `grounding === 'measured'`, the brain row count that backs this
+     * placement. Undefined for 'capability-fact' and 'judgment' entries.
+     */
+    n?: number;
+}
+/**
+ * alpha.21 introspection shape — a per-archetype chain with grounding on
+ * every position. Consumers reading this never see naked string ids;
+ * everything carries provenance.
+ */
+interface ChainWithGrounding {
+    archetype: IntentArchetypeName;
+    /** Ordered: position 0 = primary, rising index = fallback positions. */
+    entries: ChainEntry[];
+}
 
-export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type RecordOutcomeInput as e, type OracleScore as f, type CompileResult as g, type Provider as h, type CallAttempt as i, CallError as j, type Constraints as k, type MutationApplied as l, type NormalizedTokens as m, type OutcomeKind as n, type PromptSection as o, type ToolDefinition as p };
+export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type Grounding as G, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type RecordOutcomeInput as e, type OracleScore as f, type CompileResult as g, type Provider as h, type ChainEntry as i, type CallAttempt as j, CallError as k, type ChainWithGrounding as l, type Constraints as m, type MutationApplied as n, type NormalizedTokens as o, type OutcomeKind as p, type PromptSection as q, type ToolDefinition as r };

package/dist/profiles.d.mts

@@ -1,4 +1,4 @@
-import { h as Provider } from './ir-DTMbSnyE.mjs';
+import { h as Provider } from './ir-CruZBtpK.mjs';
 import { IntentArchetypeName } from './dialect.mjs';
 
 /**

package/dist/profiles.d.ts

@@ -1,4 +1,4 @@
-import { h as Provider } from './ir-CsTU4cMB.js';
+import { h as Provider } from './ir-Wr5lc8Mi.js';
 import { IntentArchetypeName } from './dialect.js';
 
 /**

package/dist/{types-CwtaDaWN.d.ts → types-BiZKJU41.d.ts}

@@ -1,4 +1,4 @@
-import { l as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, i as CallAttempt } from './ir-CsTU4cMB.js';
+import { n as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, j as CallAttempt } from './ir-Wr5lc8Mi.js';
 
 /**
  * Glass-Box observability types (alpha.17).

package/dist/{types-BYj1Kl2m.d.mts → types-zk238uNL.d.mts}

@@ -1,4 +1,4 @@
-import { l as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, i as CallAttempt } from './ir-DTMbSnyE.mjs';
+import { n as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, j as CallAttempt } from './ir-CruZBtpK.mjs';
 
 /**
  * Glass-Box observability types (alpha.17).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmdrift/kgauto-compiler",
-  "version": "2.0.0-alpha.20",
+  "version": "2.0.0-alpha.21",
   "description": "Prompt compiler + central learning brain for multi-model AI apps. Swap models without rewriting prompts.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",