@warmdrift/kgauto-compiler 2.0.0-alpha.3 → 2.0.0-alpha.31

package/dist/index.d.ts

@@ -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-C5lVqF8_.js';
-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-C5lVqF8_.js';
-export { ALL_ARCHETYPES, ContextBucket, DIALECT_VERSION, HistoryDepth, INTENT_ARCHETYPES, IntentArchetypeName, OutputMode, ShapeSignature, ToolCountBucket, bucketContext, bucketHistory, bucketToolCount, hashShape, isArchetype, learningKey } from './dialect.js';
+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 SectionRewrite, R as RecordInput, e as RecordOutcomeInput, O as OutcomeResult, f as OracleScore, g as CompileResult, B as BestPracticeAdvisory, h as Adapter, i as PerAxisMetrics, j as Provider, k as ChainEntry, G as Grounding } from './ir-BIAT9gJk.js';
+export { l as CallAttempt, m as CallError, n as ChainWithGrounding, o as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, p as MutationApplied, q as NormalizedTokens, r as OutcomeKind, s as PerAxisMetricsByModel, t as PromptSection, u as SectionKind, T as ToolCall, v as ToolDefinition } from './ir-BIAT9gJk.js';
+import { ModelProfile } from './profiles.js';
+export { ALIASES, CacheStrategy, CliffRule, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, profilesByProvider, tryGetProfile } from './profiles.js';
+import { IntentArchetypeName } from './dialect.js';
+export { ALL_ARCHETYPES, ContextBucket, DIALECT_VERSION, HistoryDepth, INTENT_ARCHETYPES, OutputMode, ShapeSignature, ToolCountBucket, bucketContext, bucketHistory, bucketToolCount, hashShape, isArchetype, learningKey } from './dialect.js';
 
 /**
  * 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.
@@ -83,15 +95,28 @@ declare function execute(request: CompiledRequest, opts?: ExecuteOptions): Promi
 declare function call(ir: PromptIR, opts?: CallOptions): Promise<CallResult>;
 
 /**
- * Brain client — fire-and-forget telemetry to the central kgauto Supabase.
- *
- * The brain is the centralized learning store. Apps POST outcomes here;
- * mutations flow back through a separate pull (in v2.1).
+ * 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`.
  *
- * Design: never blocks the caller. Failures are silent (logged via optional
- * onError hook). Uses fetch() — works in Node 18+, Edge runtimes, and browsers.
+ * 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;
+    /** 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;
+}
 interface BrainConfig {
     /** Brain HTTP endpoint base URL (e.g., https://kgauto-brain.vercel.app/api). */
     endpoint: string;
@@ -103,6 +128,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 +142,90 @@ 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>;
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -189,6 +301,1078 @@ declare function resetTokenizer(): void;
  */
 declare function countTokens(text: string): number;
 
+/**
+ * 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[];
+}
+/**
+ * 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;
+}>;
+
+/**
+ * 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>;
+
+/**
+ * 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;
+}
+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>;
+
 /**
  * @warmdrift/kgauto v2 — prompt compiler + central learning brain.
  *
@@ -235,4 +1419,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, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type SupportedProvider, TRANSLATOR_FLOOR, applySectionRewrites, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };