@warmdrift/kgauto-compiler 2.0.0-alpha.37 → 2.0.0-alpha.38

package/dist/index.d.mts

@@ -203,11 +203,28 @@ interface BrainQueryConfig {
     pricing?: boolean;
     /** Default true when endpoint set. Brain-driven model registry + aliases. */
     models?: boolean;
+    /**
+     * alpha.38 — opt-in compile-time advisor for stale exclusions. Default
+     * `true` when endpoint is set. When enabled, the library reads
+     * `exclusion_findings` from the central kgauto-dashboard for the consumer's
+     * `app_id` (no consumer-side proxy work required) and surfaces a
+     * `stale-exclusion-candidate` advisory when compile()'s archetype has a
+     * recommend-probe finding open. Set `false` to silence (no fetch, no
+     * advisory).
+     */
+    findingsExclusions?: boolean;
     /** SWR window in ms. Default 300_000 (5 min). */
     cacheTtlMs?: number;
     /** Override the GET URL when the read endpoint differs from the write one.
      *  Defaults to `${endpoint}/v2/config` when omitted. */
     configEndpoint?: string;
+    /**
+     * alpha.38 — override the findings endpoint when the consumer wants to
+     * proxy `exclusion_findings` reads through their own service rather than
+     * reading directly from the kgauto-dashboard. Library appends `?app_id=X`.
+     * Defaults to `https://kgauto-dashboard.vercel.app/api/kgauto-v2/findings/exclusions`.
+     */
+    findingsEndpoint?: string;
 }
 interface BrainConfig {
     /** Brain HTTP endpoint base URL (e.g., https://kgauto-brain.vercel.app/api). */
@@ -1465,6 +1482,105 @@ declare const loadModelsFromBrain: () => Map<string, ModelProfile>;
  */
 declare const loadAliasesFromBrain: () => Record<string, string>;
 
+/**
+ * exclusion-findings-brain — alpha.38 KG-19 adapter.
+ *
+ * Per-tenant SWR cache for the `exclusion_findings` table populated by the
+ * `kgauto-exclusion-re-evaluation-watch` cron (alpha.37 substrate). Distinct
+ * from the cross-tenant `brain-query.ts` snapshot because exclusion findings
+ * are scoped per `app_id` — one process = one consumer = one appId, but the
+ * cache key supports multi-app processes by keying snapshots by appId.
+ *
+ * Architecture mirrors `brain-query.ts` but with a per-(appId) snapshot:
+ *
+ * - **Sync API surface.** `getStaleExclusionFindings({ appId, archetype })`
+ *   returns `ExclusionFindingRow[]` immediately. First call returns the
+ *   bundled fallback (empty array); async refresh fires in background;
+ *   subsequent calls within TTL return brain data.
+ *
+ * - **Per-appId snapshot.** Each appId gets its own cache entry. One fetch
+ *   per appId per TTL window. Tests can reset between cases.
+ *
+ * - **Tolerant.** Brain down / endpoint misconfigured / unexpected shape →
+ *   silent bundled fallback (empty array). Never throws. Warns once per
+ *   process per error to avoid log spam.
+ *
+ * - **Opt-in.** Activation gated on `configureExclusionFindingsBrain()`
+ *   having been called with a runtime. The public `configureBrain()` in
+ *   brain.ts wires this up automatically when `BrainConfig.brainQuery
+ *   .findingsExclusions !== false`.
+ *
+ * Default endpoint:
+ *   `https://kgauto-dashboard.vercel.app/api/kgauto-v2/findings/exclusions`
+ *   The route accepts `?app_id=X` and returns a JSON array of findings
+ *   for that app filtered to `resolved_at IS NULL`. Public read; data
+ *   carries no consumer PII (app id, archetype, model id, cost ratio,
+ *   savings estimate).
+ */
+/**
+ * Shape of one row from the `exclusion_findings` cache table. Mirrors the
+ * snake_case JSONB returned by the brain RPC + the dashboard endpoint.
+ * Camel-case mapping happens at the boundary (rowToFinding) so the in-memory
+ * shape stays consistent with the rest of the library.
+ */
+interface ExclusionFindingRow {
+    /** Intent archetype the finding applies to (e.g. 'hunt', 'classify'). */
+    archetype: string;
+    /** Canonical model id that the consumer has excluded (zero traffic in window). */
+    excludedModel: string;
+    /** Provider of the excluded model (e.g. 'deepseek', 'openai'). */
+    excludedProvider: string;
+    /** Detection verdict — alpha.37 ships 'recommend-probe' only. */
+    verdict: 'recommend-probe' | 'unblock' | 'stay-excluded' | 'inconclusive';
+    /**
+     * Estimated 30-day savings in USD if the excluded model becomes primary
+     * on this archetype. Null when pricing is incomplete or excluded model is
+     * more expensive than the leader.
+     */
+    estimatedSavingsUsd30d: number | null;
+    /** Renderable summary; produced by the detector / RPC. */
+    message: string;
+    /** Actionable recommendation; produced by the detector / RPC. */
+    suggestion: string;
+    /** Detector confidence tier. */
+    confidence: 'high' | 'medium' | 'low';
+    /**
+     * Free-form evidence pack (cost ratio, leader info, promo flags, parallel-
+     * tool hint, etc.). Surfaced verbatim to advisor rules for richer messages.
+     * Optional — older detector runs may not populate every field.
+     */
+    evidence?: Record<string, unknown>;
+}
+/**
+ * Default endpoint hosted on the kgauto-dashboard. Public read — data carries
+ * no PII (app id, archetype, model id, cost ratio, savings estimate). Mirrors
+ * the cross-tenant `/api/kgauto-v2/config` pattern.
+ */
+declare const DEFAULT_FINDINGS_ENDPOINT = "https://kgauto-dashboard.vercel.app/api/kgauto-v2/findings/exclusions";
+/**
+ * Sync introspection — is the findings-brain active? Used by advisor rules
+ * to decide whether to even attempt a read.
+ */
+declare function isExclusionFindingsBrainActive(): boolean;
+interface GetExclusionFindingsOpts {
+    /** App id to read findings for. Required. */
+    appId: string;
+    /**
+     * Optional archetype filter. When set, returns only findings where
+     * `archetype` matches. When omitted, returns all findings for the app.
+     */
+    archetype?: string;
+}
+/**
+ * Sync reader. Returns the cached findings for `appId`, optionally filtered
+ * to a single archetype. First call returns empty array and triggers async
+ * refresh; subsequent calls within TTL return brain data.
+ *
+ * NEVER throws. Brain down / endpoint misconfigured / mapper exception →
+ * empty array.
+ */
+declare function getStaleExclusionFindings(opts: GetExclusionFindingsOpts): ExclusionFindingRow[];
+
 /**
  * @warmdrift/kgauto v2 — prompt compiler + central learning brain.
  *
@@ -1511,4 +1627,4 @@ declare const loadAliasesFromBrain: () => Record<string, string>;
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, DEFAULT_FINDINGS_ENDPOINT, type ExclusionFindingRow, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };

package/dist/index.d.ts

@@ -203,11 +203,28 @@ interface BrainQueryConfig {
     pricing?: boolean;
     /** Default true when endpoint set. Brain-driven model registry + aliases. */
     models?: boolean;
+    /**
+     * alpha.38 — opt-in compile-time advisor for stale exclusions. Default
+     * `true` when endpoint is set. When enabled, the library reads
+     * `exclusion_findings` from the central kgauto-dashboard for the consumer's
+     * `app_id` (no consumer-side proxy work required) and surfaces a
+     * `stale-exclusion-candidate` advisory when compile()'s archetype has a
+     * recommend-probe finding open. Set `false` to silence (no fetch, no
+     * advisory).
+     */
+    findingsExclusions?: boolean;
     /** SWR window in ms. Default 300_000 (5 min). */
     cacheTtlMs?: number;
     /** Override the GET URL when the read endpoint differs from the write one.
      *  Defaults to `${endpoint}/v2/config` when omitted. */
     configEndpoint?: string;
+    /**
+     * alpha.38 — override the findings endpoint when the consumer wants to
+     * proxy `exclusion_findings` reads through their own service rather than
+     * reading directly from the kgauto-dashboard. Library appends `?app_id=X`.
+     * Defaults to `https://kgauto-dashboard.vercel.app/api/kgauto-v2/findings/exclusions`.
+     */
+    findingsEndpoint?: string;
 }
 interface BrainConfig {
     /** Brain HTTP endpoint base URL (e.g., https://kgauto-brain.vercel.app/api). */
@@ -1465,6 +1482,105 @@ declare const loadModelsFromBrain: () => Map<string, ModelProfile>;
  */
 declare const loadAliasesFromBrain: () => Record<string, string>;
 
+/**
+ * exclusion-findings-brain — alpha.38 KG-19 adapter.
+ *
+ * Per-tenant SWR cache for the `exclusion_findings` table populated by the
+ * `kgauto-exclusion-re-evaluation-watch` cron (alpha.37 substrate). Distinct
+ * from the cross-tenant `brain-query.ts` snapshot because exclusion findings
+ * are scoped per `app_id` — one process = one consumer = one appId, but the
+ * cache key supports multi-app processes by keying snapshots by appId.
+ *
+ * Architecture mirrors `brain-query.ts` but with a per-(appId) snapshot:
+ *
+ * - **Sync API surface.** `getStaleExclusionFindings({ appId, archetype })`
+ *   returns `ExclusionFindingRow[]` immediately. First call returns the
+ *   bundled fallback (empty array); async refresh fires in background;
+ *   subsequent calls within TTL return brain data.
+ *
+ * - **Per-appId snapshot.** Each appId gets its own cache entry. One fetch
+ *   per appId per TTL window. Tests can reset between cases.
+ *
+ * - **Tolerant.** Brain down / endpoint misconfigured / unexpected shape →
+ *   silent bundled fallback (empty array). Never throws. Warns once per
+ *   process per error to avoid log spam.
+ *
+ * - **Opt-in.** Activation gated on `configureExclusionFindingsBrain()`
+ *   having been called with a runtime. The public `configureBrain()` in
+ *   brain.ts wires this up automatically when `BrainConfig.brainQuery
+ *   .findingsExclusions !== false`.
+ *
+ * Default endpoint:
+ *   `https://kgauto-dashboard.vercel.app/api/kgauto-v2/findings/exclusions`
+ *   The route accepts `?app_id=X` and returns a JSON array of findings
+ *   for that app filtered to `resolved_at IS NULL`. Public read; data
+ *   carries no consumer PII (app id, archetype, model id, cost ratio,
+ *   savings estimate).
+ */
+/**
+ * Shape of one row from the `exclusion_findings` cache table. Mirrors the
+ * snake_case JSONB returned by the brain RPC + the dashboard endpoint.
+ * Camel-case mapping happens at the boundary (rowToFinding) so the in-memory
+ * shape stays consistent with the rest of the library.
+ */
+interface ExclusionFindingRow {
+    /** Intent archetype the finding applies to (e.g. 'hunt', 'classify'). */
+    archetype: string;
+    /** Canonical model id that the consumer has excluded (zero traffic in window). */
+    excludedModel: string;
+    /** Provider of the excluded model (e.g. 'deepseek', 'openai'). */
+    excludedProvider: string;
+    /** Detection verdict — alpha.37 ships 'recommend-probe' only. */
+    verdict: 'recommend-probe' | 'unblock' | 'stay-excluded' | 'inconclusive';
+    /**
+     * Estimated 30-day savings in USD if the excluded model becomes primary
+     * on this archetype. Null when pricing is incomplete or excluded model is
+     * more expensive than the leader.
+     */
+    estimatedSavingsUsd30d: number | null;
+    /** Renderable summary; produced by the detector / RPC. */
+    message: string;
+    /** Actionable recommendation; produced by the detector / RPC. */
+    suggestion: string;
+    /** Detector confidence tier. */
+    confidence: 'high' | 'medium' | 'low';
+    /**
+     * Free-form evidence pack (cost ratio, leader info, promo flags, parallel-
+     * tool hint, etc.). Surfaced verbatim to advisor rules for richer messages.
+     * Optional — older detector runs may not populate every field.
+     */
+    evidence?: Record<string, unknown>;
+}
+/**
+ * Default endpoint hosted on the kgauto-dashboard. Public read — data carries
+ * no PII (app id, archetype, model id, cost ratio, savings estimate). Mirrors
+ * the cross-tenant `/api/kgauto-v2/config` pattern.
+ */
+declare const DEFAULT_FINDINGS_ENDPOINT = "https://kgauto-dashboard.vercel.app/api/kgauto-v2/findings/exclusions";
+/**
+ * Sync introspection — is the findings-brain active? Used by advisor rules
+ * to decide whether to even attempt a read.
+ */
+declare function isExclusionFindingsBrainActive(): boolean;
+interface GetExclusionFindingsOpts {
+    /** App id to read findings for. Required. */
+    appId: string;
+    /**
+     * Optional archetype filter. When set, returns only findings where
+     * `archetype` matches. When omitted, returns all findings for the app.
+     */
+    archetype?: string;
+}
+/**
+ * Sync reader. Returns the cached findings for `appId`, optionally filtered
+ * to a single archetype. First call returns empty array and triggers async
+ * refresh; subsequent calls within TTL return brain data.
+ *
+ * NEVER throws. Brain down / endpoint misconfigured / mapper exception →
+ * empty array.
+ */
+declare function getStaleExclusionFindings(opts: GetExclusionFindingsOpts): ExclusionFindingRow[];
+
 /**
  * @warmdrift/kgauto v2 — prompt compiler + central learning brain.
  *
@@ -1511,4 +1627,4 @@ declare const loadAliasesFromBrain: () => Record<string, string>;
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, DEFAULT_FINDINGS_ENDPOINT, type ExclusionFindingRow, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };

package/dist/index.js

@@ -25,6 +25,7 @@ __export(index_exports, {
   ALL_ARCHETYPES: () => ALL_ARCHETYPES,
   ARCHETYPE_FLOOR_DEFAULT: () => ARCHETYPE_FLOOR_DEFAULT,
   CallError: () => CallError,
+  DEFAULT_FINDINGS_ENDPOINT: () => DEFAULT_FINDINGS_ENDPOINT,
   DIALECT_VERSION: () => DIALECT_VERSION,
   INTENT_ARCHETYPES: () => INTENT_ARCHETYPES,
   MEASURED_GROUNDING_MIN_N: () => MEASURED_GROUNDING_MIN_N,
@@ -56,11 +57,13 @@ __export(index_exports, {
   getReachabilityDiagnostic: () => getReachabilityDiagnostic,
   getSequentialStarterChain: () => getSequentialStarterChain,
   getSequentialStarterChainWithGrounding: () => getSequentialStarterChainWithGrounding,
+  getStaleExclusionFindings: () => getStaleExclusionFindings,
   getStarterChain: () => getStarterChain,
   getStarterChainWithGrounding: () => getStarterChainWithGrounding,
   hashShape: () => hashShape,
   isArchetype: () => isArchetype,
   isBrainQueryActiveFor: () => isBrainQueryActiveFor,
+  isExclusionFindingsBrainActive: () => isExclusionFindingsBrainActive,
   isModelReachable: () => isModelReachable,
   isProviderReachable: () => isProviderReachable,
   learningKey: () => learningKey,
@@ -2400,6 +2403,125 @@ function getModelCompatibility(modelId, intent) {
   };
 }
 
+// src/exclusion-findings-brain.ts
+function isValidVerdict(v) {
+  return v === "recommend-probe" || v === "unblock" || v === "stay-excluded" || v === "inconclusive";
+}
+function isValidConfidence(v) {
+  return v === "high" || v === "medium" || v === "low";
+}
+function isRawFindingRow(x) {
+  if (!x || typeof x !== "object") return false;
+  const r = x;
+  return typeof r.intent_archetype === "string" && typeof r.excluded_model === "string" && typeof r.excluded_provider === "string" && typeof r.verdict === "string" && typeof r.message === "string" && typeof r.suggestion === "string" && typeof r.confidence === "string";
+}
+function mapRowsToFindings(rows) {
+  const out = [];
+  for (const row of rows) {
+    if (!isRawFindingRow(row)) continue;
+    if (!isValidVerdict(row.verdict)) continue;
+    if (!isValidConfidence(row.confidence)) continue;
+    let savings = null;
+    if (typeof row.estimated_savings_usd_30d === "number") {
+      savings = Number.isFinite(row.estimated_savings_usd_30d) ? row.estimated_savings_usd_30d : null;
+    } else if (typeof row.estimated_savings_usd_30d === "string") {
+      const n = Number(row.estimated_savings_usd_30d);
+      savings = Number.isFinite(n) ? n : null;
+    }
+    out.push({
+      archetype: row.intent_archetype,
+      excludedModel: row.excluded_model,
+      excludedProvider: row.excluded_provider,
+      verdict: row.verdict,
+      estimatedSavingsUsd30d: savings,
+      message: row.message,
+      suggestion: row.suggestion,
+      confidence: row.confidence,
+      evidence: row.evidence && typeof row.evidence === "object" ? row.evidence : void 0
+    });
+  }
+  return out;
+}
+var snapshots = /* @__PURE__ */ new Map();
+var runtime2;
+var warnedOnce = false;
+var DEFAULT_FINDINGS_ENDPOINT = "https://kgauto-dashboard.vercel.app/api/kgauto-v2/findings/exclusions";
+function configureExclusionFindingsBrain(rt) {
+  runtime2 = rt;
+  snapshots.clear();
+  warnedOnce = false;
+}
+function isExclusionFindingsBrainActive() {
+  return runtime2 !== void 0;
+}
+function getStaleExclusionFindings(opts) {
+  const rt = runtime2;
+  if (!rt) return [];
+  const appId = opts.appId;
+  if (!appId) return [];
+  let snap = snapshots.get(appId);
+  if (!snap) {
+    snap = { data: [], expiresAt: 0, refreshing: false };
+    snapshots.set(appId, snap);
+  }
+  const now = Date.now();
+  const stale = snap.expiresAt <= now;
+  if (stale && !snap.refreshing) {
+    snap.refreshing = true;
+    void asyncRefresh2(rt, appId);
+  }
+  if (opts.archetype) {
+    return snap.data.filter((f) => f.archetype === opts.archetype);
+  }
+  return snap.data;
+}
+var pendingRefreshes = /* @__PURE__ */ new Map();
+async function asyncRefresh2(rt, appId) {
+  const promise = doRefresh2(rt, appId);
+  pendingRefreshes.set(appId, promise);
+  try {
+    await promise;
+  } finally {
+    if (pendingRefreshes.get(appId) === promise) {
+      pendingRefreshes.delete(appId);
+    }
+  }
+}
+async function doRefresh2(rt, appId) {
+  const url = `${rt.endpoint}?app_id=${encodeURIComponent(appId)}`;
+  let snap = snapshots.get(appId);
+  if (!snap) {
+    snap = { data: [], expiresAt: 0, refreshing: false };
+    snapshots.set(appId, snap);
+  }
+  try {
+    const res = await rt.fetchImpl(url, { method: "GET" });
+    if (!res.ok) {
+      throw new Error(`findings ${res.status}: ${res.statusText}`);
+    }
+    const body = await res.json();
+    if (runtime2 !== rt) return;
+    const rows = Array.isArray(body) ? mapRowsToFindings(body) : [];
+    snap.data = rows;
+    snap.expiresAt = Date.now() + rt.ttlMs;
+    snap.refreshing = false;
+  } catch (err) {
+    if (runtime2 !== rt) return;
+    snap.refreshing = false;
+    snap.expiresAt = Date.now() + rt.ttlMs;
+    if (!warnedOnce) {
+      warnedOnce = true;
+      (rt.onError ?? defaultOnError2)(err);
+    }
+  }
+}
+function defaultOnError2(err) {
+  console.warn(
+    "[kgauto] exclusion-findings fetch failed (using empty fallback):",
+    err
+  );
+}
+
 // src/advisor.ts
 var QUALITY_FLOOR_FOR_RECOMMENDATION = 6;
 var TIER_DOWN_COST_RATIO = 0.5;
@@ -2419,6 +2541,9 @@ function runAdvisor(ir, result, profile, policy, phase2) {
   if (!translatorClearedToolCallCliff(phase2)) {
     out.push(...detectArchetypePerfFloorBreach(ir, profile));
   }
+  if (policy?.posture !== "locked") {
+    out.push(...detectStaleExclusionCandidate(ir));
+  }
   return out;
 }
 function translatorClearedToolCallCliff(phase2) {
@@ -2627,6 +2752,39 @@ function detectArchetypePerfFloorBreach(ir, profile) {
     }
   ];
 }
