@warmdrift/kgauto-compiler 2.0.0-alpha.31 → 2.0.0-alpha.33

package/dist/{chunk-WXCFWUCN.mjs → chunk-XJZRDGHF.mjs}

@@ -328,7 +328,8 @@ var STARTER_CHAINS_GROUNDED = {
     { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Reasoning + cost balance \u2014 engineer pick" },
     { id: "claude-opus-4-7", grounding: "judgment", reason: 'Same-provider walk-UP on 429 (rare exception to "always cheaper")' },
     { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor" },
-    { id: "deepseek-v4-pro", grounding: "judgment", reason: "Tier 3 cost floor \u2014 no brain evidence yet" }
+    { id: "deepseek-v4-pro", grounding: "judgment", reason: "Tier 3 cost floor \u2014 no brain evidence yet" },
+    { id: "gpt-5.4", grounding: "judgment", reason: "alpha.33: third-provider tail (archetypePerf=7) \u2014 closes openai-in-default-fallback-chains" }
   ],
   // Quality + cost match.
   generate: [
@@ -359,7 +360,8 @@ var STARTER_CHAINS_GROUNDED = {
     { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Quality anchor \u2014 engineer pick" },
     { id: "claude-haiku-4-5", grounding: "judgment", reason: "Same-provider step-down" },
     { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor" },
-    { id: "gemini-2.5-flash", grounding: "judgment", reason: "Cost floor \u2014 forgiving archetype tolerates Flash" }
+    { id: "gemini-2.5-flash", grounding: "judgment", reason: "Cost floor \u2014 forgiving archetype tolerates Flash" },
+    { id: "gpt-5.4-mini", grounding: "judgment", reason: "alpha.33: third-provider tail (archetypePerf=7) \u2014 closes openai-in-default-fallback-chains" }
   ],
   // Parallel-tool throughput champion — Flash leads on the L-040 cliff
   // (capability-fact: Flash 15-75 parallel calls/step vs DeepSeek 7-8).
@@ -367,21 +369,24 @@ var STARTER_CHAINS_GROUNDED = {
     { id: "gemini-2.5-flash", grounding: "capability-fact", reason: "L-040 parallel-tool throughput champion (15-75 calls/step)" },
     { id: "gemini-2.5-pro", grounding: "capability-fact", reason: "Cross-provider tier 1 with strong parallel-tool support" },
     { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Quality safety net for blocked-Flash case" },
-    { id: "claude-haiku-4-5", grounding: "judgment", reason: "Reduced tool budget \u2014 cliff at 16 fires" }
+    { id: "claude-haiku-4-5", grounding: "judgment", reason: "Reduced tool budget \u2014 cliff at 16 fires" },
+    { id: "gpt-5.4-mini", grounding: "judgment", reason: "alpha.33: third-provider tail \u2014 OpenAI parallel-tool capable archetype" }
   ],
   // Cost-sensitive + tolerant. DeepSeek brain-evidence tier 1.
   summarize: [
     { id: "gemini-2.5-flash", grounding: "judgment", reason: "Cost-sensitive primary \u2014 engineer pick" },
     { id: "deepseek-v4-flash", grounding: "measured", reason: "Brain-validated tier 1 for cost-sensitive summarize workloads", n: 169 },
     { id: "claude-haiku-4-5", grounding: "judgment", reason: "Quality safety net" },
-    { id: "gemini-2.5-flash-lite", grounding: "judgment", reason: "Emergency floor \u2014 onboarded s22, no brain evidence yet" }
+    { id: "gemini-2.5-flash-lite", grounding: "judgment", reason: "Emergency floor \u2014 onboarded s22, no brain evidence yet" },
+    { id: "gpt-5.4-nano", grounding: "judgment", reason: "alpha.33: third-provider tail (archetypePerf=6) \u2014 cheapest OpenAI, matches summarize cost-band" }
   ],
   // Brain-validated DeepSeek tier 1 (169 rows, 0% empty rate).
   classify: [
     { id: "gemini-2.5-flash", grounding: "judgment", reason: "Cost-sensitive primary \u2014 engineer pick" },
     { id: "deepseek-v4-flash", grounding: "measured", reason: "Brain-validated tier 1 (169 rows, 0% empty rate)", n: 169 },
     { id: "claude-haiku-4-5", grounding: "judgment", reason: "Quality safety net" },
-    { id: "gemini-2.5-flash-lite", grounding: "judgment", reason: "Cache-discount 10\xD7 floor for repeat-prompt workloads" }
+    { id: "gemini-2.5-flash-lite", grounding: "judgment", reason: "Cache-discount 10\xD7 floor for repeat-prompt workloads" },
+    { id: "gpt-5.4-nano", grounding: "judgment", reason: "alpha.33: third-provider tail (archetypePerf=6) \u2014 cheapest OpenAI for classify" }
   ]
 };
 var STARTER_CHAINS = (() => {
@@ -436,7 +441,7 @@ function resolveStarterForMode(archetype, toolOrchestration, allChains) {
   return allChains[archetype];
 }
 function getDefaultFallbackChain(opts) {
-  const { archetype, primary, maxDepth = 3, policy, reachability, toolOrchestration } = opts;
+  const { archetype, primary, maxDepth = 4, policy, reachability, toolOrchestration } = opts;
   if (maxDepth < 1) {
     throw new Error(
       `getDefaultFallbackChain: maxDepth must be >= 1, got ${maxDepth}`

package/dist/glassbox/index.d.mts

@@ -1,6 +1,6 @@
-import { G as GlassboxEvent } from '../types-BjrIFPGe.mjs';
-export { A as AdvisoryFiredData, C as CompileDoneData, a as CompileStartData, E as ExecuteAttemptData, b as ExecuteSuccessData, F as FallbackWalkedData, c as GLASSBOX_STREAM_TTL_MS, d as GlassboxEventKind, e as GlassboxPubSub } from '../types-BjrIFPGe.mjs';
-import '../ir-De2AQtlr.mjs';
+import { G as GlassboxEvent } from '../types-2QzI0Ep1.mjs';
+export { A as AdvisoryFiredData, C as CompileDoneData, a as CompileStartData, E as ExecuteAttemptData, b as ExecuteSuccessData, F as FallbackWalkedData, c as GLASSBOX_STREAM_TTL_MS, d as GlassboxEventKind, e as GlassboxPubSub } from '../types-2QzI0Ep1.mjs';
+import '../ir-DubC20e3.mjs';
 import '../dialect.mjs';
 
 /**

package/dist/glassbox/index.d.ts

@@ -1,6 +1,6 @@
-import { G as GlassboxEvent } from '../types-D_JAhCv4.js';
-export { A as AdvisoryFiredData, C as CompileDoneData, a as CompileStartData, E as ExecuteAttemptData, b as ExecuteSuccessData, F as FallbackWalkedData, c as GLASSBOX_STREAM_TTL_MS, d as GlassboxEventKind, e as GlassboxPubSub } from '../types-D_JAhCv4.js';
-import '../ir-BIAT9gJk.js';
+import { G as GlassboxEvent } from '../types-DYcO82xh.js';
+export { A as AdvisoryFiredData, C as CompileDoneData, a as CompileStartData, E as ExecuteAttemptData, b as ExecuteSuccessData, F as FallbackWalkedData, c as GLASSBOX_STREAM_TTL_MS, d as GlassboxEventKind, e as GlassboxPubSub } from '../types-DYcO82xh.js';
+import '../ir-GnYPkpGo.js';
 import '../dialect.js';
 
 /**

package/dist/glassbox-routes/index.d.mts

@@ -1,5 +1,5 @@
-import { G as GlassboxEvent } from '../types-BjrIFPGe.mjs';
-import { h as Adapter, u as SectionKind } from '../ir-De2AQtlr.mjs';
+import { G as GlassboxEvent } from '../types-2QzI0Ep1.mjs';
+import { i as Adapter, v as SectionKind } from '../ir-DubC20e3.mjs';
 import '../dialect.mjs';
 
 /**
@@ -148,6 +148,99 @@ interface TraceDetail extends TraceSummary {
     health: TraceHealth;
 }
 
+/**
+ * proxy(req) — Glass-Box replay query handler.
+ *
+ * GET /api/glassbox/proxy?traceId=<id>   → single compile_outcomes row for trace
+ * GET /api/glassbox/proxy?limit=<N>      → N most-recent compile_outcomes rows
+ * GET /api/glassbox/proxy                → defaults to limit=20
+ *
+ * Brain reads go through PostgREST on Supabase. We always filter by
+ * `app_id=eq.<appId>` even though the scoped JWT's RLS policy already
+ * enforces tenant isolation — the explicit filter trims the network payload
+ * and makes the query intent obvious to anyone reading logs.
+ *
+ * Scrub: the optional `scrub` hook runs on each row before responding so
+ * sensitive payloads (rendered prompts, tool calls) can be redacted at the
+ * proxy boundary. Default is identity (no-op).
+ */
+
+/**
+ * Typed boundary transformer: compile_outcomes row (snake_case, Postgres
+ * native) → TraceSummary (camelCase, TypeScript native + extension wire
+ * contract). Single canonical mapping site — every DB-shape ↔ wire-shape
+ * crossing routes through here so renderer-expected fields can't silently
+ * go missing. See `feedback_typed_boundary_transformers.md` for the rule.
+ */
+declare function rowToSummary(row: Record<string, unknown>): TraceSummary;
+/**
+ * Typed boundary transformer (L-118): compile_outcomes row → TraceDetail.
+ * Single canonical mapping site for the detail-view wire contract. Pre-018
+ * brain rows return NULL for the new columns; this transformer applies
+ * type-safe defaults (0 for token columns, undefined for optional strings)
+ * so the renderer never crashes on missing fields.
+ *
+ * alpha.28 extends the field set per the renderer design contract — every
+ * extended field has a default. The `counterfactuals` + `projectedDailyCost`
+ * fields are populated by the proxy AFTER this transformer runs (they need
+ * profile lookup / brain query / async I/O).
+ */
+declare function rowToDetail(row: Record<string, unknown>): TraceDetail;
+
+/**
+ * computeCounterfactuals — for a served trace, compute up to 2 cheaper
+ * alternatives that ALSO meet the archetype quality floor.
+ *
+ * Pure function. Called at detail-view time by the proxy's `rowToDetail`
+ * path. The cost-equivalent answer to "what could this have run on without
+ * tanking quality?" lets the Glass-Box render `💰 Cheaper alternatives` so a
+ * founder sees the actual cost of the routing choice rather than just the
+ * served cost.
+ *
+ * Mechanism (per design contract Phase 0 spec):
+ *   1. Walk the archetype's full default fallback chain.
+ *   2. For each model in the chain (excluding the served model):
+ *      - Skip if archetypePerf[archetype] < ARCHETYPE_FLOOR_DEFAULT (6).
+ *        Matches the cliff-advisor work — never recommend a swap that
+ *        violates the quality floor. (Composition with Builder C is
+ *        intentional.)
+ *      - Skip if profile missing.
+ *      - Compute estimated cost at the OBSERVED token counts:
+ *          non_cached_in = tokensIn - cacheReadInputTokens
+ *          cost = (non_cached_in / 1e6) * profile.costInputPer1m
+ *               + (cacheable_in   / 1e6) * profile.costInputPer1m
+ *                                       * profile.lowering.cache.discount
+ *               + (tokensOut      / 1e6) * profile.costOutputPer1m
+ *      - Only include if estimatedCostUsd ≤ 0.9 × servedCostUsd
+ *        (≥10% cheaper — below that's noise of token-count estimation).
+ *   3. Sort cheapest first.
+ *   4. Cap to top 2.
+ *
+ * Edge cases:
+ *   - tokensIn === 0 → return [] (can't meaningfully estimate).
+ *   - servedCostUsd === 0 → return [] (no baseline to beat).
+ *   - Zero matching alternatives → return [] (renderer hides the card).
+ *   - Served model isn't in the chain (e.g. forceModel'd off-chain) → use
+ *     the chain for the archetype anyway.
+ */
+
+/** Only surface swaps that save at least 10% vs. served. */
+declare const COUNTERFACTUAL_MIN_SAVINGS_RATIO = 0.1;
+/** Cap on alternatives surfaced per trace. */
+declare const COUNTERFACTUAL_MAX_RESULTS = 2;
+interface ComputeCounterfactualsArgs {
+    servedModel: string;
+    servedCostUsd: number;
+    archetype: string;
+    tokensIn: number;
+    tokensOut: number;
+    /** Defaults to 0 when caller doesn't know. */
+    cacheReadInputTokens?: number;
+    /** Reserved for future per-mode chain selection. */
+    toolOrchestration?: 'parallel' | 'sequential' | 'either';
+}
+declare function computeCounterfactuals(args: ComputeCounterfactualsArgs): TraceCounterfactual[];
+
 /**
  * Public entry point for `@warmdrift/kgauto-compiler/glassbox-routes`.
  *
@@ -239,4 +332,4 @@ interface GlassboxRoutes {
 }
 declare function createGlassboxRoutes(config: GlassboxRoutesConfig): GlassboxRoutes;
 
-export { type GlassboxRoutes, type GlassboxRoutesConfig, type TraceDetail, type TraceSummary, createGlassboxRoutes };
+export { type AdvisoryRecord, COUNTERFACTUAL_MAX_RESULTS, COUNTERFACTUAL_MIN_SAVINGS_RATIO, type ComputeCounterfactualsArgs, type GlassboxRoutes, type GlassboxRoutesConfig, type TraceCounterfactual, type TraceDetail, type TraceHealth, type TraceSectionRewrite, type TraceSummary, computeCounterfactuals, createGlassboxRoutes, rowToDetail, rowToSummary };

package/dist/glassbox-routes/index.d.ts

@@ -1,5 +1,5 @@
-import { G as GlassboxEvent } from '../types-D_JAhCv4.js';
-import { h as Adapter, u as SectionKind } from '../ir-BIAT9gJk.js';
+import { G as GlassboxEvent } from '../types-DYcO82xh.js';
+import { i as Adapter, v as SectionKind } from '../ir-GnYPkpGo.js';
 import '../dialect.js';
 
 /**
@@ -148,6 +148,99 @@ interface TraceDetail extends TraceSummary {
     health: TraceHealth;
 }
 
+/**
+ * proxy(req) — Glass-Box replay query handler.
+ *
+ * GET /api/glassbox/proxy?traceId=<id>   → single compile_outcomes row for trace
+ * GET /api/glassbox/proxy?limit=<N>      → N most-recent compile_outcomes rows
+ * GET /api/glassbox/proxy                → defaults to limit=20
+ *
+ * Brain reads go through PostgREST on Supabase. We always filter by
+ * `app_id=eq.<appId>` even though the scoped JWT's RLS policy already
+ * enforces tenant isolation — the explicit filter trims the network payload
+ * and makes the query intent obvious to anyone reading logs.
+ *
+ * Scrub: the optional `scrub` hook runs on each row before responding so
+ * sensitive payloads (rendered prompts, tool calls) can be redacted at the
+ * proxy boundary. Default is identity (no-op).
+ */
+
+/**
+ * Typed boundary transformer: compile_outcomes row (snake_case, Postgres
+ * native) → TraceSummary (camelCase, TypeScript native + extension wire
+ * contract). Single canonical mapping site — every DB-shape ↔ wire-shape
+ * crossing routes through here so renderer-expected fields can't silently
+ * go missing. See `feedback_typed_boundary_transformers.md` for the rule.
+ */
+declare function rowToSummary(row: Record<string, unknown>): TraceSummary;
+/**
+ * Typed boundary transformer (L-118): compile_outcomes row → TraceDetail.
+ * Single canonical mapping site for the detail-view wire contract. Pre-018
+ * brain rows return NULL for the new columns; this transformer applies
+ * type-safe defaults (0 for token columns, undefined for optional strings)
+ * so the renderer never crashes on missing fields.
+ *
+ * alpha.28 extends the field set per the renderer design contract — every
+ * extended field has a default. The `counterfactuals` + `projectedDailyCost`
+ * fields are populated by the proxy AFTER this transformer runs (they need
+ * profile lookup / brain query / async I/O).
+ */
+declare function rowToDetail(row: Record<string, unknown>): TraceDetail;
+
+/**
+ * computeCounterfactuals — for a served trace, compute up to 2 cheaper
+ * alternatives that ALSO meet the archetype quality floor.
+ *
+ * Pure function. Called at detail-view time by the proxy's `rowToDetail`
+ * path. The cost-equivalent answer to "what could this have run on without
+ * tanking quality?" lets the Glass-Box render `💰 Cheaper alternatives` so a
+ * founder sees the actual cost of the routing choice rather than just the
+ * served cost.
+ *
+ * Mechanism (per design contract Phase 0 spec):
+ *   1. Walk the archetype's full default fallback chain.
+ *   2. For each model in the chain (excluding the served model):
+ *      - Skip if archetypePerf[archetype] < ARCHETYPE_FLOOR_DEFAULT (6).
+ *        Matches the cliff-advisor work — never recommend a swap that
+ *        violates the quality floor. (Composition with Builder C is
+ *        intentional.)
+ *      - Skip if profile missing.
+ *      - Compute estimated cost at the OBSERVED token counts:
+ *          non_cached_in = tokensIn - cacheReadInputTokens
+ *          cost = (non_cached_in / 1e6) * profile.costInputPer1m
+ *               + (cacheable_in   / 1e6) * profile.costInputPer1m
+ *                                       * profile.lowering.cache.discount
+ *               + (tokensOut      / 1e6) * profile.costOutputPer1m
+ *      - Only include if estimatedCostUsd ≤ 0.9 × servedCostUsd
+ *        (≥10% cheaper — below that's noise of token-count estimation).
+ *   3. Sort cheapest first.
+ *   4. Cap to top 2.
+ *
+ * Edge cases:
+ *   - tokensIn === 0 → return [] (can't meaningfully estimate).
+ *   - servedCostUsd === 0 → return [] (no baseline to beat).
+ *   - Zero matching alternatives → return [] (renderer hides the card).
+ *   - Served model isn't in the chain (e.g. forceModel'd off-chain) → use
+ *     the chain for the archetype anyway.
+ */
+
+/** Only surface swaps that save at least 10% vs. served. */
+declare const COUNTERFACTUAL_MIN_SAVINGS_RATIO = 0.1;
+/** Cap on alternatives surfaced per trace. */
+declare const COUNTERFACTUAL_MAX_RESULTS = 2;
+interface ComputeCounterfactualsArgs {
+    servedModel: string;
+    servedCostUsd: number;
+    archetype: string;
+    tokensIn: number;
+    tokensOut: number;
+    /** Defaults to 0 when caller doesn't know. */
+    cacheReadInputTokens?: number;
+    /** Reserved for future per-mode chain selection. */
+    toolOrchestration?: 'parallel' | 'sequential' | 'either';
+}
+declare function computeCounterfactuals(args: ComputeCounterfactualsArgs): TraceCounterfactual[];
+
 /**
  * Public entry point for `@warmdrift/kgauto-compiler/glassbox-routes`.
  *
@@ -239,4 +332,4 @@ interface GlassboxRoutes {
 }
 declare function createGlassboxRoutes(config: GlassboxRoutesConfig): GlassboxRoutes;
 
-export { type GlassboxRoutes, type GlassboxRoutesConfig, type TraceDetail, type TraceSummary, createGlassboxRoutes };
+export { type AdvisoryRecord, COUNTERFACTUAL_MAX_RESULTS, COUNTERFACTUAL_MIN_SAVINGS_RATIO, type ComputeCounterfactualsArgs, type GlassboxRoutes, type GlassboxRoutesConfig, type TraceCounterfactual, type TraceDetail, type TraceHealth, type TraceSectionRewrite, type TraceSummary, computeCounterfactuals, createGlassboxRoutes, rowToDetail, rowToSummary };

package/dist/glassbox-routes/index.js

@@ -20,7 +20,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/glassbox-routes/index.ts
 var glassbox_routes_exports = {};
 __export(glassbox_routes_exports, {
-  createGlassboxRoutes: () => createGlassboxRoutes
+  COUNTERFACTUAL_MAX_RESULTS: () => COUNTERFACTUAL_MAX_RESULTS,
+  COUNTERFACTUAL_MIN_SAVINGS_RATIO: () => COUNTERFACTUAL_MIN_SAVINGS_RATIO,
+  computeCounterfactuals: () => computeCounterfactuals,
+  createGlassboxRoutes: () => createGlassboxRoutes,
+  rowToDetail: () => rowToDetail,
+  rowToSummary: () => rowToSummary
 });
 module.exports = __toCommonJS(glassbox_routes_exports);
 
@@ -1409,7 +1414,8 @@ var STARTER_CHAINS_GROUNDED = {
     { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Reasoning + cost balance \u2014 engineer pick" },
     { id: "claude-opus-4-7", grounding: "judgment", reason: 'Same-provider walk-UP on 429 (rare exception to "always cheaper")' },
     { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor" },
-    { id: "deepseek-v4-pro", grounding: "judgment", reason: "Tier 3 cost floor \u2014 no brain evidence yet" }
+    { id: "deepseek-v4-pro", grounding: "judgment", reason: "Tier 3 cost floor \u2014 no brain evidence yet" },
+    { id: "gpt-5.4", grounding: "judgment", reason: "alpha.33: third-provider tail (archetypePerf=7) \u2014 closes openai-in-default-fallback-chains" }
   ],
   // Quality + cost match.
   generate: [
@@ -1440,7 +1446,8 @@ var STARTER_CHAINS_GROUNDED = {
     { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Quality anchor \u2014 engineer pick" },
     { id: "claude-haiku-4-5", grounding: "judgment", reason: "Same-provider step-down" },
     { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor" },
-    { id: "gemini-2.5-flash", grounding: "judgment", reason: "Cost floor \u2014 forgiving archetype tolerates Flash" }
+    { id: "gemini-2.5-flash", grounding: "judgment", reason: "Cost floor \u2014 forgiving archetype tolerates Flash" },
+    { id: "gpt-5.4-mini", grounding: "judgment", reason: "alpha.33: third-provider tail (archetypePerf=7) \u2014 closes openai-in-default-fallback-chains" }
   ],
   // Parallel-tool throughput champion — Flash leads on the L-040 cliff
   // (capability-fact: Flash 15-75 parallel calls/step vs DeepSeek 7-8).
@@ -1448,21 +1455,24 @@ var STARTER_CHAINS_GROUNDED = {
     { id: "gemini-2.5-flash", grounding: "capability-fact", reason: "L-040 parallel-tool throughput champion (15-75 calls/step)" },
     { id: "gemini-2.5-pro", grounding: "capability-fact", reason: "Cross-provider tier 1 with strong parallel-tool support" },
     { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Quality safety net for blocked-Flash case" },
-    { id: "claude-haiku-4-5", grounding: "judgment", reason: "Reduced tool budget \u2014 cliff at 16 fires" }
+    { id: "claude-haiku-4-5", grounding: "judgment", reason: "Reduced tool budget \u2014 cliff at 16 fires" },
+    { id: "gpt-5.4-mini", grounding: "judgment", reason: "alpha.33: third-provider tail \u2014 OpenAI parallel-tool capable archetype" }
   ],
   // Cost-sensitive + tolerant. DeepSeek brain-evidence tier 1.
   summarize: [
     { id: "gemini-2.5-flash", grounding: "judgment", reason: "Cost-sensitive primary \u2014 engineer pick" },
     { id: "deepseek-v4-flash", grounding: "measured", reason: "Brain-validated tier 1 for cost-sensitive summarize workloads", n: 169 },
     { id: "claude-haiku-4-5", grounding: "judgment", reason: "Quality safety net" },
-    { id: "gemini-2.5-flash-lite", grounding: "judgment", reason: "Emergency floor \u2014 onboarded s22, no brain evidence yet" }
+    { id: "gemini-2.5-flash-lite", grounding: "judgment", reason: "Emergency floor \u2014 onboarded s22, no brain evidence yet" },
+    { id: "gpt-5.4-nano", grounding: "judgment", reason: "alpha.33: third-provider tail (archetypePerf=6) \u2014 cheapest OpenAI, matches summarize cost-band" }
   ],
   // Brain-validated DeepSeek tier 1 (169 rows, 0% empty rate).
   classify: [
     { id: "gemini-2.5-flash", grounding: "judgment", reason: "Cost-sensitive primary \u2014 engineer pick" },
     { id: "deepseek-v4-flash", grounding: "measured", reason: "Brain-validated tier 1 (169 rows, 0% empty rate)", n: 169 },
     { id: "claude-haiku-4-5", grounding: "judgment", reason: "Quality safety net" },
-    { id: "gemini-2.5-flash-lite", grounding: "judgment", reason: "Cache-discount 10\xD7 floor for repeat-prompt workloads" }
+    { id: "gemini-2.5-flash-lite", grounding: "judgment", reason: "Cache-discount 10\xD7 floor for repeat-prompt workloads" },
+    { id: "gpt-5.4-nano", grounding: "judgment", reason: "alpha.33: third-provider tail (archetypePerf=6) \u2014 cheapest OpenAI for classify" }
   ]
 };
 var STARTER_CHAINS = (() => {
@@ -1517,7 +1527,7 @@ function resolveStarterForMode(archetype, toolOrchestration, allChains) {
   return allChains[archetype];
 }
 function getDefaultFallbackChain(opts) {
-  const { archetype, primary, maxDepth = 3, policy, reachability, toolOrchestration } = opts;
+  const { archetype, primary, maxDepth = 4, policy, reachability, toolOrchestration } = opts;
   if (maxDepth < 1) {
     throw new Error(
       `getDefaultFallbackChain: maxDepth must be >= 1, got ${maxDepth}`
@@ -2454,5 +2464,10 @@ function createGlassboxRoutes(config) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createGlassboxRoutes
+  COUNTERFACTUAL_MAX_RESULTS,
+  COUNTERFACTUAL_MIN_SAVINGS_RATIO,
+  computeCounterfactuals,
+  createGlassboxRoutes,
+  rowToDetail,
+  rowToSummary
 });

package/dist/glassbox-routes/index.mjs

@@ -1,7 +1,7 @@
 import {
   ARCHETYPE_FLOOR_DEFAULT,
   getDefaultFallbackChain
-} from "../chunk-WXCFWUCN.mjs";
+} from "../chunk-XJZRDGHF.mjs";
 import {
   tryGetProfile
 } from "../chunk-JQGRWJZO.mjs";
@@ -654,5 +654,10 @@ function createGlassboxRoutes(config) {
   return { proxy, stream };
 }
 export {
-  createGlassboxRoutes
+  COUNTERFACTUAL_MAX_RESULTS,
+  COUNTERFACTUAL_MIN_SAVINGS_RATIO,
+  computeCounterfactuals,
+  createGlassboxRoutes,
+  rowToDetail,
+  rowToSummary
 };

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, S as SectionRewrite, R as RecordInput, e as RecordOutcomeInput, O as OutcomeResult, f as OracleScore, g as CompileResult, B as BestPracticeAdvisory, h as Adapter, i as PerAxisMetrics, j as Provider, k as ChainEntry, G as Grounding } from './ir-De2AQtlr.mjs';
-export { l as CallAttempt, m as CallError, n as ChainWithGrounding, o as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, p as MutationApplied, q as NormalizedTokens, r as OutcomeKind, s as PerAxisMetricsByModel, t as PromptSection, u as SectionKind, T as ToolCall, v as ToolDefinition } from './ir-De2AQtlr.mjs';
+import { C as CompilePolicy, N as NormalizedResponse, A as ApiKeys, P as ProviderOverrides, a as CompiledRequest, b as PromptIR, c as CallOptions, d as CallResult, S as SystemModelMessage, e as CompileResult, f as SectionRewrite, R as RecordInput, g as RecordOutcomeInput, O as OutcomeResult, h as OracleScore, B as BestPracticeAdvisory, i as Adapter, j as PerAxisMetrics, k as Provider, l as ChainEntry, G as Grounding } from './ir-DubC20e3.mjs';
+export { m as CallAttempt, n as CallError, o as ChainWithGrounding, p as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, q as MutationApplied, r as NormalizedTokens, s as OutcomeKind, t as PerAxisMetricsByModel, u as PromptSection, v as SectionKind, T as ToolCall, w as ToolDefinition } from './ir-DubC20e3.mjs';
 import { ModelProfile } from './profiles.mjs';
 export { ALIASES, CacheStrategy, CliffRule, LoweringSpec, RecoveryRule, StructuredOutputCapability, SystemPromptMode, allProfiles, getProfile, profilesByProvider, tryGetProfile } from './profiles.mjs';
 import { IntentArchetypeName } from './dialect.mjs';
@@ -94,6 +94,89 @@ declare function execute(request: CompiledRequest, opts?: ExecuteOptions): Promi
  */
 declare function call(ir: PromptIR, opts?: CallOptions): Promise<CallResult>;
 
+/**
+ * alpha.33 — AI-SDK streamText helpers.
+ *
+ * The cross-consumer pattern surfaced 2026-05-20 (`streamText-cache-marker-
+ * propagation-gap` on `command-center/interfaces/kgauto.md ## Requested`):
+ * AI-SDK consumers using `streamText({ system: <string>, messages:
+ * convertToModelMessages(messages), model })` silently drop the Anthropic
+ * `cache_control` markers the compiler emits on `result.request.messages`.
+ * Two losses on that line:
+ *   (a) `convertToModelMessages()` reads raw inputs not the lowered output,
+ *       dropping per-message providerOptions; and
+ *   (b) `streamText({ system: '<string>' })` strips any providerOptions
+ *       on the system prefix.
+ *
+ * Net effect prior to this surface: `cache_read_input_tokens = 0` across
+ * every measured production call by IC + tt-intel even though both
+ * consumers had `historyCachePolicy: { strategy: 'all-but-latest' }` wired
+ * since alpha.5. The compiler did the right thing; the consumer integration
+ * pattern lost the markers at the wire boundary.
+ *
+ * This helper closes the gap. Pass the consumer's already-converted messages
+ * + the kgauto CompileResult and get back a `{ system, messages }` pair
+ * with cacheControl re-attached at the deterministic indices the compiler
+ * computed (`diagnostics.historyCacheMarkIndex` + `systemMessages` with
+ * its own cacheControl markers).
+ *
+ * No I/O. Pure transform. Idempotent — calling twice with the same inputs
+ * produces structurally-identical output.
+ */
+
+/**
+ * AI-SDK-shaped converted-message structure. Matches what
+ * `convertToModelMessages()` returns at the wire layer. We don't import
+ * the AI-SDK type to avoid pulling that dep into the kgauto-compiler
+ * package — consumers pass their own already-converted messages.
+ */
+interface AISDKConvertedMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: unknown;
+    providerOptions?: {
+        anthropic?: {
+            cacheControl?: {
+                type: 'ephemeral';
+            };
+        };
+    };
+}
+/**
+ * Result of `attachCacheControlToStreamTextInput()` — ready to spread into
+ * `streamText(...)` directly.
+ *
+ * The `system` field is either the structured `SystemModelMessage[]` form
+ * (when the compiler computed at least one cacheable section + chose
+ * Anthropic) or the flat-string concatenation (when no cacheable sections
+ * exist OR the provider isn't Anthropic). Consumers can pass either form
+ * to `streamText({ system })` — the AI-SDK accepts both.
+ */
+interface AttachCacheControlResult {
+    system: string | SystemModelMessage[];
+    messages: AISDKConvertedMessage[];
+}
+/**
+ * Attach Anthropic cache_control markers to a streamText input that the
+ * consumer has already prepared via `convertToModelMessages()`. Reads
+ * `result.diagnostics.historyCacheMarkIndex` for the position-on-history
+ * marker and `result.systemMessages` for the per-section system markers.
+ *
+ * The flat-string `system` form is returned when:
+ *   - the compiler produced no `systemMessages` (e.g., zero sections kept), or
+ *   - the chosen provider is not Anthropic, so cacheControl wouldn't
+ *     achieve anything at the wire layer (other providers cache implicitly
+ *     based on prefix shape, no marker needed).
+ *
+ * Otherwise the structured `SystemModelMessage[]` form is returned —
+ * preserves the per-section cacheControl markers across `streamText`.
+ *
+ * @param result - kgauto CompileResult from `compile(ir, opts)`
+ * @param convertedMessages - the consumer's already-converted messages
+ *   (from `convertToModelMessages(rawMessages)` in their AI-SDK call site)
+ * @returns `{ system, messages }` ready to spread into `streamText(...)`
+ */
+declare function attachCacheControlToStreamTextInput(result: CompileResult, convertedMessages: AISDKConvertedMessage[]): AttachCacheControlResult;
+
 /**
  * alpha.11 — opt-in nested config for brain-query mode (chains / archetype
  * perf / pricing / models registry). Enabled by default when endpoint is
@@ -1419,4 +1502,4 @@ declare const loadAliasesFromBrain: () => Record<string, string>;
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ABSOLUTE_FLOOR, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type SupportedProvider, TRANSLATOR_FLOOR, applySectionRewrites, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };

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, S as SectionRewrite, R as RecordInput, e as RecordOutcomeInput, O as OutcomeResult, f as OracleScore, g as CompileResult, B as BestPracticeAdvisory, h as Adapter, i as PerAxisMetrics, j as Provider, k as ChainEntry, G as Grounding } from './ir-BIAT9gJk.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, u as SectionKind, T as ToolCall, v as ToolDefinition } from './ir-BIAT9gJk.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, S as SystemModelMessage, e as CompileResult, f as SectionRewrite, R as RecordInput, g as RecordOutcomeInput, O as OutcomeResult, h as OracleScore, B as BestPracticeAdvisory, i as Adapter, j as PerAxisMetrics, k as Provider, l as ChainEntry, G as Grounding } from './ir-GnYPkpGo.js';
+export { m as CallAttempt, n as CallError, o as ChainWithGrounding, p as Constraints, F as FallbackReason, H as HistoryCachePolicy, I as IntentDeclaration, M as Message, q as MutationApplied, r as NormalizedTokens, s as OutcomeKind, t as PerAxisMetricsByModel, u as PromptSection, v as SectionKind, T as ToolCall, w as ToolDefinition } from './ir-GnYPkpGo.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';
@@ -94,6 +94,89 @@ declare function execute(request: CompiledRequest, opts?: ExecuteOptions): Promi
  */
 declare function call(ir: PromptIR, opts?: CallOptions): Promise<CallResult>;
 
+/**
+ * alpha.33 — AI-SDK streamText helpers.
+ *
+ * The cross-consumer pattern surfaced 2026-05-20 (`streamText-cache-marker-
+ * propagation-gap` on `command-center/interfaces/kgauto.md ## Requested`):
+ * AI-SDK consumers using `streamText({ system: <string>, messages:
+ * convertToModelMessages(messages), model })` silently drop the Anthropic
+ * `cache_control` markers the compiler emits on `result.request.messages`.
+ * Two losses on that line:
+ *   (a) `convertToModelMessages()` reads raw inputs not the lowered output,
+ *       dropping per-message providerOptions; and
+ *   (b) `streamText({ system: '<string>' })` strips any providerOptions
+ *       on the system prefix.
+ *
+ * Net effect prior to this surface: `cache_read_input_tokens = 0` across
+ * every measured production call by IC + tt-intel even though both
+ * consumers had `historyCachePolicy: { strategy: 'all-but-latest' }` wired
+ * since alpha.5. The compiler did the right thing; the consumer integration
+ * pattern lost the markers at the wire boundary.
+ *
+ * This helper closes the gap. Pass the consumer's already-converted messages
+ * + the kgauto CompileResult and get back a `{ system, messages }` pair
+ * with cacheControl re-attached at the deterministic indices the compiler
+ * computed (`diagnostics.historyCacheMarkIndex` + `systemMessages` with
+ * its own cacheControl markers).
+ *
+ * No I/O. Pure transform. Idempotent — calling twice with the same inputs
+ * produces structurally-identical output.
+ */
+
+/**
+ * AI-SDK-shaped converted-message structure. Matches what
+ * `convertToModelMessages()` returns at the wire layer. We don't import
+ * the AI-SDK type to avoid pulling that dep into the kgauto-compiler
+ * package — consumers pass their own already-converted messages.
+ */
+interface AISDKConvertedMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: unknown;
+    providerOptions?: {
+        anthropic?: {
+            cacheControl?: {
+                type: 'ephemeral';
+            };
+        };
+    };
+}
+/**
+ * Result of `attachCacheControlToStreamTextInput()` — ready to spread into
+ * `streamText(...)` directly.
+ *
+ * The `system` field is either the structured `SystemModelMessage[]` form
+ * (when the compiler computed at least one cacheable section + chose
+ * Anthropic) or the flat-string concatenation (when no cacheable sections
+ * exist OR the provider isn't Anthropic). Consumers can pass either form
+ * to `streamText({ system })` — the AI-SDK accepts both.
+ */
+interface AttachCacheControlResult {
+    system: string | SystemModelMessage[];
+    messages: AISDKConvertedMessage[];
+}
+/**
+ * Attach Anthropic cache_control markers to a streamText input that the
+ * consumer has already prepared via `convertToModelMessages()`. Reads
+ * `result.diagnostics.historyCacheMarkIndex` for the position-on-history
+ * marker and `result.systemMessages` for the per-section system markers.
+ *
+ * The flat-string `system` form is returned when:
+ *   - the compiler produced no `systemMessages` (e.g., zero sections kept), or
+ *   - the chosen provider is not Anthropic, so cacheControl wouldn't
+ *     achieve anything at the wire layer (other providers cache implicitly
+ *     based on prefix shape, no marker needed).
+ *
+ * Otherwise the structured `SystemModelMessage[]` form is returned —
+ * preserves the per-section cacheControl markers across `streamText`.
+ *
+ * @param result - kgauto CompileResult from `compile(ir, opts)`
+ * @param convertedMessages - the consumer's already-converted messages
+ *   (from `convertToModelMessages(rawMessages)` in their AI-SDK call site)
+ * @returns `{ system, messages }` ready to spread into `streamText(...)`
+ */
+declare function attachCacheControlToStreamTextInput(result: CompileResult, convertedMessages: AISDKConvertedMessage[]): AttachCacheControlResult;
+
 /**
  * alpha.11 — opt-in nested config for brain-query mode (chains / archetype
  * perf / pricing / models registry). Enabled by default when endpoint is
@@ -1419,4 +1502,4 @@ declare const loadAliasesFromBrain: () => Record<string, string>;
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ABSOLUTE_FLOOR, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type SupportedProvider, TRANSLATOR_FLOOR, applySectionRewrites, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };
+export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainQueryConfig, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, type GetActionableAdvisoriesOptions, type GetDefaultFallbackChainOpts, type GetPerAxisMetricsOpts, Grounding, IntentArchetypeName, type LLMJudgeOptions, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProfileToRowOptions, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, SectionRewrite, type SupportedProvider, SystemModelMessage, TRANSLATOR_FLOOR, applySectionRewrites, attachCacheControlToStreamTextInput, buildLLMJudge, call, clearBrain, compile, configureBrain, countTokens, execute, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStarterChain, getStarterChainWithGrounding, isBrainQueryActiveFor, isModelReachable, isProviderReachable, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, profileToRow, record, recordOutcome, resetTokenizer, resolvePricingAt, resolveProviderKey, runAdvisor, setTokenizer };

package/dist/index.js

@@ -33,6 +33,7 @@ __export(index_exports, {
   TRANSLATOR_FLOOR: () => TRANSLATOR_FLOOR,
   allProfiles: () => allProfiles,
   applySectionRewrites: () => applySectionRewrites,
+  attachCacheControlToStreamTextInput: () => attachCacheControlToStreamTextInput,
   bucketContext: () => bucketContext,
   bucketHistory: () => bucketHistory,
   bucketToolCount: () => bucketToolCount,
@@ -2771,6 +2772,9 @@ function compile(ir, opts = {}) {
   const handle = makeHandle();
   const finalShape = computeShape(workingIR, inputTokens);
   const _learningKey = learningKey(ir.intent.archetype, profile.id, finalShape);
+  const historyCacheMarkIndex = computeHistoryCacheMarkIndex(workingIR);
+  const systemMessages = buildSystemMessages(workingIR, profile.provider);
+  const systemCacheMarkIndex = lastCacheableSystemIndex(systemMessages);
   const diagnostics = {
     sectionsKept: workingIR.sections.length,
     sectionsDropped: ir.sections.length - workingIR.sections.length,
@@ -2784,7 +2788,10 @@ function compile(ir, opts = {}) {
     historyTokensTotal: compressed.historyTokensTotal,
     // alpha.20 E3: mirror the consumer's declared mode for Glass-Box +
     // brain observability. Undefined when not declared (pre-alpha.20).
-    toolOrchestration: ir.constraints?.toolOrchestration
+    toolOrchestration: ir.constraints?.toolOrchestration,
+    // alpha.33 — see top-of-block comment.
+    historyCacheMarkIndex,
+    systemCacheMarkIndex
   };
   if (ir.intent.archetype === "hunt" && ir.constraints?.toolOrchestration === "sequential") {
     accumulatedMutations.push({
@@ -2834,9 +2841,45 @@ function compile(ir, opts = {}) {
     advisories,
     diagnostics,
     sectionRewritesApplied,
-    wireOverrides
+    wireOverrides,
+    systemMessages
   };
 }
+function computeHistoryCacheMarkIndex(ir) {
+  const policy = ir.historyCachePolicy;
+  if (!policy || policy.strategy === "none") return void 0;
+  const historyLen = ir.history?.length ?? 0;
+  if (historyLen === 0) return void 0;
+  if (policy.strategy === "all-but-latest") {
+    return historyLen - 1;
+  }
+  if (policy.strategy === "fixed-suffix") {
+    const idx = historyLen - 1 - policy.suffix;
+    if (idx < 0) return void 0;
+    return idx;
+  }
+  return void 0;
+}
+function buildSystemMessages(ir, provider) {
+  const sections = ir.sections;
+  if (!sections || sections.length === 0) return [];
+  return sections.map((s) => {
+    const base = { role: "system", content: s.text };
+    if (provider === "anthropic" && s.cacheable) {
+      base.providerOptions = { anthropic: { cacheControl: { type: "ephemeral" } } };
+    }
+    return base;
+  });
+}
+function lastCacheableSystemIndex(systemMessages) {
+  for (let i = systemMessages.length - 1; i >= 0; i--) {
+    const entry = systemMessages[i];
+    if (entry && entry.providerOptions?.anthropic?.cacheControl) {
+      return i;
+    }
+  }
+  return void 0;
+}
 function validateIR(ir) {
   if (!ir.appId) throw new Error("compile(): ir.appId is required");
   if (!ir.intent || !ir.intent.archetype) {
@@ -3581,7 +3624,8 @@ var STARTER_CHAINS_GROUNDED = {
     { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Reasoning + cost balance \u2014 engineer pick" },
     { id: "claude-opus-4-7", grounding: "judgment", reason: 'Same-provider walk-UP on 429 (rare exception to "always cheaper")' },
     { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor" },
-    { id: "deepseek-v4-pro", grounding: "judgment", reason: "Tier 3 cost floor \u2014 no brain evidence yet" }
+    { id: "deepseek-v4-pro", grounding: "judgment", reason: "Tier 3 cost floor \u2014 no brain evidence yet" },
+    { id: "gpt-5.4", grounding: "judgment", reason: "alpha.33: third-provider tail (archetypePerf=7) \u2014 closes openai-in-default-fallback-chains" }
   ],
   // Quality + cost match.
   generate: [
@@ -3612,7 +3656,8 @@ var STARTER_CHAINS_GROUNDED = {
     { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Quality anchor \u2014 engineer pick" },
     { id: "claude-haiku-4-5", grounding: "judgment", reason: "Same-provider step-down" },
     { id: "gemini-2.5-pro", grounding: "judgment", reason: "Cross-provider anchor" },
-    { id: "gemini-2.5-flash", grounding: "judgment", reason: "Cost floor \u2014 forgiving archetype tolerates Flash" }
+    { id: "gemini-2.5-flash", grounding: "judgment", reason: "Cost floor \u2014 forgiving archetype tolerates Flash" },
+    { id: "gpt-5.4-mini", grounding: "judgment", reason: "alpha.33: third-provider tail (archetypePerf=7) \u2014 closes openai-in-default-fallback-chains" }
   ],
   // Parallel-tool throughput champion — Flash leads on the L-040 cliff
   // (capability-fact: Flash 15-75 parallel calls/step vs DeepSeek 7-8).
@@ -3620,21 +3665,24 @@ var STARTER_CHAINS_GROUNDED = {
     { id: "gemini-2.5-flash", grounding: "capability-fact", reason: "L-040 parallel-tool throughput champion (15-75 calls/step)" },
     { id: "gemini-2.5-pro", grounding: "capability-fact", reason: "Cross-provider tier 1 with strong parallel-tool support" },
     { id: "claude-sonnet-4-6", grounding: "judgment", reason: "Quality safety net for blocked-Flash case" },
-    { id: "claude-haiku-4-5", grounding: "judgment", reason: "Reduced tool budget \u2014 cliff at 16 fires" }
+    { id: "claude-haiku-4-5", grounding: "judgment", reason: "Reduced tool budget \u2014 cliff at 16 fires" },
+    { id: "gpt-5.4-mini", grounding: "judgment", reason: "alpha.33: third-provider tail \u2014 OpenAI parallel-tool capable archetype" }
   ],
   // Cost-sensitive + tolerant. DeepSeek brain-evidence tier 1.
   summarize: [
     { id: "gemini-2.5-flash", grounding: "judgment", reason: "Cost-sensitive primary \u2014 engineer pick" },
     { id: "deepseek-v4-flash", grounding: "measured", reason: "Brain-validated tier 1 for cost-sensitive summarize workloads", n: 169 },
     { id: "claude-haiku-4-5", grounding: "judgment", reason: "Quality safety net" },
-    { id: "gemini-2.5-flash-lite", grounding: "judgment", reason: "Emergency floor \u2014 onboarded s22, no brain evidence yet" }
+    { id: "gemini-2.5-flash-lite", grounding: "judgment", reason: "Emergency floor \u2014 onboarded s22, no brain evidence yet" },
+    { id: "gpt-5.4-nano", grounding: "judgment", reason: "alpha.33: third-provider tail (archetypePerf=6) \u2014 cheapest OpenAI, matches summarize cost-band" }
   ],
   // Brain-validated DeepSeek tier 1 (169 rows, 0% empty rate).
   classify: [
     { id: "gemini-2.5-flash", grounding: "judgment", reason: "Cost-sensitive primary \u2014 engineer pick" },
     { id: "deepseek-v4-flash", grounding: "measured", reason: "Brain-validated tier 1 (169 rows, 0% empty rate)", n: 169 },
     { id: "claude-haiku-4-5", grounding: "judgment", reason: "Quality safety net" },
-    { id: "gemini-2.5-flash-lite", grounding: "judgment", reason: "Cache-discount 10\xD7 floor for repeat-prompt workloads" }
+    { id: "gemini-2.5-flash-lite", grounding: "judgment", reason: "Cache-discount 10\xD7 floor for repeat-prompt workloads" },
+    { id: "gpt-5.4-nano", grounding: "judgment", reason: "alpha.33: third-provider tail (archetypePerf=6) \u2014 cheapest OpenAI for classify" }
   ]
 };
 var STARTER_CHAINS = (() => {
@@ -3689,7 +3737,7 @@ function resolveStarterForMode(archetype, toolOrchestration, allChains) {
   return allChains[archetype];
 }
 function getDefaultFallbackChain(opts) {
-  const { archetype, primary, maxDepth = 3, policy, reachability, toolOrchestration } = opts;
+  const { archetype, primary, maxDepth = 4, policy, reachability, toolOrchestration } = opts;
   if (maxDepth < 1) {
     throw new Error(
       `getDefaultFallbackChain: maxDepth must be >= 1, got ${maxDepth}`
@@ -4521,6 +4569,34 @@ function safeEmit(fn) {
   }
 }
 
+// src/streamtext-helpers.ts
+function attachCacheControlToStreamTextInput(result, convertedMessages) {
+  const messages = convertedMessages.map((m) => ({ ...m }));
+  const markIdx = result.diagnostics.historyCacheMarkIndex;
+  if (result.provider === "anthropic" && typeof markIdx === "number" && markIdx >= 0 && markIdx < messages.length) {
+    const target = messages[markIdx];
+    if (target) {
+      messages[markIdx] = {
+        role: target.role,
+        content: target.content,
+        providerOptions: {
+          ...target.providerOptions ?? {},
+          anthropic: {
+            ...target.providerOptions?.anthropic ?? {},
+            cacheControl: { type: "ephemeral" }
+          }
+        }
+      };
+    }
+  }
+  const systemMessages = result.systemMessages;
+  const hasStructuredSystemCacheControl = result.provider === "anthropic" && systemMessages.some(
+    (m) => m.providerOptions?.anthropic?.cacheControl !== void 0
+  );
+  const system = hasStructuredSystemCacheControl ? systemMessages : systemMessages.map((m) => m.content).join("\n\n");
+  return { system, messages };
+}
+
 // src/oracle.ts
 var DEFAULT_DIMENSIONS = ["correctness", "completeness", "conciseness", "format"];
 var judgeCallTimes = [];
@@ -5021,6 +5097,7 @@ function compile2(ir, opts) {
   TRANSLATOR_FLOOR,
   allProfiles,
   applySectionRewrites,
+  attachCacheControlToStreamTextInput,
   bucketContext,
   bucketHistory,
   bucketToolCount,

package/dist/index.mjs

@@ -32,7 +32,7 @@ import {
   isProviderReachable,
   loadChainsFromBrain,
   resolveProviderKey
-} from "./chunk-WXCFWUCN.mjs";
+} from "./chunk-XJZRDGHF.mjs";
 import {
   ALIASES,
   _setProfileBrainHook,
@@ -1197,6 +1197,9 @@ function compile(ir, opts = {}) {
   const handle = makeHandle();
   const finalShape = computeShape(workingIR, inputTokens);
   const _learningKey = learningKey(ir.intent.archetype, profile.id, finalShape);
+  const historyCacheMarkIndex = computeHistoryCacheMarkIndex(workingIR);
+  const systemMessages = buildSystemMessages(workingIR, profile.provider);
+  const systemCacheMarkIndex = lastCacheableSystemIndex(systemMessages);
   const diagnostics = {
     sectionsKept: workingIR.sections.length,
     sectionsDropped: ir.sections.length - workingIR.sections.length,
@@ -1210,7 +1213,10 @@ function compile(ir, opts = {}) {
     historyTokensTotal: compressed.historyTokensTotal,
     // alpha.20 E3: mirror the consumer's declared mode for Glass-Box +
     // brain observability. Undefined when not declared (pre-alpha.20).
-    toolOrchestration: ir.constraints?.toolOrchestration
+    toolOrchestration: ir.constraints?.toolOrchestration,
+    // alpha.33 — see top-of-block comment.
+    historyCacheMarkIndex,
+    systemCacheMarkIndex
   };
   if (ir.intent.archetype === "hunt" && ir.constraints?.toolOrchestration === "sequential") {
     accumulatedMutations.push({
@@ -1260,9 +1266,45 @@ function compile(ir, opts = {}) {
     advisories,
     diagnostics,
     sectionRewritesApplied,
-    wireOverrides
+    wireOverrides,
+    systemMessages
   };
 }
+function computeHistoryCacheMarkIndex(ir) {
+  const policy = ir.historyCachePolicy;
+  if (!policy || policy.strategy === "none") return void 0;
+  const historyLen = ir.history?.length ?? 0;
+  if (historyLen === 0) return void 0;
+  if (policy.strategy === "all-but-latest") {
+    return historyLen - 1;
+  }
+  if (policy.strategy === "fixed-suffix") {
+    const idx = historyLen - 1 - policy.suffix;
+    if (idx < 0) return void 0;
+    return idx;
+  }
+  return void 0;
+}
+function buildSystemMessages(ir, provider) {
+  const sections = ir.sections;
+  if (!sections || sections.length === 0) return [];
+  return sections.map((s) => {
+    const base = { role: "system", content: s.text };
+    if (provider === "anthropic" && s.cacheable) {
+      base.providerOptions = { anthropic: { cacheControl: { type: "ephemeral" } } };
+    }
+    return base;
+  });
+}
+function lastCacheableSystemIndex(systemMessages) {
+  for (let i = systemMessages.length - 1; i >= 0; i--) {
+    const entry = systemMessages[i];
+    if (entry && entry.providerOptions?.anthropic?.cacheControl) {
+      return i;
+    }
+  }
+  return void 0;
+}
 function validateIR(ir) {
   if (!ir.appId) throw new Error("compile(): ir.appId is required");
   if (!ir.intent || !ir.intent.archetype) {
@@ -2247,6 +2289,34 @@ function safeEmit(fn) {
   }
 }
 
+// src/streamtext-helpers.ts
+function attachCacheControlToStreamTextInput(result, convertedMessages) {
+  const messages = convertedMessages.map((m) => ({ ...m }));
+  const markIdx = result.diagnostics.historyCacheMarkIndex;
+  if (result.provider === "anthropic" && typeof markIdx === "number" && markIdx >= 0 && markIdx < messages.length) {
+    const target = messages[markIdx];
+    if (target) {
+      messages[markIdx] = {
+        role: target.role,
+        content: target.content,
+        providerOptions: {
+          ...target.providerOptions ?? {},
+          anthropic: {
+            ...target.providerOptions?.anthropic ?? {},
+            cacheControl: { type: "ephemeral" }
+          }
+        }
+      };
+    }
+  }
+  const systemMessages = result.systemMessages;
+  const hasStructuredSystemCacheControl = result.provider === "anthropic" && systemMessages.some(
+    (m) => m.providerOptions?.anthropic?.cacheControl !== void 0
+  );
+  const system = hasStructuredSystemCacheControl ? systemMessages : systemMessages.map((m) => m.content).join("\n\n");
+  return { system, messages };
+}
+
 // src/oracle.ts
 var DEFAULT_DIMENSIONS = ["correctness", "completeness", "conciseness", "format"];
 var judgeCallTimes = [];
@@ -2746,6 +2816,7 @@ export {
   TRANSLATOR_FLOOR,
   allProfiles,
   applySectionRewrites,
+  attachCacheControlToStreamTextInput,
   bucketContext,
   bucketHistory,
   bucketToolCount,

package/dist/{ir-De2AQtlr.d.mts → ir-DubC20e3.d.mts}

@@ -564,6 +564,86 @@ interface CompileResult {
          * treat as 'parallel' equivalent for back-compat.
          */
         toolOrchestration?: 'parallel' | 'sequential' | 'either';
+        /**
+         * alpha.33. Zero-based index into the resolved (post-compression) history
+         * array at which Anthropic prompt-cache marker should land — i.e., the
+         * last message that belongs to the stable cacheable prefix. Consumers
+         * using AI-SDK's `streamText({ messages: convertToModelMessages(...) })`
+         * lose the per-message `providerOptions.anthropic.cacheControl` markers
+         * the compiler emits on `result.request.messages`, because
+         * `convertToModelMessages` reads raw input not the lowered output.
+         * This index gives the consumer a single deterministic position to
+         * attach `cacheControl: { type: 'ephemeral' }` after their own conversion.
+         *
+         * Computation:
+         *   - `historyCachePolicy.strategy === 'all-but-latest'`: history.length - 1
+         *     (or undefined if history is empty)
+         *   - `historyCachePolicy.strategy === 'fixed-suffix'` with `suffix: N`:
+         *     history.length - 1 - N (undefined if N exceeds history length)
+         *   - `historyCachePolicy.strategy === 'none'` or omitted: undefined
+         *
+         * The companion helper `attachCacheControlToStreamTextInput()` reads
+         * this field + the consumer's converted messages to perform the per-
+         * attempt mutation correctly. Filed by IC + tt-intel cross-consumer
+         * pattern 2026-05-20 (`streamText-cache-marker-propagation-gap`).
+         */
+        historyCacheMarkIndex?: number;
+        /**
+         * alpha.33. Zero-based index into the structured `systemMessages` array
+         * (see top-level `systemMessages` field) at which the cacheable system
+         * prefix ends. Useful when the consumer is building a multi-block
+         * system parameter for Anthropic streamText — they can attach
+         * `providerOptions.anthropic.cacheControl` to `systemMessages[index]`.
+         *
+         * Undefined when no section had `cacheable: true` OR `systemMessages` is
+         * empty. Matches `historyCacheMarkIndex` semantics on the history axis.
+         */
+        systemCacheMarkIndex?: number;
+    };
+    /**
+     * alpha.33. Structured `system` for AI-SDK `streamText({ system })`
+     * consumers. When the consumer's lowered request has cacheable section
+     * markers, the flat `system: string` form loses the marker assignment
+     * (every `streamText({ system: '<string>' })` call silently strips
+     * providerOptions). Pass `systemMessages` instead to `streamText({
+     * system: result.systemMessages })` so the cacheable prefix is structurally
+     * preserved.
+     *
+     * Each entry is a `SystemModelMessage`-shaped object:
+     *   { role: 'system', content: string, providerOptions?: { anthropic?:
+     *     { cacheControl: { type: 'ephemeral' } } } }
+     *
+     * Provider-agnostic on emit: only Anthropic actually consumes the
+     * cacheControl block; Gemini / OpenAI / DeepSeek receive the same
+     * shape but ignore the marker (matching their implicit-caching semantics).
+     *
+     * Empty array when the IR carried zero sections (rare; usually means the
+     * compiler dropped everything for the chosen intent). Consumers can fall
+     * back to `result.systemMessages.length === 0 ? '' : result.systemMessages`
+     * or use the helper `attachCacheControlToStreamTextInput()` which handles
+     * both shapes.
+     */
+    systemMessages: SystemModelMessage[];
+}
+/**
+ * alpha.33. AI-SDK-compatible system-message shape carried on
+ * `CompileResult.systemMessages`. Matches the AI-SDK `streamText({ system })`
+ * structured form — consumers can pass these directly without conversion.
+ *
+ * The `providerOptions` field is set ONLY for entries that came from a
+ * section with `cacheable: true` AND the chosen provider is Anthropic AND
+ * the compiler computed a non-zero `cacheableTokens`. Other providers see
+ * `providerOptions: undefined` (or omitted entirely).
+ */
+interface SystemModelMessage {
+    role: 'system';
+    content: string;
+    providerOptions?: {
+        anthropic?: {
+            cacheControl: {
+                type: 'ephemeral';
+            };
+        };
     };
 }
 /**
@@ -1028,4 +1108,4 @@ interface PerAxisMetrics {
 /** Per-axis metrics keyed by model — used for chain-comparison views. */
 type PerAxisMetricsByModel = Record<string, PerAxisMetrics>;
 
-export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type Grounding as G, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type SectionRewrite as S, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type RecordOutcomeInput as e, type OracleScore as f, type CompileResult as g, type Adapter as h, type PerAxisMetrics as i, type Provider as j, type ChainEntry as k, type CallAttempt as l, CallError as m, type ChainWithGrounding as n, type Constraints as o, type MutationApplied as p, type NormalizedTokens as q, type OutcomeKind as r, type PerAxisMetricsByModel as s, type PromptSection as t, type SectionKind as u, type ToolDefinition as v };
+export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type Grounding as G, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type SystemModelMessage 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, type SectionRewrite as f, type RecordOutcomeInput as g, type OracleScore as h, type Adapter as i, type PerAxisMetrics as j, type Provider as k, type ChainEntry as l, type CallAttempt as m, CallError as n, type ChainWithGrounding as o, type Constraints as p, type MutationApplied as q, type NormalizedTokens as r, type OutcomeKind as s, type PerAxisMetricsByModel as t, type PromptSection as u, type SectionKind as v, type ToolDefinition as w };

package/dist/{ir-BIAT9gJk.d.ts → ir-GnYPkpGo.d.ts}

@@ -564,6 +564,86 @@ interface CompileResult {
          * treat as 'parallel' equivalent for back-compat.
          */
         toolOrchestration?: 'parallel' | 'sequential' | 'either';
+        /**
+         * alpha.33. Zero-based index into the resolved (post-compression) history
+         * array at which Anthropic prompt-cache marker should land — i.e., the
+         * last message that belongs to the stable cacheable prefix. Consumers
+         * using AI-SDK's `streamText({ messages: convertToModelMessages(...) })`
+         * lose the per-message `providerOptions.anthropic.cacheControl` markers
+         * the compiler emits on `result.request.messages`, because
+         * `convertToModelMessages` reads raw input not the lowered output.
+         * This index gives the consumer a single deterministic position to
+         * attach `cacheControl: { type: 'ephemeral' }` after their own conversion.
+         *
+         * Computation:
+         *   - `historyCachePolicy.strategy === 'all-but-latest'`: history.length - 1
+         *     (or undefined if history is empty)
+         *   - `historyCachePolicy.strategy === 'fixed-suffix'` with `suffix: N`:
+         *     history.length - 1 - N (undefined if N exceeds history length)
+         *   - `historyCachePolicy.strategy === 'none'` or omitted: undefined
+         *
+         * The companion helper `attachCacheControlToStreamTextInput()` reads
+         * this field + the consumer's converted messages to perform the per-
+         * attempt mutation correctly. Filed by IC + tt-intel cross-consumer
+         * pattern 2026-05-20 (`streamText-cache-marker-propagation-gap`).
+         */
+        historyCacheMarkIndex?: number;
+        /**
+         * alpha.33. Zero-based index into the structured `systemMessages` array
+         * (see top-level `systemMessages` field) at which the cacheable system
+         * prefix ends. Useful when the consumer is building a multi-block
+         * system parameter for Anthropic streamText — they can attach
+         * `providerOptions.anthropic.cacheControl` to `systemMessages[index]`.
+         *
+         * Undefined when no section had `cacheable: true` OR `systemMessages` is
+         * empty. Matches `historyCacheMarkIndex` semantics on the history axis.
+         */
+        systemCacheMarkIndex?: number;
+    };
+    /**
+     * alpha.33. Structured `system` for AI-SDK `streamText({ system })`
+     * consumers. When the consumer's lowered request has cacheable section
+     * markers, the flat `system: string` form loses the marker assignment
+     * (every `streamText({ system: '<string>' })` call silently strips
+     * providerOptions). Pass `systemMessages` instead to `streamText({
+     * system: result.systemMessages })` so the cacheable prefix is structurally
+     * preserved.
+     *
+     * Each entry is a `SystemModelMessage`-shaped object:
+     *   { role: 'system', content: string, providerOptions?: { anthropic?:
+     *     { cacheControl: { type: 'ephemeral' } } } }
+     *
+     * Provider-agnostic on emit: only Anthropic actually consumes the
+     * cacheControl block; Gemini / OpenAI / DeepSeek receive the same
+     * shape but ignore the marker (matching their implicit-caching semantics).
+     *
+     * Empty array when the IR carried zero sections (rare; usually means the
+     * compiler dropped everything for the chosen intent). Consumers can fall
+     * back to `result.systemMessages.length === 0 ? '' : result.systemMessages`
+     * or use the helper `attachCacheControlToStreamTextInput()` which handles
+     * both shapes.
+     */
+    systemMessages: SystemModelMessage[];
+}
+/**
+ * alpha.33. AI-SDK-compatible system-message shape carried on
+ * `CompileResult.systemMessages`. Matches the AI-SDK `streamText({ system })`
+ * structured form — consumers can pass these directly without conversion.
+ *
+ * The `providerOptions` field is set ONLY for entries that came from a
+ * section with `cacheable: true` AND the chosen provider is Anthropic AND
+ * the compiler computed a non-zero `cacheableTokens`. Other providers see
+ * `providerOptions: undefined` (or omitted entirely).
+ */
+interface SystemModelMessage {
+    role: 'system';
+    content: string;
+    providerOptions?: {
+        anthropic?: {
+            cacheControl: {
+                type: 'ephemeral';
+            };
+        };
     };
 }
 /**
@@ -1028,4 +1108,4 @@ interface PerAxisMetrics {
 /** Per-axis metrics keyed by model — used for chain-comparison views. */
 type PerAxisMetricsByModel = Record<string, PerAxisMetrics>;
 
-export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type Grounding as G, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type SectionRewrite as S, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type RecordOutcomeInput as e, type OracleScore as f, type CompileResult as g, type Adapter as h, type PerAxisMetrics as i, type Provider as j, type ChainEntry as k, type CallAttempt as l, CallError as m, type ChainWithGrounding as n, type Constraints as o, type MutationApplied as p, type NormalizedTokens as q, type OutcomeKind as r, type PerAxisMetricsByModel as s, type PromptSection as t, type SectionKind as u, type ToolDefinition as v };
+export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type Grounding as G, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type SystemModelMessage 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, type SectionRewrite as f, type RecordOutcomeInput as g, type OracleScore as h, type Adapter as i, type PerAxisMetrics as j, type Provider as k, type ChainEntry as l, type CallAttempt as m, CallError as n, type ChainWithGrounding as o, type Constraints as p, type MutationApplied as q, type NormalizedTokens as r, type OutcomeKind as s, type PerAxisMetricsByModel as t, type PromptSection as u, type SectionKind as v, type ToolDefinition as w };

package/dist/profiles.d.mts

@@ -1,4 +1,4 @@
-import { j as Provider } from './ir-De2AQtlr.mjs';
+import { k as Provider } from './ir-DubC20e3.mjs';
 import { IntentArchetypeName } from './dialect.mjs';
 
 /**

package/dist/profiles.d.ts

@@ -1,4 +1,4 @@
-import { j as Provider } from './ir-BIAT9gJk.js';
+import { k as Provider } from './ir-GnYPkpGo.js';
 import { IntentArchetypeName } from './dialect.js';
 
 /**

package/dist/{types-BjrIFPGe.d.mts → types-2QzI0Ep1.d.mts}

@@ -1,4 +1,4 @@
-import { p as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, l as CallAttempt } from './ir-De2AQtlr.mjs';
+import { q as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, m as CallAttempt } from './ir-DubC20e3.mjs';
 
 /**
  * Glass-Box observability types (alpha.17).

package/dist/{types-D_JAhCv4.d.ts → types-DYcO82xh.d.ts}

@@ -1,4 +1,4 @@
-import { p as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, l as CallAttempt } from './ir-BIAT9gJk.js';
+import { q as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, m as CallAttempt } from './ir-GnYPkpGo.js';
 
 /**
  * Glass-Box observability types (alpha.17).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmdrift/kgauto-compiler",
-  "version": "2.0.0-alpha.31",
+  "version": "2.0.0-alpha.33",
   "description": "Prompt compiler + central learning brain for multi-model AI apps. Swap models without rewriting prompts.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",