@warmdrift/kgauto-compiler 2.0.0-alpha.5 → 2.0.0-alpha.51

package/dist/index.d.mts

@@ -1,6 +1,9 @@
-import { M as ModelProfile, C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, R as RecordInput, O as OracleScore, e as CompileResult } from './profiles-DHdCRBVH.mjs';
-export { f as ALIASES, g as CacheStrategy, h as CallAttempt, i as CallError, j as CliffRule, k as Constraints, I as IntentDeclaration, L as LoweringSpec, l as Message, m as MutationApplied, n as NormalizedTokens, o as PromptSection, p as Provider, q as RecoveryRule, S as StructuredOutputCapability, r as SystemPromptMode, T as ToolCall, s as ToolDefinition, t as allProfiles, u as getProfile, v as profilesByProvider, w as tryGetProfile } from './profiles-DHdCRBVH.mjs';
-export { ALL_ARCHETYPES, ContextBucket, DIALECT_VERSION, HistoryDepth, INTENT_ARCHETYPES, IntentArchetypeName, OutputMode, ShapeSignature, ToolCountBucket, bucketContext, bucketHistory, bucketToolCount, hashShape, isArchetype, learningKey } from './dialect.mjs';
+import { C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, S as SystemModelMessage, e as CompileResult, f as SectionRewrite, R as RecordInput, g as RecordOutcomeInput, O as OutcomeResult, h as OracleScore, B as BestPracticeAdvisory, i as Adapter, j as PerAxisMetrics, k as Provider, l as ChainEntry, G as Grounding } from './ir-dDcG8Pvu.mjs';
+export { m as CallAttempt, n as CallError, o as ChainModelEntry, p as ChainWithGrounding, q as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, r as MutationApplied, s as NormalizedTokens, t as OutcomeKind, u as PerAxisMetricsByModel, v as PromptSection, w as SectionKind, x as ShadowProbeConfig, T as ToolCall, y as ToolDefinition } from './ir-dDcG8Pvu.mjs';
+import { ModelProfile, ArchetypeConvention } from './profiles.mjs';
+export { ALIASES, CacheStrategy, CliffRule, LATENCY_TIER_MS, LatencyTier, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, latencyTierOf, profilesByProvider, tryGetProfile } from './profiles.mjs';
+import { IntentArchetypeName } from './dialect.mjs';
+export { ALL_ARCHETYPES, ContextBucket, DIALECT_VERSION, HistoryDepth, INTENT_ARCHETYPES, OutputMode, ShapeSignature, ToolCountBucket, bucketContext, bucketHistory, bucketToolCount, hashShape, isArchetype, learningKey } from './dialect.mjs';
 
 /**
  * compile() — the main orchestrator.
@@ -19,6 +22,15 @@ interface CompileOptions {
     toolRelevanceThreshold?: number;
     /** History compression — turns count threshold (default 8). */
     compressHistoryAfter?: number;
+    /**
+     * History compression — token threshold (alpha.7). When total history
+     * tokens exceed this AND there are more recent turns to keep, compress
+     * even when count threshold is below `compressHistoryAfter`. Catches
+     * fat-message bloat (tool-using agents pack many tool-call/result pairs
+     * into single assistant messages — count stays low, tokens explode).
+     * Default undefined (disabled — backward-compatible).
+     */
+    compressHistoryAboveTokens?: number;
     /**
      * Consumer-declared policy. Filters blocked models, enforces cost
      * ceiling, boosts preferred. See CompilePolicy in ir.ts.
@@ -42,6 +54,15 @@ interface ExecuteOptions {
     apiKeys?: ApiKeys;
     fetchImpl?: typeof fetch;
     providerOverrides?: ProviderOverrides;
+    /**
+     * alpha.34. When supplied AND the chosen provider supports streaming, the
+     * execute() per-provider branch switches to SSE wire format and invokes
+     * `onChunk(delta)` once per text-delta event. Single-shot behavior
+     * preserved when omitted (current consumers unaffected). Wired from
+     * `CallOptions.onChunk` by `call()` after gating on `profile.streaming`
+     * and `!opts.noStream`.
+     */
+    onChunk?: (chunk: string) => void;
 }
 interface ExecuteOk {
     ok: true;
@@ -81,17 +102,194 @@ declare function execute(request: CompiledRequest, opts?: ExecuteOptions): Promi
  * exhausted without success.
  */
 declare function call(ir: PromptIR, opts?: CallOptions): Promise<CallResult>;
+/** Served-side result the AI-SDK consumer already holds from streamText. */
+interface ProbeShadowServed {
+    /** Model id that actually served the user (becomes `current_model` on the row). */
+    model: string;
+    /** The served response text (stored as a preview; never the prompt). */
+    responseText: string;
+    /** Served prompt tokens (AI SDK `usage.promptTokens`). */
+    tokensIn: number;
+    /** Served completion tokens (AI SDK `usage.completionTokens`). */
+    tokensOut: number;
+    /** The user's actual wait in ms (alpha.46 served-latency axis). */
+    latencyMs: number;
+}
+/** Options for the standalone {@link probeShadow} export. */
+interface ProbeShadowOptions {
+    /** The served leg the consumer supplies; kgauto runs the candidate leg. */
+    served: ProbeShadowServed;
+    /** Model id(s)/family alias(es) to shadow-test against the served model. */
+    candidates: string | string[];
+    /** Probability [0,1] a given call fires a probe. Default 0.05; pin 1 for dogfood. */
+    sampleRate?: number;
+    /** Phase 1 = 'off' (offline rollup). 'opus' inline judge is Phase 2. Default 'off'. */
+    judge?: 'off' | 'opus';
+    /** Override API keys (defaults: process.env). Gates candidate reachability. */
+    apiKeys?: ApiKeys;
+    /** Override fetch (for tests / custom transport). */
+    fetchImpl?: typeof fetch;
+    /** Provider-specific request fields shallow-merged into the candidate request. */
+    providerOverrides?: ProviderOverrides;
+    /** Forwarded to compile() for the candidate run (match the served-side compile). */
+    policy?: CompilePolicy;
+    toolRelevanceThreshold?: number;
+    compressHistoryAfter?: number;
+}
+/**
+ * s54 — standalone full-IR shadow probe for AI-SDK consumers (tt-intel hunt, IC
+ * chat) that own their own streamText round-trip and never call call(). Fire it
+ * from the streamText `onFinish` callback, wrapped in the platform's
+ * `waitUntil()` / `after()`, so it runs after the response is flushed — no
+ * blocking, no `sync:true`, no teardown race (cleaner than call()'s in-process
+ * fire-and-forget for Edge runtimes; L-086).
+ *
+ * Runs the SAME candidate loop as the call()-inline probe ({@link
+ * runProbeCandidates}): same gates (sample, self-skip, G4 judge-self,
+ * reachability, G6), same fidelity=1.0 full-IR rows, same alpha.46 latency
+ * capture. The consumer supplies the served leg it already has; kgauto runs the
+ * candidate(s) and writes the `probe_outcomes` row.
+ *
+ * Requires `configureBrain()` to have been called (same as call()).
+ * Fire-and-forget: never throws into the caller.
+ *
+ * @example
+ * const result = streamText({ model, system, messages,
+ *   onFinish: ({ text, usage }) => {
+ *     after(() => probeShadow(ir, {
+ *       served: { model: servedModelId, responseText: text,
+ *                 tokensIn: usage.promptTokens, tokensOut: usage.completionTokens,
+ *                 latencyMs: Date.now() - t0 },
+ *       candidates: ['deepseek-v4-pro'], sampleRate: 0.05,
+ *     }));
+ *   },
+ * });
+ */
+declare function probeShadow(ir: PromptIR, opts: ProbeShadowOptions): Promise<void>;
+
+/**
+ * alpha.33 — AI-SDK streamText helpers.
+ *
+ * The cross-consumer pattern surfaced 2026-05-20 (`streamText-cache-marker-
+ * propagation-gap` on `command-center/interfaces/kgauto.md ## Requested`):
+ * AI-SDK consumers using `streamText({ system: <string>, messages:
+ * convertToModelMessages(messages), model })` silently drop the Anthropic
+ * `cache_control` markers the compiler emits on `result.request.messages`.
+ * Two losses on that line:
+ *   (a) `convertToModelMessages()` reads raw inputs not the lowered output,
+ *       dropping per-message providerOptions; and
+ *   (b) `streamText({ system: '<string>' })` strips any providerOptions
+ *       on the system prefix.
+ *
+ * Net effect prior to this surface: `cache_read_input_tokens = 0` across
+ * every measured production call by IC + tt-intel even though both
+ * consumers had `historyCachePolicy: { strategy: 'all-but-latest' }` wired
+ * since alpha.5. The compiler did the right thing; the consumer integration
+ * pattern lost the markers at the wire boundary.
+ *
+ * This helper closes the gap. Pass the consumer's already-converted messages
+ * + the kgauto CompileResult and get back a `{ system, messages }` pair
+ * with cacheControl re-attached at the deterministic indices the compiler
+ * computed (`diagnostics.historyCacheMarkIndex` + `systemMessages` with
+ * its own cacheControl markers).
+ *
+ * No I/O. Pure transform. Idempotent — calling twice with the same inputs
+ * produces structurally-identical output.
+ */
 
 /**
- * Brain client — fire-and-forget telemetry to the central kgauto Supabase.
+ * AI-SDK-shaped converted-message structure. Matches what
+ * `convertToModelMessages()` returns at the wire layer. We don't import
+ * the AI-SDK type to avoid pulling that dep into the kgauto-compiler
+ * package — consumers pass their own already-converted messages.
+ */
+interface AISDKConvertedMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: unknown;
+    providerOptions?: {
+        anthropic?: {
+            cacheControl?: {
+                type: 'ephemeral';
+            };
+        };
+    };
+}
+/**
+ * Result of `attachCacheControlToStreamTextInput()` — ready to spread into
+ * `streamText(...)` directly.
+ *
+ * The `system` field is either the structured `SystemModelMessage[]` form
+ * (when the compiler computed at least one cacheable section + chose
+ * Anthropic) or the flat-string concatenation (when no cacheable sections
+ * exist OR the provider isn't Anthropic). Consumers can pass either form
+ * to `streamText({ system })` — the AI-SDK accepts both.
+ */
+interface AttachCacheControlResult {
+    system: string | SystemModelMessage[];
+    messages: AISDKConvertedMessage[];
+}
+/**
+ * Attach Anthropic cache_control markers to a streamText input that the
+ * consumer has already prepared via `convertToModelMessages()`. Reads
+ * `result.diagnostics.historyCacheMarkIndex` for the position-on-history
+ * marker and `result.systemMessages` for the per-section system markers.
+ *
+ * The flat-string `system` form is returned when:
+ *   - the compiler produced no `systemMessages` (e.g., zero sections kept), or
+ *   - the chosen provider is not Anthropic, so cacheControl wouldn't
+ *     achieve anything at the wire layer (other providers cache implicitly
+ *     based on prefix shape, no marker needed).
  *
- * The brain is the centralized learning store. Apps POST outcomes here;
- * mutations flow back through a separate pull (in v2.1).
+ * Otherwise the structured `SystemModelMessage[]` form is returned —
+ * preserves the per-section cacheControl markers across `streamText`.
  *
- * Design: never blocks the caller. Failures are silent (logged via optional
- * onError hook). Uses fetch() — works in Node 18+, Edge runtimes, and browsers.
+ * @param result - kgauto CompileResult from `compile(ir, opts)`
+ * @param convertedMessages - the consumer's already-converted messages
+ *   (from `convertToModelMessages(rawMessages)` in their AI-SDK call site)
+ * @returns `{ system, messages }` ready to spread into `streamText(...)`
  */
+declare function attachCacheControlToStreamTextInput(result: CompileResult, convertedMessages: AISDKConvertedMessage[]): AttachCacheControlResult;
 
+/**
+ * alpha.11 — opt-in nested config for brain-query mode (chains / archetype
+ * perf / pricing / models registry). Enabled by default when endpoint is
+ * set; per-table opt-out via explicit `false`.
+ *
+ * Locked via /plan-eng-review 2026-05-15 (decision D3). Structured group
+ * keeps the BrainConfig surface clean as more brain-driven tables ship.
+ */
+interface BrainQueryConfig {
+    /** Default true when endpoint set. Brain-driven fallback chains. */
+    chains?: boolean;
+    /** Default true when endpoint set. Brain-driven archetype perf scores. */
+    perf?: boolean;
+    /** Default true when endpoint set. Brain-driven pricing with at-time resolution. */
+    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). */
     endpoint: string;
@@ -103,6 +301,9 @@ interface BrainConfig {
     sync?: boolean;
     /** Optional fetch override (for tests). */
     fetchImpl?: typeof fetch;
+    /** alpha.11 — brain-query mode for config tables. Default-on per table
+     *  when endpoint is set; opt-out via `false`. See BrainQueryConfig. */
+    brainQuery?: BrainQueryConfig;
 }
 declare function configureBrain(config: BrainConfig): void;
 declare function clearBrain(): void;
@@ -114,6 +315,175 @@ declare function clearBrain(): void;
  * network error is swallowed/forwarded to onError.
  */
 declare function record(input: RecordInput): Promise<void>;