+function detectStaleExclusionCandidate(ir) {
+  if (!isExclusionFindingsBrainActive()) return [];
+  if (!ir.appId) return [];
+  const findings = getStaleExclusionFindings({
+    appId: ir.appId,
+    archetype: ir.intent.archetype
+  });
+  if (findings.length === 0) return [];
+  const ranked = [...findings].sort((a, b) => {
+    const sa = a.estimatedSavingsUsd30d ?? -Infinity;
+    const sb = b.estimatedSavingsUsd30d ?? -Infinity;
+    if (sa !== sb) return sb - sa;
+    return confidenceRank(b.confidence) - confidenceRank(a.confidence);
+  });
+  const top = ranked[0];
+  const extraCount = findings.length - 1;
+  const extraNote = extraCount > 0 ? ` (+ ${extraCount} more excluded model${extraCount === 1 ? "" : "s"} for this archetype)` : "";
+  return [
+    {
+      level: "info",
+      code: "stale-exclusion-candidate",
+      message: `${top.message}${extraNote}`,
+      suggestion: top.suggestion,
+      recommendationType: "tier-down",
+      docsUrl: "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#best-practice-advisories"
+    }
+  ];
+}
+function confidenceRank(c) {
+  if (c === "high") return 3;
+  if (c === "medium") return 2;
+  return 1;
+}
 
 // src/translator.ts
 var TRANSLATOR_FLOOR = ARCHETYPE_FLOOR_DEFAULT;
