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

package/dist/index.js

@@ -36,7 +36,10 @@ __export(index_exports, {
   configureBrain: () => configureBrain,
   countTokens: () => countTokens,
   execute: () => execute,
+  getAllStarterChains: () => getAllStarterChains,
+  getDefaultFallbackChain: () => getDefaultFallbackChain,
   getProfile: () => getProfile,
+  getStarterChain: () => getStarterChain,
   hashShape: () => hashShape,
   isArchetype: () => isArchetype,
   learningKey: () => learningKey,
@@ -524,7 +527,11 @@ function lowerAnthropic(ir, profile, hints) {
       system: systemBlocks,
       messages,
       tools,
-      max_tokens: hints.forceTerseOutput ? 200 : Math.min(profile.maxOutputTokens, 4096)
+      // alpha.8: trust profile.maxOutputTokens. The historical Math.min(_, 4096)
+      // floor surprised every consumer once (PB-Cairn contract-gaps brief, Gap 3).
+      // Profile is the single source of truth; consumers wanting a tighter
+      // budget can pass providerOverrides.anthropic.max_tokens explicitly.
+      max_tokens: hints.forceTerseOutput ? 200 : profile.maxOutputTokens
     },
     diagnostics: {
       cacheableTokens,
@@ -855,7 +862,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",
@@ -887,7 +911,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",
@@ -911,7 +948,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",
@@ -941,7 +994,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 ──
   {
@@ -1019,7 +1088,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",
@@ -1055,7 +1248,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",
@@ -1093,7 +1300,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
@@ -1133,7 +1356,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",
@@ -1169,7 +1409,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 = {
@@ -1205,12 +1460,13 @@ function profilesByProvider(provider) {
 }
 
 // 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) {
@@ -1282,6 +1538,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;
@@ -1354,7 +1624,8 @@ function compile(ir, opts = {}) {
       tokensIn: inputTokens,
       diagnostics
     },
-    profile
+    profile,
+    opts.policy
   );
   return {
     handle,
@@ -1806,44 +2077,48 @@ async function call(ir, opts = {}) {
       fetchImpl: opts.fetchImpl,
       providerOverrides: opts.providerOverrides
     });
-    if (exec.ok) {
+    const validated = exec.ok ? validateStructuredContract(exec, ir) : exec;
+    if (validated.ok) {
       attempts.push({ model: targetModel, status: "success" });
       const latencyMs2 = Date.now() - start;
-      const responseWithStructured = withStructuredOutput(exec.response, ir);
       await record({
         handle: initial.handle,
-        tokensIn: responseWithStructured.tokens.input,
-        tokensOut: responseWithStructured.tokens.output,
+        tokensIn: validated.response.tokens.input,
+        tokensOut: validated.response.tokens.output,
         latencyMs: latencyMs2,
         success: true,
-        emptyResponse: responseWithStructured.tokens.output === 0,
-        toolsCalled: responseWithStructured.toolCalls.map((tc) => tc.name),
+        emptyResponse: validated.response.tokens.output === 0,
+        toolsCalled: validated.response.toolCalls.map((tc) => tc.name),
         actualModel: targetModel !== initial.target ? targetModel : void 0,
         mutationsApplied: targetModel !== initial.target ? activeCompile.mutationsApplied.map((m) => m.id) : void 0,
         promptPreview: extractPromptPreview(ir),
-        responsePreview: responseWithStructured.text.slice(0, 200),
-        cacheReadInputTokens: responseWithStructured.tokens.cached,
-        cacheCreationInputTokens: responseWithStructured.tokens.cacheCreated
+        responsePreview: validated.response.text.slice(0, 200),
+        cacheReadInputTokens: validated.response.tokens.cached,
+        cacheCreationInputTokens: validated.response.tokens.cacheCreated
       });
+      const fellOver = targetModel !== initial.target;
       return {
         handle: initial.handle,
         actualModel: targetModel,
         requestedModel: initial.target,
         provider: activeCompile.provider,
-        response: responseWithStructured,
+        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({
       model: targetModel,
-      status: exec.errorType,
-      errorCode: exec.errorCode,
-      message: exec.message
+      status: validated.errorType,
+      errorCode: validated.errorCode,
+      message: validated.message
     });
-    lastErr = exec;
-    if (exec.errorType === "terminal" || opts.noFallback) {
+    lastErr = validated;
+    if (validated.errorType === "terminal" || opts.noFallback) {
       break;
     }
   }
@@ -1880,20 +2155,49 @@ function extractPromptPreview(ir) {
   if (lastHist) return lastHist.slice(0, 200);
   return void 0;
 }
-function withStructuredOutput(response, ir) {
-  if (!ir.constraints?.structuredOutput) return response;
-  if (!response.text) return response;
+function validateStructuredContract(exec, ir) {
+  if (!ir.constraints?.structuredOutput) {
+    return { ok: true, response: exec.response };
+  }
+  const finish = (exec.response.finishReason ?? "").toLowerCase();
+  if (finish === "max_tokens" || finish === "length") {
+    return {
+      ok: false,
+      status: exec.status,
+      errorType: "retryable",
+      errorCode: "max_tokens_on_structured_output",
+      message: `Provider returned finishReason="${exec.response.finishReason}" on a structured-output call \u2014 output truncated mid-token, JSON cannot be valid`,
+      raw: exec.response.raw
+    };
+  }
+  if (!exec.response.text) {
+    return { ok: true, response: exec.response };
+  }
   try {
-    const parsed = JSON.parse(response.text);
-    return { ...response, structuredOutput: parsed };
+    const parsed = JSON.parse(exec.response.text);
+    return { ok: true, response: { ...exec.response, structuredOutput: parsed } };
   } catch (err) {
     return {
-      ...response,
-      structuredOutput: null,
-      parseError: err instanceof Error ? err.message : String(err)
+      ok: false,
+      status: exec.status,
+      errorType: "retryable",
+      errorCode: "structured_output_parse_failed",
+      message: err instanceof Error ? err.message : String(err),
+      raw: exec.response.raw
     };
   }
 }
+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"];
@@ -1983,6 +2287,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);
@@ -2007,7 +2431,10 @@ function compile2(ir, opts) {
   configureBrain,
   countTokens,
   execute,
+  getAllStarterChains,
+  getDefaultFallbackChain,
   getProfile,
+  getStarterChain,
   hashShape,
   isArchetype,
   learningKey,