@warmdrift/kgauto-compiler 2.0.0-alpha.9 → 2.0.0-alpha.91

package/dist/index.d.mts

@@ -1,7 +1,11 @@
-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, B as BestPracticeAdvisory } from './profiles-NUZOIzGr.mjs';
-export { f as ALIASES, g as CacheStrategy, h as CallAttempt, i as CallError, j as CliffRule, k as Constraints, F as FallbackReason, H as HistoryCachePolicy, 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-NUZOIzGr.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';
+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, B as BestPracticeAdvisory, F as FallbackReason, f as SectionRewrite, R as RecordInput, g as RecordOutcomeInput, O as OutcomeResult, h as OutcomeSource, i as OracleScore, j as Adapter, k as PerAxisMetrics, l as Provider, m as ChainEntry, G as Grounding } from './ir-DeYMLWge.mjs';
+export { n as CallAttempt, o as CallError, p as ChainModelEntry, q as ChainWithGrounding, r as Constraints, E as EffortLevel, s as GoldenCaptureOptions, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, t as MutationApplied, u as NormalizedTokens, v as OutcomeKind, w as PerAxisMetricsByModel, x as PromptSection, y as SectionKind, z as ShadowProbeConfig, T as ToolCall, D as ToolDefinition, J as captureGoldenIr, K as hasMutation, L as mutationId, Q as parseGoldenCaptureRate, U as resolveGoldenCaptureRate, V as shouldCaptureGolden } from './ir-DeYMLWge.mjs';
+import { ModelProfile, ArchetypeConvention } from './profiles.mjs';
+export { ALIASES, CacheStrategy, CliffRule, LATENCY_TIER_MS, LatencyTier, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, _testClearConsumerProfiles, allProfiles, bestEffortProfile, getProfile, inferProviderFromId, latencyTierOf, profilesByProvider, registerProfiles, resolveModelAlias, tryGetProfile } from './profiles.mjs';
+export { BrainForwardConfig, BrainForwardRoutes, createBrainForwardRoutes } from './brain-proxy.mjs';
+export { KEY_FINGERPRINT_DOMAIN, KEY_FINGERPRINT_LENGTH, KeyHealthConfig, KeyHealthProvider, KeyHealthResponseBody, KeyHealthResult, KeyHealthRoute, createKeyHealthRoute, keyFingerprint } from './key-health.mjs';
+import { IntentArchetypeName, OutputMode } from './dialect.mjs';
+export { ALL_ARCHETYPES, ContextBucket, DIALECT_VERSION, HistoryDepth, INTENT_ARCHETYPES, ShapeSignature, ToolCountBucket, bucketContext, bucketHistory, bucketToolCount, hashShape, isArchetype, learningKey } from './dialect.mjs';
 
 /**
  * compile() — the main orchestrator.
@@ -34,6 +38,15 @@ interface CompileOptions {
      * ceiling, boosts preferred. See CompilePolicy in ir.ts.
      */
     policy?: CompilePolicy;
+    /**
+     * alpha.68 / Release A (delegation-fanout-accelerator §5.0, R0 linkage) —
+     * transport for the fan-out parent handle. Threaded from
+     * `CallOptions.parentHandle` on the call() path (and settable directly on the
+     * public compile() path). Release A does NOT route on it — it only labels the
+     * outcome row (fanout_role / trace_id / parent_handle) at record-registration
+     * time. `registerCompile` reads it to derive the linkage. Absent ⇒ root call.
+     */
+    parentHandle?: string;
 }
 
 /**
@@ -52,6 +65,29 @@ 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;
+    /**
+     * alpha.78 — abort signal for the provider fetch. call() composes
+     * `AbortSignal.timeout(attemptTimeoutMs)` with the caller's own
+     * `CallOptions.abortSignal`; direct execute() consumers may pass anything.
+     * TimeoutError reasons classify retryable `timeout` (chain walks);
+     * AbortError reasons classify terminal `aborted` (caller cancelled).
+     */
+    signal?: AbortSignal;
+    /**
+     * alpha.78 — per-chunk stall bound, streaming paths only (see
+     * StreamingOptions.stallTimeoutMs). Ignored on non-streaming requests,
+     * where `signal` carries the total attempt bound instead.
+     */
+    stallTimeoutMs?: number;
 }
 interface ExecuteOk {
     ok: true;
@@ -65,6 +101,19 @@ interface ExecuteErr {
     errorCode: string;
     message: string;
     raw: unknown;
+    /**
+     * alpha.66 — real token usage when the failure is a SYNTHESIZED
+     * structured-output contract violation (the provider returned 200 with
+     * usage; the response just violated the contract). Absent on transport-
+     * level failures (4xx/5xx/network) where no usage exists. Lets the
+     * brain's failure rows carry true `tokens_in` for the cliff class —
+     * PB's 2026-05-18 `chain-walk-on-structured-output-parse-failed` ask 4
+     * (tokens_in=0 on a 72s parse-fail made diagnosis ambiguous).
+     */
+    tokens?: {
+        input: number;
+        output: number;
+    };
 }
 type ExecuteResult = ExecuteOk | ExecuteErr;
 declare function execute(request: CompiledRequest, opts?: ExecuteOptions): Promise<ExecuteResult>;
@@ -85,26 +134,347 @@ declare function execute(request: CompiledRequest, opts?: ExecuteOptions): Promi
  * Hard cap at fallbackChain.length + 1 attempts. Terminal errors short-circuit.
  */
 
+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>;
+
 /**
- * Compile, execute, normalize, record. Returns a CallResult once a provider
- * actually serves the request. Throws CallError if the fallback chain is
- * exhausted without success.
+ * 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.
  */
-declare function call(ir: PromptIR, opts?: CallOptions): Promise<CallResult>;
 
 /**
- * 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).
+ *
+ * Otherwise the structured `SystemModelMessage[]` form is returned —
+ * preserves the per-section cacheControl markers across `streamText`.
+ *
+ * @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.52 — official AI-SDK-v6 compile adapter + compile-then-discard guard.
+ *
+ * Until now each AI-SDK consumer (tt-intel, IC) hand-rolled this adapter in
+ * its own `lib/kgauto-v2/index.ts`: `compile()` → reassemble the system param
+ * per provider → extract kept tool names per provider → re-derive the history
+ * cache-mark index (a copy of the compiler's own `historyCacheMarkIndex`
+ * logic — drift-prone). This centralizes that boilerplate and DRYs the two
+ * near-identical wrappers.
  *
- * The brain is the centralized learning store. Apps POST outcomes here;
- * mutations flow back through a separate pull (in v2.1).
+ * It also closes the compile-then-discard hole. The discard pattern is:
+ *
+ *     const c = compileForAISDKv6(ir);            // compile runs
+ *     const out = await generateText({            // …but a hand-built prompt
+ *       model: getModel(otherId), prompt });      //    + a DIFFERENT model run
+ *     await record({ handle: c.handle, … });      // brain row attributed to `c`
+ *
+ * The recorded row's `mutations_applied` / `estimated_tokens_in` /
+ * `system_prompt_chars` then describe a compile that never reached the wire.
+ * A library-level runtime guard could NOT catch this while the adapter lived
+ * in consumer code (the consumer wrapper always reads `compile()`'s result to
+ * build its own object, so any getter there is "consumed" every time,
+ * regardless of whether the final caller used the wrapper output). With the
+ * adapter IN the library, the object the FINAL caller reads is library-owned,
+ * so consume-tracking getters on `.system` / `.model` / `.raw` detect non-use
+ * and `record()` warns. See `interfaces/kgauto.md` (## Requested:
+ * `compiled-output-discarded-guard`).
+ *
+ * The guard is OPT-IN-BY-USE: only `compileForAISDKv6` arms tracking, so
+ * `call()` paths and raw `compile()` users never see a false warning.
+ */
+
+interface CompileForAISDKv6Result {
+    /**
+     * Pass to `streamText`/`generateText({ model })` — the caller maps this id
+     * to an AI-SDK `LanguageModel`. Reading this marks the compile "consumed"
+     * (silences the compile-then-discard guard).
+     */
+    readonly model: string;
+    /**
+     * System parameter for `streamText`/`generateText({ system })`. Returns the
+     * structured `SystemModelMessage[]` form when the target is Anthropic AND a
+     * cacheable section exists (preserves the cache_control marker across the
+     * wire); a flat concatenated string otherwise. Reading this marks
+     * "consumed". (Same rule as `attachCacheControlToStreamTextInput`.)
+     */
+    readonly system: string | SystemModelMessage[];
+    /**
+     * The raw kgauto `CompileResult` — for `attachCacheControlToStreamTextInput(raw, msgs)`
+     * and `probeShadow(raw.ir-equivalent, …)` paths. Reading this marks
+     * "consumed" (it means you're using the compile output via the raw result).
+     */
+    readonly raw: CompileResult;
+    /** Tool names that survived budget + relevance — filter your SDK tool map to these. */
+    keptToolNames: Set<string>;
+    /** providerOptions for `streamText` — Anthropic cache_control on the cacheable prefix. Undefined otherwise. */
+    providerOptions?: {
+        anthropic?: {
+            cacheControl?: {
+                type: 'ephemeral';
+            };
+        };
+    };
+    /**
+     * Index (into post-strip history) for the Anthropic history cache marker
+     * (alpha.33). Mirror of `result.diagnostics.historyCacheMarkIndex` — no
+     * consumer re-derivation needed. Undefined when no marker fires, and (since
+     * alpha.55) always undefined for non-Anthropic targets: the marker is an
+     * Anthropic wire concept, other providers cache prefixes implicitly. The
+     * ungated value remains on `diagnostics.historyCacheMarkIndex`.
+     */
+    historyCacheMarkIndex?: number;
+    /** Compile handle — pass to `record()` after the call. */
+    handle: string;
+    /**
+     * Mutation ids the compiler fired (informational).
+     *
+     * ⚠️ alpha.78 — element type differs BY SURFACE: this adapter carries
+     * `string[]` (ids), while `CompileResult`/`CallResult.mutationsApplied`
+     * carry `MutationApplied[]` (objects with `description`, `rankDelta`, …).
+     * Coding to one surface's type while reading the other's runtime is a
+     * silent false negative (PB 2026-07-25). Use the shape-proof helpers
+     * `mutationId(m)` / `hasMutation(list, 'quality-gate-measured-*')` from
+     * the package root instead of `typeof` checks. Neither element type can
+     * change without breaking a live consumer (tt-intel joins these ids;
+     * object readers want `description`), so the divergence is documented
+     * rather than unified.
+     */
+    mutationsApplied: string[];
+    /** Best-practice advisories (alpha.6). Empty when none fired. */
+    advisories: BestPracticeAdvisory[];
+    /** Compiler diagnostics + the three commonly-logged top-level fields. */
+    diagnostics: CompileResult['diagnostics'] & {
+        targetProvider: string;
+        estimatedCostUsd: number;
+        fallbackChain: string[];
+    };
+    /** The compiled IR — pass to `probeShadow(ir, …)` in `onFinish` (alpha.48). */
+    ir: PromptIR;
+}
+/**
+ * Compile a `PromptIR` and lower it to an AI-SDK-v6 `streamText`/`generateText`
+ * bundle. Replaces the hand-rolled per-consumer adapter.
  *
- * Design: never blocks the caller. Failures are silent (logged via optional
- * onError hook). Uses fetch() — works in Node 18+, Edge runtimes, and browsers.
+ * Arms the compile-then-discard guard: read `.system` / `.model` / `.raw` to
+ * serve the call. If you `record()` the handle without reading any of them,
+ * `record()` emits a dev-mode warning that the compile was discarded.
  */
+declare function compileForAISDKv6(ir: PromptIR, opts?: CompileOptions): CompileForAISDKv6Result;
 
+/**
+ * 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;
+    /**
+     * alpha.64 — hard opt-out of the surface-promotions fetch layer (Stage 2).
+     * Default true; only matters when consent (`BrainConfig.autoPromote` /
+     * `KGAUTO_AUTO_PROMOTE`) is present — without consent the layer is off
+     * regardless. Set `false` to disable the fetch even while consented
+     * (debug/emergency lever).
+     */
+    promotions?: 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;
+    /**
+     * alpha.64 — override the surface-promotions endpoint (Stage 2). Only
+     * consulted when the consumer opted in via `BrainConfig.autoPromote` /
+     * `KGAUTO_AUTO_PROMOTE`. Library appends `?app_id=X`. Defaults to
+     * `https://kgauto-dashboard.vercel.app/api/kgauto-v2/promotions`.
+     */
+    promotionsEndpoint?: string;
+    /**
+     * alpha.70 — hard opt-out of the measured-failure gate fetch layer.
+     * Default true (the gate is opt-OUT, see `BrainConfig.measuredFailureGate`).
+     */
+    measuredFailure?: boolean;
+    /**
+     * alpha.70 — override the measured-failure endpoint. Library appends
+     * `?app_id=X`. Defaults to
+     * `https://kgauto-dashboard.vercel.app/api/kgauto-v2/measured-failure`.
+     */
+    measuredFailureEndpoint?: string;
+}
 interface BrainConfig {
     /** Brain HTTP endpoint base URL (e.g., https://kgauto-brain.vercel.app/api). */
     endpoint: string;
+    /**
+     * alpha.73 — the consumer's app id, declared once so brain-driven levers can
+     * start their first read at configuration time instead of at the first
+     * compile.
+     *
+     * Optional and purely an optimisation: every IR already carries `appId`, and
+     * omitting this changes no verdict — it only means the measured-failure
+     * gate's warm-up starts when `call()` runs rather than when the module
+     * initialises. Declaring it lets a short-lived isolate spend its startup
+     * time on the fetch, so the bounded wait in `call()` usually costs nothing.
+     * Consumers running one app per process should set it.
+     */
+    appId?: string;
     /** Bearer token for auth. */
     apiKey?: string;
     /** Optional error hook for debugging. Defaults to console.warn. */
@@ -113,16 +483,163 @@ 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;
+    /**
+     * alpha.52 — emit a dev-mode `console.warn` when a `compileForAISDKv6()`
+     * result is passed to record() but its `.system` / `.model` / `.raw` were
+     * never read (the compile-then-discard pattern: the recorded brain row's
+     * `mutations_applied` / `estimated_tokens_in` / `system_prompt_chars`
+     * describe a compile that did NOT shape the served call). Default: warn
+     * when `NODE_ENV !== 'production'`, silent in production. Set `true` to
+     * force-on (e.g. a prod audit window) or `false` to silence. No-op for
+     * `call()` paths and raw `compile()` users — only `compileForAISDKv6`
+     * arms the tracking, so good actors never see a false warning.
+     */
+    warnOnDiscardedCompile?: boolean;
+    /**
+     * alpha.59 — per-leg timeout (ms) applied to every brain WRITE POST
+     * (record() primary + advisory secondary, recordOutcome(),
+     * recordShadowProbe()) via `AbortSignal.timeout`. Default 10000.
+     *
+     * Why: `sync: true` puts these fetches on the USER path (Edge consumers
+     * await record() before responding), and alpha.56's representation
+     * passthrough added a second sequential POST (advisory secondary) to that
+     * same path — an unbounded hang on either leg holds the user to the Edge
+     * limit (GE's `brainconfig-first-class-timeout` filing; GE bounded it at
+     * 3s via a hand-rolled fetchImpl wrapper every sync consumer had to
+     * rediscover).
+     *
+     * A fired timeout follows each leg's existing degraded-brain path
+     * (fire-and-forget: swallowed via onError; sync: `persistence_failed`
+     * result — never a throw into the user path). Wraps the configured
+     * `fetchImpl` rather than replacing it, so it composes with
+     * consumer-supplied impls. Set `0` to disable (pre-alpha.59 unbounded
+     * behavior). Brain-query reads (config tables) are cached + SWR and are
+     * not affected.
+     */
+    timeoutMs?: number;
+    /**
+     * alpha.64 (Stage 2 of the eval trust ladder) — consent switch for the
+     * surface-promotion routing effect. Default OFF.
+     *
+     * When true (or when the `KGAUTO_AUTO_PROMOTE` env var is '1'/'true' and
+     * this field is left undefined — env-as-consent, the KGAUTO_GOLDEN_CAPTURE
+     * precedent; an explicit `false` here overrides the env), compile()
+     * consults the brain's active `kgauto_promotions` rows for this app and
+     * boosts the promoted model at scoring time. Promotions are written only
+     * by the automated golden-eval trigger after a promote-ready verdict on a
+     * price-dominant (cheaper) candidate, and every promotion sits behind the
+     * 7-day rollback guard (daily watcher auto-reverts on regression vs the
+     * frozen baseline).
+     *
+     * Not opted in ⇒ promotions have ZERO routing effect (they remain visible
+     * as advisories + dashboard rows). Consumer sovereignty is preserved even
+     * when opted in: `forceModel`, `policy.blockedModels`, and cost ceilings
+     * always win, and a non-empty `policy.preferredModels` defers the
+     * promotion entirely.
+     */
+    autoPromote?: boolean;
+    /**
+     * alpha.70 — the measured-failure quality gate. **Default ON** wherever
+     * the brain is configured; set `false` (or `KGAUTO_MEASURED_FAILURE_GATE=0`)
+     * to disable. An explicit value here wins over the env var.
+     *
+     * Why this is opt-OUT while `autoPromote` is opt-IN: a promotion silently
+     * changes WHICH model serves you on kgauto's evidence, so it needs
+     * consent. This gate only ever DE-RANKS a model that the consumer's own
+     * outcome rows show failing them — the failures are already being paid
+     * for on their bill and their users' latency, and the model stays
+     * available as a graceful fallback. Requiring an opt-in to stop paying
+     * would be the wrong default.
+     *
+     * Consumer sovereignty is unchanged: `forceModel` still wins. Unlike a
+     * promotion, `policy.preferredModels` does NOT defer the gate — a
+     * preference says which model you would like to lead, not that a
+     * measurably-failing one works.
+     */
+    measuredFailureGate?: boolean;
 }
 declare function configureBrain(config: BrainConfig): void;
 declare function clearBrain(): void;
+interface BrainHealthSnapshot {
+    configState: 'configured' | 'not_configured';
+    /** Host of the configured endpoint (never the full URL — no secrets/paths). */
+    endpointHost?: string;
+    /** True when writes are awaited (BrainConfig.sync). */
+    sync: boolean;
+    /** Write POSTs attempted (all routes, primary + secondary). */
+    sent: number;
+    /** Write POSTs acknowledged 2xx without redirect. */
+    acked: number;
+    /** Write POSTs that failed (non-2xx, redirect, timeout, network throw). */
+    failed: number;
+    /** Subset of `failed` that failed the redirect check (middleware-drift class). */
+    redirected: number;
+    lastAckAt?: string;
+    lastFailureAt?: string;
+    /** Most recent failure message, truncated. */
+    lastFailure?: string;
+    deadLetterCount: number;
+}
+interface BrainDeadLetterEntry {
+    /** Brain route segment the payload was bound for. */
+    route: 'outcomes' | 'compile_outcome_quality' | 'probe_outcomes' | 'compile_outcome_advisories' | 'golden_irs';
+    /**
+     * Endpoint the payload was originally bound for. Flush replays ONLY entries
+     * matching the currently-configured endpoint — a reconfigure must never
+     * replay another brain's payloads into the new target (caught live by
+     * smoke-brain-timeout: a hung-socket test payload auto-flushed into the
+     * real brain after the smoke re-pointed configureBrain).
+     */
+    endpoint: string;
+    /** The exact JSON body that failed to land. */
+    payload: unknown;
+    failedAt: string;
+    /** Delivery attempts so far (1 = the original failed POST). */
+    attempts: number;
+    lastError: string;
+}
+/**
+ * Process-local brain write delivery ledger. `acked` is the only number that
+ * means "a row landed" — fire-and-forget callers that need delivery evidence
+ * read this (or set `BrainConfig.sync`). Cheap enough to attach to any debug
+ * or health surface the consumer already exposes.
+ */
+declare function brainHealth(): BrainHealthSnapshot;
+/** Read-only view of the pending dead-letter (for consumer-side persistence). */
+declare function peekBrainDeadLetter(): readonly BrainDeadLetterEntry[];
+/**
+ * Replay pending dead-letter payloads against the configured brain. Delivered
+ * entries are removed; failures increment `attempts` and entries are dropped
+ * after 3 total attempts (bounded — never an infinite retry, per the Redis
+ * DLQ rule). Safe to call any time; no-ops when unconfigured or already
+ * flushing. Also runs opportunistically after any successful write.
+ */
+declare function flushBrainDeadLetter(): Promise<{
+    attempted: number;
+    delivered: number;
+    remaining: number;
+}>;
 /**
- * Record the outcome of a compiled call. Fire-and-forget by default.
+ * alpha.87 — `KGAUTO_SOURCE` env default for the synthetic self-mark
+ * (migration 056). An explicit `source` on the input always wins; when
+ * absent, the env var marks every outcome row this PROCESS writes — the
+ * zero-code path for replay harnesses and smoke environments that share
+ * `call()`/`record()` with real traffic (PB s89's ask: their harness sets
+ * `KGAUTO_SOURCE=smoke` in the harness env and touches no call sites).
  *
- * Returns a Promise so callers in `sync` mode can await; in async mode the
- * promise resolves immediately (after the request is queued) and any
- * network error is swallowed/forwarded to onError.
+ * An unrecognized value maps to `'synthetic'` with a one-time warning
+ * rather than passing through: migration 056's CHECK constraint would
+ * reject the row server-side and the fire-and-forget write would swallow
+ * the rejection — silent data loss — while dropping the value entirely
+ * would mark declared-synthetic traffic as organic and poison liveness
+ * stats. `'synthetic'` keeps both the row and the discriminator honest.
  */
+declare function resolveOutcomeSource(explicit?: string): OutcomeSource | undefined;
+/** @internal — test hook: re-arm the one-time invalid-KGAUTO_SOURCE warning. */
+declare function _testResetOutcomeSourceWarning(): void;
 declare function record(input: RecordInput): Promise<void>;
 /**
  * Wire shape POSTed by `record()` to the brain proxy's `/outcomes` endpoint.
@@ -156,6 +673,17 @@ interface OutcomePayload {
     latency_ms: number;
     success: boolean;
     empty_response: boolean;
+    /**
+     * alpha.86 (migration 056) — synthetic-writer self-mark. Key OMITTED for
+     * organic traffic (and against pre-056 brains). NULL in the table means
+     * organic; liveness rules compute over `source IS NULL` rows.
+     */
+    source?: string;
+    /**
+     * alpha.89 (migration 065) — per-end-user metering: the consumer's opaque
+     * customer id, truncated to 128 chars at write. NULL = no end user.
+     */
+    end_user_id?: string;
     error_type?: string;
     tools_called?: string[];
     oracle_score?: number;
