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

package/dist/ir-BIAT9gJk.d.ts

@@ -0,0 +1,1031 @@
+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;
+}
+interface Constraints {
+    /** Hard latency ceiling — compiler will down-rank slow models. Advisory. */
+    maxLatencyMs?: number;
+    /** Hard cost ceiling per call (USD). Advisory. */
+    maxCostUsd?: number;
+    /** 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';
+}
+/**
+ * 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, in caller-preference order. Compiler picks among these. */
+    models: string[];
+    /** 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.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.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';
+    };
+}
+/**
+ * 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>;
+}
+interface CallOptions {
+    /** Forwarded to compile(). */
+    policy?: CompilePolicy;
+    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;
+}
+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;
+}
+/**
+ * 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.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. Returned by compile() via CompileResult.outcomeId. */
+    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 when the POST landed (2xx). False when brain not configured or POST failed. */
+    ok: boolean;
+    /** 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 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 SectionRewrite as S, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type RecordOutcomeInput as e, type OracleScore as f, type CompileResult as g, type Adapter as h, type PerAxisMetrics as i, type Provider as j, type ChainEntry as k, type CallAttempt as l, CallError as m, type ChainWithGrounding as n, type Constraints as o, type MutationApplied as p, type NormalizedTokens as q, type OutcomeKind as r, type PerAxisMetricsByModel as s, type PromptSection as t, type SectionKind as u, type ToolDefinition as v };