@@ -2990,20 +3148,31 @@ function configureBrain(config) {
   }
   if (enabledTables.size === 0) {
     configureBrainQuery(void 0);
-    return;
+  } else {
+    configureBrainQuery({
+      endpoint,
+      configEndpoint: bq.configEndpoint,
+      ttlMs: bq.cacheTtlMs ?? 3e5,
+      fetchImpl: config.fetchImpl ?? fetch,
+      enabledTables,
+      onError: config.onError
+    });
+  }
+  if (bq.findingsExclusions !== false) {
+    configureExclusionFindingsBrain({
+      endpoint: bq.findingsEndpoint ?? DEFAULT_FINDINGS_ENDPOINT,
+      ttlMs: bq.cacheTtlMs ?? 3e5,
+      fetchImpl: config.fetchImpl ?? fetch,
+      onError: config.onError
+    });
+  } else {
+    configureExclusionFindingsBrain(void 0);
   }
-  configureBrainQuery({
-    endpoint,
-    configEndpoint: bq.configEndpoint,
-    ttlMs: bq.cacheTtlMs ?? 3e5,
-    fetchImpl: config.fetchImpl ?? fetch,
-    enabledTables,
-    onError: config.onError
-  });
 }
 function clearBrain() {
   activeConfig = void 0;
   configureBrainQuery(void 0);
+  configureExclusionFindingsBrain(void 0);
 }
 var compileRegistry = /* @__PURE__ */ new Map();
 var REGISTRY_MAX_ENTRIES = 1e4;
@@ -3107,7 +3276,7 @@ async function record(input) {
       }
       outcomeId = await tryExtractOutcomeId(res);
     } catch (err) {
-      (config.onError ?? defaultOnError2)(err);
+      (config.onError ?? defaultOnError3)(err);
       return;
     }
     const advisories = input.advisories ?? reg?.advisoriesFromCompile;
@@ -3129,7 +3298,7 @@ async function record(input) {
         throw new Error(`brain advisories ${res.status}: ${text}`);
       }
     } catch (err) {
-      (config.onError ?? defaultOnError2)(err);
+      (config.onError ?? defaultOnError3)(err);
     }
   };
   if (config.sync) {
@@ -3138,7 +3307,7 @@ async function record(input) {
     void send();
   }
 }
-function defaultOnError2(err) {
+function defaultOnError3(err) {
   console.warn("[kgauto] brain record failed:", err);
 }
 function buildPayload(input, reg) {
@@ -3270,12 +3439,12 @@ async function recordOutcome(input) {
       if (!res.ok) {
         const text = await res.text().catch(() => "<no body>");
         const err = new Error(`brain ${res.status}: ${text}`);
-        (config.onError ?? defaultOnError2)(err);
+        (config.onError ?? defaultOnError3)(err);
         return { ok: false, reason: "persistence_failed" };
       }
       return { ok: true };
     } catch (err) {
-      (config.onError ?? defaultOnError2)(err);
+      (config.onError ?? defaultOnError3)(err);
       return { ok: false, reason: "persistence_failed" };
     }
   };
@@ -5397,6 +5566,7 @@ function compile2(ir, opts) {
   ALL_ARCHETYPES,
   ARCHETYPE_FLOOR_DEFAULT,
   CallError,
+  DEFAULT_FINDINGS_ENDPOINT,
   DIALECT_VERSION,
   INTENT_ARCHETYPES,
   MEASURED_GROUNDING_MIN_N,
@@ -5428,11 +5598,13 @@ function compile2(ir, opts) {
   getReachabilityDiagnostic,
   getSequentialStarterChain,
   getSequentialStarterChainWithGrounding,
+  getStaleExclusionFindings,
   getStarterChain,
   getStarterChainWithGrounding,
   hashShape,
   isArchetype,
   isBrainQueryActiveFor,
+  isExclusionFindingsBrainActive,
   isModelReachable,
   isProviderReachable,
   learningKey,

package/dist/index.mjs

@@ -825,6 +825,125 @@ function getArchetypePerfScore(modelId, archetype) {
   return { score, n, grounding };
 }
 
+// src/exclusion-findings-brain.ts
+function isValidVerdict(v) {
+  return v === "recommend-probe" || v === "unblock" || v === "stay-excluded" || v === "inconclusive";
+}
+function isValidConfidence(v) {
+  return v === "high" || v === "medium" || v === "low";
+}
+function isRawFindingRow(x) {
+  if (!x || typeof x !== "object") return false;
+  const r = x;
+  return typeof r.intent_archetype === "string" && typeof r.excluded_model === "string" && typeof r.excluded_provider === "string" && typeof r.verdict === "string" && typeof r.message === "string" && typeof r.suggestion === "string" && typeof r.confidence === "string";
+}
+function mapRowsToFindings(rows) {
+  const out = [];
+  for (const row of rows) {
+    if (!isRawFindingRow(row)) continue;
+    if (!isValidVerdict(row.verdict)) continue;
+    if (!isValidConfidence(row.confidence)) continue;
+    let savings = null;
+    if (typeof row.estimated_savings_usd_30d === "number") {
+      savings = Number.isFinite(row.estimated_savings_usd_30d) ? row.estimated_savings_usd_30d : null;
+    } else if (typeof row.estimated_savings_usd_30d === "string") {
+      const n = Number(row.estimated_savings_usd_30d);
+      savings = Number.isFinite(n) ? n : null;
+    }
+    out.push({
+      archetype: row.intent_archetype,
+      excludedModel: row.excluded_model,
+      excludedProvider: row.excluded_provider,
+      verdict: row.verdict,
+      estimatedSavingsUsd30d: savings,
+      message: row.message,
+      suggestion: row.suggestion,
+      confidence: row.confidence,
+      evidence: row.evidence && typeof row.evidence === "object" ? row.evidence : void 0
+    });
+  }
+  return out;
+}
+var snapshots = /* @__PURE__ */ new Map();
+var runtime;
+var warnedOnce = false;
+var DEFAULT_FINDINGS_ENDPOINT = "https://kgauto-dashboard.vercel.app/api/kgauto-v2/findings/exclusions";
+function configureExclusionFindingsBrain(rt) {
+  runtime = rt;
+  snapshots.clear();
+  warnedOnce = false;
+}
+function isExclusionFindingsBrainActive() {
+  return runtime !== void 0;
+}
+function getStaleExclusionFindings(opts) {
+  const rt = runtime;
+  if (!rt) return [];
+  const appId = opts.appId;
+  if (!appId) return [];
+  let snap = snapshots.get(appId);
+  if (!snap) {
+    snap = { data: [], expiresAt: 0, refreshing: false };
+    snapshots.set(appId, snap);
+  }
+  const now = Date.now();
+  const stale = snap.expiresAt <= now;
+  if (stale && !snap.refreshing) {
+    snap.refreshing = true;
+    void asyncRefresh(rt, appId);
+  }
+  if (opts.archetype) {
+    return snap.data.filter((f) => f.archetype === opts.archetype);
+  }
+  return snap.data;
+}
+var pendingRefreshes = /* @__PURE__ */ new Map();
+async function asyncRefresh(rt, appId) {
+  const promise = doRefresh(rt, appId);
+  pendingRefreshes.set(appId, promise);
+  try {
+    await promise;
+  } finally {
+    if (pendingRefreshes.get(appId) === promise) {
+      pendingRefreshes.delete(appId);
+    }
+  }
+}
+async function doRefresh(rt, appId) {
+  const url = `${rt.endpoint}?app_id=${encodeURIComponent(appId)}`;
+  let snap = snapshots.get(appId);
+  if (!snap) {
+    snap = { data: [], expiresAt: 0, refreshing: false };
+    snapshots.set(appId, snap);
+  }
+  try {
+    const res = await rt.fetchImpl(url, { method: "GET" });
+    if (!res.ok) {
+      throw new Error(`findings ${res.status}: ${res.statusText}`);
+    }
+    const body = await res.json();
+    if (runtime !== rt) return;
+    const rows = Array.isArray(body) ? mapRowsToFindings(body) : [];
+    snap.data = rows;
+    snap.expiresAt = Date.now() + rt.ttlMs;
+    snap.refreshing = false;
+  } catch (err) {
+    if (runtime !== rt) return;
+    snap.refreshing = false;
+    snap.expiresAt = Date.now() + rt.ttlMs;
+    if (!warnedOnce) {
+      warnedOnce = true;
+      (rt.onError ?? defaultOnError)(err);
+    }
+  }
+}
+function defaultOnError(err) {
+  console.warn(
+    "[kgauto] exclusion-findings fetch failed (using empty fallback):",
+    err
+  );
+}
+
 // src/advisor.ts
 var QUALITY_FLOOR_FOR_RECOMMENDATION = 6;
 var TIER_DOWN_COST_RATIO = 0.5;
@@ -844,6 +963,9 @@ function runAdvisor(ir, result, profile, policy, phase2) {
   if (!translatorClearedToolCallCliff(phase2)) {
     out.push(...detectArchetypePerfFloorBreach(ir, profile));
   }
+  if (policy?.posture !== "locked") {
+    out.push(...detectStaleExclusionCandidate(ir));
+  }
   return out;
 }
 function translatorClearedToolCallCliff(phase2) {
@@ -1052,6 +1174,39 @@ function detectArchetypePerfFloorBreach(ir, profile) {
     }
   ];
 }
+function detectStaleExclusionCandidate(ir) {
+  if (!isExclusionFindingsBrainActive()) return [];
+  if (!ir.appId) return [];
+  const findings = getStaleExclusionFindings({
+    appId: ir.appId,
+    archetype: ir.intent.archetype
+  });
+  if (findings.length === 0) return [];
+  const ranked = [...findings].sort((a, b) => {
+    const sa = a.estimatedSavingsUsd30d ?? -Infinity;
+    const sb = b.estimatedSavingsUsd30d ?? -Infinity;
+    if (sa !== sb) return sb - sa;
+    return confidenceRank(b.confidence) - confidenceRank(a.confidence);
+  });
+  const top = ranked[0];
+  const extraCount = findings.length - 1;
+  const extraNote = extraCount > 0 ? ` (+ ${extraCount} more excluded model${extraCount === 1 ? "" : "s"} for this archetype)` : "";
+  return [
+    {
+      level: "info",
+      code: "stale-exclusion-candidate",
+      message: `${top.message}${extraNote}`,
+      suggestion: top.suggestion,
+      recommendationType: "tier-down",
+      docsUrl: "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#best-practice-advisories"
+    }
+  ];
+}
+function confidenceRank(c) {
+  if (c === "high") return 3;
+  if (c === "medium") return 2;
+  return 1;
+}
 
 // src/translator.ts
 var TRANSLATOR_FLOOR = ARCHETYPE_FLOOR_DEFAULT;
@@ -1415,20 +1570,31 @@ function configureBrain(config) {
   }
   if (enabledTables.size === 0) {
     configureBrainQuery(void 0);
-    return;
+  } else {
+    configureBrainQuery({
+      endpoint,
+      configEndpoint: bq.configEndpoint,
+      ttlMs: bq.cacheTtlMs ?? 3e5,
+      fetchImpl: config.fetchImpl ?? fetch,
+      enabledTables,
+      onError: config.onError
+    });
+  }
+  if (bq.findingsExclusions !== false) {
+    configureExclusionFindingsBrain({
+      endpoint: bq.findingsEndpoint ?? DEFAULT_FINDINGS_ENDPOINT,
+      ttlMs: bq.cacheTtlMs ?? 3e5,
+      fetchImpl: config.fetchImpl ?? fetch,
+      onError: config.onError
+    });
+  } else {
+    configureExclusionFindingsBrain(void 0);
   }
-  configureBrainQuery({
-    endpoint,
-    configEndpoint: bq.configEndpoint,
-    ttlMs: bq.cacheTtlMs ?? 3e5,
-    fetchImpl: config.fetchImpl ?? fetch,
-    enabledTables,
-    onError: config.onError
-  });
 }
 function clearBrain() {
   activeConfig = void 0;
   configureBrainQuery(void 0);
+  configureExclusionFindingsBrain(void 0);
 }
 var compileRegistry = /* @__PURE__ */ new Map();
 var REGISTRY_MAX_ENTRIES = 1e4;
@@ -1532,7 +1698,7 @@ async function record(input) {
       }
       outcomeId = await tryExtractOutcomeId(res);
     } catch (err) {
-      (config.onError ?? defaultOnError)(err);
+      (config.onError ?? defaultOnError2)(err);
       return;
     }
     const advisories = input.advisories ?? reg?.advisoriesFromCompile;