+/**
+ * Wire shape POSTed by `record()` to the brain proxy's `/outcomes` endpoint.
+ *
+ * Exported so consumer proxies can `import { OutcomePayload } from
+ * '@warmdrift/kgauto-compiler'` instead of redefining the shape — that way
+ * TypeScript catches future schema additions (cache fields, advisory
+ * telemetry, etc.) at consumer build time, not silently at runtime.
+ *
+ * **Forward-compat rule:** consumer proxies should pass the body through to
+ * Supabase rather than reconstructing field-by-field. The recommended shape
+ * is `const row = { ...body }` (or `await supabase.from('compile_outcomes')
+ * .insert(body)` directly). Filtering proxies break schema evolution
+ * silently — see s17 root-cause investigation 2026-05-10.
+ */
+interface OutcomePayload {
+    handle: string;
+    app_id?: string;
+    intent_archetype?: string;
+    /** The model that ACTUALLY RAN (post-fallback). */
+    model?: string;
+    /** The model v2 compile() originally targeted. NULL when no fallback. */
+    requested_model?: string;
+    provider?: string;
+    shape_key?: string;
+    learning_key?: string;
+    mutations_applied: string[];
+    tokens_in: number;
+    tokens_out: number;
+    estimated_tokens_in?: number;
+    latency_ms: number;
+    success: boolean;
+    empty_response: boolean;
+    error_type?: string;
+    tools_called?: string[];
+    oracle_score?: number;
+    oracle_dimensions?: Record<string, number>;
+    oracle_rationale?: string;
+    prompt_preview?: string;
+    response_preview?: string;
+    dialect_version: string;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+    cost_usd_actual?: number;
+    ttft_ms?: number;
+    history_cacheable_tokens?: number;
+    history_tokens_at_compile?: number;
+    /**
+     * Mirrors `ir.constraints.toolOrchestration` from compile time. NULL when
+     * the consumer hadn't adopted the constraint (pre-alpha.20). Powers
+     * per-mode model-perf queries on the brain (the L-040 parallel-tool
+     * cliff lumps DeepSeek sequential perf with parallel without this).
+     */
+    tool_orchestration?: 'parallel' | 'sequential' | 'either' | null;
+    finish_reason?: string;
+    total_ms?: number;
+    tools_count?: number;
+    history_depth?: number;
+    system_prompt_chars?: number;
+    fell_over_from?: string;
+    fallback_reason?: 'rate_limit' | 'provider_auth_failed' | 'provider_error' | 'cliff' | 'cost_cap' | 'contract_violation';
+    /**
+     * Per-call SectionRewrite[] captured at compile time. Omitted (sent as
+     * undefined → stored NULL) when no rewrites fired. Powers cross-app
+     * learning aggregates ("rule X fired N times on (app, model, archetype),
+     * downstream outcome quality lifted by M points").
+     */
+    section_rewrites_applied?: SectionRewrite[] | null;
+}
+/**
+ * alpha.20 Entry 4: record a quality outcome for a previously-compiled call.
+ *
+ * Fires after the consumer's UX surfaces an approve/reject event (e.g., user
+ * clicks Approve on a hunt result). Joins to the original `compile_outcomes`
+ * row via outcomeId — enables per-(model, archetype) approve-rate measurement
+ * once N ≥ 10 outcomes accumulate.
+ *
+ * Fire-and-forget by default (matches record() semantics). Set BrainConfig.sync
+ * = true for runtime contexts that can't tolerate fire-and-forget teardown
+ * (Vercel Edge, Cloudflare Workers, AWS Lambda) — see L-086.
+ *
+ * Returns OutcomeResult with ok: false + stable reason on persistence
+ * failure. Never throws.
+ */
+declare function recordOutcome(input: RecordOutcomeInput): Promise<OutcomeResult>;
+/**
+ * True when the active brain config requests synchronous (awaited) writes.
+ * call()'s shadow-probe path reads this to decide whether to await the probe
+ * (Edge/Worker/Lambda — L-086) or fire-and-forget (Node). False when no brain
+ * is configured.
+ */
+declare function isBrainSync(): boolean;
+/**
+ * Full-IR inline shadow-probe record input (Shape B, Phase 1 — s51). Carries
+ * ONLY response previews + metadata; the prompt (system/context/payload) is
+ * never included — `promptHash` is an irreversible grouping key, not content.
+ */
+interface ShadowProbeRecordInput {
+    appId: string;
+    archetype: string;
+    family: string;
+    candidateModel: string;
+    currentModel: string;
+    /** Irreversible grouping hash (NOT the prompt). */
+    promptHash: string;
+    /** Served model's response, truncated (RESPONSE text only — never the prompt). */
+    currentResponsePreview?: string;
+    /** Candidate model's response, truncated. */
+    candidateResponsePreview?: string;
+    tokensCurrentIn?: number;
+    tokensCurrentOut?: number;
+    tokensCandidateIn?: number;
+    tokensCandidateOut?: number;
+    /**
+     * Wall-clock latency of the served call, ms (alpha.46). The third swap-decision
+     * axis alongside quality + cost — a verdict needs to know the candidate is
+     * slower, not just better/cheaper. Served latency mirrors
+     * `compile_outcomes.latency_ms`; carried here so a probe row is self-contained.
+     */
+    latencyCurrentMs?: number;
+    /** Wall-clock latency of the candidate replay call, ms (alpha.46). */
+    latencyCandidateMs?: number;
+    /**
+     * alpha — probe-row class (migration 029). Defaults to `'completed'` (the
+     * pre-029 row shape: candidate ran, columns populated). `'aborted_latency_budget'`
+     * and `'skipped_slow_tier_sync'` are DIAGNOSTIC rows from sync-mode latency
+     * protection — no candidate response, no verdict, no false quality signal. A
+     * verdict rollup MUST filter to `outcome='completed'`.
+     */
+    outcome?: 'completed' | 'aborted_latency_budget' | 'skipped_slow_tier_sync';
+}
+/**
+ * Pure builder for the `probe_outcomes` row written by the inline shadow-probe.
+ * Exported so a test can assert the G3 privacy invariant: the row carries NO
+ * prompt/system/context text — only response previews + metadata + a hash.
+ *
+ * Phase 1 (judge: 'off'): `judge_verdict` / `judge_score` are null — the row
+ * is an unjudged sample for the Phase-2 offline batch judge. `prompt_fidelity`
+ * is 1.0 by construction (the candidate ran the full IR, not a truncated
+ * preview), and `replay_source='inline-full-ir'` marks it as a trustworthy row
+ * (vs the watchers' lossy `replay-preview`).
+ */
+declare function buildShadowProbeRow(input: ShadowProbeRecordInput): {
+    app_id: string;
+    intent_archetype: string;
+    family: string;
+    candidate_model: string;
+    current_model: string;
+    prompt_hash: string;
+    current_response: string | null;
+    candidate_response: string | null;
+    judge_verdict: null;
+    judge_score: null;
+    tokens_current_in: number | null;
+    tokens_current_out: number | null;
+    tokens_candidate_in: number | null;
+    tokens_candidate_out: number | null;
+    latency_current_ms: number | null;
+    latency_candidate_ms: number | null;
+    prompt_fidelity: number;
+    replay_source: 'inline-full-ir';
+    outcome: 'completed' | 'aborted_latency_budget' | 'skipped_slow_tier_sync';
+};
+/**
+ * Persist one inline shadow-probe row to `probe_outcomes`. Fire-and-forget by
+ * default; honors `BrainConfig.sync` (L-086). Never throws — failures route to
+ * onError. Mirrors record()'s POST shape; consumer proxies forward
+ * `/probe_outcomes` the same way they forward `/outcomes`.
+ */
+declare function recordShadowProbe(input: ShadowProbeRecordInput): Promise<void>;
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -166,6 +536,34 @@ interface LLMJudgeOptions {
  */
 declare function buildLLMJudge(opts: LLMJudgeOptions): AppOracle;
 
+/**
+ * Resolve the effective ArchetypeConvention[] for a given selected profile,
+ * walking family inheritance once. Model-specific entries on the selected
+ * profile take precedence over family-level entries for the same archetype.
+ *
+ * Pure; safe to call from any context (probe-watcher uses the same logic
+ * via `applyArchetypeConvention`).
+ */
+declare function resolveConventionsForProfile(profile: ModelProfile): ArchetypeConvention[];
+/**
+ * Pure helper: apply the matching ArchetypeConvention's suffix (and
+ * prefix, when meaningful) to a plain prompt-text string. Used by the
+ * exclusion-probe-watcher (`probeOne`) so probe calls carry the same
+ * forcing-function shape consumers see at compile time. Without this,
+ * every reasoner probe on a decisive archetype gets unfairly stay-excluded
+ * for hedging — as ID 20 demonstrated on 2026-05-28.
+ *
+ * Resolution: looks up the family-rep profile for `family` and reads its
+ * `archetypeConventions`. Returns the original text unchanged when no
+ * convention matches or when the suffix is already present.
+ *
+ * @param promptText raw user-prompt text (or prompt_preview from outcome)
+ * @param archetype  intent_archetype from the finding row
+ * @param family     family tag from deriveFamilyFromModelId / brain row
+ * @returns text with prefix/suffix applied (idempotent)
+ */
+declare function applyArchetypeConvention(promptText: string, archetype: string, family: string): string;
+
 /**
  * Tokenizer abstraction.
  *
@@ -189,6 +587,1645 @@ declare function resetTokenizer(): void;
  */
 declare function countTokens(text: string): number;
 
+/**
+ * archetype-fits — alpha.43.
+ *
+ * Static table of "this archetype tends to be a better fit for this family"
+ * recommendations. Powers the `cross-family-fit-candidate` compile-time
+ * advisor (see `advisor-rules/cross-family-fit.ts`).
+ *
+ * Strategic framing (Sacha, 2026-05-28): "If we get better results and
+ * better price then we do. Even if volume is currently low, that's not an
+ * argument to not do it. Volume can increase quickly if tools is great to
+ * use, let's not create future bottlenecks because we could have wired in
+ * better solution at moment of knowing."
+ *
+ * The convention substrate (passApplyConventions) is the NEGATIVE side:
+ * make a family usable on archetypes it currently fails. This table is the
+ * POSITIVE side: actively surface that a different family is the better
+ * fit for the archetype's shape — even when current volume is low.
+ *
+ * Entries are added only when:
+ *   - the archetype's shape and the family's behavior have a clear
+ *     architectural fit (not vibes)
+ *   - real-world evidence (brain rows, probe outcomes, or published
+ *     benchmark) backs the claim, OR the reasoning is structurally so clear
+ *     that "wait for volume" would create a future bottleneck
+ *
+ * Alpha.43 ships two entries — `plan` and `critique`. Both fit the
+ * reasoner-family architectural read: plan is multi-step reasoning;
+ * critique rewards epistemic humility and explicit reasoning. Other
+ * archetype-family-fits ride later alphas as evidence accumulates.
+ *
+ * Anti-pattern: do NOT add archetype-family-fits for archetypes where the
+ * fit is unclear (summarize, classify, extract, hunt with parallel tools).
+ * The advisor only earns trust when its recommendations land.
+ */
+
+/**
+ * One archetype-family-fit recommendation. Read by the compile-time
+ * `cross-family-fit-candidate` advisor to decide when to surface a positive
+ * recommendation. The advisor pulls `costGuidance` verbatim into the
+ * advisory message.
+ */
+interface ArchetypeFamilyFit {
+    /** Intent archetype this fit applies to. */
+    archetype: IntentArchetypeName;
+    /** Family tag that fits the archetype better than alternatives. Matches the
+     *  same family taxonomy used by `family-resolution.deriveFamilyFromModelId`
+     *  (e.g. `'deepseek-reasoner'`, `'gemini-flash'`, `'claude-opus'`). */
+    betterFitFamily: string;
+    /** Architectural / evidentiary justification. Appears in the advisor's
+     *  internal logs and the advisory `evidence` payload, NOT verbatim in the
+     *  consumer-facing message. */
+    reason: string;
+    /** Cost-context clause surfaced VERBATIM in the consumer-facing advisory
+     *  message (e.g. "substantially cheaper at current pricing"). Keep
+     *  declarative; the advisor wraps this into the larger sentence. */
+    costGuidance: string;
+}
+/**
+ * Frozen registry. Add entries by extending the array. Order is irrelevant
+ * — the advisor filters by `(archetype, currentFamily)` independently.
+ */
+declare const ARCHETYPE_FAMILY_FITS: readonly ArchetypeFamilyFit[];
+/**
+ * Pure lookup: does `(archetype, currentFamily)` have a better-fit family?
+ * Returns the fit entry when the current family is NOT the better fit; null
+ * otherwise. Used by the advisor to decide whether to fire.
+ */
+declare function findBetterFit(archetype: string, currentFamily: string): ArchetypeFamilyFit | null;
+
+/**
+ * Best-practice advisor — alpha.6 Phase 1.
+ *
+ * Inspects an IR + the selected profile + compile diagnostics and emits a
+ * list of `BestPracticeAdvisory` entries describing detected gaps. Runs
+ * after `lower()` in the compile pipeline; the result lands on
+ * `CompileResult.advisories` for the consumer to log, surface, or filter.
+ *
+ * Driven by interfaces/kgauto.md `best-practice-advisories` (IC, 2026-05-07).
+ * Phase 1 ships 4 starter rules sourced from the s14 kgauto comment +
+ * s15 empirical seed of brain anti-patterns:
+ *
+ *   1. `caching-off-on-claude`        system >2000 chars on Anthropic, no cacheable=true
+ *   2. `single-chunk-system`          Anthropic, only one PromptSection >1000 chars
+ *   3. `tool-bloat`                   >10 tools on a short-output archetype
+ *   4. `history-uncached-on-claude`   Anthropic, ≥2 history messages, no historyCachePolicy
+ *
+ * Each rule is a pure function: (ir, result, profile) → BestPracticeAdvisory[].
+ * No side effects. No randomness. Deterministic for a given IR.
+ *
+ * The thresholds (2000 chars, 1000 chars, 10 tools, 2 history) are chosen
+ * to balance noise vs. signal — too low fires on innocuous calls, too high
+ * misses real waste. They may tune with brain evidence over time; for now
+ * they're literals in the rule bodies. Make them configurable when the
+ * cost-watcher's R-rules graduate to here.
+ */
+
+/** Subset of CompileResult fields the advisor needs. */
+type AdvisorContext = Pick<CompileResult, 'target' | 'provider' | 'tokensIn' | 'diagnostics'>;
+/**
+ * Optional Phase 2 (alpha.22) context — fallback chain + a profile resolver
+ * for cross-model comparison. Three new rules
+ * (`cost-mismatched-archetype`, `model-stale-evidence`, `tier-down`) consume
+ * this to surface measurement-substrate signals (alpha.20 clean-attribution +
+ * alpha.21 grounding labels) as actionable consumer guidance.
+ *
+ * When `fallbackChain` is empty, rules 1 + 3 stay silent (nothing to
+ * compare against). When `profileResolver` is omitted, the rules degrade
+ * gracefully — they can still inspect the chosen profile but not chain
+ * alternatives. Rule 2 (`model-stale-evidence`) is independent of chain
+ * shape and works on the chosen model alone.
+ */
+interface RunAdvisorPhase2Context {
+    fallbackChain: string[];
+    profileResolver?: (id: string) => ModelProfile | undefined;
+    /**
+     * alpha.29 — translator rewrites that fired this compile. When a rewrite
+     * cleared the cliff (e.g. `tool_call_contract` → sequential-tool preamble
+     * + `parallelToolCalls: false`), the matching cliff advisor
+     * (`archetype-perf-floor-breach`) MUST suppress for the same call. Without
+     * suppression both fire — the advisory contradicts the rewrite ("cliff is
+     * unaddressed" vs "we just addressed it").
+     *
+     * Empty array / undefined → no suppression (alpha.28 behavior preserved).
+     */
+    sectionRewritesApplied?: SectionRewrite[];
+}
+/**
+ * alpha.42 — rule codes whose advisories are positioned for kgauto (not
+ * the consumer) to act on. Used by `compile()` to default the `ownership`
+ * stamp on each advisory when the rule didn't self-declare. Consumer-side
+ * rules don't need to be listed — they default to `'consumer-actionable'`
+ * via fall-through.
+ *
+ *   - `model-stale-evidence`: kgauto's profile data is out of date; the
+ *     consumer can't fix that, kgauto needs to update profiles or refresh
+ *     archetypePerf scores.
+ *   - `promote-ready`: kgauto's promotion-probe-watcher detected a
+ *     candidate model worth promoting; consumer-side adoption is downstream
+ *     of kgauto adding it to the chain / family taxonomy.
+ *
+ * Frozen so consumers and tests can't mutate the global ownership map.
+ */
+declare const PRODUCER_OWNED_RULE_CODES: ReadonlySet<string>;
+/**
+ * alpha.42 — pure function used by `compile()` to decide ownership for an
+ * advisory. Rule-self-declared wins; falls back to the static map; defaults
+ * `consumer-actionable`. Exported so consumer-side code (or a Glass-Box
+ * renderer) can derive the same classification from a rule code alone
+ * without needing the advisory object.
+ */
+declare function deriveOwnership(code: string, selfDeclared?: 'consumer-actionable' | 'producer-owned'): 'consumer-actionable' | 'producer-owned';
+/**
+ * Run all phased rules and return collected advisories. Order is fixed so
+ * output is stable across runs. The `policy` argument is alpha.9 — the
+ * `single-model-array` rule needs to know whether the consumer explicitly
+ * declared `posture: 'locked'` (in which case single-model is intentional
+ * and shouldn't warn).
+ *
+ * `phase2` is alpha.22 — gives the advisor access to the fallback chain +
+ * a profile resolver so the three new compile-time recommendation rules
+ * (`cost-mismatched-archetype`, `model-stale-evidence`, `tier-down`) can
+ * compare the chosen model against in-chain alternatives. Optional for
+ * backward compatibility with consumers calling `runAdvisor()` directly.
+ */
+declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: ModelProfile, policy?: CompilePolicy, phase2?: RunAdvisorPhase2Context): BestPracticeAdvisory[];
+
+/**
+ * Translator primitive — alpha.31.
+ *
+ * Pure function. Walks `IR.sections`, matches each section's `kind` against
+ * a per-rule dispatch table keyed on (kind, profile, archetype), and applies
+ * a model-aware rewrite when a rule fires. Returns the rewritten IR + the
+ * list of rewrites for `CompileResult.sectionRewritesApplied` and brain
+ * persistence.
+ *
+ * This is the s37 translator-framing eureka in code: kgauto graduates from
+ * "gate" (alpha.28's cliff advisor: "consumer must accept adapter") to
+ * "translator" (alpha.29: "consumer declared the section kind, kgauto
+ * applies the adapter at compile time without consumer-side branching").
+ *
+ * Rules shipped:
+ *
+ *   alpha.29 — tool_call_contract + archetypePerf[archetype] < TRANSLATOR_FLOOR
+ *     → prepend sequential-tool-pattern guidance
+ *     → emit wireOverrides: { parallelToolCalls: false }
+ *     → rule_id: 'sequential-tool-cliff-below-floor'
+ *
+ *   alpha.31 — narration_contract + profile.provider === 'anthropic'
+ *     → prepend terse-log narration guidance
+ *     → no wireOverrides
+ *     → rule_id: 'narration-drift-anthropic'
+ *
+ *   alpha.31 — narration_contract + profile.provider === 'deepseek'
+ *     → prepend <thinking>-suppression guidance
+ *     → no wireOverrides
+ *     → rule_id: 'narration-thinking-leak-deepseek'
+ *
+ * Per-rule walk (alpha.31 refactor): the alpha.30 short-circuit
+ * `if (!cliffFires) return passthrough` was correct when only the
+ * cliff-gated tool_call_contract rule existed; alpha.31's narration rules
+ * fire on every call regardless of cliff (narration drift is steady-state,
+ * not a cliff condition). Each section now consults the dispatch table
+ * independently — first-match wins per (section.kind, profile, archetype).
+ *
+ * **Interaction with the cliff advisor (alpha.28):** when this translator
+ * fires for a `tool_call_contract` section, the advisor's
+ * `archetype-perf-floor-breach` rule MUST suppress for the same call — the
+ * cliff was structurally cleared by the rewrite, not unaddressed. The
+ * suppression check lives in `advisor.ts` and consults the
+ * `CompileResult.sectionRewritesApplied` list.
+ *
+ * Design contracts:
+ *   command-center/advisory/kgauto/2026-05-21_alpha-29-translator-and-advisories-api.md
+ *   command-center/advisory/kgauto/2026-05-22_alpha-31-narration-contract.md
+ */
+
+/**
+ * Re-export of `ARCHETYPE_FLOOR_DEFAULT` as the canonical "translator fires
+ * below this score" threshold. Same constant as the cliff advisor — the
+ * single threshold is shared (alpha.28's "below this, advisor warns"; alpha.29's
+ * "below this, translator AUTO-APPLIES the adapter").
+ */
+declare const TRANSLATOR_FLOOR = 6;
+/**
+ * Stable identifier of the alpha.29 sequential-tool rule. Surfaces on
+ * `SectionRewrite.rule` and in brain aggregates. The brain treats this
+ * identifier together with the preamble string as the rule's wire
+ * fingerprint — both stay byte-stable across releases.
+ */
+declare const RULE_SEQUENTIAL_TOOL_CLIFF = "sequential-tool-cliff-below-floor";
+interface ApplySectionRewritesArgs {
+    ir: PromptIR;
+    profile: ModelProfile;
+    archetype: IntentArchetypeName;
+}
+interface ApplySectionRewritesResult {
+    /**
+     * IR with section.text fields possibly rewritten. When no rewrites fired,
+     * this is identical to the input IR (referentially distinct array but
+     * same section payloads).
+     */
+    rewrittenIR: PromptIR;
+    /**
+     * One entry per section the translator rewrote. Empty array when no
+     * rules fired. Order matches the corresponding section in
+     * `rewrittenIR.sections`.
+     */
+    rewrites: SectionRewrite[];
+}
+/**
+ * Pure function. Apply model-aware section rewrites to the IR at compile time.
+ *
+ * Discipline:
+ *   - Never mutates the input IR; returns a new IR with new sections array
+ *     when at least one rewrite fired; otherwise returns the input IR by
+ *     reference (referential identity preserved on no-op).
+ *   - Sections without a `kind` (or `kind === 'arbitrary'`) pass through
+ *     unchanged.
+ *   - Empty `sections` array → returns `{ rewrittenIR: ir, rewrites: [] }`.
+ *   - Sections of the same `kind` are processed in array order; first-match
+ *     wins per section. (Today every rule is a single-match rule.)
+ *
+ * @example
+ * ```ts
+ * import { applySectionRewrites } from '@warmdrift/kgauto-compiler';
+ * import { getProfile } from '@warmdrift/kgauto-compiler';
+ *
+ * const { rewrittenIR, rewrites } = applySectionRewrites({
+ *   ir,
+ *   profile: getProfile('deepseek-v4-pro'),
+ *   archetype: 'hunt',
+ * });
+ * if (rewrites.length > 0) console.log('translator fired:', rewrites);
+ * ```
+ */
+declare function applySectionRewrites(args: ApplySectionRewritesArgs): ApplySectionRewritesResult;
+
+/**
+ * advisories-api — structured advisories API (alpha.29 Workstream B).
+ *
+ * Closes the L-117 family bottleneck: kgauto's `result.advisories[]` (the
+ * compile-time warnings about caching-off, tool-bloat, archetype-perf-floor
+ * breaches, etc.) used to disappear after the consumer read the compile
+ * result. The s34 caching-off advisory pattern is the canonical failure: an
+ * advisory fired 100+ times in 24h on `generate::sonnet` at 99.4% empty
+ * rate, and nobody knew because there was no structured channel to surface
+ * "what's open right now?"
+ *
+ * Migration 020 ships the substrate: `compile_outcome_advisories` gains
+ * lifecycle columns (`resolved_at`, `resolution_source`, `resolution_note`)
+ * and the `actionable_advisories_v` view rolls per-firing rows into
+ * per-(app_id, code) tuples with deterministic stable ids + server-side
+ * auto-resolution.
+ *
+ * Public surface:
+ *   getActionableAdvisories({ appId, severity?, status?, brainEndpoint, brainJwt, brainAnonKey, fetch? })
+ *     → Promise<ActionableAdvisory[]>
+ *
+ *   markAdvisoryResolved({ id, resolutionNote?, brainEndpoint, brainJwt, brainAnonKey, fetch? })
+ *     → Promise<{ ok: true } | { ok: false; reason: string }>
+ *
+ * Both functions are pure I/O — no module-level state. The fetch wiring
+ * mirrors `createProxyHandler` in `glassbox-routes/proxy.ts`: scoped JWT in
+ * `Authorization: Bearer`, `apikey` header carries the anon key.
+ *
+ * The auto-resolution rule is enforced server-side in `actionable_advisories_v`:
+ *   • Latest firing > 14 days ago             → status='resolved' (auto-pruned)
+ *   • All firings have resolved_at set        → status='resolved' (consumer-marked)
+ *   • Otherwise                               → status='open'
+ *
+ * `markAdvisoryResolved` is the consumer override: "I fixed it; the next
+ * firing will reopen the rule, but until then it stays resolved."
+ */
+
+/**
+ * Severity of an advisory. Maps to the `level` column on
+ * `compile_outcome_advisories` (info | warn | critical).
+ */
+type AdvisorySeverity = 'info' | 'warn' | 'critical';
+/**
+ * Status of an advisory rollup.
+ *
+ * - `open` — at least one unresolved firing in the last 14 days
+ * - `resolved` — either auto-pruned (no firings >14d) or consumer-marked
+ * - `snoozed` — reserved for alpha.30+ (snooze-until-date); type-accepted
+ *   today but the view will never emit this value
+ */
+type AdvisoryStatus = 'open' | 'snoozed' | 'resolved';
+/**
+ * Source of resolution when status='resolved'.
+ *
+ * - `auto` — server-side rule auto-pruned (>14d since last firing)
+ * - `consumer-marked` — consumer called `markAdvisoryResolved`
+ * - `declined` — reserved (alpha.30+: consumer marked the suggestion
+ *   inapplicable; the advisor will still fire but UIs can hide it)
+ */
+type AdvisoryResolutionSource = 'auto' | 'consumer-marked' | 'declined';
+/**
+ * Suggested-fix metadata. `null` when the advisor has no actionable fix
+ * (info-level rules can be observational). When set, the consumer's
+ * Admin UI can render a one-click apply (alpha.30+) or surface the
+ * before/after diff inline.
+ */
+interface AdvisorySuggestedFix {
+    type: 'config-change' | 'one-liner' | 'env-var' | 'manual';
+    /** File:line hint if kgauto can infer (reserved — alpha.30+). */
+    siteHint?: string;
+    before?: string;
+    after?: string;
+    docsLink?: string;
+}
+/**
+ * Per-(app_id, code) advisory rollup. The `id` is stable across polls
+ * until the rule auto-resolves and re-opens (a new firing after the 14d
+ * boundary advances `opened_at` → new id). Treat id-changes as
+ * intentional "fresh re-open" signals.
+ *
+ * Wire-shape from `actionable_advisories_v`. The transformer maps the
+ * view's snake_case columns to camelCase. See `feedback_typed_boundary_transformers.md`
+ * (L-118) for the rationale.
+ */
+interface ActionableAdvisory {
+    id: string;
+    rule: string;
+    severity: AdvisorySeverity;
+    openedAt: string;
+    lastObservedAt: string;
+    observationCount: number;
+    appliesTo: {
+        archetype?: IntentArchetypeName;
+        model?: string;
+        callSiteHint?: string;
+    };
+    message: string;
+    suggestedFix: AdvisorySuggestedFix | null;
+    /** Reserved — always `false` in alpha.29. alpha.30+ ships actual auto-apply. */
+    autoApplicable: boolean;
+    status: AdvisoryStatus;
+    resolvedAt?: string;
+    resolutionSource?: AdvisoryResolutionSource;
+    resolutionNote?: string;
+}
+/**
+ * Filter + transport for `getActionableAdvisories`. The brain JWT must
+ * carry an `app_id` claim matching `opts.appId` — RLS enforces tenant
+ * isolation on the underlying table, so a mismatch silently returns [].
+ */
+interface GetActionableAdvisoriesOptions {
+    appId: string;
+    /** Severity filter; if omitted, all severities are returned. */
+    severity?: AdvisorySeverity;
+    /** Status filter; defaults to 'open'. Pass 'all' for the full set. */
+    status?: 'open' | 'snoozed' | 'resolved' | 'all';
+    brainEndpoint: string;
+    brainJwt: string;
+    brainAnonKey: string;
+    fetch?: typeof fetch;
+}
+interface MarkAdvisoryResolvedOptions {
+    /** Stable id from a prior `getActionableAdvisories` call. */
+    id: string;
+    resolutionNote?: string;
+    brainEndpoint: string;
+    brainJwt: string;
+    brainAnonKey: string;
+    fetch?: typeof fetch;
+}
+/**
+ * Query the open advisory set for an app. Pulls from
+ * `actionable_advisories_v` (per-(app_id, code) rollup with stable ids
+ * + server-side auto-resolution).
+ *
+ * Default behavior (no status filter): returns only `status='open'`.
+ * Pass `status: 'all'` to see resolved + open together — useful for
+ * Admin UIs that show "recently fixed" badges.
+ *
+ * Fetch failures bubble out as thrown Errors. (`markAdvisoryResolved`
+ * uses the ok/reason envelope; this read path throws to match
+ * existing kgauto query semantics where the consumer can decide to
+ * retry or render an error state.)
+ */
+declare function getActionableAdvisories(opts: GetActionableAdvisoriesOptions): Promise<ActionableAdvisory[]>;
+/**
+ * Mark an advisory as consumer-resolved.
+ *
+ * Lookup strategy:
+ *   1. Query `actionable_advisories_v?id=eq.<id>` to find the (app_id, code)
+ *      tuple for this advisory.
+ *   2. PATCH the latest unresolved firing in `compile_outcome_advisories`
+ *      matching that tuple via the underlying outcome's app_id.
+ *
+ * The (app_id, code) lookup is necessary because `compile_outcome_advisories`
+ * has no `app_id` column — it inherits scope via the FK to compile_outcomes.
+ * PostgREST cannot PATCH with a JOIN predicate, so the markAdvisoryResolved
+ * path is a two-step round-trip. The cost is one extra GET per resolve call;
+ * acceptable because marks are low-frequency operator actions, not per-call
+ * hot path.
+ *
+ * Idempotent re-marks: if the advisory is already resolved (no unresolved
+ * firings match), the PATCH affects zero rows and the call still returns
+ * `ok: true`. The function returns `ok: false` only on transport / auth /
+ * lookup failures.
+ *
+ * Returns ok/reason envelope (vs throwing) because consumer Admin UIs
+ * typically want to render the failure inline rather than crash.
+ */
+declare function markAdvisoryResolved(opts: MarkAdvisoryResolvedOptions): Promise<{
+    ok: true;
+} | {
+    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).
+ *
+ * One question, one answer: *given this model and this intent, can it work
+ * — and if not, what adapter (if any) would make it work?*
+ *
+ * Replaces the silent-archetype-cliff failure mode where a consumer picks a
+ * model that's structurally wrong for the intent and kgauto compiles cleanly
+ * without surfacing the gap. The triggering incident: tt-intel shipped
+ * `deepseek-v4-pro` as the hunt default per a local spec; the kgauto coord
+ * doc said L-040 — V4 is structurally wrong for hunt (sequential tools).
+ * `archetypePerf.hunt = 4` was already in the profile data. The compiler
+ * stayed silent. This API + the matching advisor rule surfaces it.
+ *
+ * Pure function. No network. No brain query. No side effects. ~1ms.
+ *
+ * Consultation doc:
+ *   command-center/advisory/kgauto/2026-05-21_archetype-cliff-advisor.md
+ *
+ * Refinements applied per tt-intel-Cairn ratification (2026-05-21):
+ *   R1: every variant carries `archetypePerf: number` (raw score) — and
+ *       `requires-adapter` adds `archetypePerfWithAdapter: number` so
+ *       consumer policy can be expressed as "accept adapter only when score
+ *       crosses some threshold WITH the adapter on."
+ *   R2: every variant carries a plain-English `reason: string`. No internal
+ *       jargon ("L-040", "archetypePerf=4") — the consumer chooses whether
+ *       to render it as UI hint or operator-tooling tooltip.
+ *   R3: `Adapter` is a CLOSED discriminated union, not `| string`. alpha.28
+ *       ships ONE variant (`toolOrchestration: 'sequential'`). Future
+ *       adapter parameters extend the union explicitly in named releases.
+ *       NO escape hatch — the whole point is catching "I added a new
+ *       adapter and forgot to update consumer policy" at compile time.
+ */
+
+/**
+ * Minimum `archetypePerf[archetype]` score to count as `compatible` under
+ * Option A (default policy). Below this, a documented adapter is needed
+ * to lift the model above the floor; if no adapter exists, the model is
+ * rejected.
+ *
+ * Matches `QUALITY_FLOOR_FOR_RECOMMENDATION` in `advisor.ts` — kgauto's
+ * library-wide convention for "below this score, swap recommendations stop."
+ */
+declare const ARCHETYPE_FLOOR_DEFAULT = 6;
+/**
+ * Absolute floor — below this, the cliff is too steep for ANY adapter to
+ * lift cleanly. Reserved under Option A (unused today; every below-floor
+ * case is gated by adapter availability). Would gate `reject` vs
+ * `requires-adapter` under a future Option B per consultation doc Q1.
+ *
+ * Exported so consumer-side policy can read it (e.g. "accept adapter only
+ * when archetypePerf >= ABSOLUTE_FLOOR + 1"). Not used internally by
+ * `getModelCompatibility` today — the gate is "does an adapter exist for
+ * this cliff?", not score-based.
+ */
+declare const ABSOLUTE_FLOOR = 4;
+/**
+ * The intent the call is expressing — archetype + optional orchestration
+ * mode. Same shape as `ir.intent.archetype` + `ir.constraints.toolOrchestration`
+ * so a consumer can pass `{ archetype: ir.intent.archetype,
+ * toolOrchestration: ir.constraints?.toolOrchestration }` directly.
+ */
+interface CompatibilityIntent {
+    archetype: IntentArchetypeName;
+    toolOrchestration?: 'parallel' | 'sequential' | 'either';
+}
+/**
+ * `Adapter` — re-exported above. Canonical definition lives in `ir.ts` to
+ * avoid an import cycle (compatibility.ts → profiles.ts → ir.ts).
+ *
+ * **CLOSED discriminated union per R3.** Future adapter parameters extend
+ * the union explicitly in named alpha releases. No `| string` escape hatch
+ * — consumer policy code SHOULD write exhaustive `switch (adapter.parameter)`
+ * and rely on the compiler to flag "I added a new adapter parameter and
+ * forgot to update the consumer's policy."
+ *
+ * alpha.28 variants:
+ *   - `{ parameter: 'toolOrchestration'; value: 'sequential'; consequence }`
+ *     Lifts DeepSeek V4-family on `hunt` from sequential-tool cliff (L-040).
+ *     The "consequence" plain-English-ifies the trade-off:
+ *     "Tool calls run one at a time — slower but reliable."
+ *
+ * alpha.29+ likely additions (per tt-intel-Cairn priority list):
+ *   - `{ parameter: 'parallelToolCalls'; value: false; consequence }`
+ *   - `{ parameter: 'maxTools'; value: number; consequence }`
+ *   - `{ parameter: 'thinkingBudget'; value: 0; consequence }`
+ *
+ * Each new variant lands in its own named release with the union extended
+ * in `ir.ts`. Consumers see the change at compile time.
+ */
+/**
+ * The compatibility verdict for a (model, intent) pair. Discriminated union
+ * on `status` — `compatible` | `requires-adapter` | `reject`.
+ *
+ * **Every variant carries `archetypePerf` (R1) + `reason` (R2):**
+ * - `archetypePerf` — the raw 0-10 score for (model, archetype). Lets
+ *   consumers build their own thresholds without re-importing the profile
+ *   registry.
+ * - `reason` — plain-English, consumer-renderable. NOT internal jargon
+ *   like "L-040 cliff" or "archetypePerf=4". Examples in R2 ratification:
+ *   - compatible:        "Suited for hunt-style parallel discovery."
+ *   - requires-adapter:  "Best with sequential tool calls for hunt — slower but works."
+ *   - reject:            "Not suited for hunt — would underperform significantly."
+ *
+ * `requires-adapter` additionally carries:
+ * - `archetypePerfWithAdapter` — estimated post-adapter score. May be an
+ *   estimate (we don't measure post-adapter scores yet); kgauto's prior is
+ *   "adapter lifts to ARCHETYPE_FLOOR_DEFAULT + 1" unless brain-evidenced.
+ * - `adapter` — the closed-union variant describing the structural change.
+ *
+ * Backward-compat: an unknown model returns `reject` with a "model not
+ * registered" reason; callers never throw. Unknown archetype is impossible
+ * at the type level (`IntentArchetypeName` is a closed union).
+ */
+type ModelCompatibility = {
+    status: 'compatible';
+    reason: string;
+    archetypePerf: number;
+} | {
+    status: 'requires-adapter';
+    reason: string;
+    archetypePerf: number;
+    archetypePerfWithAdapter: number;
+    adapter: Adapter;
+} | {
+    status: 'reject';
+    reason: string;
+    archetypePerf: number;
+};
+/**
+ * Compatibility query — *does this model fit this intent, and if not,
+ * what would?*
+ *
+ * **Rules (Option A from consultation doc Q1):**
+ * 1. If model is unregistered → `reject` with "model not registered" reason.
+ * 2. If intent provides `toolOrchestration: 'sequential'` AND that adapter
+ *    silences the cliff (because the cliff IS the sequential-tool one)
+ *    → return `compatible` with raw score (NOT the post-adapter estimate
+ *    — caller already paid the adapter, score reflects reality).
+ * 3. If raw `archetypePerf[archetype] >= ARCHETYPE_FLOOR_DEFAULT`
+ *    → `compatible`.
+ * 4. If below floor BUT a documented adapter exists that lifts to floor
+ *    → `requires-adapter` with adapter + estimated post-adapter score.
+ * 5. If below floor AND no adapter exists → `reject`.
+ *
+ * **Pure function.** Deterministic for `(modelId, intent)`. No I/O.
+ *
+ * @example
+ * ```ts
+ * import { getModelCompatibility } from '@warmdrift/kgauto-compiler';
+ *
+ * const c = getModelCompatibility('deepseek-v4-pro', { archetype: 'hunt' });
+ * // → { status: 'requires-adapter',
+ * //     reason: 'Best with sequential tool calls for hunt — slower but works.',
+ * //     archetypePerf: 4,
+ * //     archetypePerfWithAdapter: 7,
+ * //     adapter: {
+ * //       parameter: 'toolOrchestration',
+ * //       value: 'sequential',
+ * //       consequence: 'Tool calls run one at a time...'
+ * //     } }
+ *
+ * // With the adapter already declared:
+ * const c2 = getModelCompatibility('deepseek-v4-pro', {
+ *   archetype: 'hunt',
+ *   toolOrchestration: 'sequential',
+ * });
+ * // → { status: 'compatible',
+ * //     reason: 'Suited for hunt with sequential tool calls.',
+ * //     archetypePerf: 4 }
+ * ```
+ */
+declare function getModelCompatibility(modelId: string, intent: CompatibilityIntent): ModelCompatibility;
+
+/**
+ * alpha.22 — sync introspection: is brain-query mode active for a given
+ * table? Used by the advisor (`model-stale-evidence` rule) to decide
+ * whether a `judgment`-grounded chosen model is a measurement gap worth
+ * surfacing. Returns false on cold start, when configureBrain() was never
+ * called, or when the consumer explicitly opted the table out via
+ * `BrainConfig.brainQuery.<table> = false`.
+ */
+declare function isBrainQueryActiveFor(table: string): boolean;
+interface GetPerAxisMetricsOpts {
+    /** App id to filter on. Required. */
+    appId: string;
+    /** Intent archetype to filter on. Required. */
+    archetype: string;
+    /** Canonical model id to filter on. Required. */
+    model: string;
+    /**
+     * Window in days. Default 30. Only rows with
+     * `created_at > now() - windowDays` are counted.
+     */
+    windowDays?: number;
+    /**
+     * Consumer-declared quality floor (0..1 oracle/approve-rate scale).
+     * When set, the response's `qualityFloorMet` is true/false; when omitted,
+     * `qualityFloorMet` is null (no floor declared, no judgment).
+     */
+    qualityFloor?: number;
+    /** Pluggable fetch (tests inject mock). Defaults to global fetch. */
+    fetch?: typeof fetch;
+    /**
+     * PostgREST base endpoint (e.g. `https://kgauto-brain.vercel.app/api`).
+     * When omitted, falls back to the active configureBrainQuery runtime's
+     * endpoint. Returns null when neither is set.
+     */
+    endpoint?: string;
+    /** Bearer token. Forwarded as `Authorization: Bearer ${apiKey}`. */
+    apiKey?: string;
+}
+/**
+ * Call the `get_per_axis_metrics` RPC and return the typed result.
+ *
+ * Returns null when:
+ *   - no endpoint provided AND no configureBrainQuery runtime active
+ *   - RPC returns empty / null / unexpected shape
+ *   - brain unreachable / fetch throws / HTTP error
+ *
+ * Never throws — operator-facing query, must not blow up the caller.
+ */
+declare function getPerAxisMetrics(opts: GetPerAxisMetricsOpts): Promise<PerAxisMetrics | null>;
+
+/**
+ * env.ts — provider env-key resolution + reachability predicates.
+ *
+ * Centralizes the per-provider env var names that kgauto checks for
+ * reachability. Used by:
+ *
+ *   - execute.ts          — to find an API key when one isn't passed via apiKeys
+ *   - call.ts             — to auto-filter unreachable models from the fallback walk
+ *   - getDefaultFallbackChain — opt-in chain filter when consumer passes `reachability`
+ *   - operator scripts    — getReachabilityDiagnostic() prints what's wired up
+ *
+ * Keeping the map in ONE place means execute() and the reachability check
+ * always agree. Without this, kgauto could declare a model "reachable" because
+ * env.ts found GOOGLE_GENERATIVE_AI_API_KEY, while execute() looks at
+ * GOOGLE_API_KEY only and 401s — shipping the bug we're trying to fix.
+ *
+ * Resolution order (apiKeys takes precedence):
+ *   1. opts.apiKeys?.[provider]
+ *   2. process.env[name] for each name in PROVIDER_ENV_KEYS[provider] (first-present wins)
+ *
+ * alpha.10 (2026-05-14). Resolves the auto-filter-unreachable-models-silently
+ * request from PB after first-deploy 401 on the alpha.9 summarize chain.
+ */
+
+/**
+ * Providers kgauto can resolve keys for today. Subset of `Provider` — `mistral`
+ * and `xai` are declared in the type union but not yet executable (no profiles,
+ * no execute() handler, no env-var convention). Narrowing here keeps the
+ * reachability check structurally honest.
+ */
+type SupportedProvider = 'anthropic' | 'google' | 'openai' | 'deepseek';
+/**
+ * Per-provider env var names kgauto recognizes. Order doesn't matter —
+ * first-present wins. Multiple names per provider supported because Google
+ * has historical drift (`GOOGLE_API_KEY` from older Google Cloud SDKs,
+ * `GEMINI_API_KEY` in many examples, `GOOGLE_GENERATIVE_AI_API_KEY` is the
+ * Vercel AI SDK convention used by IC + tt-intel adapters).
+ *
+ * Frozen so consumers/tests can't mutate (would break the cache invariant
+ * that execute() and reachability checks agree).
+ */
+declare const PROVIDER_ENV_KEYS: Readonly<Record<SupportedProvider, readonly string[]>>;
+interface ReachabilityOpts {
+    /** Explicit keys (alpha.3 ApiKeys). Checked first; takes precedence over env. */
+    apiKeys?: ApiKeys;
+    /**
+     * Override env source. Defaults to `process.env` in Node-shaped runtimes,
+     * `{}` everywhere else. Pass `{}` explicitly in tests for hermetic runs.
+     */
+    envSource?: Record<string, string | undefined>;
+}
+/**
+ * Resolve a usable API key for the provider. Returns the key string, or
+ * undefined if neither apiKeys nor any of the env names are set.
+ *
+ * Used internally by execute.ts so the reachability check and the actual
+ * call check stay in sync.
+ */
+declare function resolveProviderKey(provider: Provider, opts?: ReachabilityOpts): string | undefined;
+/**
+ * True iff the provider has a usable key — either via explicit `apiKeys`
+ * or one of the `PROVIDER_ENV_KEYS[provider]` names is set in envSource.
+ */
+declare function isProviderReachable(provider: Provider, opts?: ReachabilityOpts): boolean;
+/**
+ * True iff the model's profile exists AND its provider is reachable.
+ * Unknown model id returns false (treat as unreachable; the chain walker
+ * will surface "no reachable models" if everything filters out).
+ */
+declare function isModelReachable(modelId: string, opts?: ReachabilityOpts): boolean;
+interface ProviderReachability {
+    reachable: boolean;
+    /** How the key was found. `null` when unreachable. */
+    via: 'apiKeys' | 'env' | null;
+    /** Which env var name supplied the key (only when via === 'env'). */
+    envKeyFound?: string;
+}
+/**
+ * Snapshot of which providers are reachable from the current env / apiKeys.
+ * Useful for operator scripts ("kgauto diagnose"), startup-time logging,
+ * and the cost-watcher's "which consumer is missing what" report.
+ *
+ * Does NOT log the key value itself — only the env var name that supplied it.
+ */
+declare function getReachabilityDiagnostic(opts?: ReachabilityOpts): Record<SupportedProvider, ProviderReachability>;
+/**
+ * Brain-read env contract — canonical names + accepted fallbacks for the
+ * env vars kgauto's brain-read APIs need.
+ *
+ * Affected APIs: `getActionableAdvisories`, `markAdvisoryResolved`,
+ * `markExclusionFindingHandled`, `markPromoteReadyHandled`,
+ * `getStaleExclusionFindings`, and future brain-read surfaces. Each accepts
+ * `brainEndpoint`/`brainJwt`/`brainAnonKey` as call-site arguments; this
+ * helper centralizes resolution from the consumer's environment.
+ *
+ * Resolution order (first-truthy-trimmed wins):
+ *   endpoint = KGAUTO_V2_BRAIN_SUPABASE_URL ?? KGAUTO_V2_BRAIN_URL
+ *   jwt      = KGAUTO_V2_BRAIN_JWT          ?? GLASSBOX_BRAIN_JWT
+ *   anonKey  = KGAUTO_V2_BRAIN_ANON_KEY     (no fallback)
+ *
+ * Why fallbacks exist:
+ *
+ *   1. Pre-alpha.42, some consumers set `KGAUTO_V2_BRAIN_URL` pointing at
+ *      the kgauto-dashboard URL (write target). The canonical
+ *      `KGAUTO_V2_BRAIN_SUPABASE_URL` is the Supabase project URL (read
+ *      target — PostgREST against `/rest/v1/`). Until consumers split the
+ *      two names, the fallback grabs whichever URL is set. When BOTH are
+ *      set, canonical wins (the consumer has explicitly split).
+ *
+ *   2. The s33 Glass-Box ship provisioned `GLASSBOX_BRAIN_JWT` across all
+ *      consumers with the same `app_id` claim shape, signed by the same
+ *      JWT_SECRET. Reusing it for brain-read avoids re-minting + re-pasting
+ *      a second JWT per consumer per surface.
+ *
+ * `missingEnv` lists the CANONICAL names that aren't satisfied by either
+ * canonical OR fallback. Consumer policy: if `missingEnv.length > 0`,
+ * render `not_configured`; otherwise pass `endpoint`/`jwt`/`anonKey` to
+ * `getActionableAdvisories({ ... })` et al.
+ *
+ * Pre-trim semantics carry from `readKeyValue` — paste-newline-trap
+ * (L-060 / L-083 / L-108) closure extends to brain env vars.
+ *
+ * Filed by tt-intel-Cairn (s89, 2026-05-27) after the s89 actionable-
+ * advisories ref template hit `malformed brain response` on prod because
+ * the endpoint env var pointed at the kgauto-dashboard URL instead of the
+ * Supabase URL, AND because IC's ref template used a third env name
+ * (`KGAUTO_V2_BRAIN_ENDPOINT`) that was unset. Three distinct name shapes
+ * across two consumers — the durable closure is one canonical contract.
+ */
+interface BrainReadEnv {
+    /** Supabase project URL (PostgREST base). Undefined when neither canonical nor fallback is set. */
+    endpoint?: string;
+    /** JWT carrying `app_id` claim, signed by brain JWT_SECRET. Undefined when neither canonical nor fallback is set. */
+    jwt?: string;
+    /** Supabase anon (publishable) key. Undefined when not set. */
+    anonKey?: string;
+    /**
+     * Canonical names not satisfied by either canonical OR fallback. Subset
+     * (in order) of:
+     *   ['KGAUTO_V2_BRAIN_SUPABASE_URL', 'KGAUTO_V2_BRAIN_JWT', 'KGAUTO_V2_BRAIN_ANON_KEY']
+     * Consumer policy: render `not_configured` when length > 0.
+     */
+    missingEnv: string[];
+}
+/**
+ * Resolve brain-read env vars. Defaults to `process.env`; pass `envSource`
+ * for hermetic tests. Trims surrounding whitespace and treats
+ * empty-after-trim as unset (same shape as `resolveProviderKey`).
+ */
+declare function readBrainReadEnv(envSource?: Record<string, string | undefined>): BrainReadEnv;
+
+/**
+ * getDefaultFallbackChain — the alpha.9 cascading ship.
+ *
+ * Returns a per-archetype fallback chain that walks the cost/performance
+ * Pareto frontier (master plan §1.3 + §3). Three customer postures:
+ *
+ *   locked    — caller passes [theOneModel]; never call this function
+ *   preferred — caller passes `primary`; chain returned is [primary, ...fallbacks]
+ *   open      — caller passes no `primary`; chain returned is [best, ...fallbacks]
+ *
+ * The chain at each step:
+ *   1. Costs strictly less than the previous (no expensive sideways moves)
+ *   2. Comes from a different provider than the previous step where possible
+ *      (correlated outages don't kill consecutive attempts)
+ *   3. Stays above the archetype's perf floor (skip models scored <baseline
+ *      for archetypes where degradation would be unacceptable)
+ *
+ * In alpha.9 the chain is **hand-curated** per archetype (§3.3 starter
+ * table). Brain-query mode lands in alpha.10. Policy.blockedModels filters
+ * the result; policy.maxCostPerCallUsd is NOT applied here because the
+ * function doesn't see the IR's token counts — that filtering happens at
+ * `passScoreTargets()` time inside compile().
+ *
+ * The function is **pure** — no brain query, no I/O, no randomness. Same
+ * inputs always produce the same chain.
+ */
+
+/**
+ * Posture passed into `getDefaultFallbackChain`. The chain function only
+ * sees `'open'` and `'preferred'` — callers in `'locked'` posture should
+ * pass `models: [theOneModel]` directly and skip this function entirely.
+ *
+ * Equivalent to `CompilePolicy.posture` minus `'locked'`. Kept distinct so
+ * the type system enforces "don't ask for a chain when you don't want one."
+ */
+type FallbackPosture = 'open' | 'preferred';
+interface GetDefaultFallbackChainOpts {
+    /** The archetype the call is performing. Drives chain shape. */
+    archetype: IntentArchetypeName;
+    /**
+     * The user-selected or caller-anchored primary model. When provided, it
+     * appears at position 0 of the returned chain and fallbacks follow.
+     * When omitted, the function picks the best-perf model for the archetype
+     * as position 0 (open posture).
+     */
+    primary?: string;
+    /**
+     * Informational. `'preferred'` and `'open'` produce the same chain shape
+     * given the same `primary`/no-primary input — posture is a tag the brain
+     * uses to distinguish "user-anchored" from "library-anchored" telemetry.
+     */
+    posture?: FallbackPosture;
+    /**
+     * Cap on chain length. Default 3. Min 1. Useful when the consumer wants
+     * to keep the worst-case latency low (each fallback adds a round-trip).
+     */
+    maxDepth?: number;
+    /**
+     * Consumer-side gating. `blockedModels` are filtered from the chain.
+     * `preferredModels` is informational (no boost applied at this layer —
+     * compile()'s `passScoreTargets` handles preference ranking).
+     * `maxCostPerCallUsd` is NOT applied here — needs IR-level token
+     * estimation. Use compile()'s policy plumbing instead.
+     */
+    policy?: CompilePolicy;
+    /**
+     * alpha.10. When provided, the chain is filtered to models whose provider
+     * has a reachable API key (via `apiKeys` or one of `PROVIDER_ENV_KEYS[provider]`).
+     * Models whose provider can't be reached are silently dropped. If filtering
+     * leaves the chain empty, returns `[]` — caller decides what to do (call()
+     * throws CallError; this function stays pure).
+     *
+     * Pass `{}` to opt in with `process.env` as the env source. Pass `{ apiKeys, envSource }`
+     * for explicit control (tests, non-Node runtimes). Omit entirely for the
+     * legacy unfiltered behavior — preserves alpha.9 callers byte-for-byte.
+     */
+    reachability?: ReachabilityOpts;
+    /**
+     * alpha.20 E3: consumer-declared tool-orchestration shape. Currently
+     * only affects `archetype: 'hunt'`, where 'sequential' swaps the
+     * parallel-tool-tier-0 chain (Flash → Pro → Sonnet → Haiku) for a
+     * DeepSeek-tier-0 chain (V4-Pro → Flash → Sonnet) — DeepSeek's L-040
+     * parallel-tool cliff doesn't apply when the consumer commits to
+     * single-step orchestration.
+     *
+     * Other archetypes are NOT mode-aware in this release — they ship the
+     * same chain regardless of toolOrchestration. Future versions may
+     * extend mode-awareness to ask/generate/etc. when brain evidence
+     * supports it.
+     *
+     * Default (omitted or 'either'): parallel chain. Back-compat with all
+     * pre-alpha.20 callers.
+     */
+    toolOrchestration?: 'parallel' | 'sequential' | 'either';
+}
+/**
+ * Returns the fallback chain for an archetype as a plain `string[]` of
+ * model ids.
+ *
+ * @deprecated since alpha.21 — prefer
+ * {@link getDefaultFallbackChainWithGrounding}, which returns the same chain
+ * shape with a `grounding` label on every entry (measured / capability-fact /
+ * judgment). The string[] return is preserved indefinitely for back-compat —
+ * no functional change in alpha.21. Existing callers don't need to migrate
+ * unless they want to surface the grounding gap to users.
+ */
+declare function getDefaultFallbackChain(opts: GetDefaultFallbackChainOpts): string[];
+/**
+ * Returns a shallow copy of the hand-curated starter chain for an archetype.
+ * Useful for tests + the `scripts/digest.mjs` operator readout.
+ */
+declare function getStarterChain(archetype: IntentArchetypeName): string[];
+/**
+ * Returns a shallow copy of all starter chains keyed by archetype.
+ * Useful for the `digest.mjs` readout and consumer audits.
+ */
+declare function getAllStarterChains(): Record<IntentArchetypeName, string[]>;
+/**
+ * alpha.20 E3 introspection — returns the sequential-mode overlay for an
+ * archetype, or `undefined` when no overlay is registered (the archetype
+ * is mode-agnostic and reuses `STARTER_CHAINS[archetype]`).
+ *
+ * Useful for tests + the `scripts/digest.mjs` operator readout to surface
+ * the mode-aware chains.
+ */
+declare function getSequentialStarterChain(archetype: IntentArchetypeName): string[] | undefined;
+/**
+ * alpha.21 (s78 Entry 1) — returns the fallback chain as `ChainEntry[]`,
+ * with a `grounding` label on every position.
+ *
+ * Same selection logic as {@link getDefaultFallbackChain} (primary anchoring,
+ * blockedModels filter, dedupe, reachability filter, maxDepth cap) — the
+ * only difference is the return shape: each position is a `ChainEntry`
+ * carrying `{ id, grounding, reason?, n? }` instead of a bare string.
+ *
+ * Use this when surfacing the chain to consumers who care WHY each entry
+ * sits where it sits — Glass-Box panels, operator dashboards, eval
+ * scaffolding deciding which entries deserve measurement priority.
+ *
+ * Returns `[]` when filtering empties the chain (same semantics as the
+ * string variant) — consumer decides what to do.
+ */
+declare function getDefaultFallbackChainWithGrounding(opts: GetDefaultFallbackChainOpts): ChainEntry[];
+/**
+ * alpha.21 introspection — returns the grounded starter chain for an
+ * archetype (no primary anchoring, no policy filtering, no maxDepth cap).
+ * Use this when you want the raw, hand-curated grounded chain — every
+ * entry carries a `grounding` label and optional reason/n.
+ */
+declare function getStarterChainWithGrounding(archetype: IntentArchetypeName): ChainEntry[];
+/**
+ * alpha.21 introspection — all grounded starter chains keyed by archetype.
+ * Useful for the `digest.mjs` readout and consumer audits that want to
+ * surface the grounding gap across the entire chain table.
+ */
+declare function getAllStarterChainsWithGrounding(): Record<IntentArchetypeName, ChainEntry[]>;
+/**
+ * alpha.21 introspection — sequential-mode overlay with grounding labels,
+ * or `undefined` when no overlay is registered for the archetype.
+ */
+declare function getSequentialStarterChainWithGrounding(archetype: IntentArchetypeName): ChainEntry[] | undefined;
+
+/**
+ * chains-brain — alpha.11 KG-11 adapter.
+ *
+ * Brain-driven STARTER_CHAINS for `getDefaultFallbackChain`. Reads
+ * `kgauto_chains` table via the shared brain-query SWR cache (D6 + D8);
+ * falls back to bundled STARTER_CHAINS on cold-start, brain-down, or
+ * empty/missing table (D2 + D4).
+ *
+ * Behavioral note (locked via D2): the sync API surface returns bundled on
+ * cold-start, with a background refresh fired. Subsequent calls within the
+ * 5-min TTL return brain data. Vercel cold-start consumers see the seed
+ * snapshot (functionally identical to pre-alpha.11); warm-start consumers
+ * see live brain mutations within 5 min.
+ */
+/**
+ * Sync reader for the brain-driven chains map. Returns bundled
+ * STARTER_CHAINS when brain-query is disabled, cold, or unreachable.
+ */
+declare const loadChainsFromBrain: () => Record<"ask" | "hunt" | "classify" | "summarize" | "generate" | "extract" | "plan" | "critique" | "transform", string[]>;
+
+/**
+ * archetype-perf-brain — alpha.11 KG-12 adapter.
+ *
+ * Brain-driven archetypePerf scores. Substrate for the future closed-loop
+ * tuning engine (KG-12.5): brain telemetry → human or automated bumps →
+ * brain UPDATE → consumers see new scores within 5-min cache TTL with
+ * zero refresh.
+ *
+ * Today: data migrates to brain. No runtime call site reads archetypePerf
+ * (it's metadata for the master plan §2.5 anti-hallucination guardrail +
+ * future auto-tuning). The adapter exists so future readers — auto-tuning
+ * + operator scripts + KG-12.5 — have a shipped substrate to consume.
+ */
+
+type ArchetypePerfMap = Map<string, Partial<Record<IntentArchetypeName, number>>>;
+/**
+ * alpha.21: per-(model, archetype) row count map. Same shape as
+ * ArchetypePerfMap but stores brain row counts when the brain backs a
+ * placement. Undefined entries → no row count seen → score is the
+ * hand-curated cold-start prior (grounding='judgment').
+ */
+type ArchetypePerfNMap = Map<string, Partial<Record<IntentArchetypeName, number>>>;
+/**
+ * Sync reader for the brain-driven archetypePerf map. Returns bundled
+ * profile.archetypePerf data when brain-query is disabled, cold, or
+ * unreachable. Identical shape pre/post-alpha.11 by design (D2).
+ */
+declare const loadArchetypePerfFromBrain: () => ArchetypePerfMap;
+/**
+ * alpha.21 — sync reader for the brain row-count map paired with
+ * archetype-perf. Returns empty map (no measured backing) on cold start /
+ * brain-down / unreachable — all `getArchetypePerfScore` calls then
+ * resolve to `grounding: 'judgment'`. When the brain table includes an
+ * `n` column on each row, this map mirrors those counts so consumers can
+ * see how many measurements back each score.
+ */
+declare const loadArchetypePerfNFromBrain: () => ArchetypePerfNMap;
+/**
+ * Threshold above which a brain row count counts as 'measured' grounding.
+ * Below this, the score is treated as 'judgment' (cold-start prior or
+ * not-yet-enough-evidence). Mirrors the alpha.20 `getCleanPerfScore`
+ * `minRows` default — same rule for consistency.
+ */
+declare const MEASURED_GROUNDING_MIN_N = 10;
+/**
+ * alpha.21 — return shape for the extended {@link getArchetypePerfScore}.
+ * Wraps the existing 0..10 score with:
+ *
+ *   - `n`: brain row count backing this score (0 when no measurement).
+ *   - `grounding`: derived label — 'measured' when n >= 10, else 'judgment'.
+ *
+ * The score itself is unchanged from pre-alpha.21 (numeric, 5 = neutral
+ * default). 'capability-fact' is NOT a perf-score grounding — capability
+ * decisions live on chain entries, not on perf scores.
+ */
+interface ArchetypePerfScoreResult {
+    /** 0..10 perf score. 5 = neutral default when no entry exists. */
+    score: number;
+    /**
+     * Brain row count backing this score. 0 when bundled (cold-start prior)
+     * or when the brain row didn't carry an `n` column.
+     */
+    n: number;
+    /**
+     * Provenance — 'measured' when `n >= 10`, else 'judgment'.
+     * Never 'capability-fact' (that label is reserved for chain-entry
+     * inclusion/exclusion decisions).
+     */
+    grounding: Grounding;
+}
+/**
+ * Per-model accessor with grounding (alpha.21). Returns 5 (neutral) when no
+ * entry is found — consistent with the master plan §3.3 "missing archetypes
+ * default to 5" convention documented in profiles.ts
+ * ModelProfile.archetypePerf.
+ *
+ * Backwards-compat note: pre-alpha.21 callers expected `number` here. The
+ * new return shape `{ score, n, grounding }` is a breaking shape change at
+ * the type level, but `.score` carries the legacy value. Callers reading
+ * `.score` field-by-field continue working; callers using the bare number
+ * arithmetically need to switch to `.score`. The migration is single-line
+ * (`const x = getArchetypePerfScore(...)` → `const x = getArchetypePerfScore(...).score`).
+ */
+declare function getArchetypePerfScore(modelId: string, archetype: IntentArchetypeName): ArchetypePerfScoreResult;
+
+/**
+ * pricing-brain — alpha.11 KG-13 adapter.
+ *
+ * Brain-driven pricing data with **time-bounded resolution** (`valid_from`
+ * / `valid_until` columns). The V4-Pro 75%-off promo through 2026-05-31
+ * gets modeled as two rows; `at` parameter resolution picks the correct
+ * row per call timestamp. Promo flips happen automatically at the
+ * boundary without alpha cuts.
+ *
+ * SWR cache holds the FULL pricing snapshot (all active rows for all
+ * models). Per-call `at` filtering is in-memory — keeps the SWR semantics
+ * uniform with other adapters (one cache, one snapshot, sync reads).
+ */
+interface PricingRow {
+    modelId: string;
+    costInputPer1m: number;
+    costOutputPer1m: number;
+    cacheInputPer1m?: number;
+    cacheCreationPer1m?: number;
+    validFrom: number;
+    validUntil?: number;
+    source?: string;
+}
+/**
+ * Sync reader for the brain-driven pricing snapshot. Returns bundled
+ * profile pricing when brain-query is disabled, cold, or unreachable.
+ * Caller filters by `at` via {@link resolvePricingAt}.
+ */
+declare const loadPricingFromBrain: () => PricingRow[];
+/**
+ * Resolve the active pricing row for a model at a given timestamp.
+ * Picks the row with the latest `valid_from <= at` whose
+ * `valid_until > at` (or NULL — open-ended).
+ *
+ * Returns `undefined` when no row matches. Callers should fall back to
+ * profile static pricing in that case.
+ */
+declare function resolvePricingAt(modelId: string, at?: Date): PricingRow | undefined;
+
+/**
+ * models-brain — alpha.11 KG-14 adapter (the largest of the four).
+ *
+ * Brain-driven model registry + aliases. Two adapters share the same
+ * SWR snapshot:
+ *
+ * - `loadModelsFromBrain()` — `Map<modelId, ModelProfile>` from
+ *   `kgauto_models` table (cliffs/lowering/recovery as JSONB columns).
+ * - `loadAliasesFromBrain()` — `Record<aliasId, canonicalId>` from
+ *   `kgauto_aliases` table.
+ *
+ * After alpha.11, new-model onboarding becomes brain INSERT (vs PR + alpha
+ * cut + 3 consumer refreshes). The auto-onboard pipeline
+ * (`scripts/check-model-releases.mjs`) shifts from emitting profile.ts
+ * edits to writing brain rows directly.
+ *
+ * **D5 — alias resolution stable regardless of canonical's active state.**
+ * `canonicalId('deepseek-chat') → 'deepseek-v4-flash'` even when the
+ * canonical row is `active=false`. Aliases are wire-format contracts;
+ * legacy callers' resolution promise outlives the canonical's active
+ * status. Deprecation (`active=false`) affects chain composition only.
+ */
+
+/**
+ * Exported brain-row shape for `kgauto_models`. Mirrors the SQL table
+ * (`v2/brain/migrations/010_kgauto_models_and_aliases.sql`) — column names
+ * are snake_case to match PostgREST. Used by operator scripts that write
+ * to brain (auto-onboard, promote-model) — see `profileToRow()`.
+ *
+ * Read path stays internal via `RawModelRow` to keep `rowToProfile()`'s
+ * tolerance contract from leaking into write callers.
+ */
+interface ModelBrainRow {
+    model_id: string;
+    provider: string;
+    status?: string;
+    max_context_tokens?: number;
+    max_output_tokens?: number;
+    max_tools?: number;
+    parallel_tool_calls?: boolean;
+    structured_output?: string;
+    system_prompt_mode?: string;
+    streaming?: boolean;
+    cliffs?: unknown;
+    lowering?: unknown;
+    recovery?: unknown;
+    strengths?: string[] | null;
+    weaknesses?: string[] | null;
+    cost_input_per_1m?: number;
+    cost_output_per_1m?: number;
+    notes?: string | null;
+    verified_against_docs?: string | null;
+    archetype_perf?: Record<string, number> | null;
+    version_added?: string;
+    version_removed?: string | null;
+    active?: boolean;
+    /** alpha.41 — model-family tag (migration 024 column). */
+    family?: string | null;
+    /** alpha.49 — explicit latency bucket (migration 028 column). */
+    latency_tier?: string | null;
+    /** alpha.49 — per-archetype prompt-shape conventions (migration 028 column). */
+    archetype_conventions?: ArchetypeConvention[] | null;
+}
+interface ProfileToRowOptions {
+    /** e.g. `'2.0.0-alpha.12'` — leave undefined to omit from row. */
+    versionAdded?: string;
+    /** Pass `null` to clear; omit to leave field unset. */
+    versionRemoved?: string | null;
+    /** Defaults to true if omitted. */
+    active?: boolean;
+    /**
+     * Override verifiedAgainstDocs (e.g. set to `null` for auto-onboard).
+     * When omitted, the profile's own value is used. Pass `null` explicitly
+     * to write a SQL NULL (e.g. unverified auto-onboard rows).
+     */
+    verifiedAgainstDocs?: string | null;
+}
+/**
+ * Inverse of `rowToProfile` — serialize a `ModelProfile` to a `kgauto_models`
+ * row payload for INSERT/UPSERT. Used by operator scripts that write to
+ * brain (auto-onboard pipeline, promote-model verification CLI).
+ *
+ * Row-level fields (`version_added`, `version_removed`, `active`) are
+ * operator-controlled and pass through `opts`. `verifiedAgainstDocs` can
+ * also be overridden via `opts` — auto-onboard explicitly passes `null` to
+ * mark unverified rows (the column is DATE, doesn't accept the
+ * `'UNVERIFIED-AUTO-ONBOARD'` sentinel used in PROFILES_RAW).
+ */
+declare function profileToRow(profile: ModelProfile, opts?: ProfileToRowOptions): ModelBrainRow;
+/**
+ * Sync reader for the brain-driven model registry. Returns bundled
+ * PROFILES_RAW when brain-query is disabled, cold, or unreachable.
+ */
+declare const loadModelsFromBrain: () => Map<string, ModelProfile>;
+/**
+ * Sync reader for the brain-driven aliases map. Returns bundled ALIASES
+ * when brain-query is disabled, cold, or unreachable.
+ *
+ * D5: this map carries both active and inactive canonical mappings —
+ * alias resolution is stable regardless of canonical's `active` state.
+ */
+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[];
+
+/**
+ * Family resolution — alpha.41.
+ *
+ * "I want the latest Opus" → kgauto picks the current+active model in the
+ * `claude-opus` family. Closes the loop where consumer code carries hardcoded
+ * `claude-opus-4-6` literals long after `claude-opus-4-7` ships and goes
+ * current — the s47 trigger (IC's `generate` chain still routing 43 calls to
+ * legacy 4-6 in production).
+ *
+ * Two surfaces:
+ *   - `getRecommendedPrimary({ family, ..., fallback })` — public, sync,
+ *     used at IR-construction time when the consumer wants a literal id back
+ *     (with a fallback floor for cold-start brain).
+ *   - `resolveFamilyEntry({ family, archetype?, appId? })` — internal,
+ *     called from compile() when an IR's `models[]` entry is shaped
+ *     `{ family: string }`. Throws `FamilyResolutionError` on failure.
+ *
+ * Both routes share the same algorithm (locked in the alpha.41 Phase 0
+ * design contract); they differ only in the fallback ergonomics. The
+ * public route accepts a required `fallback: string`; the IR route throws.
+ *
+ * Pure resolution. No network. No async. Brain-registry reads go through
+ * the existing SWR cache (`loadModelsFromBrain` from `models-brain.ts`) —
+ * cold-start returns bundled profiles, which still resolve via the
+ * `deriveFamilyFromModelId` fallback when the brain row's `family` column
+ * is null (G1 contract: graceful pre-migration behavior).
+ *
+ * @see command-center/advisory/kgauto/2026-05-26_alpha-41-model-family-aliases-and-promotion-probe-watcher.md
+ */
+
+interface GetRecommendedPrimaryOptions {
+    /**
+     * Family tag (e.g. `'claude-opus'`, `'gemini-flash'`). See the Phase 0
+     * design contract's family taxonomy table for the locked initial set;
+     * extensible via brain migrations.
+     */
+    family: string;
+    /**
+     * Optional archetype gate. When provided, candidates must clear
+     * {@link ARCHETYPE_FLOOR_DEFAULT} on `archetypePerf[archetype]`. Also used
+     * as the primary sort key (DESC) when multiple candidates qualify.
+     */
+    archetype?: IntentArchetypeName;
+    /**
+     * Optional consumer-app id. When provided, candidates matching a
+     * `stay-excluded` finding for `(appId, archetype)` in the
+     * exclusion-findings cache (alpha.38 substrate) are filtered out.
+     */
+    appId?: string;
+    /**
+     * Consumer-posture tag. `'locked'` short-circuits resolution and returns
+     * the literal `fallback` unconditionally — useful for compliance /
+     * contract / brand-promise flows where the consumer doesn't want kgauto
+     * picking the model on their behalf.
+     */
+    posture?: 'preferred' | 'open' | 'locked';
+    /**
+     * Last-resort literal model id. REQUIRED. Returned when (a) brain
+     * registry is cold / no candidates exist, (b) `posture === 'locked'`,
+     * (c) every candidate was filtered out by archetype / exclusion gates.
+     *
+     * The fallback is NOT validated against the family — kgauto trusts the
+     * consumer to pass a meaningful floor. The contract intent is "even when
+     * everything below is on fire, you still get a model id back."
+     */
+    fallback: string;
+}
+/**
+ * Thrown by `resolveFamilyEntry` (the internal compile-time twin) when a
+ * `{ family: string }` IR entry can't resolve to any current+active model.
+ * Surfaces with the family string + a one-line cause so consumer error
+ * handling can distinguish "you typo'd the family tag" from "brain is cold
+ * and nothing matches."
+ *
+ * The public `getRecommendedPrimary` does NOT throw — it returns
+ * `fallback` instead.
+ */
+declare class FamilyResolutionError extends Error {
+    readonly family: string;
+    readonly cause: string;
+    constructor(family: string, cause: string);
+}
+/**
+ * Deterministic model_id → family inference. Pure function; no brain
+ * lookup. Used as the runtime fallback when a brain row's `family` column
+ * is null (pre-migration 024) and as the canonical mapping that migration
+ * 024's CASE statement mirrors.
+ *
+ * Returns null for unrecognized ids — caller must handle (typically by
+ * skipping the row in family resolution).
+ *
+ * Order matters: more specific patterns first (e.g. `flash-lite` before
+ * `flash`; `pro` before `chat`). The brain-side CASE statement uses the
+ * same priority.
+ */
+declare function deriveFamilyFromModelId(modelId: string): string | null;
+/**
+ * Public sync resolver. Pure (modulo brain snapshot read). Returns the
+ * literal model id of the best candidate, or `fallback` when resolution
+ * yields nothing.
+ */
+declare function getRecommendedPrimary(opts: GetRecommendedPrimaryOptions): string;
+
+/**
+ * promote-ready-brain — alpha.41 substrate.
+ *
+ * Per-tenant SWR cache for the `promote_ready_findings` table populated by
+ * the autonomous `promotion-probe-watcher` (Mode 2). Mirrors
+ * `exclusion-findings-brain.ts` shape byte-for-byte where applicable; this
+ * is the read-side substrate for the compile-time `promote-ready` advisor
+ * rule.
+ *
+ * Architecture (mirror of exclusion-findings-brain):
+ *
+ * - **Sync API surface.** `getPromoteReadyFindings({ appId, archetype,
+ *   family })` returns `PromoteReadyFindingRow[]` 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 reset between cases via
+ *   `_testResetPromoteReadyFindings()`.
+ *
+ * - **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 `configurePromoteReadyBrain()` having
+ *   been called with a runtime. The public `configureBrain()` in brain.ts
+ *   wires this up automatically when
+ *   `BrainConfig.brainQuery.findingsPromoteReady !== false`.
+ *
+ * Plus: `markPromoteReadyHandled` — direct PostgREST PATCH against the
+ * brain (no kgauto proxy). Mirrors `markExclusionFindingHandled` shape
+ * byte-for-byte. Idempotent on `resolved_at=is.null` filter.
+ *
+ * Default endpoint:
+ *   `https://kgauto-dashboard.vercel.app/api/kgauto-v2/findings/promote-ready`
+ *   The route accepts `?app_id=X` and returns a JSON array of findings
+ *   for that app filtered to `resolved_at IS NULL`.
+ */
+
+/**
+ * Shape of one row from the `promote_ready_findings` cache table. Mirrors
+ * the snake_case JSONB returned by the brain endpoint, mapped to camelCase
+ * at the boundary (rowToFinding) so the in-memory shape stays consistent
+ * with the rest of the library.
+ */
+interface PromoteReadyFindingRow {
+    /** Intent archetype the finding applies to. */
+    archetype: string;
+    /** Model family (e.g. 'claude-opus', 'gemini-flash'). */
+    family: string;
+    /** The candidate model that the probe validated. */
+    candidateModel: string;
+    /** The current production model the candidate was compared against. */
+    currentModel: string;
+    /** Sample size of the probe run (typically 10). */
+    sampleN: number;
+    /** Fraction of probes where the judge verdict was 'candidate-better' or
+     *  'tied'. 0.000 to 1.000. */
+    judgePassRate: number;
+    /** Mean judge score across the probe sample. 1.00 to 5.00. */
+    judgeAvgScore: number;
+    /** Signed cost delta as a fraction (negative = candidate is cheaper).
+     *  Null when pricing data was incomplete at probe time. */
+    costDeltaPct: number | null;
+    /** ISO timestamp of detection (when the probe wrote the row). */
+    detectedAt: string;
+}
+/**
+ * Resolution sources supported by alpha.41 `markPromoteReadyHandled`. The
+ * three values map to the three CHECK-constrained resolution values on
+ * `promote_ready_findings.resolution`:
+ *
+ * - `'promoted'`         — consumer migrated to the candidate model. Strong
+ *                          positive signal; the probe was right.
+ * - `'declined'`         — consumer evaluated and chose not to promote.
+ *                          Strong negative signal; revisit only on new
+ *                          family entries or material score swings.
+ * - `'still-evaluating'` — consumer acknowledges the finding but defers
+ *                          the decision. Acknowledges-without-deciding;
+ *                          finding silences this cycle but next probe may
+ *                          re-surface.
+ */
+type PromoteReadyResolution = 'promoted' | 'declined' | 'still-evaluating';
+interface MarkPromoteReadyHandledOptions {
+    /** App id the finding belongs to. Required (RLS scopes writes by this). */
+    appId: string;
+    /** Archetype the finding applies to (e.g. 'hunt', 'classify'). */
+    archetype: IntentArchetypeName | string;
+    /** Model family the finding applies to (e.g. 'claude-opus'). */
+    family: string;
+    /** Resolution semantics — see `PromoteReadyResolution`. */
+    resolution: PromoteReadyResolution;
+    /** Optional free-form note explaining the decision. */
+    resolutionNote?: string;
+    /** Brain Supabase URL base (e.g. `https://<project>.supabase.co`). */
+    brainEndpoint: string;
+    /** Consumer-scoped JWT carrying the `app_id` claim. */
+    brainJwt: string;
+    /** Supabase anon key for the `apikey` header. */
+    brainAnonKey: string;
+    /** Injected fetch for tests. Defaults to global fetch. */
+    fetch?: typeof fetch;
+}
+/**
+ * Mark a probe-validated promote-ready finding as handled. Returns an
+ * `ok/reason` envelope matching `markExclusionFindingHandled`.
+ *
+ * Idempotent: if no row matches the (app_id, archetype, family) tuple
+ * (already resolved, never existed, watcher not yet UPSERTed), PostgREST
+ * returns 200/204 with zero affected rows and we return `{ ok: true }`.
+ *
+ * Reasons surfaced on failure:
+ *   - `app_id_required` / `archetype_required` / `family_required`
+ *   - `resolution_invalid` — not one of the three documented values
+ *   - `brain_auth_misconfig` — 401/403
+ *   - `brain_unavailable` — 5xx
+ *   - `network_error:<message>` — fetch threw
+ *   - `patch_failed:<status>` — anything else non-2xx
+ */
+declare function markPromoteReadyHandled(opts: MarkPromoteReadyHandledOptions): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+
 /**
  * @warmdrift/kgauto v2 — prompt compiler + central learning brain.
  *
@@ -235,4 +2272,4 @@ declare function countTokens(text: string): number;
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ApiKeys, type AppOracle, type BrainConfig, CallOptions, CallResult, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type LLMJudgeOptions, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, PromptIR, ProviderOverrides, RecordInput, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, record, resetTokenizer, setTokenizer };
+export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, ArchetypeConvention, type ArchetypeFamilyFit, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, type BrainReadEnv, 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, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type ShadowProbeRecordInput, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, buildShadowProbeRow, call, clearBrain, compile, configureBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, probeShadow, profileToRow, readBrainReadEnv, record, recordOutcome, recordShadowProbe, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };