@warmdrift/kgauto-compiler 2.0.0-alpha.8 → 2.0.0-alpha.9

package/dist/{chunk-MBEI5UOM.mjs → chunk-3KVKELZN.mjs}

@@ -51,7 +51,24 @@ var PROFILES_RAW = [
     ],
     strengths: ["reasoning", "agentic_coding", "long_context", "reliable_tool_use", "structured_output"],
     weaknesses: ["cost", "latency"],
-    notes: "Frontier (2026-05). Step-change improvement over 4.6 in agentic coding. Adaptive thinking only \u2014 no extended-thinking toggle. 1M context, 128k max output."
+    notes: "Frontier (2026-05). Step-change improvement over 4.6 in agentic coding. Adaptive thinking only \u2014 no extended-thinking toggle. 1M context, 128k max output.",
+    // Frontier perf. Drops on archetypes where parallel-tool throughput
+    // (hunt) or low-budget cost-sensitivity (classify/summarize) matters
+    // more than reasoning depth.
+    archetypePerf: {
+      critique: 10,
+      plan: 10,
+      generate: 9,
+      ask: 9,
+      extract: 9,
+      transform: 9,
+      hunt: 8,
+      // strong but Flash dominates parallel tool throughput
+      summarize: 8,
+      // overkill for tolerant archetype; cost-out of frontier
+      classify: 8
+      // overkill; brain-validated cheaper models cover this
+    }
   },
   {
     id: "claude-opus-4-6",
@@ -83,7 +100,20 @@ var PROFILES_RAW = [
     ],
     strengths: ["reasoning", "long_context", "reliable_tool_use", "structured_output", "extended_thinking"],
     weaknesses: ["cost", "latency"],
-    notes: "Predecessor to 4.7. Still current in Anthropic legacy table. Same pricing as 4.7 \u2014 choose 4.7 unless you need extended-thinking budget control (4.7 is adaptive-only)."
+    notes: "Predecessor to 4.7. Still current in Anthropic legacy table. Same pricing as 4.7 \u2014 choose 4.7 unless you need extended-thinking budget control (4.7 is adaptive-only).",
+    // One notch below 4.7 across the board — extended-thinking edge does
+    // not flip any archetype ranking. Legacy: chains should prefer 4.7.
+    archetypePerf: {
+      critique: 9,
+      plan: 9,
+      generate: 9,
+      ask: 9,
+      extract: 9,
+      transform: 9,
+      hunt: 7,
+      summarize: 8,
+      classify: 8
+    }
   },
   {
     id: "claude-sonnet-4-6",
@@ -107,7 +137,23 @@ var PROFILES_RAW = [
     ],
     strengths: ["quality", "tool_use", "long_context", "cache_friendly", "extended_thinking"],
     weaknesses: [],
-    notes: "Workhorse. Best price/quality for most multi-turn agentic work. 1M context, 64k max output."
+    notes: "Workhorse. Best price/quality for most multi-turn agentic work. 1M context, 64k max output.",
+    // Master plan §6.2 anchor. Tier 0 for plan/generate/ask/extract/transform
+    // in starter chains; tier 1 cross-provider for hunt/summarize/classify.
+    archetypePerf: {
+      ask: 9,
+      generate: 9,
+      plan: 9,
+      critique: 9,
+      extract: 9,
+      transform: 9,
+      hunt: 7,
+      // strong but Flash beats on parallel tool throughput
+      summarize: 8,
+      // overkill for tolerant archetype
+      classify: 8
+      // overkill
+    }
   },
   {
     id: "claude-haiku-4-5",
@@ -137,7 +183,23 @@ var PROFILES_RAW = [
     ],
     strengths: ["speed", "cost", "classification", "cache_friendly", "extended_thinking"],
     weaknesses: ["complex_reasoning", "large_tool_sets"],
-    notes: "Cheapest Anthropic. Great for classify, summarize, ask shapes. 200k context, 64k max output. API alias `claude-haiku-4-5` resolves to dated snapshot `claude-haiku-4-5-20251001`."
+    notes: "Cheapest Anthropic. Great for classify, summarize, ask shapes. 200k context, 64k max output. API alias `claude-haiku-4-5` resolves to dated snapshot `claude-haiku-4-5-20251001`.",
+    // Tier 1 cross-provider anchor for short-output chains (classify/
+    // summarize/extract/transform). Falls off on plan/critique where
+    // reasoning depth matters; competes with Pro on cost+latency.
+    archetypePerf: {
+      classify: 8,
+      summarize: 8,
+      ask: 7,
+      transform: 7,
+      extract: 7,
+      hunt: 6,
+      // tool reliability drops at 16 — cliff guard fires
+      generate: 6,
+      plan: 5,
+      critique: 4
+      // reasoning depth gap vs Sonnet/Opus
+    }
   },
   // ── Google ──
   {
@@ -215,7 +277,131 @@ var PROFILES_RAW = [
     ],
     strengths: ["speed", "volume", "classification", "1m_context", "cost"],
     weaknesses: ["complex_schemas", "large_tool_sets", "high_context_quality"],
-    notes: "Fast and cheap with 1M context. Quality cliffs at 8K context and 20 tools \u2014 guard with cliffs."
+    notes: "Fast and cheap with 1M context. Quality cliffs at 8K context and 20 tools \u2014 guard with cliffs.",
+    // Master plan §6.2 anchor. Tier 0 for hunt (parallel tool throughput
+    // 15-75 calls/step beats Sonnet — L-040), summarize, classify.
+    archetypePerf: {
+      hunt: 9,
+      // L-040: parallel tool throughput 15-75/step
+      classify: 7,
+      // brain-validated, 218 rows
+      summarize: 7,
+      // brain-validated; cliff strips tools when present
+      transform: 7,
+      ask: 7,
+      generate: 6,
+      plan: 5,
+      extract: 6,
+      // alpha.8 MAX_TOKENS history on structured output
+      critique: 4
+      // reasoning shallower than Sonnet/Opus
+    }
+  },
+  {
+    // ── Gemini 2.5 Flash-Lite ──
+    // Onboarded 2026-05-13 (s22) after the model-release watcher surfaced
+    // it as a UNREGISTERED + NEW candidate. Released by Google July 2025,
+    // stable. Positioned BELOW Flash on the cost/perf frontier:
+    //   input  $0.10/M (Flash $0.30/M)   — 3× cheaper
+    //   output $0.40/M (Flash $2.50/M)   — 6× cheaper
+    //   cache  $0.01/M                    — 1/10 of input (vs Flash 0.25 discount)
+    // Cliffs are HYPOTHESIZED from Flash's known failure modes — Flash-Lite
+    // is a smaller sibling, so we inherit Flash's cliffs at equal-or-tighter
+    // thresholds. The brain will validate/relax these as evidence accumulates
+    // per (archetype, model) tuple. Currently ZERO brain rows for this model.
+    id: "gemini-2.5-flash-lite",
+    verifiedAgainstDocs: "2026-05-13",
+    provider: "google",
+    status: "current",
+    maxContextTokens: 1048576,
+    maxOutputTokens: 65536,
+    maxTools: 128,
+    parallelToolCalls: true,
+    structuredOutput: "native",
+    systemPromptMode: "separate",
+    streaming: true,
+    cliffs: [
+      {
+        metric: "input_tokens",
+        threshold: 8e3,
+        action: "downgrade_quality_warning",
+        reason: "Inherited from Flash: quality degrades above ~8K. Smaller model \u2014 likely degrades faster. Re-tune from brain after n\u226520."
+      },
+      {
+        metric: "tool_count",
+        threshold: 10,
+        action: "drop_to_top_relevant",
+        reason: "Conservative: Flash drops at 20, Flash-Lite is smaller \u2014 assume tighter ceiling until brain proves otherwise."
+      },
+      {
+        metric: "thinking_with_short_output",
+        threshold: 1,
+        action: "force_thinking_budget_zero",
+        reason: "Thinking enabled per Google API (thinking: true). Same drain risk as Flash \u2014 thinking tokens consume maxOutputTokens."
+      },
+      {
+        // Strong prior: Flash hit 5/5 empty rate on summarize+tools (s11
+        // trust artifact, kgauto commit 3872832). Flash-Lite shares the
+        // same architectural family — almost certainly inherits this cliff.
+        // Ship the guard preemptively; brain telemetry confirms or relaxes.
+        metric: "tool_count",
+        threshold: 1,
+        whenIntent: "summarize",
+        action: "strip_tools",
+        reason: "Inherited from Flash s11 cliff: summarize+tools \u2192 empty response. Preemptive guard until brain evidence on Flash-Lite specifically."
+      }
+    ],
+    costInputPer1m: 0.1,
+    costOutputPer1m: 0.4,
+    lowering: {
+      ...GOOGLE_LOWERING_BASE,
+      // Cache discount 10× (vs Flash 4×) — Google's spec is $0.01/M cache vs
+      // $0.10/M input. Material for repeat-prompt workloads (classify shape).
+      cache: { ...GOOGLE_LOWERING_BASE.cache, discount: 0.1 },
+      thinking: { field: "generationConfig.thinkingConfig.thinkingBudget", default: "auto" }
+    },
+    recovery: [
+      {
+        signal: "empty_response_after_tool",
+        action: "retry_with_params",
+        retryParams: { "generationConfig.thinkingConfig.thinkingBudget": 0 },
+        maxRetries: 1,
+        reason: "Known on Flash family: empty after tool result \u2014 retry with thinking off."
+      },
+      {
+        signal: "empty_response",
+        action: "retry_with_params",
+        retryParams: { "generationConfig.thinkingConfig.thinkingBudget": 0 },
+        maxRetries: 1,
+        reason: "Empty response \u2014 try with thinking off."
+      },
+      {
+        signal: "malformed_function_call",
+        action: "escalate",
+        reason: "MALFORMED_FUNCTION_CALL maps to stop \u2014 escalate to next target."
+      }
+    ],
+    strengths: ["lowest_cost", "speed", "volume", "classification", "summarize", "1m_context", "cache_friendly"],
+    weaknesses: ["complex_reasoning", "large_tool_sets", "complex_schemas", "structured_output_unproven", "long_context_quality"],
+    notes: "Bottom-frontier anchor on cost: $0.10/$0.40 per 1M tokens, 1M context, 65K max output. Released July 2025 (stable). Positioned for classify / summarize / transform archetypes where quality bar is forgiving. Cliffs inherited from Flash at equal-or-tighter thresholds \u2014 re-tune per (archetype) once brain has n\u226520 rows. Alpha.8 contract layer handles MAX_TOKENS-on-structured-output via fallback chain, so structuredOutput=native is safe to declare even though Flash had alpha.8 history. Cache discount in spec: $0.01/M = 1/10 of input (richer than Flash 25%) \u2014 meaningful for repeat-prompt workloads.",
+    // Tier 3 emergency floor for summarize/classify chains. ZERO brain
+    // rows — all values are starter hypotheses anchored to "smaller
+    // sibling of Flash, at-or-below Flash perf on every archetype." The
+    // first 50 brain rows per archetype will validate or relax these.
+    archetypePerf: {
+      classify: 6,
+      // starter hypothesis — verify (Flash is 7, lite likely ≤)
+      summarize: 6,
+      // starter hypothesis — verify; cliff strips tools
+      transform: 6,
+      // starter hypothesis — verify
+      ask: 5,
+      hunt: 5,
+      generate: 4,
+      extract: 4,
+      plan: 3,
+      critique: 3
+    }
   },
   {
     id: "gemini-2.5-pro",
@@ -251,7 +437,21 @@ var PROFILES_RAW = [
       }
     ],
     strengths: ["reasoning", "1m_context", "structured_output", "tool_use"],
-    weaknesses: ["pricing_above_200k"]
+    weaknesses: ["pricing_above_200k"],
+    // Master plan §3.3 anchor: tier-2 cross-provider in almost every chain.
+    // Sits on the frontier at perf-9 — close to Sonnet but cheaper input.
+    archetypePerf: {
+      critique: 9,
+      plan: 9,
+      ask: 8,
+      generate: 8,
+      extract: 8,
+      transform: 8,
+      hunt: 8,
+      // tier 1 cross-provider for hunt chain
+      summarize: 7,
+      classify: 7
+    }
   },
   {
     id: "gemini-3.1-pro-preview",
@@ -289,7 +489,23 @@ var PROFILES_RAW = [
     ],
     strengths: ["reasoning", "1m_context", "agentic_coding", "structured_output", "tool_use"],
     weaknesses: ["cost", "preview_status", "pricing_above_200k"],
-    notes: "Frontier Gemini (preview, 2026-Q2). Step-change agentic coding per Google. Cache discount 10\xD7 (vs 4\xD7 for 2.5 Pro). Use status=preview to flag rollback path until GA."
+    notes: "Frontier Gemini (preview, 2026-Q2). Step-change agentic coding per Google. Cache discount 10\xD7 (vs 4\xD7 for 2.5 Pro). Use status=preview to flag rollback path until GA.",
+    // Frontier-Gemini preview — bumped one notch over 2.5 Pro on agentic
+    // coding / reasoning per Google's release notes. Preview status:
+    // chains should stay on 2.5 Pro until GA. Starter hypothesis.
+    archetypePerf: {
+      critique: 10,
+      // Google claims step-change on reasoning
+      plan: 10,
+      ask: 9,
+      generate: 9,
+      extract: 9,
+      transform: 8,
+      hunt: 9,
+      // step-change agentic per Google
+      summarize: 8,
+      classify: 7
+    }
   },
   // ── DeepSeek ──
   // 2026-05-08 audit (L-073): DeepSeek's `deepseek-chat` was silently aliased