@@ -1554,7 +1720,7 @@ async function record(input) {
         throw new Error(`brain advisories ${res.status}: ${text}`);
       }
     } catch (err) {
-      (config.onError ?? defaultOnError)(err);
+      (config.onError ?? defaultOnError2)(err);
     }
   };
   if (config.sync) {
@@ -1563,7 +1729,7 @@ async function record(input) {
     void send();
   }
 }
-function defaultOnError(err) {
+function defaultOnError2(err) {
   console.warn("[kgauto] brain record failed:", err);
 }
 function buildPayload(input, reg) {
@@ -1695,12 +1861,12 @@ async function recordOutcome(input) {
       if (!res.ok) {
         const text = await res.text().catch(() => "<no body>");
         const err = new Error(`brain ${res.status}: ${text}`);
-        (config.onError ?? defaultOnError)(err);
+        (config.onError ?? defaultOnError2)(err);
         return { ok: false, reason: "persistence_failed" };
       }
       return { ok: true };
     } catch (err) {
-      (config.onError ?? defaultOnError)(err);
+      (config.onError ?? defaultOnError2)(err);
       return { ok: false, reason: "persistence_failed" };
     }
   };
@@ -3116,6 +3282,7 @@ export {
   ALL_ARCHETYPES,
   ARCHETYPE_FLOOR_DEFAULT,
   CallError,
+  DEFAULT_FINDINGS_ENDPOINT,
   DIALECT_VERSION,
   INTENT_ARCHETYPES,
   MEASURED_GROUNDING_MIN_N,
@@ -3147,11 +3314,13 @@ export {
   getReachabilityDiagnostic,
   getSequentialStarterChain,
   getSequentialStarterChainWithGrounding,
+  getStaleExclusionFindings,
   getStarterChain,
   getStarterChainWithGrounding,
   hashShape,
   isArchetype,
   isBrainQueryActiveFor,
+  isExclusionFindingsBrainActive,
   isModelReachable,
   isProviderReachable,
   learningKey,

package/package.json

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