@@ -169,8 +697,580 @@ interface OutcomePayload {
     cost_usd_actual?: number;
     ttft_ms?: number;
     history_cacheable_tokens?: number;
+    effort?: string;
     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?: FallbackReason;
+    /**
+     * alpha.71 (migration 044) — the precise `errorCode` behind
+     * `fallback_reason`. Key OMITTED when no fallback fired, so brains that
+     * haven't applied 044 never see it.
+     */
+    fell_over_error_code?: string;
+    /**
+     * True when the same-model retry (CallOptions.sameModelRetry) fired
+     * during this call. Key OMITTED (not false) when no retry fired — safe
+     * against brains that haven't applied migration 039 yet.
+     */
+    retried_same_model?: boolean;
+    /**
+     * 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;
+    /**
+     * R0 linkage (§5.0). Parent call's handle when this row is a fan-out branch;
+     * key OMITTED (undefined → dropped by JSON.stringify → stored NULL) for a
+     * root, safe against pre-042 brains.
+     */
+    parent_handle?: string;
+    /**
+     * R0 linkage (§5.0). Root handle of the fan-out trace (= parent_handle when a
+     * branch, else this row's own handle). Emitted for every registered compile.
+     */
+    trace_id?: string;
+    /**
+     * R0 linkage (§5.0). root | branch | composer. Emitted for every registered
+     * compile; surface baselines filter to root/NULL so branch traffic never
+     * contaminates a promotion/eval baseline. Release A emits only root/branch.
+     */
+    fanout_role?: 'root' | 'branch' | 'composer';
+    /**
+     * RD discipline gate-token accounting (§5.D). Measured token tax of the
+     * discipline_contract gate block; 0 when the gate didn't fire.
+     */
+    discipline_gate_tokens?: number;
+}
+/**
+ * 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 (alpha.61): `{ok: true}` only when the POST was acknowledged 2xx
+ * (sync mode); `{ok: 'queued'}` in fire-and-forget mode (handed to the
+ * runtime, NOT acked — read `brainHealth()` for delivery evidence);
+ * `{ok: false, reason}` on known 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; `candidate_error` added by 032).
+     * 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; `'candidate_error'`
+     * (alpha.53) is the failed-candidate diagnostic — the candidate call
+     * errored, with the error class + latency-at-death recorded instead of
+     * silence (the IC demo-night probe deaths were invisible for ~90 min under
+     * the old record-no-row rule). Diagnostic rows carry no candidate response
+     * and no verdict — no false quality signal. A verdict rollup MUST filter to
+     * `outcome='completed'`.
+     */
+    outcome?: 'completed' | 'aborted_latency_budget' | 'skipped_slow_tier_sync' | 'candidate_error';
+    /**
+     * alpha.53 (migration 032) — error class for `outcome='candidate_error'`
+     * rows. Values follow execute()'s taxonomy (`rate_limit`, `timeout`,
+     * `server_error`, `model_not_found`, `auth`, `invalid_request`, `unknown`)
+     * plus `execute_rejected` (the execute promise rejected outright). NULL /
+     * omitted on all other row classes.
+     */
+    errorClass?: string;
+}
+/**
+ * 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' | 'candidate_error';
+    error_class: string | null;
+};
+/**
+ * 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>;
+/**
+ * Golden-IR capture input. UNLIKE every other brain write, this row carries the
+ * RAW full PromptIR — an explicit, documented posture change from the s51
+ * "brain holds no raw consumer prompts" rule, gated on consumer opt-in
+ * (`KGAUTO_GOLDEN_CAPTURE` env / `CallOptions.goldenCapture`). The `consent`
+ * field records the provenance of that opt-in at capture time.
+ */
+interface GoldenIrRecordInput {
+    appId: string;
+    archetype: string;
+    /** hashShape() of the call at compile time (peek before record() pops). */
+    shapeKey?: string;
+    /** The full PromptIR, verbatim. Plain JSON by construction (ir.ts). */
+    ir: unknown;
+    incumbentModel: string;
+    incumbentOutput?: string;
+    incumbentLatencyMs?: number;
+    incumbentTokensIn?: number;
+    incumbentTokensOut?: number;
+    /** 'sampled' (capture flag fired on live traffic) | 'curated' (operator). */
+    source: 'sampled' | 'curated';
+    /** Consent provenance, e.g. 'KGAUTO_GOLDEN_CAPTURE=0.1 (consumer env opt-in)'. */
+    consent: string;
+    /** Optional link back to the compile handle of the captured call. */
+    outcomeHandle?: string;
+}
+/** Pure builder for the `kgauto_golden_irs` row (snake_case wire shape). */
+declare function buildGoldenIrRow(input: GoldenIrRecordInput): {
+    app_id: string;
+    intent_archetype: string;
+    shape_key: string | null;
+    ir: unknown;
+    incumbent_model: string;
+    incumbent_output: string | null;
+    incumbent_latency_ms: number | null;
+    incumbent_tokens_in: number | null;
+    incumbent_tokens_out: number | null;
+    source: 'sampled' | 'curated';
+    consent: string;
+    outcome_handle: string | null;
+};
+/**
+ * Persist one golden IR to `kgauto_golden_irs`. Same G1 write-leg discipline as
+ * every other brain route (redirect check, ledger, dead-letter); fire-and-forget
+ * by default, honors `BrainConfig.sync`. Never throws.
+ */
+declare function recordGoldenIr(input: GoldenIrRecordInput): Promise<void>;
+
+/**
+ * Golden-set eval engine (alpha.62, eval spine — design brief 2026-07-17).
+ *
+ * Implements the quality-floor-guarded model-swap contract:
+ *
+ *   > A model replaces another on a surface only by demonstrating
+ *   > same-or-better quality on that surface's real workload — never by
+ *   > price, recency, or judgment alone.
+ *
+ * One eval run: load the active golden set for (app, archetype), replay every
+ * IR on BOTH the incumbent and the candidate (fresh outputs on both sides —
+ * fair comparison, no stale stored output), apply mechanical hard floors,
+ * then a pairwise LLM judge (order-swapped to cancel position bias), and
+ * aggregate under the non-inferiority rule:
+ *
+ *   promote-ready  ⇔  wins-or-ties ≥ threshold (default 80%)
+ *                     AND zero hard-floor violations
+ *                     AND candidate p50 latency ≤ ratio × incumbent p50
+ *
+ * Evidence lands as brain rows: one `kgauto_golden_eval_runs` aggregate + one
+ * `probe_outcomes` row per case (`replay_source='golden-replay'`, full
+ * fidelity by construction) + an evidence-attached advisory on the consumer's
+ * advisory surface (trust-ladder Stage 1: eval runs, human clicks promote).
+ *
+ * Judging is PAIRWISE, not absolute — it operationalizes the quality-floor
+ * Common Pattern directly ("same or better, never less"). Each pair is judged
+ * twice with A/B order swapped; disagreement between the two orders is scored
+ * a tie (the honest reading of positional noise).
+ *
+ * This module is operator-grade: it talks to the brain via direct PostgREST
+ * with a service key (the watchers' convention), never through consumer
+ * proxies, and it deliberately does NOT call record() — eval traffic must not
+ * pollute compile_outcomes.
+ */
+
+/**
+ * Default judge model (judge chain tier 0). Exported so operator scripts
+ * (golden-eval-trigger's judge pre-flight) probe the SAME model the engine
+ * will call — two inline literals of one concept is the s75 drift shape.
+ * 2026-08-25: the judge had no pre-flight at all, so an Anthropic billing
+ * outage would have burned incumbent+candidate replay spend on non-Anthropic
+ * surfaces before dying verdictless at judge time.
+ *
+ * 2026-08-25 (same session): moved 'claude-opus-4-8' → 'claude-opus-5'. The
+ * guard test caught the old default sitting on a status:'legacy' roster
+ * entry (4-8 went legacy 2026-07-25 with the Opus 5 generation; nobody moved
+ * the judge). Verdict comparability across the switch is preserved by
+ * `judge_model` on every run + case row (migrations 024/036).
+ */
+declare const DEFAULT_JUDGE_MODEL = "claude-opus-5";
+/**
+ * What "better" means per archetype. Fed verbatim into the pairwise judge
+ * prompt. Kept deliberately short — the judge sees the full request, so the
+ * rubric only needs to name the failure modes that matter for the archetype.
+ */
+declare const JUDGE_RUBRICS: Record<string, string>;
+declare function rubricFor(archetype: string): string;
+/** Render the golden IR's request for the judge (system sections + user turn). */
+declare function renderIrForJudge(ir: PromptIR): string;
+declare function buildPairwiseJudgePrompt(args: {
+    archetype: string;
+    renderedInput: string;
+    outputA: string;
+    outputB: string;
+}): string;
+type PairwiseWinner = 'A' | 'B' | 'tie';
+/** Parse the judge's JSON verdict. Returns undefined when unparseable. */
+declare function parseJudgeVerdict(raw: string): {
+    winner: PairwiseWinner;
+    rationale?: string;
+} | undefined;
+/**
+ * Combine the two order-swapped verdicts into a case verdict. Both verdicts
+ * are expressed in incumbent/candidate terms BEFORE this call (the caller
+ * un-swaps run 2). Agreement → that verdict; disagreement → 'tied' (positional
+ * noise reads as a tie, never as a win).
+ */
+declare function combineOrderSwappedVerdicts(run1: 'candidate-better' | 'current-better' | 'tied', run2: 'candidate-better' | 'current-better' | 'tied'): 'candidate-better' | 'current-better' | 'tied';
+/**
+ * Release B — the eval's comparison primitive is arm-agnostic: a MODEL
+ * comparison varies `model` and holds `ir`; a STRATEGY comparison varies
+ * `ir` and holds `model`. Same replay, same judge, same order-swap, same
+ * floors.
+ */
+type GoldenEvalAxis = 'model' | 'strategy';
+/** Strategies the eval can measure. Closed set — a strategy is only
+ * measurable against its exact frozen bytes. The `-alt` wording is
+ * EVAL-ONLY: it exists to attribute a v1 loss to wording vs mechanism
+ * (§6) and never ships in a production compile. */
+type GoldenEvalStrategyId = 'discipline-gates-v1' | 'discipline-gates-v1-alt' | 'discipline-gates-v1-alt-blind';
+/** Both re-wordings of v1. Dispatch keys on this, never on a string prefix,
+ * so adding a fourth arm is one edit rather than a grep. */
+declare const ALT_STRATEGY_IDS: readonly GoldenEvalStrategyId[];
+declare function isAltStrategy(id: GoldenEvalStrategyId | undefined): boolean;
+interface GoldenEvalOptions {
+    appId: string;
+    archetype: string;
+    /**
+     * Release B — comparison axis. Default 'model' (alpha.62 behavior,
+     * unchanged). On 'strategy': arm A = the golden IR as stored (gates-off),
+     * arm B = the same IR with a `discipline_contract` section appended
+     * (gates-on), both replayed on ONE model (`strategyModel` or the resolved
+     * incumbent). `candidateModel` is ignored on the strategy axis;
+     * `strategy` is required.
+     */
+    axis?: GoldenEvalAxis;
+    /** Required when axis==='strategy': the strategy under measurement. */
+    strategy?: GoldenEvalStrategyId;
+    /**
+     * axis==='strategy' only: the model both arms run on. Default: the
+     * resolved incumbent (most-captured model in the golden set).
+     */
+    strategyModel?: string;
+    /** Required when axis is 'model' (the default). */
+    candidateModel?: string;
+    /**
+     * Incumbent to compare against. Default: the most frequent incumbent_model
+     * across the loaded golden set (the surface's de-facto leader).
+     */
+    incumbentModel?: string;
+    /** Judge model id. Default `DEFAULT_JUDGE_MODEL` (judge chain tier 0). */
+    judgeModel?: string;
+    /** Max golden cases to load (newest first). Default 50. */
+    limit?: number;
+    /** Non-inferiority threshold on wins-or-ties. Default 0.8. */
+    winOrTieThreshold?: number;
+    /** Latency hard floor: candidate p50 ≤ ratio × incumbent p50. Default 3. */
+    latencyFloorRatio?: number;
+    /** Minimum judged cases for a non-inconclusive verdict. Default 5. */
+    minJudgeableCases?: number;
+    /** What fired the eval. Default 'manual' (Stage 1). */
+    triggerSource?: 'manual' | 'supply' | 'price' | 'demand';
+    /** Brain access — direct PostgREST (operator convention). */
+    supabaseUrl: string;
+    serviceKey: string;
+    /** Provider keys for the replay + judge calls. Default: process.env. */
+    apiKeys?: ApiKeys;
+    fetchImpl?: typeof fetch;
+    /** Replay + judge but write NOTHING to the brain. */
+    dryRun?: boolean;
+    onProgress?: (message: string) => void;
+}
+interface GoldenEvalCase {
+    goldenIrId: number;
+    verdict: 'candidate-better' | 'tied' | 'current-better' | 'inconclusive';
+    /**
+     * Release B — the RAW order-swapped pair, in incumbent/candidate terms,
+     * BEFORE `combineOrderSwappedVerdicts` folds disagreement into 'tied'.
+     * The fold is public API and unchanged; this records what it discards,
+     * because positional DISAGREEMENT RATE is an objective reliability metric
+     * needing no ground truth (§4.0 — the strategy experiment's primary
+     * metric is positional consistency, not judge quality).
+     */
+    orderVerdicts?: {
+        run1: 'candidate-better' | 'current-better' | 'tied';
+        run2: 'candidate-better' | 'current-better' | 'tied';
+    };
+    judgeRationale?: string;
+    /** Hard-floor violations on the candidate side for this case. */
+    floorViolations: Array<'empty' | 'schema' | 'candidate_error'>;
+    errorClass?: string;
+    incumbent?: {
+        latencyMs: number;
+        tokensIn: number;
+        tokensOut: number;
+        text: string;
+    };
+    candidate?: {
+        latencyMs: number;
+        tokensIn: number;
+        tokensOut: number;
+        text: string;
+    };
+    /** Case excluded from the denominator (incumbent replay/judge failed). */
+    excludedReason?: string;
+}
+interface GoldenEvalRunResult {
+    verdict: 'promote-ready' | 'not-inferior' | 'inconclusive';
+    runId?: number;
+    /**
+     * Release B — which axis produced this verdict. Load-bearing, not
+     * cosmetic: a results table that can't tell you which axis produced a
+     * verdict is a false-attribution engine. On 'strategy',
+     * incumbentModel === candidateModel (the model held constant) and
+     * `strategy` names the arm-B mutation.
+     */
+    axis: GoldenEvalAxis;
+    strategy?: GoldenEvalStrategyId;
+    appId: string;
+    archetype: string;
+    incumbentModel: string;
+    candidateModel: string;
+    judgeModel: string;
+    nCases: number;
+    wins: number;
+    ties: number;
+    losses: number;
+    floorViolations: number;
+    floorDetail: Record<string, number>;
+    winOrTieRatio: number | null;
+    latencyRatio: number | null;
+    costIncumbentUsd: number | null;
+    costCandidateUsd: number | null;
+    advisoryOutcomeId?: number;
+    cases: GoldenEvalCase[];
+    notes: string[];
+}
+declare function withDisciplineContract(ir: PromptIR): PromptIR;
+declare const DISCIPLINE_GATES_V1_ALT_HEADER = "Before stating any conclusion, run this check:";
+declare function altGatesBlockFor(args: {
+    outputMode: 'text' | 'json' | 'tool_call';
+    hasTools: boolean;
+}): string;
+declare const ALT_BLIND_TOKEN_BUDGET_BREACH: {
+    readonly ceilingTokens: 264;
+    readonly measuredTokensTextWithTools: 285;
+    readonly note: string;
+};
+declare const DISCIPLINE_GATES_V1_ALT_BLIND_HEADER = "Before stating any conclusion, run this check:";
+/**
+ * The variant matrix — and this is the ONE place this seat's judgment enters
+ * the blind arm, so it is stated rather than buried.
+ *
+ * cc's instruction: adapt MECHANICALLY where the injection format demands it,
+ * note the diff, never edit semantics. Choosing which gates to drop per
+ * surface is a selection, not an edit — the bytes of every retained gate are
+ * untouched — but the selection is still mine, so:
+ *
+ *   NO TOOLS   drops `toolPredict`. Forced, not chosen: the string opens
+ *              "When using tools" and is literally inapplicable without them.
+ *              Mirrors v1 dropping its compressed-item bullet.
+ *   STRUCTURED drops `markAssumed` ONLY. It is the sole gate whose entire
+ *              function is text in the final answer ('mark anything unchecked
+ *              as "assumed"'), which a JSON/tool_call schema has no field for
+ *              and which would corrupt the parse.
+ *
+ * The judgment call worth flagging: v1 drops TWO bullets on structured
+ * surfaces, and a stricter reading would also drop `falsify` ("state in one
+ * line") and `deviation` ("say so explicitly"), since both demand output
+ * text. I kept them. Their output demand is incidental (and conditional, for
+ * `deviation`) while their primary effect is on reasoning before the answer
+ * exists — whereas v1's dropped pair (`label`, `gap`) are purely
+ * output-shaping. Dropping three of five would leave a two-gate arm that no
+ * longer tests the same mechanism, and an arm crippled by my formatting
+ * choice would read as a wording loss that was actually a scoping loss.
+ * If the structured surface shows anomalous results, this is the first
+ * thing to re-examine.
+ */
+declare function altBlindGatesBlockFor(args: {
+    outputMode: 'text' | 'json' | 'tool_call';
+    hasTools: boolean;
+}): string;
+/**
+ * The alt arm injects its block DIRECTLY as an untagged section — it must
+ * not carry `kind: 'discipline_contract'`, or the translator would prepend
+ * the v1 bytes on top and the arm would measure both wordings at once. The
+ * variant choice mirrors matchRule()'s exactly (same outputMode + hasTools
+ * inputs), so the alt arm no-ops nowhere v1 fires and fires nowhere v1
+ * no-ops — the attribution is about WORDING, and everything else is held.
+ */
+declare function withAltDisciplineContract(ir: PromptIR): PromptIR;
+/**
+ * Same injection contract as `withAltDisciplineContract` — untagged section,
+ * so the translator never prepends the v1 bytes on top and the arm measures
+ * exactly one wording. Same variant inputs, so the blind arm no-ops nowhere
+ * v1 fires and fires nowhere v1 no-ops; the comparison is about WORDING and
+ * everything else is held.
+ */
+declare function withAltBlindDisciplineContract(ir: PromptIR): PromptIR;
+declare function runGoldenEval(opts: GoldenEvalOptions): Promise<GoldenEvalRunResult>;
+/**
+ * Aggregate outcome of one strategy run, in gates-on terms. 'loses' is the
+ * only branch that costs a third replay — and the only one where wording
+ * attribution matters.
+ */
+type StrategyOutcome = 'wins' | 'ties' | 'loses' | 'inconclusive';
+declare function classifyStrategyOutcome(r: GoldenEvalRunResult): StrategyOutcome;
+/**
+ * The §6 attribution matrix. The load-bearing distinction: a WORDING failure
+ * recorded as a mechanism failure would let Factor B permanently disable a
+ * real capability on evidence about one author's prose.
+ *
+ * THREE arms since 2026-07-29. Both re-wordings run on a v1 loss, and a win
+ * by EITHER is enough to acquit the mechanism — the question "does some
+ * wording of this work?" is answered by one existence proof, so there is no
+ * reason to require agreement between the alts.
+ *
+ *   v1 vs off | alt / alt-blind vs off | attribution
+ *   ----------+------------------------+------------------------------------
+ *   wins      | (not run)              | mechanism-works — ship
+ *   ties      | (not run)              | no-lift — inconclusive at n, re-eval
+ *   loses     | either wins            | wording-failure — do NOT disable
+ *   loses     | BOTH lose              | mechanism-failure — Factor B may disable
+ *   loses     | neither wins, not both lose | wording-inconclusive — no disable
+ *
+ * The `mechanism-failure` cell is the one that changed character. It used to
+ * rest on two wordings by one author, so a shared blind spot (the principles
+ * being the wrong principles) was invisible and the verdict was hedged. The
+ * blind arm was authored by a context-free subagent with no knowledge of this
+ * repo, the experiment, or who was asking — so a both-lose verdict now spans
+ * independent authorship and is strong on its own terms. That is exactly the
+ * gap `STRATEGY_AUTHORSHIP_LIMITATION` was written to confess, which is why
+ * the limitation text is now conditional on whether the blind arm ran.
+ */
+type StrategyAttribution = 'mechanism-works' | 'no-lift' | 'wording-failure' | 'mechanism-failure' | 'wording-inconclusive' | 'inconclusive';
+interface StrategyAttributionResult {
+    attribution: StrategyAttribution;
+    primary: GoldenEvalRunResult;
+    /** Present ONLY when the primary lost (the loss-triggered arms). */
+    alt?: GoldenEvalRunResult;
+    /** The independently-authored arm. Present ONLY when the primary lost. */
+    altBlind?: GoldenEvalRunResult;
+    /** The authorship limitation, restated on every result so no downstream
+     * reader can cite an attribution without it. Which string this carries
+     * depends on whether the blind arm actually ran — see below. */
+    limitation: string;
 }