@@ -329,7 +545,24 @@ var PROFILES_RAW = [
     ],
     strengths: ["cost", "1m_context", "json_output", "code", "reasoning"],
     weaknesses: ["parallel_tools", "large_tool_sets"],
-    notes: "Cheap workhorse. 1M context, 384k max output. Cache-hit input $0.0028/M (1/50\xD7 of miss). Aliased as `deepseek-chat` (non-thinking) and `deepseek-reasoner` (thinking) \u2014 see ALIASES."
+    notes: "Cheap workhorse. 1M context, 384k max output. Cache-hit input $0.0028/M (1/50\xD7 of miss). Aliased as `deepseek-chat` (non-thinking) and `deepseek-reasoner` (thinking) \u2014 see ALIASES.",
+    // Master plan §6.2 anchor. Brain-validated tier 1 cross-provider for
+    // classify (169 rows, 0% empty). Tier 0 for summarize-with-no-tools.
+    // Falls off on hunt (sequential tools — L-040) and reasoning depth.
+    archetypePerf: {
+      classify: 7,
+      // brain-validated, 169 rows
+      summarize: 7,
+      // archetype-tolerant, no brain evidence yet
+      ask: 6,
+      transform: 6,
+      generate: 5,
+      plan: 5,
+      extract: 5,
+      critique: 4,
+      hunt: 4
+      // sequential tool calls only — L-040
+    }
   },
   {
     id: "deepseek-v4-pro",
@@ -365,7 +598,22 @@ var PROFILES_RAW = [
     ],
     strengths: ["quality", "reasoning", "1m_context", "json_output", "code", "extended_thinking"],
     weaknesses: ["parallel_tools", "large_tool_sets"],
-    notes: "Pro tier. 1M context, 384k max output. Regular pricing $1.74/$3.48; 75% promo through 2026-05-31 ($0.435/$0.87). Default mode = thinking."
+    notes: "Pro tier. 1M context, 384k max output. Regular pricing $1.74/$3.48; 75% promo through 2026-05-31 ($0.435/$0.87). Default mode = thinking.",
+    // Master plan §3.3: tier 3 cross-provider for plan chain. Reasoning
+    // bumped one notch over V4-Flash; same parallel-tool ceiling.
+    archetypePerf: {
+      plan: 7,
+      // §3.3 tier 3 for plan
+      critique: 6,
+      ask: 7,
+      generate: 6,
+      classify: 7,
+      summarize: 7,
+      extract: 6,
+      transform: 6,
+      hunt: 4
+      // sequential tools — same as V4-Flash
+    }
   }
 ];
 var ALIASES = {

package/dist/index.d.mts

@@ -1,6 +1,7 @@
-import { M as ModelProfile, 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, O as OracleScore, e as CompileResult, B as BestPracticeAdvisory } from './profiles-Py8c7zjJ.mjs';
-export { f as ALIASES, g as CacheStrategy, h as CallAttempt, i as CallError, j as CliffRule, k as Constraints, H as HistoryCachePolicy, I as IntentDeclaration, L as LoweringSpec, l as Message, m as MutationApplied, n as NormalizedTokens, o as PromptSection, p as Provider, q as RecoveryRule, S as StructuredOutputCapability, r as SystemPromptMode, T as ToolCall, s as ToolDefinition, t as allProfiles, u as getProfile, v as profilesByProvider, w as tryGetProfile } from './profiles-Py8c7zjJ.mjs';
-export { ALL_ARCHETYPES, ContextBucket, DIALECT_VERSION, HistoryDepth, INTENT_ARCHETYPES, IntentArchetypeName, OutputMode, ShapeSignature, ToolCountBucket, bucketContext, bucketHistory, bucketToolCount, hashShape, isArchetype, learningKey } from './dialect.mjs';
+import { M as ModelProfile, 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, O as OracleScore, e as CompileResult, B as BestPracticeAdvisory } from './profiles-NUZOIzGr.mjs';
+export { f as ALIASES, g as CacheStrategy, h as CallAttempt, i as CallError, j as CliffRule, k as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, L as LoweringSpec, l as Message, m as MutationApplied, n as NormalizedTokens, o as PromptSection, p as Provider, q as RecoveryRule, S as StructuredOutputCapability, r as SystemPromptMode, T as ToolCall, s as ToolDefinition, t as allProfiles, u as getProfile, v as profilesByProvider, w as tryGetProfile } from './profiles-NUZOIzGr.mjs';
+import { IntentArchetypeName } from './dialect.mjs';
+export { ALL_ARCHETYPES, ContextBucket, DIALECT_VERSION, HistoryDepth, INTENT_ARCHETYPES, OutputMode, ShapeSignature, ToolCountBucket, bucketContext, bucketHistory, bucketToolCount, hashShape, isArchetype, learningKey } from './dialect.mjs';
 
 /**
  * compile() — the main orchestrator.
@@ -275,10 +276,91 @@ declare function countTokens(text: string): number;
 /** Subset of CompileResult fields the advisor needs. */
 type AdvisorContext = Pick<CompileResult, 'target' | 'provider' | 'tokensIn' | 'diagnostics'>;
 /**
- * Run all Phase 1 rules and return collected advisories. Order is fixed
- * (same as the rule list above) so output is stable across runs.
+ * Run all phased rules and return collected advisories. Order is fixed so
+ * output is stable across runs. The `policy` argument is alpha.9 — the
+ * `single-model-array` rule needs to know whether the consumer explicitly
+ * declared `posture: 'locked'` (in which case single-model is intentional
+ * and shouldn't warn).
  */
-declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: ModelProfile): BestPracticeAdvisory[];
+declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: ModelProfile, policy?: CompilePolicy): BestPracticeAdvisory[];
+
+/**
+ * getDefaultFallbackChain — the alpha.9 cascading ship.
+ *
+ * Returns a per-archetype fallback chain that walks the cost/performance
+ * Pareto frontier (master plan §1.3 + §3). Three customer postures:
+ *
+ *   locked    — caller passes [theOneModel]; never call this function
+ *   preferred — caller passes `primary`; chain returned is [primary, ...fallbacks]
+ *   open      — caller passes no `primary`; chain returned is [best, ...fallbacks]
+ *
+ * The chain at each step:
+ *   1. Costs strictly less than the previous (no expensive sideways moves)
+ *   2. Comes from a different provider than the previous step where possible
+ *      (correlated outages don't kill consecutive attempts)
+ *   3. Stays above the archetype's perf floor (skip models scored <baseline
+ *      for archetypes where degradation would be unacceptable)
+ *
+ * In alpha.9 the chain is **hand-curated** per archetype (§3.3 starter
+ * table). Brain-query mode lands in alpha.10. Policy.blockedModels filters
+ * the result; policy.maxCostPerCallUsd is NOT applied here because the
+ * function doesn't see the IR's token counts — that filtering happens at
+ * `passScoreTargets()` time inside compile().
+ *
+ * The function is **pure** — no brain query, no I/O, no randomness. Same
+ * inputs always produce the same chain.
+ */
+
+/**
+ * Posture passed into `getDefaultFallbackChain`. The chain function only
+ * sees `'open'` and `'preferred'` — callers in `'locked'` posture should
+ * pass `models: [theOneModel]` directly and skip this function entirely.
+ *
+ * Equivalent to `CompilePolicy.posture` minus `'locked'`. Kept distinct so
+ * the type system enforces "don't ask for a chain when you don't want one."
+ */
+type FallbackPosture = 'open' | 'preferred';
+interface GetDefaultFallbackChainOpts {
+    /** The archetype the call is performing. Drives chain shape. */
+    archetype: IntentArchetypeName;
+    /**
+     * The user-selected or caller-anchored primary model. When provided, it
+     * appears at position 0 of the returned chain and fallbacks follow.
+     * When omitted, the function picks the best-perf model for the archetype
+     * as position 0 (open posture).
+     */
+    primary?: string;
+    /**
+     * Informational. `'preferred'` and `'open'` produce the same chain shape
+     * given the same `primary`/no-primary input — posture is a tag the brain
+     * uses to distinguish "user-anchored" from "library-anchored" telemetry.
+     */
+    posture?: FallbackPosture;
+    /**
+     * Cap on chain length. Default 3. Min 1. Useful when the consumer wants
+     * to keep the worst-case latency low (each fallback adds a round-trip).
+     */
+    maxDepth?: number;
+    /**
+     * Consumer-side gating. `blockedModels` are filtered from the chain.
+     * `preferredModels` is informational (no boost applied at this layer —
+     * compile()'s `passScoreTargets` handles preference ranking).
+     * `maxCostPerCallUsd` is NOT applied here — needs IR-level token
+     * estimation. Use compile()'s policy plumbing instead.
+     */
+    policy?: CompilePolicy;
+}
+declare function getDefaultFallbackChain(opts: GetDefaultFallbackChainOpts): string[];
+/**
+ * Returns a shallow copy of the hand-curated starter chain for an archetype.
+ * Useful for tests + the `scripts/digest.mjs` operator readout.
+ */
+declare function getStarterChain(archetype: IntentArchetypeName): string[];
+/**
+ * Returns a shallow copy of all starter chains keyed by archetype.
+ * Useful for the `digest.mjs` readout and consumer audits.
+ */
+declare function getAllStarterChains(): Record<IntentArchetypeName, string[]>;
 
 /**
  * @warmdrift/kgauto v2 — prompt compiler + central learning brain.
@@ -326,4 +408,4 @@ declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: Model
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ApiKeys, type AppOracle, BestPracticeAdvisory, type BrainConfig, CallOptions, CallResult, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type LLMJudgeOptions, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, PromptIR, ProviderOverrides, RecordInput, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, record, resetTokenizer, runAdvisor, setTokenizer };
+export { ApiKeys, type AppOracle, BestPracticeAdvisory, type BrainConfig, CallOptions, CallResult, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetDefaultFallbackChainOpts, IntentArchetypeName, type LLMJudgeOptions, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, PromptIR, ProviderOverrides, RecordInput, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getAllStarterChains, getDefaultFallbackChain, getStarterChain, record, resetTokenizer, runAdvisor, setTokenizer };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import { M as ModelProfile, 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, O as OracleScore, e as CompileResult, B as BestPracticeAdvisory } from './profiles-B3eNQ2py.js';
-export { f as ALIASES, g as CacheStrategy, h as CallAttempt, i as CallError, j as CliffRule, k as Constraints, H as HistoryCachePolicy, I as IntentDeclaration, L as LoweringSpec, l as Message, m as MutationApplied, n as NormalizedTokens, o as PromptSection, p as Provider, q as RecoveryRule, S as StructuredOutputCapability, r as SystemPromptMode, T as ToolCall, s as ToolDefinition, t as allProfiles, u as getProfile, v as profilesByProvider, w as tryGetProfile } from './profiles-B3eNQ2py.js';
-export { ALL_ARCHETYPES, ContextBucket, DIALECT_VERSION, HistoryDepth, INTENT_ARCHETYPES, IntentArchetypeName, OutputMode, ShapeSignature, ToolCountBucket, bucketContext, bucketHistory, bucketToolCount, hashShape, isArchetype, learningKey } from './dialect.js';
+import { M as ModelProfile, 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, O as OracleScore, e as CompileResult, B as BestPracticeAdvisory } from './profiles-BYVOc1eW.js';
+export { f as ALIASES, g as CacheStrategy, h as CallAttempt, i as CallError, j as CliffRule, k as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, L as LoweringSpec, l as Message, m as MutationApplied, n as NormalizedTokens, o as PromptSection, p as Provider, q as RecoveryRule, S as StructuredOutputCapability, r as SystemPromptMode, T as ToolCall, s as ToolDefinition, t as allProfiles, u as getProfile, v as profilesByProvider, w as tryGetProfile } from './profiles-BYVOc1eW.js';
+import { IntentArchetypeName } from './dialect.js';
+export { ALL_ARCHETYPES, ContextBucket, DIALECT_VERSION, HistoryDepth, INTENT_ARCHETYPES, OutputMode, ShapeSignature, ToolCountBucket, bucketContext, bucketHistory, bucketToolCount, hashShape, isArchetype, learningKey } from './dialect.js';
 
 /**
  * compile() — the main orchestrator.
@@ -275,10 +276,91 @@ declare function countTokens(text: string): number;
 /** Subset of CompileResult fields the advisor needs. */
 type AdvisorContext = Pick<CompileResult, 'target' | 'provider' | 'tokensIn' | 'diagnostics'>;
 /**
- * Run all Phase 1 rules and return collected advisories. Order is fixed
- * (same as the rule list above) so output is stable across runs.
+ * Run all phased rules and return collected advisories. Order is fixed so
+ * output is stable across runs. The `policy` argument is alpha.9 — the
+ * `single-model-array` rule needs to know whether the consumer explicitly
+ * declared `posture: 'locked'` (in which case single-model is intentional
+ * and shouldn't warn).
  */
-declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: ModelProfile): BestPracticeAdvisory[];
+declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: ModelProfile, policy?: CompilePolicy): BestPracticeAdvisory[];
+
+/**
+ * getDefaultFallbackChain — the alpha.9 cascading ship.
+ *
+ * Returns a per-archetype fallback chain that walks the cost/performance
+ * Pareto frontier (master plan §1.3 + §3). Three customer postures:
+ *
+ *   locked    — caller passes [theOneModel]; never call this function
+ *   preferred — caller passes `primary`; chain returned is [primary, ...fallbacks]
+ *   open      — caller passes no `primary`; chain returned is [best, ...fallbacks]
+ *
+ * The chain at each step:
+ *   1. Costs strictly less than the previous (no expensive sideways moves)
+ *   2. Comes from a different provider than the previous step where possible
+ *      (correlated outages don't kill consecutive attempts)
+ *   3. Stays above the archetype's perf floor (skip models scored <baseline
+ *      for archetypes where degradation would be unacceptable)
+ *
+ * In alpha.9 the chain is **hand-curated** per archetype (§3.3 starter
+ * table). Brain-query mode lands in alpha.10. Policy.blockedModels filters
+ * the result; policy.maxCostPerCallUsd is NOT applied here because the
+ * function doesn't see the IR's token counts — that filtering happens at
+ * `passScoreTargets()` time inside compile().
+ *
+ * The function is **pure** — no brain query, no I/O, no randomness. Same
+ * inputs always produce the same chain.
+ */
+
+/**
+ * Posture passed into `getDefaultFallbackChain`. The chain function only
+ * sees `'open'` and `'preferred'` — callers in `'locked'` posture should
+ * pass `models: [theOneModel]` directly and skip this function entirely.
+ *
+ * Equivalent to `CompilePolicy.posture` minus `'locked'`. Kept distinct so
+ * the type system enforces "don't ask for a chain when you don't want one."
+ */
+type FallbackPosture = 'open' | 'preferred';
+interface GetDefaultFallbackChainOpts {
+    /** The archetype the call is performing. Drives chain shape. */
+    archetype: IntentArchetypeName;
+    /**
+     * The user-selected or caller-anchored primary model. When provided, it
+     * appears at position 0 of the returned chain and fallbacks follow.
+     * When omitted, the function picks the best-perf model for the archetype
+     * as position 0 (open posture).
+     */
+    primary?: string;
+    /**
+     * Informational. `'preferred'` and `'open'` produce the same chain shape
+     * given the same `primary`/no-primary input — posture is a tag the brain
+     * uses to distinguish "user-anchored" from "library-anchored" telemetry.
+     */
+    posture?: FallbackPosture;
+    /**
+     * Cap on chain length. Default 3. Min 1. Useful when the consumer wants
+     * to keep the worst-case latency low (each fallback adds a round-trip).
+     */
+    maxDepth?: number;
+    /**
+     * Consumer-side gating. `blockedModels` are filtered from the chain.
+     * `preferredModels` is informational (no boost applied at this layer —
+     * compile()'s `passScoreTargets` handles preference ranking).
+     * `maxCostPerCallUsd` is NOT applied here — needs IR-level token
+     * estimation. Use compile()'s policy plumbing instead.
+     */
+    policy?: CompilePolicy;
+}
+declare function getDefaultFallbackChain(opts: GetDefaultFallbackChainOpts): string[];
+/**
+ * Returns a shallow copy of the hand-curated starter chain for an archetype.
+ * Useful for tests + the `scripts/digest.mjs` operator readout.
+ */
+declare function getStarterChain(archetype: IntentArchetypeName): string[];
+/**
+ * Returns a shallow copy of all starter chains keyed by archetype.
+ * Useful for the `digest.mjs` readout and consumer audits.
+ */
+declare function getAllStarterChains(): Record<IntentArchetypeName, string[]>;
 
 /**
  * @warmdrift/kgauto v2 — prompt compiler + central learning brain.
@@ -326,4 +408,4 @@ declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: Model
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ApiKeys, type AppOracle, BestPracticeAdvisory, type BrainConfig, CallOptions, CallResult, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type LLMJudgeOptions, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, PromptIR, ProviderOverrides, RecordInput, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, record, resetTokenizer, runAdvisor, setTokenizer };
+export { ApiKeys, type AppOracle, BestPracticeAdvisory, type BrainConfig, CallOptions, CallResult, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetDefaultFallbackChainOpts, IntentArchetypeName, type LLMJudgeOptions, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, PromptIR, ProviderOverrides, RecordInput, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getAllStarterChains, getDefaultFallbackChain, getStarterChain, record, resetTokenizer, runAdvisor, setTokenizer };