@warmdrift/kgauto-compiler 2.0.0-alpha.19 → 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,12 +56,14 @@ __export(index_exports, {
   learningKey: () => learningKey,
   loadAliasesFromBrain: () => loadAliasesFromBrain,
   loadArchetypePerfFromBrain: () => loadArchetypePerfFromBrain,
+  loadArchetypePerfNFromBrain: () => loadArchetypePerfNFromBrain,
   loadChainsFromBrain: () => loadChainsFromBrain,
   loadModelsFromBrain: () => loadModelsFromBrain,
   loadPricingFromBrain: () => loadPricingFromBrain,
   profileToRow: () => profileToRow,
   profilesByProvider: () => profilesByProvider,
   record: () => record,
+  recordOutcome: () => recordOutcome,
   resetTokenizer: () => resetTokenizer,
   resolvePricingAt: () => resolvePricingAt,
   resolveProviderKey: () => resolveProviderKey,
@@ -337,7 +345,11 @@ function passApplyCliffs(ir, profile, estimatedInputTokens) {
   const mutations = [];
   const hints = { qualityWarning: [] };
   let nextIR = ir;
+  const sequentialMode = nextIR.constraints?.toolOrchestration === "sequential";
   for (const cliff of profile.cliffs) {
+    if (sequentialMode && cliff.reason.includes("L-040")) {
+      continue;
+    }
     let triggered = false;
     switch (cliff.metric) {
       case "input_tokens":
@@ -2087,8 +2099,19 @@ function compile(ir, opts = {}) {
     cacheableTokens: lowered.diagnostics.cacheableTokens,
     estimatedCacheSavingsUsd: lowered.diagnostics.estimatedCacheSavingsUsd,
     historyCacheableTokens: lowered.diagnostics.historyCacheableTokens,
-    historyTokensTotal: compressed.historyTokensTotal
+    historyTokensTotal: compressed.historyTokensTotal,
+    // alpha.20 E3: mirror the consumer's declared mode for Glass-Box +
+    // brain observability. Undefined when not declared (pre-alpha.20).
+    toolOrchestration: ir.constraints?.toolOrchestration
   };
+  if (ir.intent.archetype === "hunt" && ir.constraints?.toolOrchestration === "sequential") {
+    accumulatedMutations.push({
+      id: "sequential-mode-chain-selected",
+      source: "tool_orchestration",
+      passName: "compile",
+      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 advisories = runAdvisor(
     ir,
     {
@@ -2352,7 +2375,9 @@ function registerCompile(appId, archetype, ir, result) {
     mutationsApplied: result.mutationsApplied.map((m) => m.id),
     startedAt: Date.now(),
     historyCacheableTokens: result.diagnostics.historyCacheableTokens,
-    historyTokensTotal: result.diagnostics.historyTokensTotal
+    historyTokensTotal: result.diagnostics.historyTokensTotal,
+    // alpha.20 E3: capture consumer's declared mode for the brain payload.
+    toolOrchestration: result.diagnostics.toolOrchestration
   });
 }
 async function record(input) {
@@ -2365,11 +2390,22 @@ async function record(input) {
   const config = activeConfig;
   const fetchFn = config.fetchImpl ?? fetch;
   const send = async () => {
+    let outcomeId;
     try {
       const res = await fetchFn(`${config.endpoint}/outcomes`, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
+          // alpha.20: request the inserted row back so we can JOIN advisories
+          // to it via outcome_id. PostgREST returns the row when
+          // `Prefer: return=representation` is set; proxies that pass the
+          // header through (the recommended `const row = { ...body }` shape
+          // from OutcomePayload's forward-compat rule) will surface
+          // the row id. Proxies that don't (legacy / hand-rolled shapes)
+          // simply produce no parseable id → secondary advisory POST is
+          // skipped silently. Best-effort — primary outcome row is the
+          // load-bearing write.
+          Prefer: "return=representation",
           ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}
         },
         body: JSON.stringify(payload)
@@ -2378,6 +2414,29 @@ async function record(input) {
         const text = await res.text().catch(() => "<no body>");
         throw new Error(`brain ${res.status}: ${text}`);
       }
+      outcomeId = await tryExtractOutcomeId(res);
+    } catch (err) {
+      (config.onError ?? defaultOnError2)(err);
+      return;
+    }
+    const advisories = input.advisories;
+    if (!advisories || advisories.length === 0) return;
+    if (outcomeId === void 0) return;
+    try {
+      const advisoryPayload = advisories.map((a) => buildAdvisoryRow(outcomeId, a));
+      const res = await fetchFn(`${config.endpoint}/compile_outcome_advisories`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Prefer: "return=minimal",
+          ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}
+        },
+        body: JSON.stringify(advisoryPayload)
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "<no body>");
+        throw new Error(`brain advisories ${res.status}: ${text}`);
+      }
     } catch (err) {
       (config.onError ?? defaultOnError2)(err);
     }
@@ -2427,7 +2486,12 @@ function buildPayload(input, reg) {
     cost_usd_actual: costUsdActual,
     ttft_ms: input.ttftMs,
     history_cacheable_tokens: reg?.historyCacheableTokens,
-    history_tokens_at_compile: reg?.historyTokensTotal
+    history_tokens_at_compile: reg?.historyTokensTotal,
+    // alpha.20 E3: mirror consumer's declared tool-orchestration mode so
+    // the brain can measure per-mode model perf separately (DeepSeek in
+    // sequential vs parallel mode is two different stories — L-040).
+    // Null when consumer hadn't adopted the constraint yet.
+    tool_orchestration: reg?.toolOrchestration ?? null
   };
 }
 function computeCostUsd(modelId, tokensIn, tokensOut) {
@@ -2444,6 +2508,77 @@ function computeCostUsd(modelId, tokensIn, tokensOut) {
   const outUsd = tokensOut / 1e6 * profile.costOutputPer1m;
   return Math.round((inUsd + outUsd) * 1e6) / 1e6;
 }
+async function tryExtractOutcomeId(res) {
+  try {
+    const ct = res.headers?.get?.("content-type") ?? "";
+    if (ct && !ct.includes("application/json")) return void 0;
+    if (typeof res.json !== "function") return void 0;
+    const body = await res.json();
+    if (Array.isArray(body) && body.length > 0) {
+      const first = body[0];
+      const id = first?.id;
+      if (typeof id === "number") return id;
+    } else if (body && typeof body === "object") {
+      const id = body.id;
+      if (typeof id === "number") return id;
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+function buildAdvisoryRow(outcomeId, a) {
+  return {
+    outcome_id: outcomeId,
+    code: a.code,
+    level: a.level,
+    message: a.message,
+    ...a.recommendationType ? { recommendation_type: a.recommendationType } : {},
+    ...a.suggestion ? { suggestion: a.suggestion } : {},
+    ...a.docsUrl ? { docs_url: a.docsUrl } : {}
+  };
+}
+async function recordOutcome(input) {
+  if (!activeConfig) {
+    return { ok: false, reason: "brain_not_configured" };
+  }
+  const config = activeConfig;
+  const fetchFn = config.fetchImpl ?? fetch;
+  const payload = {
+    outcome_id: input.outcomeId,
+    outcome: input.outcome,
+    rating: input.rating ?? null,
+    reason: input.reason ?? null,
+    observed_confidence: input.observedConfidence ?? null
+  };
+  const send = async () => {
+    try {
+      const res = await fetchFn(`${config.endpoint}/compile_outcome_quality`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}
+        },
+        body: JSON.stringify(payload)
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "<no body>");
+        const err = new Error(`brain ${res.status}: ${text}`);
+        (config.onError ?? defaultOnError2)(err);
+        return { ok: false, reason: "persistence_failed" };
+      }
+      return { ok: true };
+    } catch (err) {
+      (config.onError ?? defaultOnError2)(err);
+      return { ok: false, reason: "persistence_failed" };
+    }
+  };
+  if (config.sync) {
+    return send();
+  }
+  void send();
+  return { ok: true };
+}
 
 // src/ir.ts
 var CallError = class extends Error {
@@ -2770,92 +2905,135 @@ 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).
+  // 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 = (() => {
+  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: [
+      {
+        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;
+    if (overlay) return [...overlay];
+  }
+  return allChains[archetype];
+}
 function getDefaultFallbackChain(opts) {
-  const { archetype, primary, maxDepth = 3, policy, reachability } = opts;
+  const { archetype, primary, maxDepth = 3, policy, reachability, toolOrchestration } = opts;
   if (maxDepth < 1) {
     throw new Error(
       `getDefaultFallbackChain: maxDepth must be >= 1, got ${maxDepth}`
     );
   }
   const allChains = loadChainsFromBrain();
-  const starter = allChains[archetype];
+  const starter = resolveStarterForMode(archetype, toolOrchestration, allChains);
   if (!starter) {
     throw new Error(
       `getDefaultFallbackChain: unknown archetype "${archetype}". Known: ${Object.keys(allChains).join(", ")}`
@@ -2901,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 };
@@ -3653,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()) {
@@ -3660,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
@@ -3801,6 +4112,7 @@ function compile2(ir, opts) {
   CallError,
   DIALECT_VERSION,
   INTENT_ARCHETYPES,
+  MEASURED_GROUNDING_MIN_N,
   PROVIDER_ENV_KEYS,
   allProfiles,
   bucketContext,
@@ -3814,11 +4126,16 @@ function compile2(ir, opts) {
   countTokens,
   execute,
   getAllStarterChains,
+  getAllStarterChainsWithGrounding,
   getArchetypePerfScore,
   getDefaultFallbackChain,
+  getDefaultFallbackChainWithGrounding,
   getProfile,
   getReachabilityDiagnostic,
+  getSequentialStarterChain,
+  getSequentialStarterChainWithGrounding,
   getStarterChain,
+  getStarterChainWithGrounding,
   hashShape,
   isArchetype,
   isModelReachable,
@@ -3826,12 +4143,14 @@ function compile2(ir, opts) {
   learningKey,
   loadAliasesFromBrain,
   loadArchetypePerfFromBrain,
+  loadArchetypePerfNFromBrain,
   loadChainsFromBrain,
   loadModelsFromBrain,
   loadPricingFromBrain,
   profileToRow,
   profilesByProvider,
   record,
+  recordOutcome,
   resetTokenizer,
   resolvePricingAt,
   resolveProviderKey,