+/**
+ * Carried when the blind arm did NOT run — i.e. v1 won or tied, so no
+ * re-wording was measured at all and any claim about wording is unevidenced.
+ */
+declare const STRATEGY_AUTHORSHIP_LIMITATION: string;
+/**
+ * Carried when both re-wording arms ran. The shared-author caveat is GONE by
+ * construction, and saying so is the point: the previous version of this
+ * string confessed a gap that has since been closed, and a stale confession
+ * is its own kind of false statement — a reader would discount a verdict
+ * that no longer deserves discounting.
+ */
+declare const STRATEGY_AUTHORSHIP_INDEPENDENT: string;
+/**
+ * Run the strategy eval with loss-triggered wording attribution: v1 first;
+ * the alt arm replays ONLY on a v1 loss (mirrors the engine's retry
+ * posture — don't pay for extra evidence until a result demands it).
+ */
+declare function runStrategyEvalWithAttribution(opts: Omit<GoldenEvalOptions, 'axis' | 'strategy' | 'candidateModel'>): Promise<StrategyAttributionResult>;
+
+/**
+ * alpha.60 — the library's own version, baked as a constant so Edge/Worker
+ * runtimes (no fs, no require) can report it on wire surfaces. First
+ * consumer: `createKeyHealthRoute` carries it as `library_version`, which is
+ * how the operator dashboard's Fleet panel sees per-consumer vendor drift
+ * LIVE instead of via wrap-time package.json probes (the L-093 family
+ * "declared state lags actual" fix at the vendor-version axis — s47 found
+ * IC 13 alphas stale that way).
+ *
+ * Kept in sync with package.json by hand at each version bump; the drift
+ * guard in `tests/version.test.ts` fails the suite (and therefore
+ * `prepublishOnly`) when they diverge — a stale constant cannot reach npm.
+ */
+declare const LIBRARY_VERSION = "2.0.0-alpha.91";
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -223,6 +1323,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.
  *
@@ -247,120 +1375,2675 @@ declare function resetTokenizer(): void;
 declare function countTokens(text: string): number;
 
 /**
- * Best-practice advisor — alpha.6 Phase 1.
+ * delegate — Release D, the R2 primitive (delegation-fanout accelerator §5.2,
+ * design contract advisory/kgauto/2026-07-24_delegation-fanout-accelerator-design.md).
  *
- * 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.
+ * A consumer-mountable TOOL the orchestrating model calls mid-loop:
+ * `{ sub_archetype, input, quality_floor? }`. kgauto selects the executor
+ * from evidence, runs the sub-call through the compiler + call(), returns
+ * the result into the loop, links parent↔child rows (R0), and enforces
+ * `policy.maxCostPerTraceUsd` against the running trace spend — the field
+ * that shipped INERT in Release A precisely so this release could turn it on.
  *
- * 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:
+ * THE AUTHORITY SPLIT IS THE CONTAINMENT (§3):
+ *   - the MODEL decides whether and what to delegate (kgauto never
+ *     decomposes uninvited — §10);
+ *   - KGAUTO decides only who runs it — and never selects a model absent
+ *     from the consumer's declared `ir.models`;
+ *   - the CONSUMER consents: default OFF, `KGAUTO_AUTO_PROMOTE` posture
+ *     (explicit option beats `KGAUTO_DELEGATE` env; neither ⇒ the handler
+ *     refuses observably, never silently).
  *
- *   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
+ * Budget refusals and floor refusals are RETURNED to the model as
+ * structured tool results, never thrown — the orchestrator must be able to
+ * compose with what it has (a refusal mid-loop that crashes the loop would
+ * convert a budget into an outage).
  *
- * Each rule is a pure function: (ir, result, profile) → BestPracticeAdvisory[].
- * No side effects. No randomness. Deterministic for a given IR.
+ * Composition-verification (§7a): every sub-result is 'trusted' until the
+ * orchestrator/consumer reports otherwise via `reportComposition` —
+ * absence-of-report IS the recorded state (migration 052). Rung 3 reads
+ * this to attribute composition failures to stitching, not executor choice.
  *
- * 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.
+ * Trace-budget honesty (v1 limits, stated where consumers read):
+ *   - the in-process ledger sums DELEGATED spend for this trace (parent's
+ *     own root-call spend is not visible to a library ledger until a
+ *     brain-informed ledger lands; documented on `maxCostPerTraceUsd`);
+ *   - enforcement is estimate-ahead: a sub-call whose compile-time estimate
+ *     would cross the ceiling is refused BEFORE any spend;
+ *   - realized spend is computed from actual tokens × the executor
+ *     profile's prices after each sub-call.
  */
 
-/** Subset of CompileResult fields the advisor needs. */
-type AdvisorContext = Pick<CompileResult, 'target' | 'provider' | 'tokensIn' | 'diagnostics'>;
+declare function isDelegateEnabledFromEnv(envSource?: Record<string, string | undefined>): boolean;
+/** Arguments the ORCHESTRATING MODEL supplies when it calls the tool. */
+interface DelegateToolArgs {
+    /** The sub-task's archetype — its own learning_key downstream. */
+    sub_archetype: IntentArchetypeName | string;
+    /** Complete, self-contained sub-task input. The model owns fidelity here
+     *  (authority split): kgauto runs exactly what it is handed. */
+    input: string;
+    /**
+     * Minimum archetype-perf score (0..10) the executor must carry for this
+     * sub-archetype. Candidates below the floor are excluded BEFORE ranking;
+     * if nothing in the parent's declared pool clears it, the tool refuses
+     * with the scores so the model can lower the floor or do the work itself.
+     */
+    quality_floor?: number;
+}
+type DelegateRefusalReason = 'delegate_not_enabled' | 'invalid_sub_archetype' | 'no_qualified_executor' | 'trace_budget_exhausted' | 'call_failed';
+type DelegateResult = {
+    ok: true;
+    /** The sub-result text (or serialized structured output). */
+    output: string;
+    /** Branch handle — pass to reportComposition; joins the brain row. */
+    subHandle: string;
+    executorModel: string;
+    costUsd: number;
+    latencyMs: number;
+    /** Always 'trusted' at return time — flips only via reportComposition. */
+    verification: 'trusted';
+} | {
+    ok: false;
+    reason: DelegateRefusalReason;
+    /** Human/model-readable detail — written to be COMPOSABLE (“continue
+     *  without this sub-result”), never a stack trace. */
+    detail: string;
+};
 /**
- * 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).
+ * Provider-agnostic tool definition. Consumers adapt `inputSchema` to their
+ * SDK's tool shape (AI-SDK `parameters`, Anthropic `input_schema`, …). The
+ * description IS prompt surface — it teaches the model the authority split
+ * and the compose-on-refusal discipline (gates 4/5 of discipline-gates-v1
+ * in tool-description form).
  */
-declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: ModelProfile, policy?: CompilePolicy): BestPracticeAdvisory[];
-
-/**
- * getDefaultFallbackChain — the alpha.9 cascading ship.
+declare const DELEGATE_TOOL_DEFINITION: {
+    readonly name: "delegate";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly sub_archetype: {
+                readonly type: "string";
+                readonly enum: ("ask" | "hunt" | "classify" | "summarize" | "generate" | "extract" | "plan" | "critique" | "transform" | "judge")[];
+                readonly description: "What kind of work the sub-task is (its routing archetype).";
+            };
+            readonly input: {
+                readonly type: "string";
+                readonly description: "Complete, self-contained sub-task input. Include everything the executor needs — it sees nothing else.";
+            };
+            readonly quality_floor: {
+                readonly type: "number";
+                readonly minimum: 0;
+                readonly maximum: 10;
+                readonly description: "Optional minimum executor quality score (0-10) for this archetype. Omit to accept the evidence-ranked default.";
+            };
+        };
+        readonly required: readonly ["sub_archetype", "input"];
+        readonly additionalProperties: false;
+    };
+};
+interface CreateDelegateOpts {
+    /** The PARENT call's IR — supplies the declared model pool (the containment
+     *  boundary), appId, and dialect context. */
+    parentIr: PromptIR;
+    /** The parent's compile/call handle — R0 linkage root. Branch rows record
+     *  `parent_handle=<this>` and inherit `trace_id`. */
+    parentHandle: string;
+    /**
+     * Options forwarded to the sub-`call()` (apiKeys, fetchImpl,
+     * attemptTimeoutMs, policy…). `policy.maxCostPerTraceUsd` here is what the
+     * ledger enforces. `parentHandle` is set by the factory — a value passed
+     * in callOpts is overridden.
+     */
+    callOpts?: CallOptions & {
+        policy?: CompilePolicy;
+    };
+    /** Explicit consent — beats KGAUTO_DELEGATE env (AUTO_PROMOTE posture). */
+    enabled?: boolean;
+}
+interface DelegateHandle {
+    toolDefinition: typeof DELEGATE_TOOL_DEFINITION;
+    handler: (args: DelegateToolArgs) => Promise<DelegateResult>;
+    /**
+     * §7a — report what the orchestrator did with a sub-result. Writes a
+     * migration-052 row via the brain-read env trio (RLS-scoped to appId).
+     * Unreported sub-results are 'trusted' by definition — report only
+     * 'verified' and 'discarded'.
+     */
+    reportComposition: (report: {
+        subHandle: string;
+        disposition: 'verified' | 'discarded';
+        note?: string;
+    }) => Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    /** Ledger introspection: delegated spend recorded for this trace so far. */
+    traceSpendUsd: () => number;
+}
+declare function createDelegate(opts: CreateDelegateOpts): DelegateHandle;
+
+/**
+ * archetype-fits — alpha.43.
  *
- * Returns a per-archetype fallback chain that walks the cost/performance
- * Pareto frontier (master plan §1.3 + §3). Three customer postures:
+ * 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`).
  *
- *   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]
+ * 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 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)
+ * 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.
  *
- * 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().
+ * 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
  *
- * The function is **pure** — no brain query, no I/O, no randomness. Same
- * inputs always produce the same chain.
+ * 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.
  */
 
 /**
- * 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.
+ * 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.
  *
- * 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."
+ * 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.
  */
