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

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). */
@@ -751,6 +768,80 @@ declare function markAdvisoryResolved(opts: MarkAdvisoryResolvedOptions): Promis
     ok: false;
     reason: string;
 }>;
+/**
+ * Resolution sources supported by the alpha.39 `markExclusionFindingHandled`
+ * API. Mirrors the subset of `exclusion_findings.resolution_source` CHECK
+ * constraint values that consumers can self-set:
+ *
+ * - `'consumer-marked'` — generic "we've handled this; stop reminding."
+ *   Use this for "we evaluated and chose not to act" or "we'll act when
+ *   ready but acknowledge the finding now."
+ * - `'declined'` — explicit "this exclusion is intentional; do not surface
+ *   again." Stronger signal than consumer-marked; useful for compliance
+ *   exclusions, brand-promise exclusions, etc.
+ * - `'probed-unblock'` — alpha.40+ probe-path verdict: consumer ran a live
+ *   probe and decided to unblock the excluded model. Library accepts the
+ *   value today so the probe path doesn't need a follow-up API release.
+ * - `'probed-stay-excluded'` — alpha.40+ probe-path verdict: consumer
+ *   probed and confirmed the exclusion. Same forward-compat shape as
+ *   `'probed-unblock'`.
+ *
+ * The `'auto'` resolution_source is NOT exposed here — that's reserved
+ * for the brain's own automatic resolution (e.g. when the detection
+ * conditions no longer hold). Consumer code sets only the four values
+ * above.
+ */
+type ExclusionResolutionSource = 'consumer-marked' | 'declined' | 'probed-unblock' | 'probed-stay-excluded';
+interface MarkExclusionFindingHandledOptions {
+    /** App id the finding belongs to. Required (RLS scopes writes by this). */
+    appId: string;
+    /** Archetype the finding applies to (e.g. 'hunt', 'classify'). */
+    archetype: string;
+    /** Canonical model id that the consumer had excluded. */
+    excludedModel: string;
+    /** Resolution semantics — see `ExclusionResolutionSource` for the four
+     *  values consumers can set. */
+    resolution: ExclusionResolutionSource;
+    /** Optional free-form note explaining the decision. Surfaces in operator
+     *  digests + dashboards alongside the resolution_source. */
+    resolutionNote?: string;
+    /** Brain Supabase URL base (e.g. `https://<project>.supabase.co`). The
+     *  function appends `/rest/v1/exclusion_findings?...`. */
+    brainEndpoint: string;
+    /** Consumer-scoped JWT carrying the `app_id` claim. The brain's RLS
+     *  policy enforces that the JWT's app_id matches the finding's app_id;
+     *  cross-tenant writes fail at the database layer regardless of input. */
+    brainJwt: string;
+    /** Supabase anon key for the `apikey` header (PostgREST requires it). */
+    brainAnonKey: string;
+    /** Injected fetch for tests. Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Mark a stale-exclusion finding as handled. Returns an `ok/reason` envelope
+ * matching `markAdvisoryResolved` — consumer Admin UIs typically render the
+ * failure inline rather than crash.
+ *
+ * Idempotent: if no row matches the (app_id, archetype, excludedModel)
+ * tuple (already resolved, never existed, cron not yet UPSERTed), PostgREST
+ * returns 200 with zero affected rows and we return `{ ok: true }`. The
+ * caller's "I marked it as handled" intent is satisfied regardless of
+ * whether the row was already in that state.
+ *
+ * Reasons surfaced on failure:
+ *   - `app_id_required` / `archetype_required` / `excluded_model_required`
+ *   - `resolution_invalid` — `resolution` not one of the four documented values
+ *   - `brain_auth_misconfig` — 401/403 (JWT / anon key wrong)
+ *   - `brain_unavailable` — 5xx
+ *   - `network_error:<message>` — fetch threw
+ *   - `patch_failed:<status>` — anything else non-2xx
+ */
+declare function markExclusionFindingHandled(opts: MarkExclusionFindingHandledOptions): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
 
 /**
  * Archetype-cliff compatibility — alpha.28 (tt-intel-Cairn ratified).
@@ -1465,6 +1556,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 +1701,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 ExclusionResolutionSource, 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 MarkExclusionFindingHandledOptions, 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, markExclusionFindingHandled, 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). */
@@ -751,6 +768,80 @@ declare function markAdvisoryResolved(opts: MarkAdvisoryResolvedOptions): Promis
     ok: false;
     reason: string;
 }>;
