@warmdrift/kgauto-compiler 2.0.0-alpha.30 → 2.0.0-alpha.32

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

@@ -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

@@ -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);
 
@@ -1815,6 +1820,12 @@ function summarizeSectionRewrite(kind, rule) {
   if (kind === "tool_call_contract" && rule === "sequential-tool-cliff-below-floor") {
     return "Sequential tool pattern applied (model cliff cleared at compile time).";
   }
+  if (kind === "narration_contract" && rule === "narration-drift-anthropic") {
+    return "Narration tightened for Anthropic dialect (terse-log shape preserved).";
+  }
+  if (kind === "narration_contract" && rule === "narration-thinking-leak-deepseek") {
+    return "Thinking-block suppression applied (DeepSeek V4 internal reasoning kept off-wire).";
+  }
   return `Translator applied rule "${rule}" to ${kind} section.`;
 }
 function rowToSectionRewrite(raw) {
@@ -2448,5 +2459,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

@@ -295,6 +295,12 @@ function summarizeSectionRewrite(kind, rule) {
   if (kind === "tool_call_contract" && rule === "sequential-tool-cliff-below-floor") {
     return "Sequential tool pattern applied (model cliff cleared at compile time).";
   }
+  if (kind === "narration_contract" && rule === "narration-drift-anthropic") {
+    return "Narration tightened for Anthropic dialect (terse-log shape preserved).";
+  }
+  if (kind === "narration_contract" && rule === "narration-thinking-leak-deepseek") {
+    return "Thinking-block suppression applied (DeepSeek V4 internal reasoning kept off-wire).";
+  }
   return `Translator applied rule "${rule}" to ${kind} section.`;
 }
 function rowToSectionRewrite(raw) {
@@ -648,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

@@ -374,26 +374,42 @@ interface RunAdvisorPhase2Context {
 declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: ModelProfile, policy?: CompilePolicy, phase2?: RunAdvisorPhase2Context): BestPracticeAdvisory[];
 
 /**
- * Translator primitive — alpha.29.
+ * Translator primitive — alpha.31.
  *
  * Pure function. Walks `IR.sections`, matches each section's `kind` against
- * the model + archetype + profile, and applies a model-aware rewrite when
- * a rule fires. Returns the rewritten IR + the list of rewrites for
- * `CompileResult.sectionRewritesApplied` and brain persistence.
+ * a per-rule dispatch table keyed on (kind, profile, archetype), and applies
+ * a model-aware rewrite when a rule fires. Returns the rewritten IR + the
+ * list of rewrites for `CompileResult.sectionRewritesApplied` and brain
+ * persistence.
  *
  * This is the s37 translator-framing eureka in code: kgauto graduates from
  * "gate" (alpha.28's cliff advisor: "consumer must accept adapter") to
  * "translator" (alpha.29: "consumer declared the section kind, kgauto
  * applies the adapter at compile time without consumer-side branching").
  *
- * alpha.29 ships ONE rule:
+ * Rules shipped:
  *
- *   tool_call_contract + profile.archetypePerf[archetype] < ARCHETYPE_FLOOR_DEFAULT
+ *   alpha.29 — tool_call_contract + archetypePerf[archetype] < TRANSLATOR_FLOOR
  *     → prepend sequential-tool-pattern guidance
  *     → emit wireOverrides: { parallelToolCalls: false }
+ *     → rule_id: 'sequential-tool-cliff-below-floor'
  *
- * alpha.30+ will extend the rule table to `narration_contract`, `role_intro`,
- * etc. Each new rule lands here as an explicit branch.
+ *   alpha.31 — narration_contract + profile.provider === 'anthropic'
+ *     → prepend terse-log narration guidance
+ *     → no wireOverrides
+ *     → rule_id: 'narration-drift-anthropic'
+ *
+ *   alpha.31 — narration_contract + profile.provider === 'deepseek'
+ *     → prepend <thinking>-suppression guidance
+ *     → no wireOverrides
+ *     → rule_id: 'narration-thinking-leak-deepseek'
+ *
+ * Per-rule walk (alpha.31 refactor): the alpha.30 short-circuit
+ * `if (!cliffFires) return passthrough` was correct when only the
+ * cliff-gated tool_call_contract rule existed; alpha.31's narration rules
+ * fire on every call regardless of cliff (narration drift is steady-state,
+ * not a cliff condition). Each section now consults the dispatch table
+ * independently — first-match wins per (section.kind, profile, archetype).
  *
  * **Interaction with the cliff advisor (alpha.28):** when this translator
  * fires for a `tool_call_contract` section, the advisor's
@@ -402,8 +418,9 @@ declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: Model
  * suppression check lives in `advisor.ts` and consults the
  * `CompileResult.sectionRewritesApplied` list.
  *
- * Design contract:
+ * Design contracts:
  *   command-center/advisory/kgauto/2026-05-21_alpha-29-translator-and-advisories-api.md
+ *   command-center/advisory/kgauto/2026-05-22_alpha-31-narration-contract.md
  */
 
 /**
@@ -415,8 +432,9 @@ declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: Model
 declare const TRANSLATOR_FLOOR = 6;
 /**
  * Stable identifier of the alpha.29 sequential-tool rule. Surfaces on
- * `SectionRewrite.rule` and in brain aggregates. Future rules extend this
- * list; the brain learns per-rule effectiveness over time.
+ * `SectionRewrite.rule` and in brain aggregates. The brain treats this
+ * identifier together with the preamble string as the rule's wire
+ * fingerprint — both stay byte-stable across releases.
  */
 declare const RULE_SEQUENTIAL_TOOL_CLIFF = "sequential-tool-cliff-below-floor";
 interface ApplySectionRewritesArgs {
@@ -442,16 +460,14 @@ interface ApplySectionRewritesResult {
  * Pure function. Apply model-aware section rewrites to the IR at compile time.
  *
  * Discipline:
- *   - Never mutates the input IR; returns a new IR with new sections array.
+ *   - Never mutates the input IR; returns a new IR with new sections array
+ *     when at least one rewrite fired; otherwise returns the input IR by
+ *     reference (referential identity preserved on no-op).
  *   - Sections without a `kind` (or `kind === 'arbitrary'`) pass through
  *     unchanged.
  *   - Empty `sections` array → returns `{ rewrittenIR: ir, rewrites: [] }`.
- *   - Missing `profile.archetypePerf` → no rewrite (defensive — treat the
- *     model as un-classified rather than below-floor).
- *   - Sections of the same `kind` are processed in array order; the rule
- *     fires once per matching section (today every tool_call_contract
- *     section gets the same prepend — multiple sections of the same kind
- *     ARE supported but is an unusual consumer shape).
+ *   - Sections of the same `kind` are processed in array order; first-match
+ *     wins per section. (Today every rule is a single-match rule.)
  *
  * @example
  * ```ts

package/dist/index.d.ts

@@ -374,26 +374,42 @@ interface RunAdvisorPhase2Context {
 declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: ModelProfile, policy?: CompilePolicy, phase2?: RunAdvisorPhase2Context): BestPracticeAdvisory[];
 
 /**
- * Translator primitive — alpha.29.
+ * Translator primitive — alpha.31.
  *
  * Pure function. Walks `IR.sections`, matches each section's `kind` against
- * the model + archetype + profile, and applies a model-aware rewrite when
- * a rule fires. Returns the rewritten IR + the list of rewrites for
- * `CompileResult.sectionRewritesApplied` and brain persistence.
+ * a per-rule dispatch table keyed on (kind, profile, archetype), and applies
+ * a model-aware rewrite when a rule fires. Returns the rewritten IR + the
+ * list of rewrites for `CompileResult.sectionRewritesApplied` and brain
+ * persistence.
  *
  * This is the s37 translator-framing eureka in code: kgauto graduates from
  * "gate" (alpha.28's cliff advisor: "consumer must accept adapter") to
  * "translator" (alpha.29: "consumer declared the section kind, kgauto
  * applies the adapter at compile time without consumer-side branching").
  *
- * alpha.29 ships ONE rule:
+ * Rules shipped:
  *
- *   tool_call_contract + profile.archetypePerf[archetype] < ARCHETYPE_FLOOR_DEFAULT
+ *   alpha.29 — tool_call_contract + archetypePerf[archetype] < TRANSLATOR_FLOOR
  *     → prepend sequential-tool-pattern guidance
  *     → emit wireOverrides: { parallelToolCalls: false }
+ *     → rule_id: 'sequential-tool-cliff-below-floor'
  *
- * alpha.30+ will extend the rule table to `narration_contract`, `role_intro`,
- * etc. Each new rule lands here as an explicit branch.
+ *   alpha.31 — narration_contract + profile.provider === 'anthropic'
+ *     → prepend terse-log narration guidance
+ *     → no wireOverrides
+ *     → rule_id: 'narration-drift-anthropic'
+ *
+ *   alpha.31 — narration_contract + profile.provider === 'deepseek'
+ *     → prepend <thinking>-suppression guidance
+ *     → no wireOverrides
+ *     → rule_id: 'narration-thinking-leak-deepseek'
+ *
+ * Per-rule walk (alpha.31 refactor): the alpha.30 short-circuit
+ * `if (!cliffFires) return passthrough` was correct when only the
+ * cliff-gated tool_call_contract rule existed; alpha.31's narration rules
+ * fire on every call regardless of cliff (narration drift is steady-state,
+ * not a cliff condition). Each section now consults the dispatch table
+ * independently — first-match wins per (section.kind, profile, archetype).
  *
  * **Interaction with the cliff advisor (alpha.28):** when this translator
  * fires for a `tool_call_contract` section, the advisor's
@@ -402,8 +418,9 @@ declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: Model
  * suppression check lives in `advisor.ts` and consults the
  * `CompileResult.sectionRewritesApplied` list.
  *
- * Design contract:
+ * Design contracts:
  *   command-center/advisory/kgauto/2026-05-21_alpha-29-translator-and-advisories-api.md
+ *   command-center/advisory/kgauto/2026-05-22_alpha-31-narration-contract.md
  */
 
 /**
@@ -415,8 +432,9 @@ declare function runAdvisor(ir: PromptIR, result: AdvisorContext, profile: Model
 declare const TRANSLATOR_FLOOR = 6;
 /**
  * Stable identifier of the alpha.29 sequential-tool rule. Surfaces on
- * `SectionRewrite.rule` and in brain aggregates. Future rules extend this
- * list; the brain learns per-rule effectiveness over time.
+ * `SectionRewrite.rule` and in brain aggregates. The brain treats this
+ * identifier together with the preamble string as the rule's wire
+ * fingerprint — both stay byte-stable across releases.
  */
 declare const RULE_SEQUENTIAL_TOOL_CLIFF = "sequential-tool-cliff-below-floor";
 interface ApplySectionRewritesArgs {
@@ -442,16 +460,14 @@ interface ApplySectionRewritesResult {
  * Pure function. Apply model-aware section rewrites to the IR at compile time.
  *
  * Discipline:
- *   - Never mutates the input IR; returns a new IR with new sections array.
+ *   - Never mutates the input IR; returns a new IR with new sections array
+ *     when at least one rewrite fired; otherwise returns the input IR by
+ *     reference (referential identity preserved on no-op).
  *   - Sections without a `kind` (or `kind === 'arbitrary'`) pass through
  *     unchanged.
  *   - Empty `sections` array → returns `{ rewrittenIR: ir, rewrites: [] }`.
- *   - Missing `profile.archetypePerf` → no rewrite (defensive — treat the
- *     model as un-classified rather than below-floor).
- *   - Sections of the same `kind` are processed in array order; the rule
- *     fires once per matching section (today every tool_call_contract
- *     section gets the same prepend — multiple sections of the same kind
- *     ARE supported but is an unusual consumer shape).
+ *   - Sections of the same `kind` are processed in array order; first-match
+ *     wins per section. (Today every rule is a single-match rule.)
  *
  * @example
  * ```ts

package/dist/index.js

@@ -2630,34 +2630,62 @@ function detectArchetypePerfFloorBreach(ir, profile) {
 // src/translator.ts
 var TRANSLATOR_FLOOR = ARCHETYPE_FLOOR_DEFAULT;
 var RULE_SEQUENTIAL_TOOL_CLIFF = "sequential-tool-cliff-below-floor";
+var RULE_NARRATION_DRIFT_ANTHROPIC = "narration-drift-anthropic";
+var RULE_NARRATION_THINKING_LEAK_DEEPSEEK = "narration-thinking-leak-deepseek";
 var SEQUENTIAL_TOOL_PREAMBLE = "IMPORTANT: Use one tool call per response. Wait for the tool result before deciding the next tool. Do NOT batch tool calls in parallel.";
+var NARRATION_DRIFT_ANTHROPIC_PREAMBLE = "Output ONLY the requested content. Do not narrate your thought process. Each line \u2264 12 words.";
+var NARRATION_THINKING_LEAK_DEEPSEEK_PREAMBLE = "Reasoning is internal. Output ONLY the requested content; do not emit <thinking> blocks or internal monologue as user-facing text.";
+function matchRule(kind, profile, archetype) {
+  if (kind === "tool_call_contract") {
+    if (!profile.archetypePerf) return null;
+    const archetypeScore = profile.archetypePerf[archetype];
+    if (typeof archetypeScore !== "number" || archetypeScore >= TRANSLATOR_FLOOR) {
+      return null;
+    }
+    return {
+      id: RULE_SEQUENTIAL_TOOL_CLIFF,
+      preamble: SEQUENTIAL_TOOL_PREAMBLE,
+      wireOverrides: { parallelToolCalls: false }
+    };
+  }
+  if (kind === "narration_contract") {
+    if (profile.provider === "anthropic") {
+      return {
+        id: RULE_NARRATION_DRIFT_ANTHROPIC,
+        preamble: NARRATION_DRIFT_ANTHROPIC_PREAMBLE
+      };
+    }
+    if (profile.provider === "deepseek") {
+      return {
+        id: RULE_NARRATION_THINKING_LEAK_DEEPSEEK,
+        preamble: NARRATION_THINKING_LEAK_DEEPSEEK_PREAMBLE
+      };
+    }
+    return null;
+  }
+  return null;
+}
 function applySectionRewrites(args) {
   const { ir, profile, archetype } = args;
   if (!Array.isArray(ir.sections) || ir.sections.length === 0) {
     return { rewrittenIR: ir, rewrites: [] };
   }
-  if (!profile.archetypePerf) {
-    return { rewrittenIR: ir, rewrites: [] };
-  }
-  const archetypeScore = profile.archetypePerf[archetype];
-  const cliffFires = typeof archetypeScore === "number" && archetypeScore < TRANSLATOR_FLOOR;
-  if (!cliffFires) {
-    return { rewrittenIR: ir, rewrites: [] };
-  }
   const rewrites = [];
   const newSections = ir.sections.map((section) => {
-    if (section.kind !== "tool_call_contract") return section;
+    if (!section.kind || section.kind === "arbitrary") return section;
+    const rule = matchRule(section.kind, profile, archetype);
+    if (!rule) return section;
     const originalText = section.text;
-    const transformedText = `${SEQUENTIAL_TOOL_PREAMBLE}
+    const transformedText = `${rule.preamble}
 
 ${originalText}`;
     rewrites.push({
       sectionId: section.id,
-      kind: "tool_call_contract",
-      rule: RULE_SEQUENTIAL_TOOL_CLIFF,
+      kind: section.kind,
+      rule: rule.id,
       originalText,
       transformedText,
-      wireOverrides: { parallelToolCalls: false }
+      ...rule.wireOverrides ? { wireOverrides: rule.wireOverrides } : {}
     });
     return { ...section, text: transformedText };
   });

package/dist/index.mjs

@@ -1056,34 +1056,62 @@ function detectArchetypePerfFloorBreach(ir, profile) {
 // src/translator.ts
 var TRANSLATOR_FLOOR = ARCHETYPE_FLOOR_DEFAULT;
 var RULE_SEQUENTIAL_TOOL_CLIFF = "sequential-tool-cliff-below-floor";
+var RULE_NARRATION_DRIFT_ANTHROPIC = "narration-drift-anthropic";
+var RULE_NARRATION_THINKING_LEAK_DEEPSEEK = "narration-thinking-leak-deepseek";
 var SEQUENTIAL_TOOL_PREAMBLE = "IMPORTANT: Use one tool call per response. Wait for the tool result before deciding the next tool. Do NOT batch tool calls in parallel.";
+var NARRATION_DRIFT_ANTHROPIC_PREAMBLE = "Output ONLY the requested content. Do not narrate your thought process. Each line \u2264 12 words.";
+var NARRATION_THINKING_LEAK_DEEPSEEK_PREAMBLE = "Reasoning is internal. Output ONLY the requested content; do not emit <thinking> blocks or internal monologue as user-facing text.";
+function matchRule(kind, profile, archetype) {
+  if (kind === "tool_call_contract") {
+    if (!profile.archetypePerf) return null;
+    const archetypeScore = profile.archetypePerf[archetype];
+    if (typeof archetypeScore !== "number" || archetypeScore >= TRANSLATOR_FLOOR) {
+      return null;
+    }
+    return {
+      id: RULE_SEQUENTIAL_TOOL_CLIFF,
+      preamble: SEQUENTIAL_TOOL_PREAMBLE,
+      wireOverrides: { parallelToolCalls: false }
+    };
+  }
+  if (kind === "narration_contract") {
+    if (profile.provider === "anthropic") {
+      return {
+        id: RULE_NARRATION_DRIFT_ANTHROPIC,
+        preamble: NARRATION_DRIFT_ANTHROPIC_PREAMBLE
+      };
+    }
+    if (profile.provider === "deepseek") {
+      return {
+        id: RULE_NARRATION_THINKING_LEAK_DEEPSEEK,
+        preamble: NARRATION_THINKING_LEAK_DEEPSEEK_PREAMBLE
+      };
+    }
+    return null;
+  }
+  return null;
+}
 function applySectionRewrites(args) {
   const { ir, profile, archetype } = args;
   if (!Array.isArray(ir.sections) || ir.sections.length === 0) {
     return { rewrittenIR: ir, rewrites: [] };
   }
-  if (!profile.archetypePerf) {
-    return { rewrittenIR: ir, rewrites: [] };
-  }
-  const archetypeScore = profile.archetypePerf[archetype];
-  const cliffFires = typeof archetypeScore === "number" && archetypeScore < TRANSLATOR_FLOOR;
-  if (!cliffFires) {
-    return { rewrittenIR: ir, rewrites: [] };
-  }
   const rewrites = [];
   const newSections = ir.sections.map((section) => {
-    if (section.kind !== "tool_call_contract") return section;
+    if (!section.kind || section.kind === "arbitrary") return section;
+    const rule = matchRule(section.kind, profile, archetype);
+    if (!rule) return section;
     const originalText = section.text;
-    const transformedText = `${SEQUENTIAL_TOOL_PREAMBLE}
+    const transformedText = `${rule.preamble}
 
 ${originalText}`;
     rewrites.push({
       sectionId: section.id,
-      kind: "tool_call_contract",
-      rule: RULE_SEQUENTIAL_TOOL_CLIFF,
+      kind: section.kind,
+      rule: rule.id,
       originalText,
       transformedText,
-      wireOverrides: { parallelToolCalls: false }
+      ...rule.wireOverrides ? { wireOverrides: rule.wireOverrides } : {}
     });
     return { ...section, text: transformedText };
   });

package/package.json

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