@warmdrift/kgauto-compiler 2.0.0-alpha.10

package/dist/profiles-Bgri1pe7.d.ts

@@ -0,0 +1,728 @@
+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;
+}
+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;
+}
+/**
+ * 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;
+} | {
+    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;
+} | {
+    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;
+}
+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[];
+    /** 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;
+    };
+}
+/**
+ * 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)
+ */
+type FallbackReason = 'rate_limit' | 'provider_error' | 'cost_cap' | 'cliff' | 'contract_violation';
+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[];
+}
+/**
+ * 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;
+}
+
+/**
+ * Model profiles — executable knowledge about each provider/model.
+ *
+ * Unlike v1 which carried `known_failures` as prose strings, v2 makes them
+ * executable: cliffs trigger guards, lowering describes the wire format,
+ * recovery handlers describe what to do after specific failures.
+ *
+ * Each profile is the answer to "if I want to call THIS model with THIS
+ * shape of work, what does it need from me, and what should I do when it
+ * fails?"
+ */
+
+type StructuredOutputCapability = 'native' | 'grammar' | 'none';
+type SystemPromptMode = 'inline' | 'separate' | 'as_developer' | 'unsupported';
+type CacheStrategy = 'cache_control' | 'cachedContent' | 'unsupported';
+interface CliffRule {
+    /** What metric triggers this cliff. */
+    metric: 'input_tokens' | 'tool_count' | 'history_turns' | 'thinking_with_short_output';
+    /** Threshold — meaning depends on metric. */
+    threshold: number;
+    /** What action to take when triggered. */
+    action: 'downgrade_quality_warning' | 'drop_to_top_relevant' | 'force_thinking_budget_zero' | 'force_terse_output' | 'escalate_target' | 'strip_tools';
+    /**
+     * Optional: only fire this cliff when the IR's intent.archetype matches.
+     * Used for archetype-specific failure modes (e.g. Gemini Flash returns
+     * empty when summarize is offered tools).
+     */
+    whenIntent?: IntentArchetypeName;
+    /** Human-readable reason for digest reporting. */
+    reason: string;
+}
+interface RecoveryRule {
+    /** What signal triggers recovery. */
+    signal: 'empty_response_after_tool' | 'empty_response' | 'malformed_function_call' | 'rate_limit' | 'model_not_found' | 'context_overflow';
+    /** Action: retry with adjusted params, or escalate to next fallback. */
+    action: 'retry_with_params' | 'escalate' | 'log_only';
+    /** When action=retry_with_params, the param adjustments to apply. */
+    retryParams?: Record<string, unknown>;
+    /** Max retries with this rule. */
+    maxRetries?: number;
+    /** Human-readable reason for digest reporting. */
+    reason: string;
+}
+interface LoweringSpec {
+    /** Where the system prompt goes. */
+    system: {
+        mode: SystemPromptMode;
+        field?: string;
+    };
+    /** Cache strategy + parameters. */
+    cache: {
+        strategy: CacheStrategy;
+        /** Min tokens before caching is worth it (provider rules). */
+        minTokens?: number;
+        /** Discount factor on cached input (0.1 = 10% of normal price). */
+        discount?: number;
+        /** TTL hint in seconds. */
+        ttlSeconds?: number;
+    };
+    /** Tool format identifier — see lower.ts for supported formats. */
+    tools?: {
+        format: 'anthropic' | 'google' | 'openai' | 'deepseek';
+    };
+    /** Thinking config — present iff this model has a thinking knob. */
+    thinking?: {
+        /** Field path on the request. */
+        field: string;
+        /** Default value when caller hasn't specified. */
+        default?: number | 'auto' | 'off';
+    };
+}
+interface ModelProfile {
+    id: string;
+    provider: Provider;
+    status: 'current' | 'preview' | 'legacy';
+    maxContextTokens: number;
+    maxOutputTokens: number;
+    maxTools: number;
+    parallelToolCalls: boolean;
+    structuredOutput: StructuredOutputCapability;
+    systemPromptMode: SystemPromptMode;
+    streaming: boolean;
+    cliffs: CliffRule[];
+    costInputPer1m: number;
+    costOutputPer1m: number;
+    lowering: LoweringSpec;
+    recovery: RecoveryRule[];
+    strengths: string[];
+    weaknesses: string[];
+    notes?: string;
+    verifiedAgainstDocs?: string;
+    /**
+     * Hand-curated per-archetype performance score on a 0-10 scale.
+     *
+     *   10 = frontier on this archetype (e.g. Opus 4.7 on critique)
+     *    8 = strong second tier (Sonnet on plan, Pro on extract)
+     *    7 = competent (Haiku on classify, Flash on hunt)
+     *    5 = acceptable for tolerant archetypes (Flash-Lite on classify)
+     *    3 = degraded (Flash on critique, DeepSeek on hunt)
+     *
+     * Missing archetypes default to `5` (no data, neutral). Each non-default
+     * value should carry a one-line rationale in the profile's note or inline
+     * comment citing brain evidence, family prior, or "starter hypothesis —
+     * verify with telemetry."
+     *
+     * Source today: hand-curated from master plan §3.3 + §6.2 starter tables.
+     * Source tomorrow (alpha.10+): brain `archetype_model_evidence` view.
+     *
+     * Anti-hallucination guardrail (master plan §2.5): when the watcher's
+     * `--audit-fields` flag flags a profile stale (>90 days since
+     * verifiedAgainstDocs), the archetypePerf values get re-audited
+     * alongside capability fields. AI-trained intuition is NOT a valid
+     * source — only docs or brain evidence.
+     *
+     * alpha.9.
+     */
+    archetypePerf?: Partial<Record<IntentArchetypeName, number>>;
+}
+declare const ALIASES: Record<string, string>;
+declare function getProfile(id: string): ModelProfile;
+declare function tryGetProfile(id: string): ModelProfile | undefined;
+declare function allProfiles(): readonly ModelProfile[];
+declare function profilesByProvider(provider: Provider): readonly ModelProfile[];
+
+export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type HistoryCachePolicy as H, type IntentDeclaration as I, type LoweringSpec as L, type ModelProfile as M, type NormalizedResponse as N, type OracleScore as O, type ProviderOverrides as P, type RecordInput as R, type StructuredOutputCapability 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 Provider as f, ALIASES as g, type CacheStrategy as h, type CallAttempt as i, CallError as j, type CliffRule as k, type Constraints as l, type Message as m, type MutationApplied as n, type NormalizedTokens as o, type PromptSection as p, type RecoveryRule as q, type SystemPromptMode as r, type ToolDefinition as s, allProfiles as t, getProfile as u, profilesByProvider as v, tryGetProfile as w };