+/**
+ * Resolution sources supported by the alpha.39 `markExclusionFindingHandled`
+ * API. Mirrors the subset of `exclusion_findings.resolution_source` CHECK
+ * constraint values that consumers can self-set:
+ *
+ * - `'consumer-marked'` — generic "we've handled this; stop reminding."
+ *   Use this for "we evaluated and chose not to act" or "we'll act when
+ *   ready but acknowledge the finding now."
+ * - `'declined'` — explicit "this exclusion is intentional; do not surface
+ *   again." Stronger signal than consumer-marked; useful for compliance
+ *   exclusions, brand-promise exclusions, etc.
+ * - `'probed-unblock'` — alpha.40+ probe-path verdict: consumer ran a live
+ *   probe and decided to unblock the excluded model. Library accepts the
+ *   value today so the probe path doesn't need a follow-up API release.
+ * - `'probed-stay-excluded'` — alpha.40+ probe-path verdict: consumer
+ *   probed and confirmed the exclusion. Same forward-compat shape as
+ *   `'probed-unblock'`.
+ *
+ * The `'auto'` resolution_source is NOT exposed here — that's reserved
+ * for the brain's own automatic resolution (e.g. when the detection
+ * conditions no longer hold). Consumer code sets only the four values
+ * above.
+ */
+type ExclusionResolutionSource = 'consumer-marked' | 'declined' | 'probed-unblock' | 'probed-stay-excluded';
+interface MarkExclusionFindingHandledOptions {
+    /** App id the finding belongs to. Required (RLS scopes writes by this). */
+    appId: string;
+    /** Archetype the finding applies to (e.g. 'hunt', 'classify'). */
+    archetype: string;
+    /** Canonical model id that the consumer had excluded. */
+    excludedModel: string;
+    /** Resolution semantics — see `ExclusionResolutionSource` for the four
+     *  values consumers can set. */
+    resolution: ExclusionResolutionSource;
+    /** Optional free-form note explaining the decision. Surfaces in operator
+     *  digests + dashboards alongside the resolution_source. */
+    resolutionNote?: string;
+    /** Brain Supabase URL base (e.g. `https://<project>.supabase.co`). The
+     *  function appends `/rest/v1/exclusion_findings?...`. */
+    brainEndpoint: string;
+    /** Consumer-scoped JWT carrying the `app_id` claim. The brain's RLS
+     *  policy enforces that the JWT's app_id matches the finding's app_id;
+     *  cross-tenant writes fail at the database layer regardless of input. */
+    brainJwt: string;
+    /** Supabase anon key for the `apikey` header (PostgREST requires it). */
+    brainAnonKey: string;
+    /** Injected fetch for tests. Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Mark a stale-exclusion finding as handled. Returns an `ok/reason` envelope
+ * matching `markAdvisoryResolved` — consumer Admin UIs typically render the
+ * failure inline rather than crash.
+ *
+ * Idempotent: if no row matches the (app_id, archetype, excludedModel)
+ * tuple (already resolved, never existed, cron not yet UPSERTed), PostgREST
+ * returns 200 with zero affected rows and we return `{ ok: true }`. The
+ * caller's "I marked it as handled" intent is satisfied regardless of
+ * whether the row was already in that state.
+ *
+ * Reasons surfaced on failure:
+ *   - `app_id_required` / `archetype_required` / `excluded_model_required`
+ *   - `resolution_invalid` — `resolution` not one of the four documented values
+ *   - `brain_auth_misconfig` — 401/403 (JWT / anon key wrong)
+ *   - `brain_unavailable` — 5xx
+ *   - `network_error:<message>` — fetch threw
+ *   - `patch_failed:<status>` — anything else non-2xx
+ */
+declare function markExclusionFindingHandled(opts: MarkExclusionFindingHandledOptions): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
 
 /**
  * Archetype-cliff compatibility — alpha.28 (tt-intel-Cairn ratified).
@@ -1465,6 +1556,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 +1701,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 ExclusionResolutionSource, 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 MarkExclusionFindingHandledOptions, 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, markExclusionFindingHandled, 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,
@@ -71,6 +74,7 @@ __export(index_exports, {
   loadModelsFromBrain: () => loadModelsFromBrain,
   loadPricingFromBrain: () => loadPricingFromBrain,
   markAdvisoryResolved: () => markAdvisoryResolved,
+  markExclusionFindingHandled: () => markExclusionFindingHandled,
   profileToRow: () => profileToRow,
   profilesByProvider: () => profilesByProvider,
   record: () => record,
@@ -2400,6 +2404,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 +2542,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 +2753,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 +3149,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 +3277,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 +3299,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 +3308,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 +3440,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" };
     }
   };
@@ -5264,6 +5434,66 @@ async function markAdvisoryResolved(opts) {
   }
   return { ok: true };
 }
+async function markExclusionFindingHandled(opts) {
+  const {
+    appId,
+    archetype,
+    excludedModel,
+    resolution,
+    resolutionNote,
+    brainEndpoint,
+    brainJwt,
+    brainAnonKey,
+    fetch: injectedFetch
+  } = opts;
+  if (!appId) return { ok: false, reason: "app_id_required" };
+  if (!archetype) return { ok: false, reason: "archetype_required" };
+  if (!excludedModel) {
+    return { ok: false, reason: "excluded_model_required" };
+  }
+  if (resolution !== "consumer-marked" && resolution !== "declined" && resolution !== "probed-unblock" && resolution !== "probed-stay-excluded") {
+    return { ok: false, reason: "resolution_invalid" };
+  }
+  const doFetch = resolveFetch(injectedFetch);
+  const base = normalizeEndpoint(brainEndpoint);
+  const url = `${base}/rest/v1/exclusion_findings?app_id=eq.${encodeURIComponent(appId)}&intent_archetype=eq.${encodeURIComponent(archetype)}&excluded_model=eq.${encodeURIComponent(excludedModel)}&resolved_at=is.null`;
+  const patchBody = {
+    resolved_at: (/* @__PURE__ */ new Date()).toISOString(),
+    resolution_source: resolution
+  };
+  if (resolutionNote !== void 0) {
+    patchBody.resolution_note = resolutionNote;
+  }
+  let res;
+  try {
+    res = await doFetch(url, {
+      method: "PATCH",
+      headers: {
+        Authorization: `Bearer ${brainJwt}`,
+        apikey: brainAnonKey,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        // PATCH may match zero rows when already resolved — return=minimal
+        // keeps the response body empty so the success path is uniform.
+        Prefer: "return=minimal"
+      },
+      body: JSON.stringify(patchBody)
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, reason: `network_error:${msg}` };
+  }
+  if (res.status === 401 || res.status === 403) {
+    return { ok: false, reason: "brain_auth_misconfig" };
+  }
+  if (res.status >= 500) {
+    return { ok: false, reason: "brain_unavailable" };
+  }
+  if (!res.ok) {
+    return { ok: false, reason: `patch_failed:${res.status}` };
+  }
+  return { ok: true };
+}
 
 // src/models-brain.ts
 function isModelRow(x) {
@@ -5397,6 +5627,7 @@ function compile2(ir, opts) {
   ALL_ARCHETYPES,
   ARCHETYPE_FLOOR_DEFAULT,
   CallError,
+  DEFAULT_FINDINGS_ENDPOINT,
   DIALECT_VERSION,
   INTENT_ARCHETYPES,
   MEASURED_GROUNDING_MIN_N,
@@ -5428,11 +5659,13 @@ function compile2(ir, opts) {
   getReachabilityDiagnostic,
   getSequentialStarterChain,
   getSequentialStarterChainWithGrounding,
+  getStaleExclusionFindings,
   getStarterChain,
   getStarterChainWithGrounding,
   hashShape,
   isArchetype,
   isBrainQueryActiveFor,
+  isExclusionFindingsBrainActive,
   isModelReachable,
   isProviderReachable,
   learningKey,
@@ -5443,6 +5676,7 @@ function compile2(ir, opts) {
   loadModelsFromBrain,
   loadPricingFromBrain,
   markAdvisoryResolved,
+  markExclusionFindingHandled,
   profileToRow,
   profilesByProvider,
   record,

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" };
     }
   };
@@ -2984,6 +3150,66 @@ async function markAdvisoryResolved(opts) {
   }
   return { ok: true };
 }
+async function markExclusionFindingHandled(opts) {
+  const {
+    appId,
+    archetype,
+    excludedModel,
+    resolution,
+    resolutionNote,
+    brainEndpoint,
+    brainJwt,
+    brainAnonKey,
+    fetch: injectedFetch
+  } = opts;
+  if (!appId) return { ok: false, reason: "app_id_required" };
+  if (!archetype) return { ok: false, reason: "archetype_required" };
+  if (!excludedModel) {
+    return { ok: false, reason: "excluded_model_required" };
+  }
+  if (resolution !== "consumer-marked" && resolution !== "declined" && resolution !== "probed-unblock" && resolution !== "probed-stay-excluded") {
+    return { ok: false, reason: "resolution_invalid" };
+  }
+  const doFetch = resolveFetch(injectedFetch);
+  const base = normalizeEndpoint(brainEndpoint);
+  const url = `${base}/rest/v1/exclusion_findings?app_id=eq.${encodeURIComponent(appId)}&intent_archetype=eq.${encodeURIComponent(archetype)}&excluded_model=eq.${encodeURIComponent(excludedModel)}&resolved_at=is.null`;
+  const patchBody = {
+    resolved_at: (/* @__PURE__ */ new Date()).toISOString(),
+    resolution_source: resolution
+  };
+  if (resolutionNote !== void 0) {
+    patchBody.resolution_note = resolutionNote;
+  }
+  let res;
+  try {
+    res = await doFetch(url, {
+      method: "PATCH",
+      headers: {
+        Authorization: `Bearer ${brainJwt}`,
+        apikey: brainAnonKey,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        // PATCH may match zero rows when already resolved — return=minimal
+        // keeps the response body empty so the success path is uniform.
+        Prefer: "return=minimal"
+      },
+      body: JSON.stringify(patchBody)
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { ok: false, reason: `network_error:${msg}` };
+  }
+  if (res.status === 401 || res.status === 403) {
+    return { ok: false, reason: "brain_auth_misconfig" };
+  }
+  if (res.status >= 500) {
+    return { ok: false, reason: "brain_unavailable" };
+  }
+  if (!res.ok) {
+    return { ok: false, reason: `patch_failed:${res.status}` };
+  }
+  return { ok: true };
+}
 
 // src/models-brain.ts
 function isModelRow(x) {
@@ -3116,6 +3342,7 @@ export {
   ALL_ARCHETYPES,
   ARCHETYPE_FLOOR_DEFAULT,
   CallError,
+  DEFAULT_FINDINGS_ENDPOINT,
   DIALECT_VERSION,
   INTENT_ARCHETYPES,
   MEASURED_GROUNDING_MIN_N,
@@ -3147,11 +3374,13 @@ export {
   getReachabilityDiagnostic,
   getSequentialStarterChain,
   getSequentialStarterChainWithGrounding,
+  getStaleExclusionFindings,
   getStarterChain,
   getStarterChainWithGrounding,
   hashShape,
   isArchetype,
   isBrainQueryActiveFor,
+  isExclusionFindingsBrainActive,
   isModelReachable,
   isProviderReachable,
   learningKey,
@@ -3162,6 +3391,7 @@ export {
   loadModelsFromBrain,
   loadPricingFromBrain,
   markAdvisoryResolved,
+  markExclusionFindingHandled,
   profileToRow,
   profilesByProvider,
   record,

package/package.json

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