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

package/dist/index.mjs

@@ -15,7 +15,7 @@ import {
   getProfile,
   profilesByProvider,
   tryGetProfile
-} from "./chunk-MBEI5UOM.mjs";
+} from "./chunk-3KVKELZN.mjs";
 
 // src/tokenizer.ts
 var tokenizerImpl = defaultCharBasedCounter;
@@ -691,12 +691,13 @@ function setNestedField(obj, path, value) {
 }
 
 // src/advisor.ts
-function runAdvisor(ir, result, profile) {
+function runAdvisor(ir, result, profile, policy) {
   const out = [];
   out.push(...detectCachingOff(ir, profile));
   out.push(...detectSingleChunkSystem(ir, profile));
   out.push(...detectToolBloat(ir, result));
   out.push(...detectHistoryUncached(ir, profile));
+  out.push(...detectSingleModelArray(ir, policy));
   return out;
 }
 function detectCachingOff(ir, profile) {
@@ -768,6 +769,20 @@ function detectHistoryUncached(ir, profile) {
     }
   ];
 }
+function detectSingleModelArray(ir, policy) {
+  if (ir.models.length !== 1) return [];
+  if (policy?.posture === "locked") return [];
+  const only = ir.models[0];
+  return [
+    {
+      level: "warn",
+      code: "single-model-array",
+      message: `\`ir.models\` has length 1 (only "${only}") and posture is not 'locked'. A single-model chain has no safety net \u2014 the first 429 / 5xx / cliff hits the user as a failure. Master plan \xA71.2 closes the reliability gap with a 2-step minimum.`,
+      suggestion: "Use `getDefaultFallbackChain({ archetype: ir.intent.archetype, primary: '" + only + "', posture: 'preferred' })` for a user-anchored chain, or `getDefaultFallbackChain({ archetype, posture: 'open' })` for library-picked. If single-model is intentional (compliance/brand promise), set `policy.posture = 'locked'` to silence this rule.",
+      docsUrl: "https://github.com/stue/command-center/blob/main/interfaces/kgauto.md#single-model-array"
+    }
+  ];
+}
 
 // src/compile.ts
 var counter = 0;
@@ -840,7 +855,8 @@ function compile(ir, opts = {}) {
       tokensIn: inputTokens,
       diagnostics
     },
-    profile
+    profile,
+    opts.policy
   );
   return {
     handle,
@@ -1311,6 +1327,7 @@ async function call(ir, opts = {}) {
         cacheReadInputTokens: validated.response.tokens.cached,
         cacheCreationInputTokens: validated.response.tokens.cacheCreated
       });
+      const fellOver = targetModel !== initial.target;
       return {
         handle: initial.handle,
         actualModel: targetModel,
@@ -1319,7 +1336,10 @@ async function call(ir, opts = {}) {
         response: validated.response,
         latencyMs: latencyMs2,
         mutationsApplied: activeCompile.mutationsApplied,
-        attempts
+        attempts,
+        servedBy: targetModel,
+        fellOverFrom: fellOver ? initial.target : void 0,
+        fallbackReason: fellOver ? normalizeFallbackReason(attempts) : void 0
       };
     }
     attempts.push({
@@ -1398,6 +1418,17 @@ function validateStructuredContract(exec, ir) {
     };
   }
 }
+function normalizeFallbackReason(attempts) {
+  const first = attempts.find((a) => a.status !== "success");
+  if (!first) return void 0;
+  const code = first.errorCode ?? "";
+  if (code === "rate_limit_429" || code === "rate_limit") return "rate_limit";
+  if (code === "max_tokens_on_structured_output" || code === "structured_output_parse_failed") {
+    return "cliff";
+  }
+  if (code === "cost_cap_exceeded") return "cost_cap";
+  return "provider_error";
+}
 
 // src/oracle.ts
 var DEFAULT_DIMENSIONS = ["correctness", "completeness", "conciseness", "format"];
@@ -1487,6 +1518,126 @@ function clamp(n) {
   return Math.max(0, Math.min(1, n));
 }
 
+// src/fallback.ts
+var STARTER_CHAINS = {
+  // Reasoning floor — never degrade. Walk UP on 429 to Opus → cross-provider.
+  critique: [
+    "claude-opus-4-7",
+    "claude-sonnet-4-6",
+    "gemini-2.5-pro"
+  ],
+  // Reasoning matters — Sonnet primary; walk UP to Opus on 429 (rare exception
+  // to "always cheaper"); cross-provider via Pro; DeepSeek Pro as tier 3 floor.
+  plan: [
+    "claude-sonnet-4-6",
+    "claude-opus-4-7",
+    "gemini-2.5-pro",
+    "deepseek-v4-pro"
+  ],
+  // Quality + cost match. Walk Sonnet → Haiku same-provider, Pro cross,
+  // Flash floor for the open-posture chain.
+  generate: [
+    "claude-sonnet-4-6",
+    "claude-haiku-4-5",
+    "gemini-2.5-pro",
+    "gemini-2.5-flash"
+  ],
+  ask: [
+    "claude-sonnet-4-6",
+    "claude-haiku-4-5",
+    "gemini-2.5-pro",
+    "gemini-2.5-flash"
+  ],
+  // Structured-output archetype — Flash skipped (alpha.8 MAX_TOKENS cliff),
+  // DeepSeek skipped (no brain evidence). Floor at Haiku.
+  extract: [
+    "claude-sonnet-4-6",
+    "claude-haiku-4-5",
+    "gemini-2.5-pro"
+  ],
+  // Forgiving archetype — Sonnet primary but Flash safely floors it.
+  transform: [
+    "claude-sonnet-4-6",
+    "claude-haiku-4-5",
+    "gemini-2.5-pro",
+    "gemini-2.5-flash"
+  ],
+  // Parallel-tool throughput champion (Flash, L-040). Tier 1 cross-provider
+  // Pro; tier 2 Sonnet (quality safety net for blocked-Flash case); tier 3
+  // Haiku (reduced tool budget — cliff at 16 fires).
+  hunt: [
+    "gemini-2.5-flash",
+    "gemini-2.5-pro",
+    "claude-sonnet-4-6",
+    "claude-haiku-4-5"
+  ],
+  // Cost-sensitive + tolerant. DeepSeek brain-evidence tier 1; Haiku tier 2
+  // for quality safety; Flash-Lite emergency floor (onboarded s22).
+  summarize: [
+    "gemini-2.5-flash",
+    "deepseek-v4-flash",
+    "claude-haiku-4-5",
+    "gemini-2.5-flash-lite"
+  ],
+  // Brain-validated DeepSeek tier 1 (169 rows, 0% empty); Haiku tier 2;
+  // Flash-Lite floor for repeat-prompt workloads (cache-discount 10×).
+  classify: [
+    "gemini-2.5-flash",
+    "deepseek-v4-flash",
+    "claude-haiku-4-5",
+    "gemini-2.5-flash-lite"
+  ]
+};
+function getDefaultFallbackChain(opts) {
+  const { archetype, primary, maxDepth = 3, policy } = opts;
+  if (maxDepth < 1) {
+    throw new Error(
+      `getDefaultFallbackChain: maxDepth must be >= 1, got ${maxDepth}`
+    );
+  }
+  const starter = STARTER_CHAINS[archetype];
+  if (!starter) {
+    throw new Error(
+      `getDefaultFallbackChain: unknown archetype "${archetype}". Known: ${Object.keys(STARTER_CHAINS).join(", ")}`
+    );
+  }
+  let chain;
+  if (primary) {
+    chain = [primary, ...starter.filter((id) => id !== primary)];
+  } else {
+    chain = [...starter];
+  }
+  if (policy?.blockedModels && policy.blockedModels.length > 0) {
+    const blocked = new Set(policy.blockedModels);
+    chain = chain.filter((id) => !blocked.has(id));
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const deduped = [];
+  for (const id of chain) {
+    if (!seen.has(id)) {
+      seen.add(id);
+      deduped.push(id);
+    }
+  }
+  return deduped.slice(0, maxDepth);
+}
+function getStarterChain(archetype) {
+  const chain = STARTER_CHAINS[archetype];
+  if (!chain) {
+    throw new Error(
+      `getStarterChain: unknown archetype "${archetype}"`
+    );
+  }
+  return [...chain];
+}
+function getAllStarterChains() {
+  const out = {};
+  for (const [archetype, chain] of Object.entries(STARTER_CHAINS)) {
+    out[archetype] = [...chain];
+  }
+  return out;
+}
+
 // src/index.ts
 function compile2(ir, opts) {
   const result = compile(ir, opts);
@@ -1510,7 +1661,10 @@ export {
   configureBrain,
   countTokens,
   execute,
+  getAllStarterChains,
+  getDefaultFallbackChain,
   getProfile,
+  getStarterChain,
   hashShape,
   isArchetype,
   learningKey,

package/dist/{profiles-B3eNQ2py.d.ts → profiles-BYVOc1eW.d.ts}

@@ -159,6 +159,27 @@ interface CompilePolicy {
      * 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().
@@ -418,6 +439,18 @@ interface CallAttempt {
     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;
@@ -432,6 +465,28 @@ interface CallResult {
     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;
 }
 /**
  * Thrown when call() exhausts the fallback chain without success.
@@ -609,6 +664,32 @@ interface ModelProfile {
     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;
@@ -616,4 +697,4 @@ 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 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, ALIASES as f, type CacheStrategy as g, type CallAttempt as h, CallError as i, type CliffRule as j, type Constraints as k, type Message as l, type MutationApplied as m, type NormalizedTokens as n, type PromptSection as o, type Provider 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 };
+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, ALIASES as f, type CacheStrategy as g, type CallAttempt as h, CallError as i, type CliffRule as j, type Constraints as k, type Message as l, type MutationApplied as m, type NormalizedTokens as n, type PromptSection as o, type Provider 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 };

package/dist/{profiles-Py8c7zjJ.d.mts → profiles-NUZOIzGr.d.mts}

@@ -159,6 +159,27 @@ interface CompilePolicy {
      * 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().
@@ -418,6 +439,18 @@ interface CallAttempt {
     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;
@@ -432,6 +465,28 @@ interface CallResult {
     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;
 }
 /**
  * Thrown when call() exhausts the fallback chain without success.
@@ -609,6 +664,32 @@ interface ModelProfile {
     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;
@@ -616,4 +697,4 @@ 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 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, ALIASES as f, type CacheStrategy as g, type CallAttempt as h, CallError as i, type CliffRule as j, type Constraints as k, type Message as l, type MutationApplied as m, type NormalizedTokens as n, type PromptSection as o, type Provider 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 };
+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, ALIASES as f, type CacheStrategy as g, type CallAttempt as h, CallError as i, type CliffRule as j, type Constraints as k, type Message as l, type MutationApplied as m, type NormalizedTokens as n, type PromptSection as o, type Provider 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 };

package/dist/profiles.d.mts

@@ -1,2 +1,2 @@
-export { f as ALIASES, g as CacheStrategy, j as CliffRule, L as LoweringSpec, M as ModelProfile, q as RecoveryRule, S as StructuredOutputCapability, r as SystemPromptMode, t as allProfiles, u as getProfile, v as profilesByProvider, w as tryGetProfile } from './profiles-Py8c7zjJ.mjs';
+export { f as ALIASES, g as CacheStrategy, j as CliffRule, L as LoweringSpec, M as ModelProfile, q as RecoveryRule, S as StructuredOutputCapability, r as SystemPromptMode, t as allProfiles, u as getProfile, v as profilesByProvider, w as tryGetProfile } from './profiles-NUZOIzGr.mjs';
 import './dialect.mjs';

package/dist/profiles.d.ts

@@ -1,2 +1,2 @@
-export { f as ALIASES, g as CacheStrategy, j as CliffRule, L as LoweringSpec, M as ModelProfile, q as RecoveryRule, S as StructuredOutputCapability, r as SystemPromptMode, t as allProfiles, u as getProfile, v as profilesByProvider, w as tryGetProfile } from './profiles-B3eNQ2py.js';
+export { f as ALIASES, g as CacheStrategy, j as CliffRule, L as LoweringSpec, M as ModelProfile, q as RecoveryRule, S as StructuredOutputCapability, r as SystemPromptMode, t as allProfiles, u as getProfile, v as profilesByProvider, w as tryGetProfile } from './profiles-BYVOc1eW.js';
 import './dialect.js';