-type FallbackPosture = 'open' | 'preferred';
-interface GetDefaultFallbackChainOpts {
-    /** The archetype the call is performing. Drives chain shape. */
+
+/** 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[];
+
+/**
+ * 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;
+}>;
+
+/**
+ * blocked-model-drift — advisor rule for the two ways a consumer's
+ * `CompilePolicy.blockedModels` can stop meaning what the consumer meant,
+ * without anything anywhere reporting a problem.
+ *
+ * ── The incidents this is grounded in (tt-intel s113 + s119) ─────────────
+ *
+ * (Correction, s83: an earlier draft cited "claude-sonnet-5 served 30% of
+ * tt-intel's ask traffic" as the motivating incident. That number was a
+ * FOSSIL — tt-intel's own L-188 traced all 11 calls to a 29-second burst
+ * from their own prior spend-gate experiment, fixed minutes later, and
+ * their block was in fact working. Do not resurrect it.)
+ *
+ * The real, verified incidents:
+ *
+ * 1. alpha.72 retargeted the curated `claude-sonnet` family primary from
+ *    `claude-sonnet-4-6` (now `legacy`) to `claude-sonnet-5` (now
+ *    `current`), and tt-intel's literal-id gate STOPPED MATCHING the
+ *    family's routed traffic — their s113 response was to build
+ *    consumer-side family→concrete-id resolution (`parseBlockedModels`)
+ *    before ids reach kgauto. Every consumer without that local machinery
+ *    is exposed to the same silent retarget: `blockedModels` is matched by
+ *    exact id, so a block written against yesterday's primary says nothing
+ *    about today's.
+ *
+ * 2. tt-intel s119 (2026-07-29 filing): a blocked model SERVED when an
+ *    unblocked ALIAS of it sat in the candidate set (`deepseek-chat` ≡
+ *    `deepseek-v4-flash`). That one was a kgauto correctness bug, fixed in
+ *    alpha.85 by canonical matching (`policy-match.ts`) — but it proved
+ *    the class: a block-list meaning drifts whenever the roster's id
+ *    surface moves under it, and no layer errors.
+ *
+ * ── What this rule is NOT ────────────────────────────────────────────────
+ *
+ * It does not change matching semantics. Exact-ID matching is arguably the
+ * correct contract: family-glob matching would silently widen every
+ * existing consumer's block-list, which is a breaking semantic change and
+ * not kgauto's to make unilaterally. The gap here is silence, not
+ * semantics — so the fix is a signal, not a behavior change. Selection is
+ * untouched; a consumer who blocked one exact id still gets exactly that
+ * id blocked and nothing else.
+ *
+ * ── The two branches ─────────────────────────────────────────────────────
+ *
+ * (a) `blocked-model-not-in-roster` — a `blockedModels` entry resolves to
+ *     no model in the current roster (after alias resolution). The block is
+ *     inert: it can never match anything. Causes are a typo, a model
+ *     retired out of the roster, or a stale env var carried forward. There
+ *     is no reading under which an entry matching nothing is what the
+ *     consumer wanted, so this is unambiguous.
+ *
+ * (b) `blocked-model-family-sibling-served` — the model selected for THIS
+ *     call is in the same family as a blocked entry but is a different
+ *     exact id. This is the tt-intel shape. Unlike (a) it IS ambiguous:
+ *     "block `claude-sonnet-4-6` specifically, `claude-sonnet-5` is fine"
+ *     is a legitimate and common intent. So the message states both
+ *     readings and says how to act on either. It escalates its wording —
+ *     not its level — when the blocked sibling is `legacy`/`deprecated` and
+ *     the served sibling is `current`, because that combination is the
+ *     signature of a roster lifecycle move rather than a deliberate
+ *     per-generation block.
+ *
+ * Both fire at `warn`, and both fire regardless of `policy.posture`.
+ * `posture: 'locked'` means "do not recommend models to me" — these are not
+ * recommendations, they are reports that the consumer's own declared
+ * constraint is not doing what its author expects. Same reasoning as the
+ * alpha.28 `archetype-perf-floor-breach` cliff advisor, which is also
+ * posture-independent because it reports a structural fact rather than a
+ * preference.
+ *
+ * Companion watcher: `v2/scripts/blocked-model-drift-watch.mjs` rolls the
+ * same two branches up across a consumer's recent traffic from the brain,
+ * so the signal survives a consumer who never reads `result.advisories[]`.
+ *
+ * L-073 family ("no errors = healthy"): as with DeepSeek's `deepseek-chat`
+ * compat alias and the alpha.47/.43 field-drop chain, nothing errored,
+ * nothing 404'd, latency did not move — and the cached intent was wrong for
+ * an unknown duration. The detection loop has to be built deliberately
+ * because the failure emits no natural signal.
+ */
+
+/** Stable rule code — branch (a). Written to `compile_outcome_advisories.code`. */
+declare const BLOCKED_MODEL_NOT_IN_ROSTER_CODE = "blocked-model-not-in-roster";
+/** Stable rule code — branch (b). Written to `compile_outcome_advisories.code`. */
+declare const BLOCKED_MODEL_FAMILY_SIBLING_SERVED_CODE = "blocked-model-family-sibling-served";
+
+/**
+ * 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";
+/**
+ * alpha.68 / Release A — stable identifier of the discipline-gates rule.
+ * Fires on `discipline_contract` sections that pass the two-factor eligibility
+ * screen (Factor A archetype + Factor C output-shape). Surfaces on
+ * `SectionRewrite.rule` and in brain aggregates.
+ *
+ * Versioned (`v1`) deliberately: Factor B evidence (Release B) is only valid
+ * against the EXACT bytes that produced it, so a silent gate edit would
+ * invalidate every standing verdict. A real gate change bumps this to `v2` and
+ * resets Factor B to unmeasured for every tuple.
+ */
+declare const RULE_DISCIPLINE_GATES_V1 = "discipline-gates-v1";
+/**
+ * Release B — stable identifier of the STRUCTURED-SAFE discipline-gates
+ * variant (design contract §5.D second clause, discharged via §4.0's merge:
+ * "the judge must run gates 1–4 only — which IS Path 1's structured-safe
+ * variant, arrived at as a subset-drop of frozen bytes rather than new
+ * prose"). Fires where the full block is Factor-C-forbidden: `json` and
+ * `tool_call` surfaces, where gates 5+6 are shape-altering and would
+ * manufacture the structured-output violations alpha.66 retries.
+ *
+ * Versioned with the SAME v1 stamp as its parent: its bytes are a strict
+ * subset of `discipline-gates-v1`'s, so a v1 wording change is a variant
+ * wording change by construction, and both bump together.
+ */
+declare const RULE_DISCIPLINE_GATES_V1_STRUCTURED = "discipline-gates-v1-structured";
+interface ApplySectionRewritesArgs {
+    ir: PromptIR;
+    profile: ModelProfile;
     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).
+     * alpha.68 / Release A — resolved output shape for Factor C (§5.D). `'json'`
+     * ⇒ structured surface (the discipline gate MUST NOT fire — gates 5+6 are
+     * shape-altering and would break the consumer's parser). `'text'` ⇒ free-form
+     * surface (the gate may fire). Optional: when omitted, derived from
+     * `ir.constraints?.structuredOutput` (true ⇒ 'json', else 'text') so callers
+     * / tests need not pass it. compile() passes it explicitly.
      */
-    primary?: string;
+    outputMode?: OutputMode;
+}
+interface ApplySectionRewritesResult {
     /**
-     * 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.
+     * 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).
      */
-    posture?: FallbackPosture;
+    rewrittenIR: PromptIR;
     /**
-     * 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).
+     * One entry per section the translator rewrote. Empty array when no
+     * rules fired. Order matches the corresponding section in
+     * `rewrittenIR.sections`.
      */
-    maxDepth?: number;
+    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.
+ */
+/**
+ * The window of evidence a finding was computed from — migration 054.
+ *
+ * READ THE DISTINCTION BEFORE USING THIS. It is NOT `openedAt` /
+ * `lastObservedAt` / `observationCount`, which describe the ADVISORY (how
+ * long it has been firing, how many times the watcher ran and still saw the
+ * condition). This describes what the generator LOOKED AT.
+ *
+ * A daily cron that keeps firing on a single 29-second burst reports
+ * `observationCount: 11` spanning 11 days — the most standing-looking of
+ * standing conditions — while its evidence is one event from 11 days ago.
+ * Separating the two is the entire point.
+ *
+ * `null` when the generator did not state its window. Honest unknown; it
+ * must never be read as "not a burst". Compile-time library rules carry
+ * null legitimately — they fire on ONE call, so their evidence is the call
+ * in hand and there is no window to state.
+ */
+interface AdvisoryEvidenceWindow {
+    firstAt: string;
+    lastAt: string;
+    n: number;
+    /** `lastAt - firstAt`, precomputed so no caller re-derives it wrong. */
+    spanMs: 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.
+     * `true` when the evidence is clustered tightly enough to be ONE EVENT
+     * rather than a standing rate. See `classifyEvidenceWindow`.
      */
-    policy?: CompilePolicy;
+    isBurst: boolean;
 }
-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.
+ * Burst-vs-rate, computed rather than judged.
+ *
+ * Origin: tt-intel s118. A cost query showed `claude-sonnet-5` at 30% of
+ * their `ask` traffic and 80% of ask spend. Every number true, every
+ * mechanism check correct, and every correct check made them more certain
+ * the spend gate had regressed. All eleven calls sat in a 29-second window —
+ * their own prior experiment, fixed six minutes after the last one. Their
+ * formulation: **a cluster is an event, not a rate.**
+ *
+ * The rule, deliberately crude because a subtle one would need tuning per
+ * rule and would then be wrong per rule: evidence is a burst when it spans
+ * less than `BURST_SPAN_MS` (5 minutes). Multiple observations inside five
+ * minutes are one incident — a deploy, a retry storm, a test run, a
+ * benchmark — not a pattern of behavior over time.
+ *
+ * Two deliberate non-features:
+ *
+ * - **n is not in the test.** Two rows 4 minutes apart are as much a single
+ *   event as eleven are. Requiring a minimum n would let the smallest, least
+ *   evidenced findings skip the check.
+ * - **It does not try to detect fossils.** A burst is not necessarily stale;
+ *   it is merely not a rate. Only the consumer's own deploy log can turn
+ *   "one event" into "an event we already fixed", and this library cannot
+ *   see that. Claiming otherwise would be the same over-reach the rule
+ *   exists to correct.
  */
-declare function getStarterChain(archetype: IntentArchetypeName): string[];
+declare const BURST_SPAN_MS: number;
+declare function classifyEvidenceWindow(row: {
+    evidence_first_at?: string | null;
+    evidence_last_at?: string | null;
+    evidence_n?: number | null;
+}): AdvisoryEvidenceWindow | null;
+/** Human-readable span for advisory text. Terse by design — it sits inline. */
+declare function formatEvidenceSpan(spanMs: number): string;
 /**
- * Returns a shallow copy of all starter chains keyed by archetype.
- * Useful for the `digest.mjs` readout and consumer audits.
+ * The sentence that travels with a burst-shaped finding. Written to be
+ * usable verbatim in advisory text, and to say what the library CAN claim
+ * (one event) rather than what it cannot (that the event is stale).
  */
-declare function getAllStarterChains(): Record<IntentArchetypeName, string[]>;
+declare function burstCaveat(w: AdvisoryEvidenceWindow): string;
+interface ActionableAdvisory {
+    id: string;
+    rule: string;
+    severity: AdvisorySeverity;
+    openedAt: string;
+    lastObservedAt: string;
+    observationCount: number;
+    /**
+     * Migration 054. `null` when the generator did not state a window — an
+     * honest unknown, NOT an assertion that the evidence is well-spread.
+     */
+    evidenceWindow: AdvisoryEvidenceWindow | null;
+    /**
+     * The severity the rule ASKED for, present only when this advisory's
+     * effective `severity` was downgraded because its evidence is burst-shaped.
+     * Kept so a consumer can see the downgrade happened rather than silently
+     * receiving a quieter advisory than the generator wrote.
+     */
+    severityBeforeBurstDowngrade?: AdvisorySeverity;
+    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';
+    /**
+     * alpha.78 (PB adoption-gap ask 2): the trio now DEFAULTS from
+     * `readBrainReadEnv()` when omitted, so a consumer that passes nothing
+     * gets correct behavior from the canonical env names instead of a
+     * self-authored config error. Explicit values still win.
+     */
+    brainEndpoint?: string;
+    brainJwt?: string;
+    brainAnonKey?: string;
+    fetch?: typeof fetch;
+}
+interface MarkAdvisoryResolvedOptions {
+    /** Stable id from a prior `getActionableAdvisories` call. */
+    id: string;
+    resolutionNote?: string;
+    /**
+     * alpha.78 (PB adoption-gap ask 2): the trio now DEFAULTS from
+     * `readBrainReadEnv()` when omitted, so a consumer that passes nothing
+     * gets correct behavior from the canonical env names instead of a
+     * self-authored config error. Explicit values still win.
+     */
+    brainEndpoint?: string;
+    brainJwt?: string;
+    brainAnonKey?: string;
+    fetch?: typeof fetch;
+}
+/**
+ * Map a single `actionable_advisories_v` row (snake_case, Postgres
+ * native) to the public `ActionableAdvisory` shape (camelCase). Single
+ * canonical mapping site for this boundary (L-118).
+ */
+declare function rowToAdvisory(row: Record<string, unknown>): ActionableAdvisory;
+/**
+ * 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 EVERY unresolved firing in `compile_outcome_advisories`
+ *      matching that tuple via the underlying outcome's app_id. (One call
+ *      closes the whole rollup — the alpha.71-era docblock said "latest
+ *      firing", which was never what the code did; corrected alpha.78.)
+ *
+ * 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.
+ *
+ * alpha.78 envelope (PB `resolve-envelope-cannot-close-a-rollup`, 2026-07-25):
+ * the return now reports WHAT HAPPENED, not that the request was received —
+ * `firingsResolved` is the count of rows this call actually flipped, and
+ * `status` is the rollup's state after the write. PB measured the old
+ * `ok: true` live against prod: the PATCH was being RLS-filtered to zero
+ * rows (consumer JWTs had read-grant but no update-grant — migration 049
+ * adds it) and the envelope reported success anyway. "When an API can
+ * succeed without doing anything, the return value should distinguish those
+ * cases" — this is that distinction. `firingsResolved: 0, status: 'open'`
+ * on a rollup you expected to close now points at the write grant.
+ *
+ * Idempotent re-marks stay ok: an already-resolved advisory returns
+ * `{ ok: true, firingsResolved: 0, status: 'resolved' }`.
+ *
+ * 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;
+    firingsResolved: number;
+    status: 'open' | 'resolved' | 'unknown';
+} | {
+    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?...`.
+     *  alpha.78: defaults from `readBrainReadEnv()` when omitted. */
+    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.
+     *  alpha.78: defaults from `readBrainReadEnv()` when omitted. */
+    brainJwt?: string;
+    /** Supabase anon key for the `apikey` header (PostgREST requires it).
+     *  alpha.78: defaults from `readBrainReadEnv()` when omitted. */
+    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' | 'zai' | 'moonshot';
+/**
+ * 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[];
+}
+/**
+ * alpha.78 (PB adoption-gap ask 2) — the canonical brain-read env names as
+ * an exported constant, so consumers reference them instead of retyping
+ * (PB invented three plausible-but-wrong names and carried the resulting
+ * self-authored 503 for two months).
+ */
+declare const BRAIN_READ_ENV_NAMES: {
+    readonly endpoint: "KGAUTO_V2_BRAIN_SUPABASE_URL";
+    readonly jwt: "KGAUTO_V2_BRAIN_JWT";
+    readonly anonKey: "KGAUTO_V2_BRAIN_ANON_KEY";
+    /** Accepted fallbacks, in resolution order after the canonical name. */
+    readonly fallbacks: {
+        readonly endpoint: readonly ["KGAUTO_V2_BRAIN_URL"];
+        readonly jwt: readonly ["GLASSBOX_BRAIN_JWT"];
+        readonly anonKey: readonly [];
+    };
+};
+/**
+ * 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]
+ *
+ * ## What the default chain optimizes for — READ THIS BEFORE CITING IT
+ *
+ * The default (`optimizeFor: 'quality'`) chain is ordered by **archetype
+ * performance with provider diversity**, NOT by cost. It is a reliability
+ * ladder: "if tier 0 fails, who else can do this job well."
+ *
+ * This docstring previously claimed each step "costs strictly less than the
+ * previous." **That claim was false for all ten archetypes** (verified
+ * 2026-07-29, alpha.80) and it was load-bearing — kgauto's own cost
+ * advisories cited `posture: 'open'` as a cost remedy on the strength of it.
+ * At the time, `ask` open posture led with `claude-sonnet-4-6` (retargeted
+ * to `claude-sonnet-5` in alpha.90) at ~8.6x the cost
+ * of the model the cost advisories recommend. tt-intel came within one
+ * un-run function call of tripling their hottest path's spend by following
+ * kgauto's own documented advice. See
+ * `advisory/kgauto/from-tt-intelligence/2026-07-28_chain-builder-and-cost-advisories-give-opposite-answers.md`.
+ *
+ * Some non-monotone steps are deliberate and correct: `plan` walks UP to
+ * Opus on 429, `critique`/`judge` never degrade below a reasoning floor,
+ * and cross-provider anchors are chosen for outage-independence rather
+ * than price. The defect was the unconditional claim, not the chains.
+ *
+ * The default chain at each step:
+ *   1. Comes from a different provider than the previous step where possible
+ *      (correlated outages don't kill consecutive attempts)
+ *   2. Stays above the archetype's perf floor (skip models scored <baseline
+ *      for archetypes where degradation would be unacceptable)
+ *   3. Makes NO cost guarantee. Pass `optimizeFor: 'cost'` when cost order
+ *      is what you want — that mode DOES guarantee monotone-cheaper, and
+ *      `assertChainCostMonotonicity` pins it.
+ *
+ * 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';
+    /**
+     * alpha.80 — what the chain ORDER optimizes for.
+     *
+     *   'quality' (default) — status quo, byte-for-byte. Hand-curated /
+     *      brain-loaded archetype ladder: best perf first, provider diversity
+     *      down the chain. Makes NO cost guarantee (see module docstring).
+     *
+     *   'cost' — cheapest-first among every `status: 'current'` model whose
+     *      `archetypePerf[archetype]` clears {@link ARCHETYPE_FLOOR_DEFAULT}.
+     *      Guarantees monotone-cheaper. Considers the WHOLE roster, not just
+     *      the curated chain — which is the point: `gemini-2.5-flash` ties
+     *      `claude-haiku-4-5` on `ask` perf at a third of the price and is
+     *      absent from the curated `ask` ladder entirely.
+     *
+     * The quality floor is what keeps 'cost' honest: a model with no evidence
+     * scores the neutral 5 and is therefore excluded, so cost mode can never
+     * bottom-feed into unmeasured models. Quality stays a binary floor; cost
+     * optimizes only above it.
+     *
+     * Default 'quality' — existing consumers see zero change on bump.
+     */
+    optimizeFor?: 'quality' | 'cost';
+}
+/**
+ * Reference call shape used to RANK models by cost. Deliberately a blend
+ * rather than input-only: ranking by `costInputPer1m` alone (which the
+ * advisor's `cost-mismatched-archetype` rule does) mis-orders any pair
+ * whose output multiple differs, and real traffic runs input-heavy
+ * (L-050: >85% input is the universal efficiency signal).
+ *
+ * This ranks; it does not bill. `estimateChainCostUsd` is exported so
+ * callers who know their real shape can compute against it instead.
+ */
+declare const COST_RANKING_REFERENCE_SHAPE: {
+    readonly inputTokens: 4000;
+    readonly outputTokens: 250;
+};
+/**
+ * Estimated USD for one call at a given shape. Exported so the advisor and
+ * consumer-side code share ONE derivation of "what does this model cost
+ * here" — two independent derivations of one concept will drift (s75).
+ */
+declare function estimateModelCostUsd(profile: ModelProfile, shape?: {
+    inputTokens: number;
+    outputTokens: number;
+}): number;
+/**
+ * @deprecated alpha.81 — renamed to {@link estimateModelCostUsd}; it takes a
+ * single MODEL, not a chain. Preserved because alpha.80 shipped this name and
+ * a consumer adopted it within hours. Identical behavior.
+ */
+declare const estimateChainCostUsd: typeof estimateModelCostUsd;
+/**
+ * How many distinct providers a chain spans. `1` means every fallback shares
+ * one provider's fate — the chain buys you retries, not outage independence.
+ * Exported so a cost-mode consumer can check what they traded away.
+ */
+declare function chainProviderSpread(chain: readonly string[]): number;
+/**
+ * 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" | "judge", 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;
+
+/**
+ * promotions-brain — alpha.64 Stage-2 substrate.
+ *
+ * Per-tenant SWR cache for the `kgauto_promotions` table populated by the
+ * golden-eval trigger's auto-promote actor (Stage 2 of the eval trust
+ * ladder: auto-promote downswaps behind the 7-day rollback guard). Mirrors
+ * `promote-ready-brain.ts` shape where applicable; this is the read-side
+ * substrate for the compile-time promotion boost in `passScoreTargets`.
+ *
+ * Design contract:
+ *   command-center/advisory/kgauto/2026-07-18_stage2-auto-promote-design.md
+ *
+ * Consent posture: the routing effect is OPT-IN, default OFF. The cache is
+ * only activated by `configureBrain()` when the consumer opted in via
+ * `BrainConfig.autoPromote: true` or the `KGAUTO_AUTO_PROMOTE` env var
+ * (config field wins when both are present — mirror of the
+ * `KGAUTO_GOLDEN_CAPTURE` env-as-consent precedent). Not opted in ⇒ this
+ * module never fetches and `getApplicablePromotion` returns undefined ⇒
+ * zero behavior change anywhere in compile().
+ *
+ * Architecture (mirror of promote-ready-brain):
+ *   - Sync API surface: `getApplicablePromotion({ appId, archetype })`
+ *     returns immediately. First call returns undefined (cold) and fires an
+ *     async refresh; subsequent calls within TTL return brain data.
+ *   - Per-appId snapshot; one fetch per appId per TTL window.
+ *   - Tolerant: brain down / misconfigured / unexpected shape → undefined.
+ *     Never throws. Warns once per process.
+ *
+ * A rollback (`status='rolled_back'` PATCHed by the promotion-guard
+ * watcher) drops the row from the endpoint's `status=active` filter, so
+ * routing reverts within one TTL window — the mechanism the 7-day guard's
+ * auto-revert rests on.
+ */
+
+/**
+ * One active surface promotion, camelCase-mapped at the boundary from the
+ * snake_case endpoint row (typed-boundary-transformer convention).
+ */
+/**
+ * Release B (alpha.75): `kgauto_promotions` carries two logical channels
+ * sharing one table and one lifecycle (migration 047). `mode` is the
+ * discriminator, and each mode has exactly ONE consumption site:
+ *
+ *   mode        reader                              effect
+ *   ----------  ----------------------------------  -------------------
+ *   downswap    passScoreTargets (compile pass 5)   which MODEL runs
+ *   strategy    applySectionRewrites (pass 6.5)     which IR runs
+ *
+ * The resolver is mode-filtered and no unfiltered accessor exists — an
+ * unfiltered `.find()` was the §7 read-path bug: a strategy row has
+ * promoted_model === incumbent_model, so one reaching the model-boost code
+ * would boost the incumbent and could suppress the alpha.49 quality gate on
+ * evidence that was never about quality-gating.
+ */
+type PromotionMode = 'downswap' | 'strategy';
+interface PromotionRow {
+    /** Brain row id — cited in the `promotion-applied` mutation for Glass-Box. */
+    id: number;
+    /** Intent archetype the promotion applies to. */
+    archetype: string;
+    /**
+     * Channel discriminator (migration 047). Rows from a pre-047 endpoint
+     * carry no `mode` on the wire and map to 'downswap' — every pre-047 row
+     * IS a downswap, and strategy rows can only be written by post-047 code
+     * whose endpoint serves the column.
+     */
+    mode: PromotionMode;
+    /**
+     * The strategy id for mode='strategy' rows (e.g. 'discipline-gates-v1');
+     * null on downswaps. DB CHECK: (mode='strategy') = (strategy IS NOT NULL).
+     */
+    strategy: string | null;
+    /** The model this surface now routes to. */
+    promotedModel: string;
+    /** The model it replaced (the eval's incumbent). */
+    incumbentModel: string;
+    /** The promote-ready kgauto_golden_eval_runs row this rests on. */
+    evalRunId: number | null;
+    /**
+     * Evidence-supersedes-judgment: skip the alpha.49 schema-weak
+     * quality-gate penalty for the promoted model on this surface (the eval
+     * measured the schema floor holding on real workload). Always false on
+     * strategy rows (DB CHECK kgauto_promotions_strategy_no_suppress).
+     */
+    suppressQualityGate: boolean;
+    /** ISO timestamp the promotion went active. */
+    promotedAt: string;
+    /**
+     * alpha.78 — lifecycle status. The endpoint serves rolled_back rows only
+     * when the library asks (`with_rollbacks=1`), so pre-.78 clients can
+     * never receive one. Every reader that APPLIES a promotion must filter
+     * to 'active'; rolled_back rows exist so advisors can see what the guard
+     * already adjudicated instead of re-recommending it (PB Finding 3).
+     */
+    status: 'active' | 'rolled_back';
+    /** ISO timestamp of the guard's revert, rolled_back rows only. */
+    rolledBackAt?: string;
+    /** Guard's classification ('latency' | 'economics' | 'strategy' | …). */
+    rollbackClass?: string;
+}
+interface PromotionsRuntime {
+    /** Endpoint base URL. The library appends `?app_id=<id>`. */
+    endpoint: string;
+    /** Stale-while-revalidate window in ms. */
+    ttlMs: number;
+    /** Pluggable fetch. */
+    fetchImpl: typeof fetch;
+    /** Optional warn hook. */
+    onError?: (err: unknown) => void;
+}
+/**
+ * Default endpoint hosted on the kgauto-dashboard. Serves `status='active'`
+ * kgauto_promotions rows for one app_id. Mirrors the findings convention.
+ */
+declare const DEFAULT_PROMOTIONS_ENDPOINT = "https://kgauto-dashboard.vercel.app/api/kgauto-v2/promotions";
+/**
+ * True when the KGAUTO_AUTO_PROMOTE env var opts this process in.
+ * Accepted truthy forms: '1', 'true' (case-insensitive). Everything else —
+ * unset, '', '0', 'false' — is OFF. Read at configureBrain() time, not per
+ * call.
+ */
+declare function isAutoPromoteEnabledFromEnv(envSource?: Record<string, string | undefined>): boolean;
+/**
+ * Wire (or rewire) the runtime. Pass undefined to disable. Resets all
+ * snapshots. Called from `configureBrain()` ONLY when the consumer opted in.
+ */
+declare function configurePromotionsBrain(rt: PromotionsRuntime | undefined): void;
+/** Sync introspection — is the promotions brain active (i.e. opted in)? */
+declare function isPromotionsBrainActive(): boolean;
+interface GetApplicablePromotionOpts {
+    /** App id to read promotions for. Required. */
+    appId: string;
+    /** Archetype of the compile in flight. Required. */
+    archetype: IntentArchetypeName | string;
+    /**
+     * Channel to read (migration 047). Required — there is deliberately no
+     * unfiltered accessor: with one active row per (surface, mode) legal, an
+     * unfiltered first-match-wins `.find()` returns an arbitrary channel's
+     * row, and a strategy row reaching the model-boost reader is the §7
+     * read-path bug.
+     */
+    mode: PromotionMode;
+}
+/**
+ * Sync reader. Returns the active promotion for `(appId, archetype, mode)`
+ * or undefined. First call returns undefined and triggers async refresh;
+ * subsequent calls within TTL return brain data. The brain enforces one
+ * active promotion per (surface, mode) (partial unique index), so at most
+ * one row matches.
+ *
+ * NEVER throws. Not configured / brain down / cold → undefined.
+ */
+declare function getApplicablePromotion(opts: GetApplicablePromotionOpts): PromotionRow | undefined;
+/**
+ * alpha.78 — how long a guard rollback suppresses re-recommending the same
+ * model on the same surface. Matches the measured-failure evidence window:
+ * a `rollback_class='latency'` revert deliberately keeps the model ELIGIBLE
+ * long-term (traffic patterns change), so the suppression is windowed, not
+ * permanent.
+ */
+declare const ROLLBACK_SUPPRESSION_WINDOW_DAYS = 28;
+/**
+ * alpha.78 (PB Finding 3) — sync reader: did the promotion guard recently
+ * roll back `model` on `(appId, archetype)`? The cost advisor consults this
+ * so it stops recommending "exactly the downswap your own machinery
+ * auto-reverted three days ago" — an advisory acting on it would
+ * re-litigate a decision the guard already made correctly. Same SWR
+ * posture as `getApplicablePromotion`: cold/unconfigured → undefined
+ * (advisor proceeds without rollback knowledge, as before alpha.78).
+ */
+declare function getRecentRollback(opts: {
+    appId: string;
+    archetype: IntentArchetypeName | string;
+    model: string;
+    windowDays?: number;
+    nowMs?: number;
+}): PromotionRow | undefined;
+/**
+ * alpha.86 — cold-start prefetch, the promotions twin of alpha.73's
+ * `prefetchMeasuredFailure`.
+ *
+ * alpha.73 fixed cold-isolate blindness for the measured-failure gate and
+ * did not cover this sibling subsystem: `compile()` is synchronous, so on a
+ * cold isolate `getApplicablePromotion` reads an empty snapshot and an
+ * ACTIVE promotion silently does not apply — hitting low-traffic consumers
+ * (whose isolates are cold most of the time) hardest, directly under
+ * trust-artifact #3. Found s81 via the smoke's own cold-cache bug; grep
+ * confirmed zero prefetch call sites existed.
+ *
+ * Also the fix for the s81 smoke incident's root shape: this starts the SWR
+ * refresh directly, so it cannot be defeated by `getApplicablePromotion`'s
+ * argument validation early-returns.
+ *
+ * Returns the in-flight promise (or undefined when not configured / already
+ * fresh) so a caller can await it. NEVER throws.
+ */
+declare function prefetchPromotions(appId: string): Promise<void> | undefined;
+/**
+ * alpha.86 — bounded await on the promotions warm-up, for async callers
+ * only (`call()`); `compile()` stays synchronous. Same contract as
+ * `awaitMeasuredFailureReady`: bounded, silent on timeout, protective
+ * never required — a slow or down brain delays a call by at most
+ * `timeoutMs` and can never fail one. A zero budget still kicks the
+ * prefetch (the opt-out is "do not make me wait", not "do not warm up").
+ *
+ * NEVER throws.
+ */
+declare function awaitPromotionsReady(appId: string, timeoutMs: number): Promise<void>;
+/** Reset module state. Tests must call between cases. */
+declare function _testResetPromotions(): void;
+/** Wait for any in-flight refresh to settle. */
+declare function _testWaitForPromotionsRefresh(): Promise<void>;
+
+/**
+ * measured-failure-brain — the CREATE-a-gate direction of
+ * measured-supersedes-judgment (alpha.70).
+ *
+ * alpha.49 gives kgauto a quality gate that fires off a model profile's
+ * DECLARED conventions (`archetypeConventions.structuredOutputHint: 'avoid'`).
+ * alpha.64 let a MEASURED eval verdict SUPPRESS that gate
+ * (`kgauto_promotions.suppress_quality_gate`). Nothing could go the other
+ * way — a model whose declarations are wrong could not have a gate CREATED
+ * for it, which is precisely the case where declarations cannot be trusted.
+ *
+ * The originating evidence: `claude-haiku-4-5` on playbacksam/summarize
+ * declares `structuredOutput: 'grammar'` + `archetypePerf.summarize: 8`, so
+ * every quality signal reads green and it wins the surface on price — while
+ * failing **12 of 12 in-window attempts** (2026-07-14..25, seven in one
+ * day). The brain held that evidence and nothing could act on it.
+ *
+ * ── Design notes ───────────────────────────────────────────────────────
+ *
+ * **No stored decision.** The gate is DERIVED from a rolling 28d window
+ * (`kgauto_surface_model_failure_v`), never written down. That kills the
+ * flap problem by construction — there is no state to flap — and it means
+ * a gated model un-gates itself once its failures age out. Combined with
+ * the gate being a DE-RANK (out of leadership, retained as graceful
+ * fallback) rather than a hard block, the model keeps earning evidence, so
+ * this cannot become the exclusion-lock-in trap where a blocked model can
+ * never prove itself again.
+ *
+ * **The threshold is a confidence bound, not a fixed sample floor.** A flat
+ * `minSample: 20` (promotion-guard's rate floor) would NOT have fired on
+ * haiku's n=12 — the consumer would keep paying while we waited for a
+ * rounder number. But distinguishing 100% from 5% needs far fewer trials
+ * than distinguishing 2% from 6%. Gating on the Wilson score lower bound
+ * makes the sample requirement adapt to the effect size automatically,
+ * which is the alpha.67 insight ("the sample floor for a median can be far
+ * lower than for a rate") generalised properly.
+ *
+ * **Direct app-scoped read, not the config-endpoint cache.** Modelled on
+ * `promotions-brain.ts`, deliberately NOT `createBrainQueryCache` — that
+ * routes through the dashboard `/v2/config` projection, which is the third
+ * layer in the L-073 "executable knowledge is dropped at every transport
+ * boundary" chain. One fewer place to forget a field.
+ */
+
+/**
+ * One row of the rolling-window evidence view, per (app, archetype, model).
+ * Raw counts only — the brain serves facts, this module decides.
+ */
+interface SurfaceFailureRow {
+    archetype: string;
+    model: string;
+    /** Total attempts in-window (served + quality walkaways). */
+    n: number;
+    /** Attempts that failed on the quality axis. */
+    nFail: number;
+}
+declare const MEASURED_FAILURE_CFG: {
+    /**
+     * Hard minimum attempts before ANY gate may be created. Guards against
+     * pathological tiny samples that the confidence bound alone would let
+     * through in edge cases. At 5-for-5 the bound clears the threshold; at
+     * 3-for-3 it does not, which is the behaviour we want (three failures is
+     * a bad day, five in a row is a pattern).
+     */
+    readonly minSample: 5;
+    /**
+     * Gate when we are 95% confident the model fails MORE OFTEN THAN IT
+     * SUCCEEDS on this surface. Deliberately unarguable rather than tuned —
+     * a model that probably fails the majority of the time has no business
+     * leading a surface, whatever its declared scores say.
+     */
+    readonly lowerBoundThreshold: 0.5;
+    /** 95% one-sided-ish confidence (standard two-sided z at α=0.05). */
+    readonly z: 1.96;
+    /** Must match the view's window. Documented here for the advisory text. */
+    readonly windowDays: 28;
+};
+/**
+ * Wilson score interval, lower bound. Preferred over the normal
+ * approximation because it stays sane at the extremes — at p̂ = 1 the
+ * normal approximation gives a zero-width interval (it would gate on a
+ * single failure), while Wilson correctly returns a bound that tightens
+ * with n.
+ *
+ * Returns 0 for n <= 0.
+ */
+declare function wilsonLowerBound(failures: number, n: number, z?: number): number;
+interface MeasuredFailureVerdict {
+    /** Whether the measured-failure quality gate fires for this tuple. */
+    gated: boolean;
+    /** Observed failure rate in-window. */
+    rate: number;
+    /** 95% lower confidence bound on that rate — what the gate tests. */
+    lowerBound: number;
+    /** Attempts backing the verdict. */
+    n: number;
+    nFail: number;
+}
+/**
+ * alpha.78 — public row normalizer (PB 2026-07-25 trap): the counts
+ * endpoint speaks snake_case (`intent_archetype`, `n_fail`) and this module
+ * speaks camelCase. A consumer reproducing a gate decision by hand from the
+ * endpoint previously got a silent `gated: false` — `wilsonLowerBound(
+ * undefined, 13)` returns a clean 0 rather than throwing. Exported so the
+ * bridge exists exactly once.
+ */
+declare function mapMeasuredFailureRows(rows: unknown[]): SurfaceFailureRow[];
+/**
+ * Pure decision, exported for tests and for the advisory text. Separated
+ * from the I/O so the policy can be exercised without a brain.
+ *
+ * alpha.78 — accepts BOTH row shapes: the module's camelCase
+ * `SurfaceFailureRow` and the counts endpoint's raw snake_case row. A
+ * snake_case row previously slipped through the type system (all fields
+ * `undefined`) and judged `gated: false` silently.
+ */
+declare function judgeMeasuredFailure(row: SurfaceFailureRow | {
+    intent_archetype: string;
+    model: string;
+    n: number | string;
+    n_fail: number | string;
+} | undefined, cfg?: typeof MEASURED_FAILURE_CFG): MeasuredFailureVerdict | undefined;
+interface MeasuredFailureRuntime {
+    /** Endpoint base URL. The library appends `?app_id=<id>`. */
+    endpoint: string;
+    /** Stale-while-revalidate window in ms. */
+    ttlMs: number;
+    fetchImpl: typeof fetch;
+    onError?: (err: unknown) => void;
+}
+/** Default endpoint on the kgauto-dashboard. Mirrors the promotions convention. */
+declare const DEFAULT_MEASURED_FAILURE_ENDPOINT = "https://kgauto-dashboard.vercel.app/api/kgauto-v2/measured-failure";
+/**
+ * Opt-out env switch. UNLIKE auto-promote this defaults ON wherever the
+ * brain is configured, because the gate is protective: it only ever
+ * de-ranks a model the consumer's OWN traffic shows to be failing them, and
+ * the failure is already being paid for. Set `KGAUTO_MEASURED_FAILURE_GATE=0`
+ * (or 'false') to disable.
+ */
+declare function isMeasuredFailureGateEnabledFromEnv(envSource?: Record<string, string | undefined>): boolean;
+declare function configureMeasuredFailureBrain(rt: MeasuredFailureRuntime | undefined): void;
+declare function isMeasuredFailureBrainActive(): boolean;
+interface GetMeasuredFailureOpts {
+    appId: string;
+    archetype: IntentArchetypeName | string;
+    model: string;
+}
+/**
+ * alpha.73 — start the warm-up WITHOUT needing a compile to trigger it.
+ *
+ * The SWR posture below ("cold start returns undefined and warms in the
+ * background") is right for a long-lived process and wrong for a
+ * short-lived isolate, where the first compile IS most compiles. Measured on
+ * playbacksam: on a cold isolate the gate was absent, `claude-haiku-4-5` led,
+ * cliffed, was same-model retried and fell over to gemini — two billed
+ * inferences and ~27–34s, every time an isolate is new. PB has ~1 user, so
+ * its isolates are cold most of the time, which inverts the usual severity
+ * ordering: this hits the LOWEST-traffic consumers hardest, and they are the
+ * ones least able to absorb it.
+ *
+ * Kicking the fetch off at `configureBrain()` moves the refresh into the time
+ * the isolate spends on everything else it does before its first compile.
+ * Fire-and-forget and non-blocking: on its own this narrows the window rather
+ * than closing it, which is why `awaitMeasuredFailureReady()` exists too.
+ *
+ * Returns the in-flight promise (or undefined when not configured / already
+ * fresh) so a caller can await it. NEVER throws.
+ */
+declare function prefetchMeasuredFailure(appId: string): Promise<void> | undefined;
+/**
+ * alpha.73 — bounded await on the warm-up, for async callers only.
+ *
+ * `compile()` is synchronous and must stay so, so it cannot block on a fetch;
+ * `call()` is async and is about to spend seconds on an inference, which makes
+ * a few hundred milliseconds here a trivially good trade against the ~27–34s
+ * and second billed inference a cold-blind gate costs.
+ *
+ * Deliberately bounded and deliberately silent on timeout: the gate is
+ * protective, never required. If the brain is slow or down, the caller
+ * proceeds un-gated exactly as it does today — this can delay a call by at
+ * most `timeoutMs`, and can never fail one.
+ *
+ * NEVER throws.
+ */
+declare function awaitMeasuredFailureReady(appId: string, timeoutMs: number): Promise<void>;
+/**
+ * Sync reader. Returns the verdict for `(appId, archetype, model)` or
+ * undefined (not configured / cold / below minSample / brain down).
+ *
+ * NEVER throws. Cold start returns undefined and warms in the background —
+ * same posture as every other brain-driven lever in compile(). Async callers
+ * that can afford a bounded wait should call `awaitMeasuredFailureReady()`
+ * first; `call()` does.
+ */
+declare function getMeasuredFailureVerdict(opts: GetMeasuredFailureOpts): MeasuredFailureVerdict | undefined;
+declare function _testResetMeasuredFailure(): void;
+declare function _testWaitForMeasuredFailureRefresh(): Promise<void>;
+
+/**
+ * Release C (Rung 1) — the decomposition coach's planning engine.
+ *
+ * Design contract §5.1: evidence-backed advisories on the existing surface —
+ * "you're paying frontier prices for grunt work; here's the measured split."
+ * No contract change; nothing here executes a fan-out. This module is PURE:
+ * templates + arithmetic. The operator script feeds it measured surface
+ * stats and evidence-picked executors; Release D's `delegate` primitive will
+ * consume the SAME templates, so they live in the library, versioned.
+ *
+ * Honesty posture (the roster-with-receipts rule, applied to ourselves):
+ *
+ *   - The per-step token SHARES are JUDGMENT v1 numbers — labelled as such
+ *     in every plan (`assumptions[]`), versioned so a future measured
+ *     replacement invalidates nothing silently. No consumer has fan-out
+ *     traffic yet (R0 shipped alpha.68, zero adopters), so there is nothing
+ *     to measure them from; the moment branch traffic exists, these
+ *     graduate per surface.
+ *   - Executor grounding is carried per step: 'measured' when the portfolio
+ *     corpus has real outcomes for (model, sub-archetype), 'judgment' when
+ *     the roster's archetypePerf is all we have.
+ *   - The coach's most credible output at low volume is "KEEP THE MONOLITH"
+ *     with the break-even volume stated — the never-worse floor in coach
+ *     form. The advisory only files when the split is MATERIAL (same $5/mo
+ *     felt-utility floor as promotions); the demo report renders every
+ *     analysis either way.
+ */
+
+declare const DECOMPOSITION_TEMPLATES_VERSION = "decomposition-templates-v1";
+interface DecompositionStep {
+    /** Human-readable step name (stable — appears in advisories/recipes). */
+    role: string;
+    /** The sub-archetype this step runs as (its own learning_key downstream). */
+    archetype: IntentArchetypeName;
+    /**
+     * Which tier runs the step. 'delegate' steps are the grunt work the coach
+     * proposes moving to a cheap executor; 'anchor' steps stay on the
+     * incumbent (composition is where fan-outs die — §7a — so the composer
+     * anchors on the strong model by design).
+     */
+    tier: 'delegate' | 'anchor';
+    /** Share of the monolith's INPUT tokens this step reads. JUDGMENT v1. */
+    inputShare: number;
+    /**
+     * Tokens this step EMITS, as a share of the monolith's input (for
+     * intermediate artifacts like extraction notes) — the next anchor step
+     * reads these instead of the raw input. JUDGMENT v1.
+     */
+    emitsShareOfInput: number;
+    /** Share of the monolith's OUTPUT tokens this step produces (0 for
+     * intermediate steps; the anchor composer typically carries 1). */
+    outputShare: number;
+}
+interface DecompositionTemplate {
+    archetype: IntentArchetypeName;
+    steps: DecompositionStep[];
+    rationale: string;
+    version: typeof DECOMPOSITION_TEMPLATES_VERSION;
+}
+/**
+ * v1 covers the three judgment-heavy archetypes with a clear split shape.
+ * Every share number below is a judgment estimate, stated in the plan's
+ * assumptions — they exist to make the ARITHMETIC honest, not to claim
+ * precision the corpus doesn't have yet.
+ */
+declare const DECOMPOSITION_TEMPLATES: Partial<Record<IntentArchetypeName, DecompositionTemplate>>;
+interface SurfaceStats {
+    appId: string;
+    archetype: IntentArchetypeName | string;
+    /** The model serving the monolith today (most-served in the window). */
+    incumbentModel: string;
+    nCalls: number;
+    windowDays: number;
+    avgTokensIn: number;
+    avgTokensOut: number;
+}
+interface ExecutorCandidate {
+    modelId: string;
+    /** archetypePerf score on the STEP's archetype. */
+    perfScore: number;
+    grounding: 'measured' | 'judgment';
+    costInputPer1m: number;
+    costOutputPer1m: number;
+}
+interface ModelPricing {
+    costInputPer1m: number;
+    costOutputPer1m: number;
+}
+interface PlannedStep extends DecompositionStep {
+    /** The picked executor ('delegate' steps) or the incumbent ('anchor'). */
+    executorModel: string;
+    executorGrounding: 'measured' | 'judgment';
+    executorPerfScore: number | null;
+    projectedCostPerCallUsd: number;
+}
+interface DecompositionPlan {
+    appId: string;
+    archetype: string;
+    incumbentModel: string;
+    template: DecompositionTemplate;
+    steps: PlannedStep[];
+    monolithCostPerCallUsd: number;
+    splitCostPerCallUsd: number;
+    savingPerCallUsd: number;
+    monthlyCalls: number;
+    projectedMonthlySavingUsd: number;
+    /** Monthly calls at which the split clears the materiality floor. null
+     * when the split doesn't save per-call at all (then no volume helps). */
+    breakEvenMonthlyCalls: number | null;
+    verdict: 'split-pays' | 'keep-monolith';
+    verdictReason: string;
+    /** Judgment inputs, stated. Every number that is not measured is here. */
+    assumptions: string[];
+}
+declare const COACH_CFG: {
+    /** Same felt-utility floor as promotions (alpha.67 family). */
+    minMonthlySavingUsd: number;
+    /** Executor must clear this archetypePerf on the step's archetype —
+     * same floor as the translator/advisor (ARCHETYPE_FLOOR_DEFAULT). */
+    executorPerfFloor: number;
+    daysPerMonth: number;
+};
+interface PlanDecompositionArgs {
+    stats: SurfaceStats;
+    incumbentPricing: ModelPricing;
+    /**
+     * Evidence-picked executor per step archetype. Return undefined when no
+     * candidate clears the perf floor — the plan then keeps that step on the
+     * incumbent and says so (a coach must not route grunt work to a model
+     * that can't do it just because it is cheap).
+     */
+    pickExecutor: (archetype: IntentArchetypeName) => ExecutorCandidate | undefined;
+    cfg?: Partial<typeof COACH_CFG>;
+}
+declare function planDecomposition(args: PlanDecompositionArgs): DecompositionPlan | undefined;
 
 /**
  * @warmdrift/kgauto v2 — prompt compiler + central learning brain.
@@ -408,4 +4091,4 @@ declare function getAllStarterChains(): Record<IntentArchetypeName, string[]>;
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ApiKeys, type AppOracle, BestPracticeAdvisory, type BrainConfig, CallOptions, CallResult, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetDefaultFallbackChainOpts, IntentArchetypeName, type LLMJudgeOptions, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, PromptIR, ProviderOverrides, RecordInput, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getAllStarterChains, getDefaultFallbackChain, getStarterChain, record, resetTokenizer, runAdvisor, setTokenizer };
+export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ALT_BLIND_TOKEN_BUDGET_BREACH, ALT_STRATEGY_IDS, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryEvidenceWindow, 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, BLOCKED_MODEL_FAMILY_SIBLING_SERVED_CODE, BLOCKED_MODEL_NOT_IN_ROSTER_CODE, BRAIN_READ_ENV_NAMES, BURST_SPAN_MS, BestPracticeAdvisory, type BrainConfig, type BrainDeadLetterEntry, type BrainHealthSnapshot, type BrainQueryConfig, type BrainReadEnv, COACH_CFG, COST_RANKING_REFERENCE_SHAPE, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type CreateDelegateOpts, DECOMPOSITION_TEMPLATES, DECOMPOSITION_TEMPLATES_VERSION, DEFAULT_FINDINGS_ENDPOINT, DEFAULT_JUDGE_MODEL, DEFAULT_MEASURED_FAILURE_ENDPOINT, DEFAULT_PROMOTIONS_ENDPOINT, DELEGATE_TOOL_DEFINITION, DISCIPLINE_GATES_V1_ALT_BLIND_HEADER, DISCIPLINE_GATES_V1_ALT_HEADER, type DecompositionPlan, type DecompositionStep, type DecompositionTemplate, type DelegateHandle, type DelegateRefusalReason, type DelegateResult, type DelegateToolArgs, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type ExecutorCandidate, type FallbackPosture, FallbackReason, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetApplicablePromotionOpts, type GetDefaultFallbackChainOpts, type GetMeasuredFailureOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, type GoldenEvalAxis, type GoldenEvalCase, type GoldenEvalOptions, type GoldenEvalRunResult, type GoldenEvalStrategyId, type GoldenIrRecordInput, Grounding, IntentArchetypeName, JUDGE_RUBRICS, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_FAILURE_CFG, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type MeasuredFailureRuntime, type MeasuredFailureVerdict, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, OutputMode, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PlannedStep, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, type PromotionRow, type PromotionsRuntime, PromptIR, Provider, ProviderOverrides, type ProviderReachability, ROLLBACK_SUPPRESSION_WINDOW_DAYS, RULE_DISCIPLINE_GATES_V1, RULE_DISCIPLINE_GATES_V1_STRUCTURED, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, STRATEGY_AUTHORSHIP_INDEPENDENT, STRATEGY_AUTHORSHIP_LIMITATION, SectionRewrite, type ShadowProbeRecordInput, type StrategyAttribution, type StrategyAttributionResult, type StrategyOutcome, type SupportedProvider, type SurfaceFailureRow, type SurfaceStats, SystemModelMessage, TRANSLATOR_FLOOR, _testResetMeasuredFailure, _testResetOutcomeSourceWarning, _testResetPromotions, _testWaitForMeasuredFailureRefresh, _testWaitForPromotionsRefresh, altBlindGatesBlockFor, altGatesBlockFor, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, awaitMeasuredFailureReady, awaitPromotionsReady, brainHealth, buildGoldenIrRow, buildLLMJudge, buildPairwiseJudgePrompt, buildShadowProbeRow, burstCaveat, call, chainProviderSpread, classifyEvidenceWindow, classifyStrategyOutcome, clearBrain, combineOrderSwappedVerdicts, compile, compileForAISDKv6, configureBrain, configureMeasuredFailureBrain, configurePromotionsBrain, countTokens, createDelegate, deriveFamilyFromModelId, deriveOwnership, estimateChainCostUsd, estimateModelCostUsd, execute, findBetterFit, flushBrainDeadLetter, formatEvidenceSpan, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getApplicablePromotion, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getMeasuredFailureVerdict, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecentRollback, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isAltStrategy, isAutoPromoteEnabledFromEnv, isBrainQueryActiveFor, isBrainSync, isDelegateEnabledFromEnv, isExclusionFindingsBrainActive, isMeasuredFailureBrainActive, isMeasuredFailureGateEnabledFromEnv, isModelReachable, isPromotionsBrainActive, isProviderReachable, judgeMeasuredFailure, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, mapMeasuredFailureRows, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, parseJudgeVerdict, peekBrainDeadLetter, planDecomposition, prefetchMeasuredFailure, prefetchPromotions, probeShadow, profileToRow, readBrainReadEnv, record, recordGoldenIr, recordOutcome, recordShadowProbe, renderIrForJudge, resetTokenizer, resolveConventionsForProfile, resolveOutcomeSource, resolvePricingAt, resolveProviderKey, rowToAdvisory, rubricFor, runAdvisor, runGoldenEval, runStrategyEvalWithAttribution, setTokenizer, wilsonLowerBound, withAltBlindDisciplineContract, withAltDisciplineContract, withDisciplineContract };