@warmdrift/kgauto-compiler 2.0.0-alpha.26 → 2.0.0-alpha.28

package/dist/index.d.ts

@@ -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-B_XX2LAO.js';
-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-B_XX2LAO.js';
+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 Adapter, i as PerAxisMetrics, j as Provider, k as ChainEntry, G as Grounding } from './ir-5W0efxt9.js';
+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, T as ToolCall, u as ToolDefinition } from './ir-5W0efxt9.js';
 import { ModelProfile } from './profiles.js';
 export { ALIASES, CacheStrategy, CliffRule, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, profilesByProvider, tryGetProfile } from './profiles.js';
 import { IntentArchetypeName } from './dialect.js';
@@ -205,6 +205,13 @@ 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';
 }
 /**
  * alpha.20 Entry 4: record a quality outcome for a previously-compiled call.
@@ -358,6 +365,180 @@ interface RunAdvisorPhase2Context {
  */
 declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: ModelProfile, policy?: CompilePolicy, phase2?: RunAdvisorPhase2Context): BestPracticeAdvisory[];
 
+/**
+ * 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 +1124,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, Adapter, ApiKeys, type AppOracle, 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 GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, 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, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, type SupportedProvider, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };