@warmdrift/kgauto-compiler 2.0.0-alpha.27 → 2.0.0-alpha.29

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, R as RecordInput, e as RecordOutcomeInput, O as OutcomeResult, f as OracleScore, g as CompileResult, B as BestPracticeAdvisory, h as PerAxisMetrics, i as Provider, j as ChainEntry, G as Grounding } from './ir-B9zqlwjH.mjs';
-export { k as CallAttempt, l as CallError, m as ChainWithGrounding, n as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, o as MutationApplied, p as NormalizedTokens, q as OutcomeKind, r as PerAxisMetricsByModel, s as PromptSection, T as ToolCall, t as ToolDefinition } from './ir-B9zqlwjH.mjs';
+import { C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, S as SectionRewrite, R as RecordInput, e as RecordOutcomeInput, O as OutcomeResult, f as OracleScore, g as CompileResult, B as BestPracticeAdvisory, h as Adapter, i as PerAxisMetrics, j as Provider, k as ChainEntry, G as Grounding } from './ir-De2AQtlr.mjs';
+export { l as CallAttempt, m as CallError, n as ChainWithGrounding, o as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, p as MutationApplied, q as NormalizedTokens, r as OutcomeKind, s as PerAxisMetricsByModel, t as PromptSection, u as SectionKind, T as ToolCall, v as ToolDefinition } from './ir-De2AQtlr.mjs';
 import { ModelProfile } from './profiles.mjs';
 export { ALIASES, CacheStrategy, CliffRule, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, profilesByProvider, tryGetProfile } from './profiles.mjs';
 import { IntentArchetypeName } from './dialect.mjs';
@@ -94,16 +94,6 @@ declare function execute(request: CompiledRequest, opts?: ExecuteOptions): Promi
  */
 declare function call(ir: PromptIR, opts?: CallOptions): Promise<CallResult>;
 
-/**
- * Brain client — fire-and-forget telemetry to the central kgauto Supabase.
- *
- * The brain is the centralized learning store. Apps POST outcomes here;
- * mutations flow back through a separate pull (in v2.1).
- *
- * Design: never blocks the caller. Failures are silent (logged via optional
- * onError hook). Uses fetch() — works in Node 18+, Edge runtimes, and browsers.
- */
-
 /**
  * alpha.11 — opt-in nested config for brain-query mode (chains / archetype
  * perf / pricing / models registry). Enabled by default when endpoint is
@@ -205,6 +195,20 @@ interface OutcomePayload {
      * cliff lumps DeepSeek sequential perf with parallel without this).
      */
     tool_orchestration?: 'parallel' | 'sequential' | 'either' | null;
+    finish_reason?: string;
+    total_ms?: number;
+    tools_count?: number;
+    history_depth?: number;
+    system_prompt_chars?: number;
+    fell_over_from?: string;
+    fallback_reason?: 'rate_limit' | 'provider_auth_failed' | 'provider_error' | 'cliff' | 'cost_cap' | 'contract_violation';
+    /**
+     * Per-call SectionRewrite[] captured at compile time. Omitted (sent as
+     * undefined → stored NULL) when no rewrites fired. Powers cross-app
+     * learning aggregates ("rule X fired N times on (app, model, archetype),
+     * downstream outcome quality lifted by M points").
+     */
+    section_rewrites_applied?: SectionRewrite[] | null;
 }
 /**
  * alpha.20 Entry 4: record a quality outcome for a previously-compiled call.
@@ -342,6 +346,17 @@ type AdvisorContext = Pick<CompileResult, 'target' | 'provider' | 'tokensIn' | '
 interface RunAdvisorPhase2Context {
     fallbackChain: string[];
     profileResolver?: (id: string) => ModelProfile | undefined;
+    /**
+     * alpha.29 — translator rewrites that fired this compile. When a rewrite
+     * cleared the cliff (e.g. `tool_call_contract` → sequential-tool preamble
+     * + `parallelToolCalls: false`), the matching cliff advisor
+     * (`archetype-perf-floor-breach`) MUST suppress for the same call. Without
+     * suppression both fire — the advisory contradicts the rewrite ("cliff is
+     * unaddressed" vs "we just addressed it").
+     *
+     * Empty array / undefined → no suppression (alpha.28 behavior preserved).
+     */
+    sectionRewritesApplied?: SectionRewrite[];
 }
 /**
  * Run all phased rules and return collected advisories. Order is fixed so
@@ -358,6 +373,451 @@ interface RunAdvisorPhase2Context {
  */
 declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: ModelProfile, policy?: CompilePolicy, phase2?: RunAdvisorPhase2Context): BestPracticeAdvisory[];
 
+/**
+ * Translator primitive — alpha.29.
+ *
+ * Pure function. Walks `IR.sections`, matches each section's `kind` against
+ * the model + archetype + profile, and applies a model-aware rewrite when
+ * a rule fires. Returns the rewritten IR + the list of rewrites for
+ * `CompileResult.sectionRewritesApplied` and brain persistence.
+ *
+ * This is the s37 translator-framing eureka in code: kgauto graduates from
+ * "gate" (alpha.28's cliff advisor: "consumer must accept adapter") to
+ * "translator" (alpha.29: "consumer declared the section kind, kgauto
+ * applies the adapter at compile time without consumer-side branching").
+ *
+ * alpha.29 ships ONE rule:
+ *
+ *   tool_call_contract + profile.archetypePerf[archetype] < ARCHETYPE_FLOOR_DEFAULT
+ *     → prepend sequential-tool-pattern guidance
+ *     → emit wireOverrides: { parallelToolCalls: false }
+ *
+ * alpha.30+ will extend the rule table to `narration_contract`, `role_intro`,
+ * etc. Each new rule lands here as an explicit branch.
+ *
+ * **Interaction with the cliff advisor (alpha.28):** when this translator
+ * fires for a `tool_call_contract` section, the advisor's
+ * `archetype-perf-floor-breach` rule MUST suppress for the same call — the
+ * cliff was structurally cleared by the rewrite, not unaddressed. The
+ * suppression check lives in `advisor.ts` and consults the
+ * `CompileResult.sectionRewritesApplied` list.
+ *
+ * Design contract:
+ *   command-center/advisory/kgauto/2026-05-21_alpha-29-translator-and-advisories-api.md
+ */
+
+/**
+ * Re-export of `ARCHETYPE_FLOOR_DEFAULT` as the canonical "translator fires
+ * below this score" threshold. Same constant as the cliff advisor — the
+ * single threshold is shared (alpha.28's "below this, advisor warns"; alpha.29's
+ * "below this, translator AUTO-APPLIES the adapter").
+ */
+declare const TRANSLATOR_FLOOR = 6;
+/**
+ * Stable identifier of the alpha.29 sequential-tool rule. Surfaces on
+ * `SectionRewrite.rule` and in brain aggregates. Future rules extend this
+ * list; the brain learns per-rule effectiveness over time.
+ */
+declare const RULE_SEQUENTIAL_TOOL_CLIFF = "sequential-tool-cliff-below-floor";
+interface ApplySectionRewritesArgs {
+    ir: PromptIR;
+    profile: ModelProfile;
+    archetype: IntentArchetypeName;
+}
+interface ApplySectionRewritesResult {
+    /**
+     * IR with section.text fields possibly rewritten. When no rewrites fired,
+     * this is identical to the input IR (referentially distinct array but
+     * same section payloads).
+     */
+    rewrittenIR: PromptIR;
+    /**
+     * One entry per section the translator rewrote. Empty array when no
+     * rules fired. Order matches the corresponding section in
+     * `rewrittenIR.sections`.
+     */
+    rewrites: SectionRewrite[];
+}
+/**
+ * Pure function. Apply model-aware section rewrites to the IR at compile time.
+ *
+ * Discipline:
+ *   - Never mutates the input IR; returns a new IR with new sections array.
+ *   - Sections without a `kind` (or `kind === 'arbitrary'`) pass through
+ *     unchanged.
+ *   - Empty `sections` array → returns `{ rewrittenIR: ir, rewrites: [] }`.
+ *   - Missing `profile.archetypePerf` → no rewrite (defensive — treat the
+ *     model as un-classified rather than below-floor).
+ *   - Sections of the same `kind` are processed in array order; the rule
+ *     fires once per matching section (today every tool_call_contract
+ *     section gets the same prepend — multiple sections of the same kind
+ *     ARE supported but is an unusual consumer shape).
+ *
+ * @example
+ * ```ts
+ * import { applySectionRewrites } from '@warmdrift/kgauto-compiler';
+ * import { getProfile } from '@warmdrift/kgauto-compiler';
+ *
+ * const { rewrittenIR, rewrites } = applySectionRewrites({
+ *   ir,
+ *   profile: getProfile('deepseek-v4-pro'),
+ *   archetype: 'hunt',
+ * });
+ * if (rewrites.length > 0) console.log('translator fired:', rewrites);
+ * ```
+ */
+declare function applySectionRewrites(args: ApplySectionRewritesArgs): ApplySectionRewritesResult;
+
+/**
+ * advisories-api — structured advisories API (alpha.29 Workstream B).
+ *
+ * Closes the L-117 family bottleneck: kgauto's `result.advisories[]` (the
+ * compile-time warnings about caching-off, tool-bloat, archetype-perf-floor
+ * breaches, etc.) used to disappear after the consumer read the compile
+ * result. The s34 caching-off advisory pattern is the canonical failure: an
+ * advisory fired 100+ times in 24h on `generate::sonnet` at 99.4% empty
+ * rate, and nobody knew because there was no structured channel to surface
+ * "what's open right now?"
+ *
+ * Migration 020 ships the substrate: `compile_outcome_advisories` gains
+ * lifecycle columns (`resolved_at`, `resolution_source`, `resolution_note`)
+ * and the `actionable_advisories_v` view rolls per-firing rows into
+ * per-(app_id, code) tuples with deterministic stable ids + server-side
+ * auto-resolution.
+ *
+ * Public surface:
+ *   getActionableAdvisories({ appId, severity?, status?, brainEndpoint, brainJwt, brainAnonKey, fetch? })
+ *     → Promise<ActionableAdvisory[]>
+ *
+ *   markAdvisoryResolved({ id, resolutionNote?, brainEndpoint, brainJwt, brainAnonKey, fetch? })
+ *     → Promise<{ ok: true } | { ok: false; reason: string }>
+ *
+ * Both functions are pure I/O — no module-level state. The fetch wiring
+ * mirrors `createProxyHandler` in `glassbox-routes/proxy.ts`: scoped JWT in
+ * `Authorization: Bearer`, `apikey` header carries the anon key.
+ *
+ * The auto-resolution rule is enforced server-side in `actionable_advisories_v`:
+ *   • Latest firing > 14 days ago             → status='resolved' (auto-pruned)
+ *   • All firings have resolved_at set        → status='resolved' (consumer-marked)
+ *   • Otherwise                               → status='open'
+ *
+ * `markAdvisoryResolved` is the consumer override: "I fixed it; the next
+ * firing will reopen the rule, but until then it stays resolved."
+ */
+
+/**
+ * Severity of an advisory. Maps to the `level` column on
+ * `compile_outcome_advisories` (info | warn | critical).
+ */
+type AdvisorySeverity = 'info' | 'warn' | 'critical';
+/**
+ * Status of an advisory rollup.
+ *
+ * - `open` — at least one unresolved firing in the last 14 days
+ * - `resolved` — either auto-pruned (no firings >14d) or consumer-marked
+ * - `snoozed` — reserved for alpha.30+ (snooze-until-date); type-accepted
+ *   today but the view will never emit this value
+ */
+type AdvisoryStatus = 'open' | 'snoozed' | 'resolved';
+/**
+ * Source of resolution when status='resolved'.
+ *
+ * - `auto` — server-side rule auto-pruned (>14d since last firing)
+ * - `consumer-marked` — consumer called `markAdvisoryResolved`
+ * - `declined` — reserved (alpha.30+: consumer marked the suggestion
+ *   inapplicable; the advisor will still fire but UIs can hide it)
+ */
+type AdvisoryResolutionSource = 'auto' | 'consumer-marked' | 'declined';
+/**
+ * Suggested-fix metadata. `null` when the advisor has no actionable fix
+ * (info-level rules can be observational). When set, the consumer's
+ * Admin UI can render a one-click apply (alpha.30+) or surface the
+ * before/after diff inline.
+ */
+interface AdvisorySuggestedFix {
+    type: 'config-change' | 'one-liner' | 'env-var' | 'manual';
+    /** File:line hint if kgauto can infer (reserved — alpha.30+). */
+    siteHint?: string;
+    before?: string;
+    after?: string;
+    docsLink?: string;
+}
+/**
+ * Per-(app_id, code) advisory rollup. The `id` is stable across polls
+ * until the rule auto-resolves and re-opens (a new firing after the 14d
+ * boundary advances `opened_at` → new id). Treat id-changes as
+ * intentional "fresh re-open" signals.
+ *
+ * Wire-shape from `actionable_advisories_v`. The transformer maps the
+ * view's snake_case columns to camelCase. See `feedback_typed_boundary_transformers.md`
+ * (L-118) for the rationale.
+ */
+interface ActionableAdvisory {
+    id: string;
+    rule: string;
+    severity: AdvisorySeverity;
+    openedAt: string;
+    lastObservedAt: string;
+    observationCount: number;
+    appliesTo: {
+        archetype?: IntentArchetypeName;
+        model?: string;
+        callSiteHint?: string;
+    };
+    message: string;
+    suggestedFix: AdvisorySuggestedFix | null;
+    /** Reserved — always `false` in alpha.29. alpha.30+ ships actual auto-apply. */
+    autoApplicable: boolean;
+    status: AdvisoryStatus;
+    resolvedAt?: string;
+    resolutionSource?: AdvisoryResolutionSource;
+    resolutionNote?: string;
+}
+/**
+ * Filter + transport for `getActionableAdvisories`. The brain JWT must
+ * carry an `app_id` claim matching `opts.appId` — RLS enforces tenant
+ * isolation on the underlying table, so a mismatch silently returns [].
+ */
+interface GetActionableAdvisoriesOptions {
+    appId: string;
+    /** Severity filter; if omitted, all severities are returned. */
+    severity?: AdvisorySeverity;
+    /** Status filter; defaults to 'open'. Pass 'all' for the full set. */
+    status?: 'open' | 'snoozed' | 'resolved' | 'all';
+    brainEndpoint: string;
+    brainJwt: string;
+    brainAnonKey: string;
+    fetch?: typeof fetch;
+}
+interface MarkAdvisoryResolvedOptions {
+    /** Stable id from a prior `getActionableAdvisories` call. */
+    id: string;
+    resolutionNote?: string;
+    brainEndpoint: string;
+    brainJwt: string;
+    brainAnonKey: string;
+    fetch?: typeof fetch;
+}
+/**
+ * Query the open advisory set for an app. Pulls from
+ * `actionable_advisories_v` (per-(app_id, code) rollup with stable ids
+ * + server-side auto-resolution).
+ *
+ * Default behavior (no status filter): returns only `status='open'`.
+ * Pass `status: 'all'` to see resolved + open together — useful for
+ * Admin UIs that show "recently fixed" badges.
+ *
+ * Fetch failures bubble out as thrown Errors. (`markAdvisoryResolved`
+ * uses the ok/reason envelope; this read path throws to match
+ * existing kgauto query semantics where the consumer can decide to
+ * retry or render an error state.)
+ */
+declare function getActionableAdvisories(opts: GetActionableAdvisoriesOptions): Promise<ActionableAdvisory[]>;
+/**
+ * Mark an advisory as consumer-resolved.
+ *
+ * Lookup strategy:
+ *   1. Query `actionable_advisories_v?id=eq.<id>` to find the (app_id, code)
+ *      tuple for this advisory.
+ *   2. PATCH the latest unresolved firing in `compile_outcome_advisories`
+ *      matching that tuple via the underlying outcome's app_id.
+ *
+ * The (app_id, code) lookup is necessary because `compile_outcome_advisories`
+ * has no `app_id` column — it inherits scope via the FK to compile_outcomes.
+ * PostgREST cannot PATCH with a JOIN predicate, so the markAdvisoryResolved
+ * path is a two-step round-trip. The cost is one extra GET per resolve call;
+ * acceptable because marks are low-frequency operator actions, not per-call
+ * hot path.
+ *
+ * Idempotent re-marks: if the advisory is already resolved (no unresolved
+ * firings match), the PATCH affects zero rows and the call still returns
+ * `ok: true`. The function returns `ok: false` only on transport / auth /
+ * lookup failures.
+ *
+ * Returns ok/reason envelope (vs throwing) because consumer Admin UIs
+ * typically want to render the failure inline rather than crash.
+ */
+declare function markAdvisoryResolved(opts: MarkAdvisoryResolvedOptions): Promise<{
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+}>;
+
+/**
+ * Archetype-cliff compatibility — alpha.28 (tt-intel-Cairn ratified).
+ *
+ * One question, one answer: *given this model and this intent, can it work
+ * — and if not, what adapter (if any) would make it work?*
+ *
+ * Replaces the silent-archetype-cliff failure mode where a consumer picks a
+ * model that's structurally wrong for the intent and kgauto compiles cleanly
+ * without surfacing the gap. The triggering incident: tt-intel shipped
+ * `deepseek-v4-pro` as the hunt default per a local spec; the kgauto coord
+ * doc said L-040 — V4 is structurally wrong for hunt (sequential tools).
+ * `archetypePerf.hunt = 4` was already in the profile data. The compiler
+ * stayed silent. This API + the matching advisor rule surfaces it.
+ *
+ * Pure function. No network. No brain query. No side effects. ~1ms.
+ *
+ * Consultation doc:
+ *   command-center/advisory/kgauto/2026-05-21_archetype-cliff-advisor.md
+ *
+ * Refinements applied per tt-intel-Cairn ratification (2026-05-21):
+ *   R1: every variant carries `archetypePerf: number` (raw score) — and
+ *       `requires-adapter` adds `archetypePerfWithAdapter: number` so
+ *       consumer policy can be expressed as "accept adapter only when score
+ *       crosses some threshold WITH the adapter on."
+ *   R2: every variant carries a plain-English `reason: string`. No internal
+ *       jargon ("L-040", "archetypePerf=4") — the consumer chooses whether
+ *       to render it as UI hint or operator-tooling tooltip.
+ *   R3: `Adapter` is a CLOSED discriminated union, not `| string`. alpha.28
+ *       ships ONE variant (`toolOrchestration: 'sequential'`). Future
+ *       adapter parameters extend the union explicitly in named releases.
+ *       NO escape hatch — the whole point is catching "I added a new
+ *       adapter and forgot to update consumer policy" at compile time.
+ */
+
+/**
+ * Minimum `archetypePerf[archetype]` score to count as `compatible` under
+ * Option A (default policy). Below this, a documented adapter is needed
+ * to lift the model above the floor; if no adapter exists, the model is
+ * rejected.
+ *
+ * Matches `QUALITY_FLOOR_FOR_RECOMMENDATION` in `advisor.ts` — kgauto's
+ * library-wide convention for "below this score, swap recommendations stop."
+ */
+declare const ARCHETYPE_FLOOR_DEFAULT = 6;
+/**
+ * Absolute floor — below this, the cliff is too steep for ANY adapter to
+ * lift cleanly. Reserved under Option A (unused today; every below-floor
+ * case is gated by adapter availability). Would gate `reject` vs
+ * `requires-adapter` under a future Option B per consultation doc Q1.
+ *
+ * Exported so consumer-side policy can read it (e.g. "accept adapter only
+ * when archetypePerf >= ABSOLUTE_FLOOR + 1"). Not used internally by
+ * `getModelCompatibility` today — the gate is "does an adapter exist for
+ * this cliff?", not score-based.
+ */
+declare const ABSOLUTE_FLOOR = 4;
+/**
+ * The intent the call is expressing — archetype + optional orchestration
+ * mode. Same shape as `ir.intent.archetype` + `ir.constraints.toolOrchestration`
+ * so a consumer can pass `{ archetype: ir.intent.archetype,
+ * toolOrchestration: ir.constraints?.toolOrchestration }` directly.
+ */
+interface CompatibilityIntent {
+    archetype: IntentArchetypeName;
+    toolOrchestration?: 'parallel' | 'sequential' | 'either';
+}
+/**
+ * `Adapter` — re-exported above. Canonical definition lives in `ir.ts` to
+ * avoid an import cycle (compatibility.ts → profiles.ts → ir.ts).
+ *
+ * **CLOSED discriminated union per R3.** Future adapter parameters extend
+ * the union explicitly in named alpha releases. No `| string` escape hatch
+ * — consumer policy code SHOULD write exhaustive `switch (adapter.parameter)`
+ * and rely on the compiler to flag "I added a new adapter parameter and
+ * forgot to update the consumer's policy."
+ *
+ * alpha.28 variants:
+ *   - `{ parameter: 'toolOrchestration'; value: 'sequential'; consequence }`
+ *     Lifts DeepSeek V4-family on `hunt` from sequential-tool cliff (L-040).
+ *     The "consequence" plain-English-ifies the trade-off:
+ *     "Tool calls run one at a time — slower but reliable."
+ *
+ * alpha.29+ likely additions (per tt-intel-Cairn priority list):
+ *   - `{ parameter: 'parallelToolCalls'; value: false; consequence }`
+ *   - `{ parameter: 'maxTools'; value: number; consequence }`
+ *   - `{ parameter: 'thinkingBudget'; value: 0; consequence }`
+ *
+ * Each new variant lands in its own named release with the union extended
+ * in `ir.ts`. Consumers see the change at compile time.
+ */
+/**
+ * The compatibility verdict for a (model, intent) pair. Discriminated union
+ * on `status` — `compatible` | `requires-adapter` | `reject`.
+ *
+ * **Every variant carries `archetypePerf` (R1) + `reason` (R2):**
+ * - `archetypePerf` — the raw 0-10 score for (model, archetype). Lets
+ *   consumers build their own thresholds without re-importing the profile
+ *   registry.
+ * - `reason` — plain-English, consumer-renderable. NOT internal jargon
+ *   like "L-040 cliff" or "archetypePerf=4". Examples in R2 ratification:
+ *   - compatible:        "Suited for hunt-style parallel discovery."
+ *   - requires-adapter:  "Best with sequential tool calls for hunt — slower but works."
+ *   - reject:            "Not suited for hunt — would underperform significantly."
+ *
+ * `requires-adapter` additionally carries:
+ * - `archetypePerfWithAdapter` — estimated post-adapter score. May be an
+ *   estimate (we don't measure post-adapter scores yet); kgauto's prior is
+ *   "adapter lifts to ARCHETYPE_FLOOR_DEFAULT + 1" unless brain-evidenced.
+ * - `adapter` — the closed-union variant describing the structural change.
+ *
+ * Backward-compat: an unknown model returns `reject` with a "model not
+ * registered" reason; callers never throw. Unknown archetype is impossible
+ * at the type level (`IntentArchetypeName` is a closed union).
+ */
+type ModelCompatibility = {
+    status: 'compatible';
+    reason: string;
+    archetypePerf: number;
+} | {
+    status: 'requires-adapter';
+    reason: string;
+    archetypePerf: number;
+    archetypePerfWithAdapter: number;
+    adapter: Adapter;
+} | {
+    status: 'reject';
+    reason: string;
+    archetypePerf: number;
+};
+/**
+ * Compatibility query — *does this model fit this intent, and if not,
+ * what would?*
+ *
+ * **Rules (Option A from consultation doc Q1):**
+ * 1. If model is unregistered → `reject` with "model not registered" reason.
+ * 2. If intent provides `toolOrchestration: 'sequential'` AND that adapter
+ *    silences the cliff (because the cliff IS the sequential-tool one)
+ *    → return `compatible` with raw score (NOT the post-adapter estimate
+ *    — caller already paid the adapter, score reflects reality).
+ * 3. If raw `archetypePerf[archetype] >= ARCHETYPE_FLOOR_DEFAULT`
+ *    → `compatible`.
+ * 4. If below floor BUT a documented adapter exists that lifts to floor
+ *    → `requires-adapter` with adapter + estimated post-adapter score.
+ * 5. If below floor AND no adapter exists → `reject`.
+ *
+ * **Pure function.** Deterministic for `(modelId, intent)`. No I/O.
+ *
+ * @example
+ * ```ts
+ * import { getModelCompatibility } from '@warmdrift/kgauto-compiler';
+ *
+ * const c = getModelCompatibility('deepseek-v4-pro', { archetype: 'hunt' });
+ * // → { status: 'requires-adapter',
+ * //     reason: 'Best with sequential tool calls for hunt — slower but works.',
+ * //     archetypePerf: 4,
+ * //     archetypePerfWithAdapter: 7,
+ * //     adapter: {
+ * //       parameter: 'toolOrchestration',
+ * //       value: 'sequential',
+ * //       consequence: 'Tool calls run one at a time...'
+ * //     } }
+ *
+ * // With the adapter already declared:
+ * const c2 = getModelCompatibility('deepseek-v4-pro', {
+ *   archetype: 'hunt',
+ *   toolOrchestration: 'sequential',
+ * });
+ * // → { status: 'compatible',
+ * //     reason: 'Suited for hunt with sequential tool calls.',
+ * //     archetypePerf: 4 }
+ * ```
+ */
+declare function getModelCompatibility(modelId: string, intent: CompatibilityIntent): ModelCompatibility;
+
 /**
  * alpha.22 — sync introspection: is brain-query mode active for a given
  * table? Used by the advisor (`model-stale-evidence` rule) to decide
@@ -943,4 +1403,4 @@ declare const loadAliasesFromBrain: () => Record<string, string>;
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ApiKeys, type AppOracle, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type ModelBrainRow, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, type SupportedProvider, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getPerAxisMetrics, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+export { ABSOLUTE_FLOOR, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type SupportedProvider, TRANSLATOR_FLOOR, applySectionRewrites, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };