@warmdrift/kgauto-compiler 2.0.0-alpha.6 → 2.0.0-alpha.61

package/dist/ir-DmUuJsWc.d.ts

@@ -0,0 +1,1386 @@
+import { IntentArchetypeName } from './dialect.js';
+
+/**
+ * Intermediate Representation — the structured form of a prompt.
+ *
+ * Everything kgauto v2 does, it does on the IR. The IR is constructed by the
+ * caller (or by `parse()` from a string-style prompt for backwards-compat),
+ * transformed by the compiler passes, and lowered to a target-specific wire
+ * request only at the very end.
+ *
+ * The IR carries STRUCTURE, not just text. Sections are first-class. Tools
+ * carry per-intent relevance. History knows its turn-age. Constraints are
+ * explicit. This is what lets passes do real work.
+ */
+
+/**
+ * A semantically-named section of the system prompt. Sections enable
+ * intent-aware slicing (drop sections not tagged for this intent), dedupe
+ * (collapse identical sections across files), and cache marking (identify
+ * the stable prefix).
+ */
+interface PromptSection {
+    /** Stable identifier — used for slicing, dedupe, and cache markers. */
+    id: string;
+    /** Section text. */
+    text: string;
+    /**
+     * Which intents this section applies to. Empty = applies to all intents.
+     * Pass `compile()` will drop sections whose intents array doesn't include
+     * the current intent.
+     */
+    intents?: IntentArchetypeName[];
+    /**
+     * If true, this section is part of the stable cacheable prefix. The lower
+     * pass uses this to place cache markers correctly per target.
+     */
+    cacheable?: boolean;
+    /**
+     * Section weight when ordering — lower = earlier in the assembled prompt.
+     * Defaults to insertion order.
+     */
+    weight?: number;
+    /**
+     * alpha.29+ — declares the section's semantic kind so kgauto can apply
+     * model-aware rewrites at compile time. Default `'arbitrary'` (when
+     * unset) for full back-compat — pre-alpha.29 sections continue working
+     * unchanged.
+     *
+     * alpha.29 ships rewrites for `tool_call_contract` only. Other kinds are
+     * type-accepted but pass through. alpha.30+ will add rewrites for
+     * `narration_contract`, `role_intro`, etc.
+     *
+     * See `translator.ts` for the rewrite engine that consumes this field.
+     */
+    kind?: SectionKind;
+}
+/**
+ * alpha.29+ — semantic kind tag for a `PromptSection`. The translator
+ * (`v2/src/translator.ts`) consumes this to apply model-aware rewrites at
+ * compile time. CLOSED union; future kinds extend it explicitly in named
+ * alpha releases.
+ *
+ * alpha.29 ships rewrites for `tool_call_contract` only. Other kinds are
+ * type-accepted but pass through.
+ *
+ * - `role_intro`         — "You are a helpful assistant", persona blocks
+ * - `tool_call_contract` — tool-use rules ("call X then Y"); the alpha.29
+ *                          translator rewrites this for models with a
+ *                          sequential-tool cliff on the active archetype
+ * - `narration_contract` — output-format rules ("don't narrate your steps");
+ *                          alpha.30+ candidate
+ * - `user_turn`          — when sections carry user content rather than
+ *                          system context (rare)
+ * - `reference`          — supporting reference data the model may consult
+ * - `arbitrary`          — explicit pass-through (default when unset)
+ */
+type SectionKind = 'role_intro' | 'tool_call_contract' | 'narration_contract' | 'user_turn' | 'reference' | 'arbitrary';
+interface ToolDefinition {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+    /**
+     * Per-intent relevance scores. Compile uses these to drop irrelevant tools.
+     * Missing intents default to 0.5 (neutral).
+     */
+    relevanceByIntent?: Partial<Record<IntentArchetypeName, number>>;
+    /** Pass-through for provider-specific fields (Anthropic input_schema, etc.). */
+    [key: string]: unknown;
+}
+interface Message {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    /** Optional structured parts (tool calls, results) — passed through to lowering. */
+    parts?: unknown[];
+    /** For tool messages — which tool this corresponds to. */
+    toolName?: string;
+    /** For tool messages — the call id. */
+    toolCallId?: string;
+}
+/**
+ * The compile-time intent declaration. `name` is the app's local label;
+ * `archetype` is the canonical dialect-v1 archetype the app maps it to.
+ *
+ * Apps with their own intent vocabulary (tt-intelligence's "ask"/"hunt"/
+ * "dashboard") declare the mapping here. The brain learns by archetype, not
+ * by app-local name.
+ */
+interface IntentDeclaration {
+    /** App-local intent name (free-form, for app's own debugging). */
+    name: string;
+    /** Canonical dialect-v1 archetype. Required for cross-app learning. */
+    archetype: IntentArchetypeName;
+}
+/**
+ * alpha.57 — dialect-level reasoning-effort tier (data-first).
+ *
+ * Vocabulary is a portfolio-level tier ladder (low → max), NOT any provider's
+ * wire value — mapping to `reasoning_effort` (OpenAI) / thinking budgets
+ * (Anthropic) / `thinkingConfig` (Gemini) stays consumer-side until
+ * routing-on-effort ships. Declaring it records the tier on the brain row
+ * (`compile_outcomes.effort`, migration 033) so effort×archetype quality
+ * evidence accumulates BEFORE any routing logic exists — same data-first
+ * sequencing as `tool_orchestration` (alpha.20).
+ */
+type EffortLevel = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+interface Constraints {
+    /** Hard latency ceiling — compiler will down-rank slow models. Advisory. */
+    maxLatencyMs?: number;
+    /** Hard cost ceiling per call (USD). Advisory. */
+    maxCostUsd?: number;
+    /**
+     * alpha.57 (data-first): the reasoning-effort tier the consumer ran (or
+     * intends to run) this call at. RECORDED, NOT APPLIED — the compiler does
+     * not emit provider thinking/effort params from this field and does not
+     * route on it yet; it flows to `compile_outcomes.effort` via record()'s
+     * registry auto-enrich (same pattern as `mutationsApplied`/advisories).
+     * Declare it truthfully: this is consumer-reported ground truth, like
+     * `tokensIn`/`latencyMs`. Does NOT enter the shape key (no learning-key
+     * fragmentation).
+     */
+    effort?: EffortLevel;
+    /** Caller wants structured (JSON) output. */
+    structuredOutput?: boolean;
+    /** Hint: caller expects a short response (used to disable thinking on Gemini). */
+    expectedShortOutput?: boolean;
+    /** Hint: max response words. */
+    maxResponseWords?: number;
+    /** Override target model selection — if set, compiler uses this instead of routing. */
+    forceModel?: string;
+    /**
+     * alpha.20: consumer-declared tool-orchestration shape for this call.
+     * - 'parallel': model may fire multiple tool calls per step (current
+     *   default behavior; the L-040 cliff applies — DeepSeek's
+     *   `tool_count >= 1` cliff trims tools because parallel-tool throughput
+     *   collapses to sequential semantics).
+     * - 'sequential': consumer commits to one tool call per step (the agentic
+     *   loop pattern). DeepSeek V4-Flash + V4-Pro can compete cleanly in
+     *   this mode — the L-040 cliff is silenced and the hunt chain shifts
+     *   to a DeepSeek-tier-1 ordering.
+     * - 'either': consumer doesn't care; library picks the parallel chain
+     *   (status-quo default) and may upgrade to brain-driven per-mode perf
+     *   selection in a future release.
+     *
+     * Affects:
+     *   - Chain composition for `archetype: 'hunt'` (see
+     *     `getDefaultFallbackChain` and `STARTER_CHAINS_BY_MODE`).
+     *   - L-040 cliff in `passApplyCliffs` (silent when 'sequential').
+     *
+     * Default (when undefined): equivalent to 'parallel' for back-compat
+     * with every pre-alpha.20 caller.
+     */
+    toolOrchestration?: 'parallel' | 'sequential' | 'either';
+}
+/**
+ * Cache marker policy for the messages array (history + currentTurn).
+ *
+ * Anthropic positional caching: a `cache_control` marker on a content block
+ * tells the API "remember the prefix up through this block." On a subsequent
+ * request whose first N tokens match, those N billed at the cached rate
+ * (10% of the input price). Without a marker, every call re-pays for the
+ * entire history.
+ *
+ * - `'none'` (default when omitted): no history cache marker. System-level
+ *   cache markers from `PromptSection.cacheable=true` still apply.
+ * - `'all-but-latest'`: marks the message immediately preceding `currentTurn`
+ *   (the last history entry). On the next call, that entire history prefix
+ *   is cacheable. Good fit for chat/agent loops where every prior turn is
+ *   stable.
+ * - `'fixed-suffix'`: marks the message `suffix` positions from the end of
+ *   `history`. Use when the last few turns are volatile (e.g., scratchpad,
+ *   draft revisions) but the earlier prefix is stable.
+ *
+ * For non-Anthropic providers, no wire-format marker is emitted (Gemini /
+ * OpenAI / DeepSeek implicit caching takes effect automatically when a
+ * stable prefix is reused). The compiler still computes
+ * `diagnostics.historyCacheableTokens` for telemetry on every provider.
+ *
+ * alpha.5.
+ */
+type HistoryCachePolicy = {
+    strategy: 'none';
+} | {
+    strategy: 'all-but-latest';
+} | {
+    strategy: 'fixed-suffix';
+    suffix: number;
+};
+/**
+ * Consumer-declared policy for model selection. Lives outside the IR
+ * (passed via CompileOptions) because it's a SESSION/APP-level constraint,
+ * not a per-call shape.
+ *
+ * The original tt-intelligence scenario (s11): user capped Anthropic
+ * spending on Sonnet for cost reasons. v2 compile() kept picking Sonnet
+ * as the best target, Hunter's preflight hit the cap and fell back to
+ * Flash — every single call. CompilePolicy.blockedModels lets the
+ * consumer tell kgauto "don't pick Sonnet right now" and the compiler
+ * routes to the next-best option directly. No wasted preflight tax.
+ *
+ * This is the "coach knows the constraints" feature — kgauto stops
+ * recommending things the consumer has already ruled out.
+ */
+interface CompilePolicy {
+    /**
+     * Model IDs the consumer has gated. Compile() will never select these.
+     * Use for: cost caps, account-level rate limits, "this model is broken
+     * for our workload" decisions.
+     */
+    blockedModels?: string[];
+    /**
+     * Hard ceiling on estimated input cost per call (USD). Models whose
+     * estimated cost exceeds this are rejected. Use for: budget enforcement
+     * on high-volume routes.
+     */
+    maxCostPerCallUsd?: number;
+    /**
+     * Model IDs the consumer prefers. When multiple models fit, preferred
+     * models get a rank boost (large enough to overcome small quality
+     * differences but not large enough to override hard rejects).
+     */
+    preferredModels?: string[];
+    /**
+     * Customer-posture tag (master plan §1.2, alpha.9).
+     *
+     *   - `'locked'`    — compliance/contract/brand-promise. Caller passes
+     *                     exactly one model; no fallback is desired. kgauto
+     *                     never walks the chain.
+     *   - `'preferred'` — user-selected primary, fallback chain as safety
+     *                     net. On 429/5xx, walk the chain and surface
+     *                     `fellOverFrom` so the consumer can show "Claude
+     *                     was busy; we used Pro for this answer."
+     *   - `'open'`      — library picks the chain. Model identity is
+     *                     irrelevant; output is the contract.
+     *
+     * The field is **informational** — kgauto's execution path is already
+     * determined by the shape of `ir.models`. Posture surfaces in
+     * telemetry so the cost-watcher can distinguish "locked failed, no
+     * fallback was tried" from "open chain exhausted." Default: when
+     * `ir.models.length === 1` posture is treated as `'locked'` by the
+     * advisor; otherwise unspecified.
+     */
+    posture?: 'locked' | 'preferred' | 'open';
+}
+/**
+ * alpha.41 — entry in `PromptIR.models[]`. Either a literal model id (the
+ * pre-alpha.41 shape, fully preserved) or a `{ family: string }` alias that
+ * resolves at compile() time to the latest-current model in that family.
+ *
+ * Family entries resolve via `resolveFamilyEntry` (internal twin of the
+ * public `getRecommendedPrimary`). Resolution fails CLOSED — a family that
+ * matches no current+active candidate throws `FamilyResolutionError` at
+ * compile time. Consumers who want a literal fallback should call
+ * `getRecommendedPrimary({ family, fallback, ... })` at IR-construction time
+ * and inline the resolved id, rather than passing `{ family }` into the IR.
+ *
+ * Family taxonomy is defined in `family-resolution.ts`; see also migration
+ * 024 (`kgauto_models.family` column + index).
+ */
+type ChainModelEntry = string | {
+    family: string;
+};
+/**
+ * The IR — the input to compile().
+ */
+interface PromptIR {
+    /** App identifier — required for multi-tenant brain. */
+    appId: string;
+    /** Intent declaration — what is this call doing? */
+    intent: IntentDeclaration;
+    /** Structured system prompt sections. */
+    sections: PromptSection[];
+    /** Available tools (compiler may drop based on intent relevance + budget). */
+    tools?: ToolDefinition[];
+    /** Conversation history (compiler may compress old turns). */
+    history?: Message[];
+    /** The user's current turn — never dropped. */
+    currentTurn?: Message;
+    /**
+     * Allowed model IDs (or family aliases — alpha.41+), in caller-preference
+     * order. Compiler resolves family entries to literal ids before scoring
+     * and picks among them. See {@link ChainModelEntry}.
+     *
+     * Internal passes downstream of compile()'s family-resolution step
+     * receive a narrowed `string[]` shape — `string` is a subtype of
+     * `ChainModelEntry`, so a `string[]` IS a `ChainModelEntry[]` at the
+     * type level. Code that needs to access string ids (passes.ts) reads
+     * via `getModelIds(ir)` from `models-runtime.ts` rather than narrowing
+     * inline.
+     */
+    models: ChainModelEntry[];
+    /** Compile constraints. */
+    constraints?: Constraints;
+    /**
+     * Cache marker placement policy for the messages array. Default = no
+     * history cache markers. See `HistoryCachePolicy` for semantics.
+     * alpha.5.
+     */
+    historyCachePolicy?: HistoryCachePolicy;
+}
+type Provider = 'anthropic' | 'google' | 'openai' | 'deepseek' | 'mistral' | 'xai';
+/**
+ * Mutation IDs that fired during compile. Empty in v1 (no mutation engine
+ * yet). Populated when the brain is online and pushing mutations.
+ */
+type MutationApplied = {
+    id: string;
+    source: string;
+    passName: string;
+    description: string;
+};
+/**
+ * Target-specific wire request. Shape varies by provider — caller passes the
+ * right field to the right SDK.
+ */
+type CompiledRequest = {
+    provider: 'anthropic';
+    model: string;
+    system: Array<{
+        type: 'text';
+        text: string;
+        cache_control?: {
+            type: 'ephemeral';
+        };
+    }>;
+    messages: Array<{
+        role: string;
+        content: unknown;
+    }>;
+    tools?: unknown[];
+    max_tokens?: number;
+    /**
+     * alpha.29 — emitted only when the translator's wire-overrides set
+     * `parallelToolCalls = false`. Shape per Anthropic Messages API docs:
+     * `{ type: 'auto', disable_parallel_tool_use: true }`. kgauto defaults
+     * to omitting `tool_choice` entirely (Anthropic defaults to auto + parallel),
+     * so this field's presence signals an explicit override.
+     */
+    tool_choice?: {
+        type: 'auto' | 'any' | 'tool' | 'none';
+        disable_parallel_tool_use?: boolean;
+        name?: string;
+    };
+} | {
+    provider: 'google';
+    model: string;
+    systemInstruction?: {
+        role: 'system';
+        parts: Array<{
+            text: string;
+        }>;
+    };
+    contents: Array<{
+        role: string;
+        parts: unknown[];
+    }>;
+    tools?: unknown[];
+    generationConfig?: Record<string, unknown>;
+    cachedContent?: string;
+} | {
+    provider: 'openai';
+    model: string;
+    messages: Array<{
+        role: string;
+        content: unknown;
+    }>;
+    tools?: unknown[];
+    response_format?: unknown;
+    reasoning_effort?: string;
+    /**
+     * alpha.29 — emitted only when the translator's wire-overrides set
+     * `parallelToolCalls = false`. OpenAI defaults parallel_tool_calls=true
+     * server-side; we explicit-set to false only when overriding.
+     */
+    parallel_tool_calls?: boolean;
+} | {
+    provider: 'deepseek';
+    model: string;
+    messages: Array<{
+        role: string;
+        content: unknown;
+    }>;
+    tools?: unknown[];
+};
+/**
+ * Best-practice advisory emitted by the compiler at compile time. Non-fatal —
+ * consumers log, surface in dev tools, gate on `level === 'critical'` in CI,
+ * or ignore. The advisor inspects the IR + selected profile + diagnostics
+ * and emits one entry per detected gap.
+ *
+ * Codes are stable across releases. `suggestion` and `docsUrl` are optional
+ * but encouraged: suggestion = the actionable diff; docsUrl = the
+ * interfaces/kgauto.md anchor for context.
+ *
+ * alpha.6 Phase 1 starter rules:
+ *   - `caching-off-on-claude` (warn)       system >2000 chars on Anthropic, no cacheable=true
+ *   - `single-chunk-system` (info)         Anthropic, only one PromptSection >1000 chars
+ *   - `tool-bloat` (warn)                  >10 tools on a short-output archetype
+ *   - `history-uncached-on-claude` (warn)  Anthropic, ≥2 history messages, no historyCachePolicy
+ *
+ * Phase 2 (catalog as `bestPractices` block in profiles) and Phase 3 (brain
+ * telemetry on `advisories_fired`) are alpha.7+ territory.
+ */
+interface BestPracticeAdvisory {
+    /**
+     * Severity. `info` = informational; `warn` = behavioral pattern that's
+     * usually expensive or wrong; `critical` = likely bug or production-grade
+     * misuse. Phase 1 ships info + warn only.
+     */
+    level: 'info' | 'warn' | 'critical';
+    /** Stable kebab-case code. Consumers filter / gate by this. */
+    code: string;
+    /** Human-readable explanation of what was detected. */
+    message: string;
+    /** Optional: how to fix — actionable diff or pattern. */
+    suggestion?: string;
+    /** Optional: link to docs anchor for more context. */
+    docsUrl?: string;
+    /**
+     * alpha.20 — actionable category for routing/dashboard surfacing. When set,
+     * the brain persists this as `recommendation_type` on
+     * `compile_outcome_advisories` so consumers can filter "show me all
+     * client-side issues that are caching-fix recommendations." Optional;
+     * absent on legacy or uncategorized rules.
+     *
+     * - `'model-swap'`          — swap to a different model fixes this
+     * - `'prompt-fix'`          — restructure prompt (sections, tools, format)
+     * - `'caching-fix'`         — add cache markers (system or history)
+     * - `'no-ai-needed'`        — the call shouldn't be using an AI model
+     * - `'tier-down'`           — current model is overkill for this archetype
+     * - `'architecture-change'` — the issue isn't fixable at the kgauto layer
+     */
+    recommendationType?: 'model-swap' | 'prompt-fix' | 'caching-fix' | 'no-ai-needed' | 'tier-down' | 'architecture-change';
+    /**
+     * alpha.36 — architectural recommendation when the call shouldn't be an
+     * AI call at all, or should be a cheaper non-AI substitute. Optional and
+     * orthogonal to {@link recommendationType}: when set, narrows the
+     * `no-ai-needed` / `architecture-change` rec-type into an actionable
+     * pattern the consumer can implement.
+     *
+     * - `'lookup-table'`       — deterministic input → output mapping (≥95% agreement at high N). Build a domain table; fall back to AI for novel inputs.
+     * - `'memoization-cache'`  — same canonical input recurs across sessions with equivalent output. Add an edge/KV cache keyed on canonical input.
+     * - `'tier-down'`          — cheaper model tier delivers equal-or-better oracle score on this shape. Move primary to the cheaper tier.
+     * - `'deterministic-parser'` — `constraints.structuredOutput: true` calls where the schema is regex/JSON-extractable from the input.
+     * - `'precompute'`         — input is derivable at build / cron / batch time; eliminate the per-request call entirely.
+     *
+     * Operator-side detection lives in `v2/scripts/no-ai-needed-detector.mjs`
+     * (alpha.36); a compile-time advisor rule that consumes the brain-side
+     * findings cache follows in a later alpha. Today populated only by the
+     * operator-side detector + the brain RPC `get_no_ai_needed_candidates`
+     * (migration 021).
+     */
+    recommendedArchitecture?: 'lookup-table' | 'memoization-cache' | 'tier-down' | 'deterministic-parser' | 'precompute';
+    /**
+     * alpha.28 — when a rule wants to surface a specific structural adaptation
+     * (not just a swap or a prompt fix), it attaches the adapter shape here.
+     * Shape is the canonical {@link Adapter} discriminated union defined in
+     * this module; `compatibility.ts` re-exports it so
+     * `getModelCompatibility()` and `BestPracticeAdvisory.suggestedAdaptation`
+     * share one source of truth.
+     *
+     * Today fired by `archetype-perf-floor-breach` (alpha.28) when a
+     * documented adapter exists for the chosen model's archetype cliff.
+     * Absent on rules without a structural adapter (caching-off-on-claude,
+     * tool-bloat, etc.) and on the `reject` branch of
+     * `archetype-perf-floor-breach` where no adapter would help.
+     *
+     * CLOSED discriminated union (R3 from consultation doc) — future adapter
+     * parameters extend the union in `compatibility.ts` in named alpha
+     * releases. No `| string` escape hatch; consumer code can write
+     * exhaustive `switch (suggestedAdaptation.parameter)`.
+     *
+     * Phase 2 cross-builder coherence: Builder A's
+     * `AdvisoryRecord.suggestedAdaptation` (in `glassbox-routes/types.ts`)
+     * MUST type to the same union. Phase 2 integration verifies.
+     */
+    suggestedAdaptation?: Adapter;
+    /**
+     * alpha.42 — the kgauto request handle that produced this advisory. Stamped
+     * by `compile()` after `runAdvisor()` returns, sourced from
+     * `CompileResult.handle`. Lets a consumer's admin UI pivot from advisory
+     * row → original trace (Glass-Box card, brain `compile_outcomes` lookup).
+     *
+     * Absent when the advisory was constructed outside the full `compile()`
+     * pipeline (e.g., a direct `runAdvisor()` call in tests). Always present
+     * on advisories returned from `compile().advisories`.
+     */
+    kgautoRequestId?: string;
+    /**
+     * alpha.42 — who is positioned to act on this advisory.
+     *
+     *   - `'consumer-actionable'` (Class A): the consumer can fix this by
+     *     changing their wire-up — add `cacheable: true` markers, swap their
+     *     model literal, declare a section, etc. The admin UI should surface
+     *     a one-click apply or a "fix it" CTA.
+     *   - `'producer-owned'` (Class B): kgauto needs to ship a code or data
+     *     change — update a profile, promote a model in the chain, fix a
+     *     wire contract. The admin UI should surface this as informational
+     *     ("kgauto is on it") and not present a consumer-side action.
+     *
+     * Stamped by `compile()` after `runAdvisor()` returns. Rules can self-
+     * declare via the matching field on their return; otherwise the stamp
+     * consults the static `PRODUCER_OWNED_RULE_CODES` set in `advisor.ts`,
+     * defaulting to `'consumer-actionable'` when the code isn't listed.
+     *
+     * Closes the s47 dogfood gap where the tt-intel admin UI conflated the
+     * two classes — consumers couldn't tell whether they should act or wait.
+     */
+    ownership?: 'consumer-actionable' | 'producer-owned';
+}
+/**
+ * alpha.28 — adapter shape attached to advisories and returned by
+ * `getModelCompatibility()`. A CLOSED discriminated union: future adapter
+ * parameters extend it 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 consumer policy."
+ *
+ * Defined here (in `ir.ts`, the foundational types module) and re-exported
+ * from `compatibility.ts` for ergonomic consumer imports. Anchoring it
+ * here avoids the import cycle that would form if both files tried to be
+ * the source of truth (ir.ts → compatibility.ts → profiles.ts → ir.ts).
+ *
+ * alpha.28 variants:
+ *   - `{ parameter: 'toolOrchestration'; value: 'sequential'; consequence }`
+ *     Lifts DeepSeek V4-family on `hunt` from the sequential-tool cliff
+ *     (L-040). `consequence` is consumer-renderable plain English.
+ *
+ * Future alpha releases will add e.g. `parallelToolCalls`, `maxTools`,
+ * `thinkingBudget` (per tt-intel-Cairn priority list).
+ */
+type Adapter = {
+    parameter: 'toolOrchestration';
+    value: 'sequential';
+    consequence: string;
+};
+/**
+ * alpha.29+ — record of a single section rewrite fired by the translator at
+ * compile time. Surfaces on `CompileResult.sectionRewritesApplied` and (in
+ * scrubbed wire form, without original/transformed text) on
+ * `TraceDetail.sectionRewritesApplied` for Glass-Box Coaching-card rendering.
+ *
+ * `originalText` / `transformedText` stay package-internal — they may carry
+ * consumer PII. The wire-shape variant (`TraceSectionRewrite` in
+ * `glassbox-routes/types.ts`) carries only `summary` for renderer use.
+ */
+interface SectionRewrite {
+    /** Stable id of the `PromptSection` that was rewritten. */
+    sectionId: string;
+    /** The `kind` discriminator that matched the rewrite rule. */
+    kind: SectionKind;
+    /**
+     * Stable identifier of the rule that fired (e.g.
+     * `'sequential-tool-cliff-below-floor'`). Future rules add named ids; the
+     * brain aggregates by this value for cross-app learning.
+     */
+    rule: string;
+    /** The section's text BEFORE the rewrite fired. */
+    originalText: string;
+    /** The text the translator emitted into the IR for this section. */
+    transformedText: string;
+    /**
+     * Wire-level overrides emitted alongside the text rewrite. Merged into
+     * `CompileResult.wireOverrides` by `applySectionRewrites`. alpha.29 ships
+     * `parallelToolCalls`; the union extends as more wire-overrides surface.
+     */
+    wireOverrides?: {
+        parallelToolCalls?: boolean;
+    };
+}
+interface CompileResult {
+    /** Unique handle for this call — pass to record() to correlate the outcome. */
+    handle: string;
+    /** Selected target model id. */
+    target: string;
+    /** Selected provider. */
+    provider: Provider;
+    /** The wire request — pass the appropriate fields to your SDK. */
+    request: CompiledRequest;
+    /** Estimated tokens (input). */
+    tokensIn: number;
+    /** Estimated cost in USD (input portion). */
+    estimatedCostUsd: number;
+    /** Mutations that fired during compile (informational). */
+    mutationsApplied: MutationApplied[];
+    /** Fallback chain — try these in order if target fails. */
+    fallbackChain: string[];
+    /**
+     * Best-practice advisories emitted by the compiler. Non-fatal. Empty
+     * array when no rules fired. alpha.6 Phase 1.
+     */
+    advisories: BestPracticeAdvisory[];
+    /**
+     * alpha.29+ — per-section rewrites applied by the translator at compile
+     * time. Empty array means no rewrites fired (or pre-alpha.29 behavior —
+     * all sections default `kind: 'arbitrary'`, which is pass-through).
+     *
+     * Surfaces to:
+     *   - Glass-Box Coaching card (via `TraceDetail.sectionRewritesApplied`,
+     *     scrubbed of original/transformed text)
+     *   - brain `compile_outcomes.section_rewrites_applied` (migration 019)
+     *     for cross-app learning
+     */
+    sectionRewritesApplied: SectionRewrite[];
+    /**
+     * alpha.29+ — wire-level overrides emitted by translator rewrites. The
+     * provider lowering pass threads these through to the wire request before
+     * emit. Today only `parallelToolCalls: boolean`; the type extends as more
+     * wire-overrides surface.
+     *
+     * Undefined when no rewrite emitted overrides — the common case.
+     */
+    wireOverrides?: {
+        parallelToolCalls?: boolean;
+    };
+    /** Diagnostics for caller-side logging. */
+    diagnostics: {
+        sectionsKept: number;
+        sectionsDropped: number;
+        toolsKept: number;
+        toolsDropped: number;
+        historyKept: number;
+        historyDropped: number;
+        cacheableTokens: number;
+        estimatedCacheSavingsUsd: number;
+        /**
+         * Tokens in `history` (and `currentTurn` when before the marker) that
+         * fall within the cacheable prefix per `historyCachePolicy`. Always
+         * computed; only Anthropic actually emits a wire-format marker. For
+         * Gemini / OpenAI / DeepSeek, this represents the theoretical cacheable
+         * prefix that implicit caching may pick up — useful telemetry for the
+         * brain to learn which (app, model, archetype) tuples benefit most
+         * from history caching. alpha.5.
+         */
+        historyCacheableTokens: number;
+        /**
+         * Total tokens in input `history` (pre-compression). Computed regardless
+         * of whether `passCompressHistory` fired — surfaces how close a tuple is
+         * to its `compressHistoryAboveTokens` threshold so dashboards / cost-
+         * watchers can see the bloat axis the count-based threshold misses.
+         * 0 when history is empty. alpha.7.
+         */
+        historyTokensTotal: number;
+        /**
+         * alpha.20 E3. Consumer-declared tool-orchestration mode for this call,
+         * mirrored from `ir.constraints.toolOrchestration` for downstream
+         * observability (Glass-Box panel, brain telemetry, advisor logs).
+         * Undefined when the consumer hadn't adopted the constraint yet —
+         * treat as 'parallel' equivalent for back-compat.
+         */
+        toolOrchestration?: 'parallel' | 'sequential' | 'either';
+        /**
+         * alpha.33. Zero-based index into the resolved (post-compression) history
+         * array at which Anthropic prompt-cache marker should land — i.e., the
+         * last message that belongs to the stable cacheable prefix. Consumers
+         * using AI-SDK's `streamText({ messages: convertToModelMessages(...) })`
+         * lose the per-message `providerOptions.anthropic.cacheControl` markers
+         * the compiler emits on `result.request.messages`, because
+         * `convertToModelMessages` reads raw input not the lowered output.
+         * This index gives the consumer a single deterministic position to
+         * attach `cacheControl: { type: 'ephemeral' }` after their own conversion.
+         *
+         * Computation:
+         *   - `historyCachePolicy.strategy === 'all-but-latest'`: history.length - 1
+         *     (or undefined if history is empty)
+         *   - `historyCachePolicy.strategy === 'fixed-suffix'` with `suffix: N`:
+         *     history.length - 1 - N (undefined if N exceeds history length)
+         *   - `historyCachePolicy.strategy === 'none'` or omitted: undefined
+         *
+         * The companion helper `attachCacheControlToStreamTextInput()` reads
+         * this field + the consumer's converted messages to perform the per-
+         * attempt mutation correctly. Filed by IC + tt-intel cross-consumer
+         * pattern 2026-05-20 (`streamText-cache-marker-propagation-gap`).
+         */
+        historyCacheMarkIndex?: number;
+        /**
+         * alpha.33. Zero-based index into the structured `systemMessages` array
+         * (see top-level `systemMessages` field) at which the cacheable system
+         * prefix ends. Useful when the consumer is building a multi-block
+         * system parameter for Anthropic streamText — they can attach
+         * `providerOptions.anthropic.cacheControl` to `systemMessages[index]`.
+         *
+         * Undefined when no section had `cacheable: true` OR `systemMessages` is
+         * empty. Matches `historyCacheMarkIndex` semantics on the history axis.
+         */
+        systemCacheMarkIndex?: number;
+        /**
+         * alpha.43. Cliff-style warnings surfaced by the convention pass
+         * (`passApplyConventions`) when the selected profile + archetype carry
+         * a `cliffWarning` whose preconditions are met. These are informational
+         * — they describe a structural mismatch between the call's shape and
+         * the chosen family (e.g. "reasoner family is wrong for parallel-tool
+         * hunt") so consumers can route differently next time.
+         *
+         * Empty array when no convention fired or no warnings surfaced.
+         * Separate from `cliff_guard` mutations in `mutationsApplied` — those
+         * are profile.cliffs[] runtime triggers; these are convention-level
+         * advisory text. Both can fire on the same call.
+         */
+        cliffWarnings: string[];
+    };
+    /**
+     * alpha.33. Structured `system` for AI-SDK `streamText({ system })`
+     * consumers. When the consumer's lowered request has cacheable section
+     * markers, the flat `system: string` form loses the marker assignment
+     * (every `streamText({ system: '<string>' })` call silently strips
+     * providerOptions). Pass `systemMessages` instead to `streamText({
+     * system: result.systemMessages })` so the cacheable prefix is structurally
+     * preserved.
+     *
+     * Each entry is a `SystemModelMessage`-shaped object:
+     *   { role: 'system', content: string, providerOptions?: { anthropic?:
+     *     { cacheControl: { type: 'ephemeral' } } } }
+     *
+     * Provider-agnostic on emit: only Anthropic actually consumes the
+     * cacheControl block; Gemini / OpenAI / DeepSeek receive the same
+     * shape but ignore the marker (matching their implicit-caching semantics).
+     *
+     * Empty array when the IR carried zero sections (rare; usually means the
+     * compiler dropped everything for the chosen intent). Consumers can fall
+     * back to `result.systemMessages.length === 0 ? '' : result.systemMessages`
+     * or use the helper `attachCacheControlToStreamTextInput()` which handles
+     * both shapes.
+     */
+    systemMessages: SystemModelMessage[];
+}
+/**
+ * alpha.33. AI-SDK-compatible system-message shape carried on
+ * `CompileResult.systemMessages`. Matches the AI-SDK `streamText({ system })`
+ * structured form — consumers can pass these directly without conversion.
+ *
+ * The `providerOptions` field is set ONLY for entries that came from a
+ * section with `cacheable: true` AND the chosen provider is Anthropic AND
+ * the compiler computed a non-zero `cacheableTokens`. Other providers see
+ * `providerOptions: undefined` (or omitted entirely).
+ */
+interface SystemModelMessage {
+    role: 'system';
+    content: string;
+    providerOptions?: {
+        anthropic?: {
+            cacheControl: {
+                type: 'ephemeral';
+            };
+        };
+    };
+}
+/**
+ * Token usage normalized across providers. `cached` and `cacheCreated` are
+ * Anthropic prompt-cache reads/writes (Gemini implicit caching populates
+ * `cached` from `usageMetadata.cachedContentTokenCount`; OpenAI populates
+ * from `prompt_tokens_details.cached_tokens`).
+ */
+interface NormalizedTokens {
+    input: number;
+    output: number;
+    total: number;
+    cached?: number;
+    cacheCreated?: number;
+}
+/**
+ * Tool call in a provider-agnostic shape. Anthropic `tool_use` blocks,
+ * Google `functionCall` parts, and OpenAI/DeepSeek `tool_calls[]` all
+ * collapse to this.
+ */
+interface ToolCall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+interface NormalizedResponse {
+    /** Main text body. Empty string if response had no text content. */
+    text: string;
+    /**
+     * Parsed structured output. Populated when ir.constraints.structuredOutput
+     * is true and JSON.parse(text) succeeds. Null otherwise.
+     */
+    structuredOutput: unknown | null;
+    /** Tool calls in normalized shape. Empty array if none. */
+    toolCalls: ToolCall[];
+    tokens: NormalizedTokens;
+    /** Provider-specific finish reason, passed through unchanged. */
+    finishReason?: string;
+    /** Untouched provider response — escape hatch for consumers needing fields not yet normalized. */
+    raw: unknown;
+    /** Set when structuredOutput parsing was attempted and failed. */
+    parseError?: string;
+}
+interface ApiKeys {
+    anthropic?: string;
+    google?: string;
+    openai?: string;
+    deepseek?: string;
+}
+/**
+ * Per-provider override fields shallow-merged into the lowered request before
+ * execution. Lets consumers reach Gemini `safetySettings`, Anthropic
+ * `tool_choice`, OpenAI `seed` etc. without bypassing kgauto.
+ */
+interface ProviderOverrides {
+    anthropic?: Record<string, unknown>;
+    google?: Record<string, unknown>;
+    openai?: Record<string, unknown>;
+    deepseek?: Record<string, unknown>;
+}
+/**
+ * Full-IR inline shadow-probe config (Shape B, Phase 1 — 2026-05-29 s51).
+ *
+ * When set on `call()`, after the primary response is served kgauto re-lowers
+ * the SAME in-memory PromptIR to each candidate and runs it, persisting a
+ * `probe_outcomes` row with `replay_source='inline-full-ir'` and
+ * `prompt_fidelity=1.0` — a fair, full-prompt measurement (vs the watchers'
+ * lossy `prompt_preview` replay). The probe NEVER blocks the user response and
+ * NEVER persists the raw prompt (system/context/payload) — only response
+ * previews + metadata, same policy the brain already holds.
+ *
+ * This is the trustworthy path that earns the right to a quality verdict;
+ * `prompt_preview` replay is retired for verdicts (see CLAUDE.md).
+ *
+ * Phase 1 enforces `sampleRate` and runs the candidate with `judge: 'off'`
+ * (responses stored for an offline batch judge). `judge: 'opus'` (inline
+ * verdict) and `maxPerDay` (per-tuple daily cap, needs a brain-count read)
+ * are accepted by the type but ENFORCED IN PHASE 2.
+ */
+interface ShadowProbeConfig {
+    /** Model id(s) or family alias(es) to shadow-test against the served model, on the same IR. */
+    candidates: string | string[];
+    /** Probability [0,1] that any given call fires a probe. Default 0.05. */
+    sampleRate?: number;
+    /**
+     * 'off' (Phase 1 default): run candidate + store both responses for an
+     * offline batch judge. 'opus': judge candidate-vs-served inline (Phase 2).
+     */
+    judge?: 'opus' | 'off';
+    /** Per-(appId, archetype, candidate) daily cap. Phase 2 (needs brain-count read). Default 20. */
+    maxPerDay?: number;
+    /**
+     * alpha — latency budget (ms) for the probe leg. **Only enforced in sync mode**
+     * (`BrainConfig.sync === true`), where `call()` awaits the probe before returning
+     * the served response (PB-class Edge consumers, L-086) and the candidate's
+     * latency therefore lands on the user-facing critical path.
+     *
+     * The probe path races against this budget: if the candidate(s) don't finish
+     * within `maxLatencyMs`, the probe aborts, `call()` returns the already-served
+     * response immediately, and an `outcome='aborted_latency_budget'` row is
+     * recorded (no verdict, no false quality data). **The user is never delayed
+     * past the budget.** Default `15000`.
+     *
+     * No-op for fire-and-forget consumers (`sync` unset/false, and every
+     * `probeShadow()` caller fired from `after()`/`waitUntil()`) — they don't block
+     * the user, so there's no latency to bound. The probe runs to completion there.
+     *
+     * Root cause this closes (PB s57 dogfood incident, 2026-06-05): PB arms the
+     * probe inline with `sync:true` on a `maxDuration:120` analyze route; arming a
+     * `latency_tier='slow'` candidate (deepseek-v4-pro, ~78–84s) pushed total
+     * handler time past the frontend's patience and the served analysis came back
+     * empty. A sync probe had no latency budget — this field is the budget.
+     */
+    maxLatencyMs?: number;
+    /**
+     * alpha — when true (the default) **in sync mode**, skip a candidate whose
+     * registry `latency_tier === 'slow'` *before starting it*: a slow-tier model
+     * (e.g. deepseek-v4-pro / deepseek-v4-flash, both `slow` = ~24s+ p50) cannot
+     * fit a sane inline budget, so starting it just to abort it wastes a provider
+     * call. An `outcome='skipped_slow_tier_sync'` row is recorded so the offline
+     * rollup can see the skip (not a silent drop, not a false verdict). Fail-safe.
+     *
+     * **The deeper rule (slow-reasoner → offline-mode):** inline shadow-probing is
+     * for FAST candidates only. To evaluate a slow reasoner you need the offline /
+     * async probe path (the Phase-2 batch direction) which runs off the response
+     * entirely — never the inline sync probe. Set this `false` only if you've moved
+     * the budget high enough that a slow candidate genuinely fits (rare), or you're
+     * in a non-sync consumer where this flag is a no-op anyway.
+     *
+     * No-op for fire-and-forget consumers (`sync` unset/false; `probeShadow()`):
+     * there's no user latency to protect, so slow candidates run normally. Default
+     * `true`.
+     */
+    skipSlowTierInSync?: boolean;
+}
+interface CallOptions {
+    /** Forwarded to compile(). */
+    policy?: CompilePolicy;
+    /**
+     * alpha (s51 Phase 1) — full-IR inline shadow-probe. When set, kgauto
+     * measures the candidate(s) on the same IR after serving the primary,
+     * fire-and-forget. See {@link ShadowProbeConfig}.
+     */
+    shadowProbe?: ShadowProbeConfig;
+    toolRelevanceThreshold?: number;
+    compressHistoryAfter?: number;
+    /** Override API keys (defaults: process.env). */
+    apiKeys?: ApiKeys;
+    /** Provider-specific request fields shallow-merged into the lowered request. */
+    providerOverrides?: ProviderOverrides;
+    /** Override fetch (for tests). */
+    fetchImpl?: typeof fetch;
+    /** Disable retry/fallback walk on retryable errors. Default: enabled. */
+    noFallback?: boolean;
+    /**
+     * alpha.10. Disable the silent auto-filter of unreachable models from the
+     * fallback walk. Default: false (filter ON). Opt-out exists for tests +
+     * the rare consumer that wants the legacy "fail at execute() with auth
+     * error" behavior. When ON (default), models whose provider has no
+     * resolvable API key are dropped from `targetsToTry` before the first
+     * network call; if the chain empties entirely, throws CallError with
+     * `lastErrorCode = 'no_reachable_models'`.
+     *
+     * Reachability source: `apiKeys` (this CallOptions) + `process.env` (via
+     * `PROVIDER_ENV_KEYS`). Override env via env.ts's `ReachabilityOpts.envSource`
+     * is not exposed here — `call()` always uses process.env. Use
+     * `getDefaultFallbackChain({ reachability: { envSource } })` upstream
+     * for hermetic test runs.
+     */
+    noAutoFilter?: boolean;
+    /**
+     * alpha.34. When provided AND the chosen provider supports streaming
+     * (`profile.streaming === true`) AND `noStream` is not set, kgauto
+     * enables provider-native SSE streaming at the wire layer and invokes
+     * `onChunk(delta)` once per provider stream event. `delta` is the text
+     * since the previous `onChunk` call (NOT cumulative) — provider
+     * stream-shape headache normalized in kgauto's lowering layer.
+     *
+     * `CallResult.response.text` is still populated with the full assembled
+     * response — kgauto buffers internally regardless of the callback.
+     * Consumers can use either the streaming side-effect OR the final
+     * `response.text`, doesn't matter.
+     *
+     * Tool calls + finish reason + usage are collected from stream events
+     * and returned in the final `CallResult` exactly as the non-streaming
+     * path would shape them. Brain telemetry latency = time-to-stream-end.
+     *
+     * Chain-walk semantics: if the streaming target fails mid-stream
+     * (network error, retryable provider error), kgauto walks to the next
+     * fallback target and restarts streaming from its first chunk —
+     * `onChunk` fires fresh from the new target. Consumer detects via the
+     * post-call `CallResult.fellOverFrom`. To opt out of fallback for
+     * streaming, set `noFallback: true` alongside `onChunk`.
+     *
+     * Filed by playbacksam s42 (2026-05-22) as `streaming-output-callback-
+     * on-callresult` for ComposeDrawer SSE; perceived-latency UX win
+     * during 10-30s draft assembly.
+     */
+    onChunk?: (chunk: string) => void;
+    /**
+     * alpha.34. Explicit opt-out of streaming even when `onChunk` is
+     * provided. Default: false (streaming enabled when `onChunk` is set).
+     * Use when the consumer wants to pass `onChunk` conditionally without
+     * branching the call site (e.g., capture chunks for instrumentation
+     * without engaging streaming wire format).
+     */
+    noStream?: boolean;
+}
+interface CallAttempt {
+    model: string;
+    status: 'success' | 'retryable' | 'terminal';
+    errorCode?: string;
+    message?: string;
+}
+/**
+ * Why fallback fired. Normalized for `CallResult.fallbackReason` (alpha.9).
+ *
+ *   - `rate_limit`           provider returned 429
+ *   - `provider_error`       5xx, network, or other retryable upstream issue
+ *   - `cost_cap`             preflight policy.maxCostPerCallUsd rejected target
+ *   - `cliff`                alpha.8 contract violation (MAX_TOKENS on
+ *                            structured output, parse-failed JSON)
+ *   - `contract_violation`   other compile-time-contract failures (reserved
+ *                            for alpha.10+ — e.g. mid-stream policy rejects)
+ *   - `provider_auth_failed` alpha.14 — initial provider returned 401/403
+ *                            (upstream key revocation, malformed-but-truthy
+ *                            key, billing lapse). The chain walks to the
+ *                            next non-same-provider target instead of
+ *                            short-circuiting; same-provider remaining
+ *                            entries skip with errorCode='auth_inferred'.
+ */
+type FallbackReason = 'rate_limit' | 'provider_error' | 'cost_cap' | 'cliff' | 'contract_violation' | 'provider_auth_failed';
+interface CallResult {
+    /** Compile handle (still valid for record() if consumer wants to add oracle scores later). */
+    handle: string;
+    /** The model that ACTUALLY served the response (post-fallback). */
+    actualModel: string;
+    /** What compile() originally targeted. */
+    requestedModel: string;
+    provider: Provider;
+    response: NormalizedResponse;
+    latencyMs: number;
+    /** Mutations that fired during compile (informational, mirrors CompileResult.mutationsApplied). */
+    mutationsApplied: MutationApplied[];
+    /** One entry per provider attempt — observability for retry/fallback walks. */
+    attempts: CallAttempt[];
+    /**
+     * Alpha.9 normalization of fallback-walk telemetry. When the chain
+     * succeeded on the first attempt, these collapse to:
+     *   - `servedBy === requestedModel`
+     *   - `fellOverFrom` undefined
+     *   - `fallbackReason` undefined
+     *
+     * When fallback fired:
+     *   - `servedBy` = `actualModel` (the model that produced the response)
+     *   - `fellOverFrom` = `requestedModel` (what the caller / compile() asked for)
+     *   - `fallbackReason` = normalized cause derived from the first
+     *     non-success attempt's `errorCode`
+     *
+     * Consumer UX use: show "Claude was busy; we used Pro for this answer"
+     * when `fellOverFrom` is set (master plan §3.6).
+     */
+    /** Model that actually answered. Equal to `actualModel`; kept distinct for clarity. */
+    servedBy: string;
+    /** Set only when fallback fired. Equal to `requestedModel` in that case. */
+    fellOverFrom?: string;
+    /** Set only when fallback fired. Normalized cause. */
+    fallbackReason?: FallbackReason;
+    /**
+     * alpha.10. Models that auto-filter dropped from the fallback walk because
+     * their provider had no reachable API key. Empty when nothing was filtered
+     * (the common case once consumers have all the keys they need). Surfaces
+     * silent self-heal so consumers can log/audit what happened without
+     * defeating the "kgauto just gets" UX.
+     *
+     * Empty array (not undefined) when filter ran but dropped nothing —
+     * distinguishes "filter ran cleanly" from "filter was disabled" (`undefined`
+     * when `noAutoFilter: true`).
+     */
+    unreachableFiltered?: string[];
+    /**
+     * alpha.16. Models that policy.blockedModels filtering dropped from the
+     * fallback walk. Defense-in-depth at the call() boundary — compile()'s
+     * passScoreTargets already excludes blocked entries from the initial
+     * target + fallbackChain, but if a consumer re-shapes the chain and
+     * threads policy through only partially, this filter catches the gap.
+     *
+     * Resolves TT-40 follow-on `policy-block-not-enforced-on-fallback-chain`
+     * (2026-05-15) where mutations_applied recorded the block intent but
+     * the call walker landed on the blocked model anyway.
+     *
+     * Undefined when no filter ran (no blockedModels set). Populated only
+     * when filter ran AND dropped at least one entry — empty drops are
+     * stored as `undefined` to keep brain telemetry quiet on the common
+     * case.
+     */
+    policyBlockedFiltered?: string[];
+    /**
+     * alpha.17. Unique identifier for this call() invocation, generated at
+     * call() entry via crypto.randomUUID(). Returned on success and emitted
+     * as the routing key for Glass-Box observability events
+     * (compile.start, compile.done, execute.attempt, execute.success,
+     * fallback.walked, advisory.fired). Pass the same id to
+     * `subscribe(traceId)` from `@warmdrift/kgauto-compiler/glassbox` to
+     * tap the in-flight event stream.
+     *
+     * Always present on success. Additive, non-breaking.
+     */
+    traceId: string;
+    /**
+     * alpha.44. Best-practice advisories emitted by the compile that actually
+     * served the response (mirrors `CompileResult.advisories`; uses the SERVED
+     * compile on fallback, same as `mutationsApplied`). Empty array when no
+     * rules fired.
+     *
+     * Closes IC's `callForAgent` side-finding (2026-05-26): call() consumers
+     * (agent paths — sweep / dyad / session-title) previously had no way to
+     * `logAdvisories('[kgauto-v2 ...]', advisories)` like compile() consumers
+     * (chat / intake) do, because the advisories were consumed internally
+     * (trace events, brain record) but never returned. Additive, non-breaking.
+     */
+    advisories: BestPracticeAdvisory[];
+}
+/**
+ * Thrown when call() exhausts the fallback chain without success.
+ * `attempts` carries every model tried + classification.
+ */
+declare class CallError extends Error {
+    readonly attempts: CallAttempt[];
+    readonly lastErrorCode?: string;
+    readonly lastStatus?: number;
+    constructor(message: string, attempts: CallAttempt[], lastStatus?: number, lastErrorCode?: string);
+}
+interface OracleScore {
+    /** 0..1 overall quality. */
+    score: number;
+    /** Optional per-dimension breakdown. */
+    dimensions?: Record<string, number>;
+    /** Free-form explanation for debugging. */
+    rationale?: string;
+}
+interface RecordInput {
+    /** Handle from CompileResult. */
+    handle: string;
+    /** Actual tokens consumed (post-call). */
+    tokensIn: number;
+    tokensOut: number;
+    /** Wall-clock latency in ms. */
+    latencyMs: number;
+    /** True iff the call returned a usable response. */
+    success: boolean;
+    /** True iff the call returned 0 output tokens despite success. */
+    emptyResponse?: boolean;
+    /** Provider error code if any. */
+    errorType?: string;
+    /** Tools actually invoked by the model. */
+    toolsCalled?: string[];
+    /** Oracle quality score — required for learning to fire. */
+    oracleScore?: OracleScore;
+    /** Optional: scrubbed prompt/response previews for debugging. */
+    promptPreview?: string;
+    responsePreview?: string;
+    /**
+     * The model that ACTUALLY RAN. Set this when consumer-side fallback ran
+     * a different model than v2 compile() targeted. Brain stores this as
+     * `model` (the truth) and the original target as `requested_model`.
+     *
+     * Omit when no fallback occurred — brain stores compile target as `model`
+     * (still the truth in that case) and `requested_model` stays NULL.
+     *
+     * s11 fix: prevents the brain from misattributing fallback traffic to
+     * the originally-requested model.
+     */
+    actualModel?: string;
+    /**
+     * Override `mutations_applied` for this outcome. Set by `call()` when
+     * fallback fires — the served compile's mutations (which actually shaped
+     * the request that went on the wire) replace the initial compile's
+     * mutations (registered against the handle). Without this override, fallback
+     * traffic is attributed to the initial compile's mutations and the brain's
+     * mutation effectiveness stats become misleading.
+     *
+     * alpha.4: extends s11 truth-in-logging to mutations.
+     */
+    mutationsApplied?: string[];
+    /**
+     * Cache read input tokens, when supported by the provider.
+     * - Anthropic: `usage.cache_read_input_tokens`
+     * - Google (implicit caching): `usageMetadata.cachedContentTokenCount`
+     * - OpenAI: `usage.prompt_tokens_details.cached_tokens`
+     *
+     * Powers the cost-and-efficiency-watcher (interfaces/kgauto.md, alpha.4):
+     * `tokens_in - cache_read_input_tokens` is the un-cached new context per call.
+     */
+    cacheReadInputTokens?: number;
+    /**
+     * Cache creation input tokens (Anthropic-specific).
+     * `usage.cache_creation_input_tokens`. The first call that pays the 25%
+     * upcharge to write a cache marker; subsequent calls hit `cacheRead`.
+     */
+    cacheCreationInputTokens?: number;
+    /**
+     * Time to first token (ms). Optional; populated when the provider/SDK
+     * surfaces it. Distinct from `latencyMs` (end-to-end wall clock).
+     */
+    ttftMs?: number;
+    /**
+     * alpha.57 (data-first) — the reasoning-effort tier this call actually ran
+     * at. Overrides the compile-declared `constraints.effort` when both are
+     * present (input wins — same precedence as `mutationsApplied`/`advisories`).
+     * When omitted, record() auto-enriches from the registry-cached compile
+     * declaration. Undefined end-to-end → the `effort` key is absent from the
+     * outcome payload entirely (safe against pre-migration-033 brains).
+     */
+    effort?: EffortLevel;
+    /**
+     * alpha.20 — advisories fired at compile() time. Persisted to the brain's
+     * `compile_outcome_advisories` sibling table via a second POST that fires
+     * AFTER the primary outcome insert succeeds. Best-effort: a failed
+     * advisory POST is logged via onError but does NOT throw or roll back the
+     * primary outcome row.
+     *
+     * Pass `result.advisories` from the CompileResult directly. The brain
+     * uses these to compute the `empty_rate_clean` comparator (rows with
+     * zero advisories fired) so consumers can distinguish "model is bad"
+     * from "client sent a bloated/uncached/malformed request."
+     *
+     * Empty array / undefined → no second POST fires.
+     */
+    advisories?: BestPracticeAdvisory[];
+    /**
+     * alpha.28 — Glass-Box renderer substrate fields (migration 018).
+     *
+     * All optional. When omitted, brain stores NULL and the renderer falls
+     * back to "—" / hidden rows. Library callers (`call.ts`) populate what
+     * they observe; adapter / SDK consumers can populate the rest from their
+     * own provider response surface.
+     */
+    /**
+     * Provider finish reason. Captured from NormalizedResponse.finishReason
+     * (Anthropic `stop_reason`, Google `finishReason`, OpenAI `finish_reason`).
+     * Lower-case canonicalization is the brain's job; consumers can pass
+     * raw provider strings.
+     */
+    finishReason?: string;
+    /**
+     * End-to-end wall-clock latency in ms. Distinct from `latencyMs` only
+     * insofar as `latencyMs` was the historical name for the same metric;
+     * `totalMs` is the new column on `compile_outcomes` (migration 018).
+     * When omitted, brain mirrors `latency_ms`.
+     */
+    totalMs?: number;
+    /** Tools kept after the tool-relevance pass. */
+    toolsCount?: number;
+    /** Number of history messages at compile time. */
+    historyDepth?: number;
+    /** Rendered system prompt size in characters. */
+    systemPromptChars?: number;
+    /** Model originally targeted when a fallback fired. */
+    fellOverFrom?: string;
+    /**
+     * Why the fallback fired. Closed set mirroring CallResult.fallbackReason —
+     * keep in sync with the wire-contract enum (TraceDetail.fallbackReason).
+     */
+    fallbackReason?: 'rate_limit' | 'provider_auth_failed' | 'provider_error' | 'cliff' | 'cost_cap' | 'contract_violation';
+}
+/**
+ * alpha.20 Entry 4: kinds of consumer-declared outcomes feeding the quality
+ * loop. Surfaces in `recordOutcome()` as the verdict the consumer's UX is
+ * forwarding to the brain.
+ *
+ *   - `approved`  user explicitly approved (thumbs up, "looks good", accepted)
+ *   - `rejected`  user explicitly rejected (thumbs down, "redo", discarded)
+ *   - `partial`   accepted with edits or partial use (mixed signal)
+ *   - `engaged`   user engaged with the output (copy/scroll/dwell)
+ *   - `abandoned` user abandoned the response (closed, navigated away)
+ *   - `unknown`   verdict could not be inferred — recorded for completeness
+ */
+type OutcomeKind = 'approved' | 'rejected' | 'partial' | 'engaged' | 'abandoned' | 'unknown';
+/**
+ * Input to `recordOutcome()` — consumer's verdict on a previously-compiled
+ * call. Joins to the original `compile_outcomes` row via outcomeId,
+ * enabling per-(model, archetype) approve-rate measurement once N ≥ 10
+ * outcomes accumulate.
+ */
+interface RecordOutcomeInput {
+    /**
+     * Joins to compile_outcomes.id. Pass the compile `handle` string
+     * (CompileResult.handle / CallResult.handle) — consumer proxies resolve
+     * handle → compile_outcomes.id via the `compile_outcomes.handle` column
+     * (reference implementations: PB `api/kgauto-v2/compile_outcome_quality.js`,
+     * tt-intel/IC `app/api/kgauto/v2/compile_outcome_quality/route.ts`). A
+     * numeric compile_outcomes.id also works if the caller already has it.
+     * (There is no `CompileResult.outcomeId` field — the brain assigns the row
+     * id at insert; `handle` is the consumer-visible correlator.)
+     */
+    outcomeId: number | string;
+    /** What did the user / system do with this output? */
+    outcome: OutcomeKind;
+    /** Optional 1-5 user rating (e.g., thumbs up/down with intensity, NPS-style). */
+    rating?: 1 | 2 | 3 | 4 | 5;
+    /** Optional free-text reason (e.g., user-typed feedback, system-inferred cause). */
+    reason?: string;
+    /**
+     * Optional model-reported confidence at compile time (0..1). Used for
+     * Brier-score calibration in later phases (alpha.21+) — pair this with
+     * the actual `outcome` to compute calibration error.
+     */
+    observedConfidence?: number;
+}
+/**
+ * Return shape of `recordOutcome()`. Never throws — persistence failures
+ * surface as `ok: false` with a stable `reason` string.
+ */
+interface OutcomeResult {
+    /**
+     * `true` — the POST was acknowledged 2xx (sync mode only).
+     * `'queued'` (alpha.61) — fire-and-forget mode: the write was handed to the
+     * runtime but NOT acknowledged; delivery is unknown at return time. Read
+     * `brainHealth()` or set `BrainConfig.sync` for delivery evidence.
+     * `false` — brain not configured, or the POST failed (sync mode).
+     * Both truthy values pass `if (result.ok)`; pre-alpha.61 code that treated
+     * the fire-and-forget `true` as an ack was reading a false signal.
+     */
+    ok: boolean | 'queued';
+    /** Stable reason code when ok=false. One of: 'brain_not_configured' | 'persistence_failed'. */
+    reason?: string;
+}
+/**
+ * alpha.21 (s78 Entry 1): provenance label on a chain entry. Surfaces WHY
+ * an entry sits where it sits so consumers can distinguish:
+ *
+ *   - 'measured'         brain has N>=10 rows with a measurable quality
+ *                        outcome backing this placement. The number lives on
+ *                        `ChainEntry.n`.
+ *   - 'capability-fact'  inclusion or exclusion driven by a published or
+ *                        measured CAPABILITY (L-040 cliff, ctx window cap,
+ *                        structured-output support). Not an opinion — a
+ *                        fact about what the model can/can't do.
+ *   - 'judgment'         engineer's pick, no measured backing yet. Cold-start
+ *                        prior; entirely valid until evidence accumulates.
+ *
+ * "Judgment" is HONEST, not a downgrade. Most of `STARTER_CHAINS` lands here
+ * in alpha.21 — that's the point: consumers can SEE the grounding gap and
+ * prioritize the measurement work that would graduate them to 'measured'.
+ */
+type Grounding = 'measured' | 'capability-fact' | 'judgment';
+/**
+ * alpha.21 (s78 Entry 1): a single position in a fallback chain, carrying its
+ * provenance label and an optional human-readable reason. The shape replaces
+ * the old `string[]` representation everywhere chains are surfaced externally.
+ *
+ * `n` is REQUIRED when `grounding === 'measured'` — the runtime helper
+ * `makeMeasuredEntry()` enforces this. For 'capability-fact' and 'judgment'
+ * entries, `n` is undefined.
+ */
+interface ChainEntry {
+    /** Canonical model id (post-alias). */
+    id: string;
+    /** Why this entry sits in this position. */
+    grounding: Grounding;
+    /**
+     * Optional one-liner explaining the grounding decision. The inline comments
+     * that historically lived next to STARTER_CHAINS entries are now expressed
+     * here as machine-readable text.
+     */
+    reason?: string;
+    /**
+     * When `grounding === 'measured'`, the brain row count that backs this
+     * placement. Undefined for 'capability-fact' and 'judgment' entries.
+     */
+    n?: number;
+}
+/**
+ * alpha.21 introspection shape — a per-archetype chain with grounding on
+ * every position. Consumers reading this never see naked string ids;
+ * everything carries provenance.
+ */
+interface ChainWithGrounding {
+    archetype: IntentArchetypeName;
+    /** Ordered: position 0 = primary, rising index = fallback positions. */
+    entries: ChainEntry[];
+}
+/** alpha.23 (s78 Phase 3): per-axis metrics returned by the brain RPC. */
+interface PerAxisMetrics {
+    appId: string;
+    archetype: string;
+    model: string;
+    windowDays: number;
+    /** Total brain rows for this tuple in the window. */
+    nRows: number;
+    /** Subset of nRows with zero advisories fired — the "clean signal" comparator. */
+    nRowsClean: number;
+    /** Count of compile_outcome_quality entries joining to this tuple's outcomes. */
+    nQualityOutcomes: number;
+    /** Approve rate from quality outcomes. null when nQualityOutcomes === 0. */
+    magicRate: number | null;
+    /** Whether magicRate >= consumer-declared qualityFloor. null when no floor declared OR no outcomes. */
+    qualityFloorMet: boolean | null;
+    costEfficiency: {
+        avgCostUsd: number | null;
+        avgCostUsdClean: number | null;
+        avgInputTokens: number | null;
+        avgOutputTokens: number | null;
+        inputTokenRatio: number | null;
+    };
+    timeEfficiency: {
+        avgLatencyMs: number | null;
+        avgTtftMs: number | null;
+    };
+    reliability: {
+        successRate: number | null;
+        successRateClean: number | null;
+        emptyRate: number | null;
+        emptyRateClean: number | null;
+    };
+    evidenceFreshnessDays: number | null;
+}
+/** Per-axis metrics keyed by model — used for chain-comparison views. */
+type PerAxisMetricsByModel = Record<string, PerAxisMetrics>;
+
+export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type EffortLevel as E, type FallbackReason as F, type Grounding as G, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type SystemModelMessage as S, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type CompileResult as e, type SectionRewrite as f, type RecordOutcomeInput as g, type OracleScore as h, type Adapter as i, type PerAxisMetrics as j, type Provider as k, type ChainEntry as l, type CallAttempt as m, CallError as n, type ChainModelEntry as o, type ChainWithGrounding as p, type Constraints as q, type MutationApplied as r, type NormalizedTokens as s, type OutcomeKind as t, type PerAxisMetricsByModel as u, type PromptSection as v, type SectionKind as w, type ShadowProbeConfig as x, type ToolDefinition as y };