@warmdrift/kgauto-compiler 2.0.0-alpha.75 → 2.0.0-alpha.77

package/dist/index.js

@@ -25,7 +25,10 @@ __export(index_exports, {
   ALL_ARCHETYPES: () => ALL_ARCHETYPES,
   ARCHETYPE_FAMILY_FITS: () => ARCHETYPE_FAMILY_FITS,
   ARCHETYPE_FLOOR_DEFAULT: () => ARCHETYPE_FLOOR_DEFAULT,
+  COACH_CFG: () => COACH_CFG,
   CallError: () => CallError,
+  DECOMPOSITION_TEMPLATES: () => DECOMPOSITION_TEMPLATES,
+  DECOMPOSITION_TEMPLATES_VERSION: () => DECOMPOSITION_TEMPLATES_VERSION,
   DEFAULT_FINDINGS_ENDPOINT: () => DEFAULT_FINDINGS_ENDPOINT,
   DEFAULT_MEASURED_FAILURE_ENDPOINT: () => DEFAULT_MEASURED_FAILURE_ENDPOINT,
   DEFAULT_PROMOTIONS_ENDPOINT: () => DEFAULT_PROMOTIONS_ENDPOINT,
@@ -125,6 +128,7 @@ __export(index_exports, {
   parseGoldenCaptureRate: () => parseGoldenCaptureRate,
   parseJudgeVerdict: () => parseJudgeVerdict,
   peekBrainDeadLetter: () => peekBrainDeadLetter,
+  planDecomposition: () => planDecomposition,
   prefetchMeasuredFailure: () => prefetchMeasuredFailure,
   probeShadow: () => probeShadow,
   profileToRow: () => profileToRow,
@@ -6422,8 +6426,33 @@ function isAuthSignatureBody(body, message) {
   const m = message.toLowerCase();
   return m.includes("api key not valid") || m.includes("invalid api key") || m.includes("invalid x-api-key") || m.includes("incorrect api key");
 }
+function isBillingExhaustedBody(status, body, message) {
+  if (status === 402) return true;
+  const m = message.toLowerCase();
+  if (m.includes("free_tier") || m.includes("free tier")) return false;
+  if (m.includes("credit balance is too low")) return true;
+  if (m.includes("insufficient balance")) return true;
+  if (m.includes("billingnotenabled") || m.includes("billing not enabled")) return true;
+  if (body && typeof body === "object") {
+    const err = body.error;
+    if (err && typeof err === "object") {
+      const e = err;
+      if (e.code === "insufficient_quota" || e.type === "insufficient_quota") return true;
+      if (Array.isArray(e.details)) {
+        for (const d of e.details) {
+          if (d && typeof d === "object" && d.reason === "BILLING_DISABLED") {
+            return true;
+          }
+        }
+      }
+    }
+  }
+  return false;
+}
 function classifyHttpError(status, body) {
   const message = extractErrorMessage(body) ?? `HTTP ${status}`;
+  if (isBillingExhaustedBody(status, body, message))
+    return { ok: false, status, errorType: "terminal", errorCode: "billing_exhausted", message, raw: body };
   if (status === 429)
     return { ok: false, status, errorType: "retryable", errorCode: "rate_limit", message, raw: body };
   if (status === 408)
@@ -6687,6 +6716,9 @@ function applyOverrides(request, overrides) {
 }
 function classifyHttpError2(status, body) {
   const message = extractErrorMessage2(body) ?? `HTTP ${status}`;
+  if (isBillingExhaustedBody(status, body, message)) {
+    return { ok: false, status, errorType: "terminal", errorCode: "billing_exhausted", message, raw: body };
+  }
   if (status === 429) {
     return { ok: false, status, errorType: "retryable", errorCode: "rate_limit", message, raw: body };
   }
@@ -7529,18 +7561,19 @@ async function call(ir, opts = {}) {
   }
   let activeCompile = initial;
   let lastErr;
-  const failedProviders = /* @__PURE__ */ new Set();
+  const failedProviders = /* @__PURE__ */ new Map();
   const sameModelRetryEnabled = opts.sameModelRetry ?? isSameModelRetryEnabledFromEnv();
   let retriedSameModel = false;
   for (let i = 0; i < targetsToTry.length; i++) {
     const targetModel = targetsToTry[i];
     const targetProfile = tryGetProfile(targetModel);
-    if (targetProfile && failedProviders.has(targetProfile.provider) && !opts.noFallback) {
+    const providerFailReason = targetProfile ? failedProviders.get(targetProfile.provider) : void 0;
+    if (targetProfile && providerFailReason && !opts.noFallback) {
       attempts.push({
         model: targetModel,
         status: "terminal",
-        errorCode: "auth_inferred",
-        message: `Skipped \u2014 provider ${targetProfile.provider} returned 401/403 earlier in this call; same key inferred to fail`
+        errorCode: `${providerFailReason}_inferred`,
+        message: providerFailReason === "billing_exhausted" ? `Skipped \u2014 provider ${targetProfile.provider} is out of credits (seen earlier in this call); a billing failure is account-wide, so this attempt cannot succeed until a human funds the account` : `Skipped \u2014 provider ${targetProfile.provider} returned 401/403 earlier in this call; same key inferred to fail`
       });
       continue;
     }
@@ -7722,15 +7755,18 @@ async function call(ir, opts = {}) {
     });
     lastErr = validated;
     if (validated.errorType === "terminal" || opts.noFallback) {
-      if (validated.errorCode === "auth" && !opts.noFallback && activeCompile.provider) {
-        failedProviders.add(activeCompile.provider);
+      if ((validated.errorCode === "auth" || validated.errorCode === "billing_exhausted") && !opts.noFallback && activeCompile.provider) {
+        failedProviders.set(
+          activeCompile.provider,
+          validated.errorCode === "billing_exhausted" ? "billing_exhausted" : "auth"
+        );
         continue;
       }
       break;
     }
   }
   const lastAttempted = [...attempts].reverse().find(
-    (a) => a.status !== "success" && a.errorCode !== "auth_inferred" && a.errorCode !== "compile_error"
+    (a) => a.status !== "success" && a.errorCode !== "auth_inferred" && a.errorCode !== "billing_exhausted_inferred" && a.errorCode !== "compile_error"
   );
   const latencyMs = Date.now() - start;
   await record({
@@ -8052,6 +8088,9 @@ function normalizeFallbackReason(attempts) {
   }
   if (code === "cost_cap_exceeded") return "cost_cap";
   if (code === "auth" || code === "auth_inferred") return "provider_auth_failed";
+  if (code === "billing_exhausted" || code === "billing_exhausted_inferred") {
+    return "provider_billing_exhausted";
+  }
   return "provider_error";
 }
 function generateTraceId() {
@@ -9039,7 +9078,7 @@ function createBrainForwardRoutes(config) {
 }
 
 // src/version.ts
-var LIBRARY_VERSION = "2.0.0-alpha.75";
+var LIBRARY_VERSION = "2.0.0-alpha.77";
 
 // src/key-health.ts
 var JSON_HEADERS2 = { "Content-Type": "application/json" };
@@ -9657,6 +9696,211 @@ async function markExclusionFindingHandled(opts) {
   return { ok: true };
 }
 
+// src/decomposition.ts
+var DECOMPOSITION_TEMPLATES_VERSION = "decomposition-templates-v1";
+var DECOMPOSITION_TEMPLATES = {
+  summarize: {
+    archetype: "summarize",
+    version: DECOMPOSITION_TEMPLATES_VERSION,
+    rationale: "A long-input summarize is mostly reading. A cheap extractor reads the full payload and emits compressed notes; the incumbent composes the summary from the notes \u2014 frontier tokens are spent only on the part that needs frontier judgment.",
+    steps: [
+      {
+        role: "chunk-extract",
+        archetype: "extract",
+        tier: "delegate",
+        inputShare: 1,
+        emitsShareOfInput: 0.15,
+        outputShare: 0
+      },
+      {
+        role: "compose",
+        archetype: "summarize",
+        tier: "anchor",
+        inputShare: 0.15,
+        // reads the notes, not the raw payload
+        emitsShareOfInput: 0,
+        outputShare: 1
+      }
+    ]
+  },
+  hunt: {
+    archetype: "hunt",
+    version: DECOMPOSITION_TEMPLATES_VERSION,
+    rationale: "Hunt decomposes into breadth (search sweeps), mechanical harvesting (extraction), and judgment (dedupe + compose). The sweeps and the harvest are grunt work; the composition anchors on the incumbent.",
+    steps: [
+      {
+        role: "search-sweep",
+        archetype: "hunt",
+        tier: "delegate",
+        inputShare: 0.5,
+        emitsShareOfInput: 0.2,
+        outputShare: 0
+      },
+      {
+        role: "harvest",
+        archetype: "extract",
+        tier: "delegate",
+        inputShare: 0.35,
+        emitsShareOfInput: 0.1,
+        outputShare: 0
+      },
+      {
+        role: "dedupe-compose",
+        archetype: "judge",
+        tier: "anchor",
+        inputShare: 0.3,
+        // sweep notes + harvest notes
+        emitsShareOfInput: 0,
+        outputShare: 1
+      }
+    ]
+  },
+  plan: {
+    archetype: "plan",
+    version: DECOMPOSITION_TEMPLATES_VERSION,
+    rationale: "Planning splits into context-gathering (mechanical reading) and the plan itself (judgment). The gatherer reads the corpus and briefs; the incumbent plans from the brief.",
+    steps: [
+      {
+        role: "gather-brief",
+        archetype: "extract",
+        tier: "delegate",
+        inputShare: 1,
+        emitsShareOfInput: 0.2,
+        outputShare: 0
+      },
+      {
+        role: "draft-plan",
+        archetype: "plan",
+        tier: "anchor",
+        inputShare: 0.2,
+        emitsShareOfInput: 0,
+        outputShare: 1
+      }
+    ]
+  }
+};
+var COACH_CFG = {
+  /** Same felt-utility floor as promotions (alpha.67 family). */
+  minMonthlySavingUsd: 5,
+  /** Executor must clear this archetypePerf on the step's archetype —
+   * same floor as the translator/advisor (ARCHETYPE_FLOOR_DEFAULT). */
+  executorPerfFloor: 6,
+  daysPerMonth: 30
+};
+function planDecomposition(args) {
+  const { stats, incumbentPricing, pickExecutor } = args;
+  const cfg = { ...COACH_CFG, ...args.cfg ?? {} };
+  const template = DECOMPOSITION_TEMPLATES[stats.archetype];
+  if (!template) return void 0;
+  const perCall = (pricing, tokensIn, tokensOut) => tokensIn / 1e6 * pricing.costInputPer1m + tokensOut / 1e6 * pricing.costOutputPer1m;
+  const monolithCostPerCallUsd = perCall(
+    incumbentPricing,
+    stats.avgTokensIn,
+    stats.avgTokensOut
+  );
+  const assumptions = [
+    `per-step token shares are ${template.version} JUDGMENT numbers \u2014 no fan-out traffic exists to measure them from yet; they graduate per surface when branch traffic lands`
+  ];
+  const steps = [];
+  let splitCostPerCallUsd = 0;
+  for (const step of template.steps) {
+    const stepTokensIn = stats.avgTokensIn * step.inputShare;
+    const stepTokensOut = stats.avgTokensIn * step.emitsShareOfInput + stats.avgTokensOut * step.outputShare;
+    if (step.tier === "anchor") {
+      const cost2 = perCall(incumbentPricing, stepTokensIn, stepTokensOut);
+      splitCostPerCallUsd += cost2;
+      steps.push({
+        ...step,
+        executorModel: stats.incumbentModel,
+        executorGrounding: "measured",
+        // the incumbent IS the measured baseline
+        executorPerfScore: null,
+        projectedCostPerCallUsd: cost2
+      });
+      continue;
+    }
+    const candidate = pickExecutor(step.archetype);
+    if (candidate && candidate.modelId === stats.incumbentModel) {
+      const cost2 = perCall(incumbentPricing, stepTokensIn, stepTokensOut);
+      splitCostPerCallUsd += cost2;
+      steps.push({
+        ...step,
+        tier: "anchor",
+        executorModel: stats.incumbentModel,
+        executorGrounding: candidate.grounding,
+        executorPerfScore: candidate.perfScore,
+        projectedCostPerCallUsd: cost2
+      });
+      assumptions.push(
+        `step '${step.role}': the cheapest qualified executor IS the incumbent \u2014 nothing to delegate to`
+      );
+      continue;
+    }
+    if (!candidate || candidate.perfScore < cfg.executorPerfFloor) {
+      const cost2 = perCall(incumbentPricing, stepTokensIn, stepTokensOut);
+      splitCostPerCallUsd += cost2;
+      steps.push({
+        ...step,
+        tier: "anchor",
+        executorModel: stats.incumbentModel,
+        executorGrounding: "measured",
+        executorPerfScore: candidate?.perfScore ?? null,
+        projectedCostPerCallUsd: cost2
+      });
+      assumptions.push(
+        `step '${step.role}' (${step.archetype}): no executor clears the perf floor ${cfg.executorPerfFloor} \u2014 kept on the incumbent`
+      );
+      continue;
+    }
+    const cost = perCall(candidate, stepTokensIn, stepTokensOut);
+    splitCostPerCallUsd += cost;
+    steps.push({
+      ...step,
+      executorModel: candidate.modelId,
+      executorGrounding: candidate.grounding,
+      executorPerfScore: candidate.perfScore,
+      projectedCostPerCallUsd: cost
+    });
+    if (candidate.grounding === "judgment") {
+      assumptions.push(
+        `step '${step.role}': ${candidate.modelId} perf ${candidate.perfScore}/10 on ${step.archetype} is JUDGMENT-grounded (no measured portfolio outcomes for the tuple yet)`
+      );
+    }
+  }
+  const savingPerCallUsd = monolithCostPerCallUsd - splitCostPerCallUsd;
+  const monthlyCalls = stats.nCalls / stats.windowDays * cfg.daysPerMonth;
+  const projectedMonthlySavingUsd = savingPerCallUsd * monthlyCalls;
+  const breakEvenMonthlyCalls = savingPerCallUsd > 0 ? cfg.minMonthlySavingUsd / savingPerCallUsd : null;
+  let verdict;
+  let verdictReason;
+  if (savingPerCallUsd <= 0) {
+    verdict = "keep-monolith";
+    verdictReason = "the split costs MORE per call than the monolith at current pricing \u2014 no volume makes it pay";
+  } else if (projectedMonthlySavingUsd < cfg.minMonthlySavingUsd) {
+    verdict = "keep-monolith";
+    verdictReason = `the split pays $${projectedMonthlySavingUsd.toFixed(2)}/mo at your ~${Math.round(monthlyCalls)} calls/mo \u2014 below the $${cfg.minMonthlySavingUsd} felt-utility floor. Break-even is ~${Math.ceil(breakEvenMonthlyCalls ?? 0)} calls/mo; revisit when volume gets there. Decomposition adds moving parts, and a saving you can't feel doesn't buy them`;
+  } else {
+    verdict = "split-pays";
+    verdictReason = `projected $${projectedMonthlySavingUsd.toFixed(2)}/mo saving at ~${Math.round(monthlyCalls)} calls/mo (monolith $${monolithCostPerCallUsd.toFixed(4)}/call \u2192 split $${splitCostPerCallUsd.toFixed(4)}/call)`;
+  }
+  return {
+    appId: stats.appId,
+    archetype: String(stats.archetype),
+    incumbentModel: stats.incumbentModel,
+    template,
+    steps,
+    monolithCostPerCallUsd,
+    splitCostPerCallUsd,
+    savingPerCallUsd,
+    monthlyCalls,
+    projectedMonthlySavingUsd,
+    breakEvenMonthlyCalls,
+    verdict,
+    verdictReason,
+    assumptions
+  };
+}
+
 // src/index.ts
 function compile2(ir, opts) {
   const result = compile(ir, opts);
@@ -9670,7 +9914,10 @@ function compile2(ir, opts) {
   ALL_ARCHETYPES,
   ARCHETYPE_FAMILY_FITS,
   ARCHETYPE_FLOOR_DEFAULT,
+  COACH_CFG,
   CallError,
+  DECOMPOSITION_TEMPLATES,
+  DECOMPOSITION_TEMPLATES_VERSION,
   DEFAULT_FINDINGS_ENDPOINT,
   DEFAULT_MEASURED_FAILURE_ENDPOINT,
   DEFAULT_PROMOTIONS_ENDPOINT,
@@ -9770,6 +10017,7 @@ function compile2(ir, opts) {
   parseGoldenCaptureRate,
   parseJudgeVerdict,
   peekBrainDeadLetter,
+  planDecomposition,
   prefetchMeasuredFailure,
   probeShadow,
   profileToRow,

package/dist/index.mjs

@@ -16,7 +16,7 @@ import {
 import {
   LIBRARY_VERSION,
   createKeyHealthRoute
-} from "./chunk-WP22F3CX.mjs";
+} from "./chunk-GB7VJQ6C.mjs";
 import {
   ABSOLUTE_FLOOR,
   ARCHETYPE_FLOOR_DEFAULT,
@@ -4222,8 +4222,33 @@ function isAuthSignatureBody(body, message) {
   const m = message.toLowerCase();
   return m.includes("api key not valid") || m.includes("invalid api key") || m.includes("invalid x-api-key") || m.includes("incorrect api key");
 }
+function isBillingExhaustedBody(status, body, message) {
+  if (status === 402) return true;
+  const m = message.toLowerCase();
+  if (m.includes("free_tier") || m.includes("free tier")) return false;
+  if (m.includes("credit balance is too low")) return true;
+  if (m.includes("insufficient balance")) return true;
+  if (m.includes("billingnotenabled") || m.includes("billing not enabled")) return true;
+  if (body && typeof body === "object") {
+    const err = body.error;
+    if (err && typeof err === "object") {
+      const e = err;
+      if (e.code === "insufficient_quota" || e.type === "insufficient_quota") return true;
+      if (Array.isArray(e.details)) {
+        for (const d of e.details) {
+          if (d && typeof d === "object" && d.reason === "BILLING_DISABLED") {
+            return true;
+          }
+        }
+      }
+    }
+  }
+  return false;
+}
 function classifyHttpError(status, body) {
   const message = extractErrorMessage(body) ?? `HTTP ${status}`;
+  if (isBillingExhaustedBody(status, body, message))
+    return { ok: false, status, errorType: "terminal", errorCode: "billing_exhausted", message, raw: body };
   if (status === 429)
     return { ok: false, status, errorType: "retryable", errorCode: "rate_limit", message, raw: body };
   if (status === 408)
@@ -4487,6 +4512,9 @@ function applyOverrides(request, overrides) {
 }
 function classifyHttpError2(status, body) {
   const message = extractErrorMessage2(body) ?? `HTTP ${status}`;
+  if (isBillingExhaustedBody(status, body, message)) {
+    return { ok: false, status, errorType: "terminal", errorCode: "billing_exhausted", message, raw: body };
+  }
   if (status === 429) {
     return { ok: false, status, errorType: "retryable", errorCode: "rate_limit", message, raw: body };
   }
@@ -4675,18 +4703,19 @@ async function call(ir, opts = {}) {
   }
   let activeCompile = initial;
   let lastErr;
-  const failedProviders = /* @__PURE__ */ new Set();
+  const failedProviders = /* @__PURE__ */ new Map();
   const sameModelRetryEnabled = opts.sameModelRetry ?? isSameModelRetryEnabledFromEnv();
   let retriedSameModel = false;
   for (let i = 0; i < targetsToTry.length; i++) {
     const targetModel = targetsToTry[i];
     const targetProfile = tryGetProfile(targetModel);
-    if (targetProfile && failedProviders.has(targetProfile.provider) && !opts.noFallback) {
+    const providerFailReason = targetProfile ? failedProviders.get(targetProfile.provider) : void 0;
+    if (targetProfile && providerFailReason && !opts.noFallback) {
       attempts.push({
         model: targetModel,
         status: "terminal",
-        errorCode: "auth_inferred",
-        message: `Skipped \u2014 provider ${targetProfile.provider} returned 401/403 earlier in this call; same key inferred to fail`
+        errorCode: `${providerFailReason}_inferred`,
+        message: providerFailReason === "billing_exhausted" ? `Skipped \u2014 provider ${targetProfile.provider} is out of credits (seen earlier in this call); a billing failure is account-wide, so this attempt cannot succeed until a human funds the account` : `Skipped \u2014 provider ${targetProfile.provider} returned 401/403 earlier in this call; same key inferred to fail`
       });
       continue;
     }
@@ -4868,15 +4897,18 @@ async function call(ir, opts = {}) {
     });
     lastErr = validated;
     if (validated.errorType === "terminal" || opts.noFallback) {
-      if (validated.errorCode === "auth" && !opts.noFallback && activeCompile.provider) {
-        failedProviders.add(activeCompile.provider);
+      if ((validated.errorCode === "auth" || validated.errorCode === "billing_exhausted") && !opts.noFallback && activeCompile.provider) {
+        failedProviders.set(
+          activeCompile.provider,
+          validated.errorCode === "billing_exhausted" ? "billing_exhausted" : "auth"
+        );
         continue;
       }
       break;
     }
   }
   const lastAttempted = [...attempts].reverse().find(
-    (a) => a.status !== "success" && a.errorCode !== "auth_inferred" && a.errorCode !== "compile_error"
+    (a) => a.status !== "success" && a.errorCode !== "auth_inferred" && a.errorCode !== "billing_exhausted_inferred" && a.errorCode !== "compile_error"
   );
   const latencyMs = Date.now() - start;
   await record({
@@ -5198,6 +5230,9 @@ function normalizeFallbackReason(attempts) {
   }
   if (code === "cost_cap_exceeded") return "cost_cap";
   if (code === "auth" || code === "auth_inferred") return "provider_auth_failed";
+  if (code === "billing_exhausted" || code === "billing_exhausted_inferred") {
+    return "provider_billing_exhausted";
+  }
   return "provider_error";
 }
 function generateTraceId() {
@@ -6438,6 +6473,211 @@ async function markExclusionFindingHandled(opts) {
   return { ok: true };
 }
 
+// src/decomposition.ts
+var DECOMPOSITION_TEMPLATES_VERSION = "decomposition-templates-v1";
+var DECOMPOSITION_TEMPLATES = {
+  summarize: {
+    archetype: "summarize",
+    version: DECOMPOSITION_TEMPLATES_VERSION,
+    rationale: "A long-input summarize is mostly reading. A cheap extractor reads the full payload and emits compressed notes; the incumbent composes the summary from the notes \u2014 frontier tokens are spent only on the part that needs frontier judgment.",
+    steps: [
+      {
+        role: "chunk-extract",
+        archetype: "extract",
+        tier: "delegate",
+        inputShare: 1,
+        emitsShareOfInput: 0.15,
+        outputShare: 0
+      },
+      {
+        role: "compose",
+        archetype: "summarize",
+        tier: "anchor",
+        inputShare: 0.15,
+        // reads the notes, not the raw payload
+        emitsShareOfInput: 0,
+        outputShare: 1
+      }
+    ]
+  },
+  hunt: {
+    archetype: "hunt",
+    version: DECOMPOSITION_TEMPLATES_VERSION,
+    rationale: "Hunt decomposes into breadth (search sweeps), mechanical harvesting (extraction), and judgment (dedupe + compose). The sweeps and the harvest are grunt work; the composition anchors on the incumbent.",
+    steps: [
+      {
+        role: "search-sweep",
+        archetype: "hunt",
+        tier: "delegate",
+        inputShare: 0.5,
+        emitsShareOfInput: 0.2,
+        outputShare: 0
+      },
+      {
+        role: "harvest",
+        archetype: "extract",
+        tier: "delegate",
+        inputShare: 0.35,
+        emitsShareOfInput: 0.1,
+        outputShare: 0
+      },
+      {
+        role: "dedupe-compose",
+        archetype: "judge",
+        tier: "anchor",
+        inputShare: 0.3,
+        // sweep notes + harvest notes
+        emitsShareOfInput: 0,
+        outputShare: 1
+      }
+    ]
+  },
+  plan: {
+    archetype: "plan",
+    version: DECOMPOSITION_TEMPLATES_VERSION,
+    rationale: "Planning splits into context-gathering (mechanical reading) and the plan itself (judgment). The gatherer reads the corpus and briefs; the incumbent plans from the brief.",
+    steps: [
+      {
+        role: "gather-brief",
+        archetype: "extract",
+        tier: "delegate",
+        inputShare: 1,
+        emitsShareOfInput: 0.2,
+        outputShare: 0
+      },
+      {
+        role: "draft-plan",
+        archetype: "plan",
+        tier: "anchor",
+        inputShare: 0.2,
+        emitsShareOfInput: 0,
+        outputShare: 1
+      }
+    ]
+  }
+};
+var COACH_CFG = {
+  /** Same felt-utility floor as promotions (alpha.67 family). */
+  minMonthlySavingUsd: 5,
+  /** Executor must clear this archetypePerf on the step's archetype —
+   * same floor as the translator/advisor (ARCHETYPE_FLOOR_DEFAULT). */
+  executorPerfFloor: 6,
+  daysPerMonth: 30
+};
+function planDecomposition(args) {
+  const { stats, incumbentPricing, pickExecutor } = args;
+  const cfg = { ...COACH_CFG, ...args.cfg ?? {} };
+  const template = DECOMPOSITION_TEMPLATES[stats.archetype];
+  if (!template) return void 0;
+  const perCall = (pricing, tokensIn, tokensOut) => tokensIn / 1e6 * pricing.costInputPer1m + tokensOut / 1e6 * pricing.costOutputPer1m;
+  const monolithCostPerCallUsd = perCall(
+    incumbentPricing,
+    stats.avgTokensIn,
+    stats.avgTokensOut
+  );
+  const assumptions = [
+    `per-step token shares are ${template.version} JUDGMENT numbers \u2014 no fan-out traffic exists to measure them from yet; they graduate per surface when branch traffic lands`
+  ];
+  const steps = [];
+  let splitCostPerCallUsd = 0;
+  for (const step of template.steps) {
+    const stepTokensIn = stats.avgTokensIn * step.inputShare;
+    const stepTokensOut = stats.avgTokensIn * step.emitsShareOfInput + stats.avgTokensOut * step.outputShare;
+    if (step.tier === "anchor") {
+      const cost2 = perCall(incumbentPricing, stepTokensIn, stepTokensOut);
+      splitCostPerCallUsd += cost2;
+      steps.push({
+        ...step,
+        executorModel: stats.incumbentModel,
+        executorGrounding: "measured",
+        // the incumbent IS the measured baseline
+        executorPerfScore: null,
+        projectedCostPerCallUsd: cost2
+      });
+      continue;
+    }
+    const candidate = pickExecutor(step.archetype);
+    if (candidate && candidate.modelId === stats.incumbentModel) {
+      const cost2 = perCall(incumbentPricing, stepTokensIn, stepTokensOut);
+      splitCostPerCallUsd += cost2;
+      steps.push({
+        ...step,
+        tier: "anchor",
+        executorModel: stats.incumbentModel,
+        executorGrounding: candidate.grounding,
+        executorPerfScore: candidate.perfScore,
+        projectedCostPerCallUsd: cost2
+      });
+      assumptions.push(
+        `step '${step.role}': the cheapest qualified executor IS the incumbent \u2014 nothing to delegate to`
+      );
+      continue;
+    }
+    if (!candidate || candidate.perfScore < cfg.executorPerfFloor) {
+      const cost2 = perCall(incumbentPricing, stepTokensIn, stepTokensOut);
+      splitCostPerCallUsd += cost2;
+      steps.push({
+        ...step,
+        tier: "anchor",
+        executorModel: stats.incumbentModel,
+        executorGrounding: "measured",
+        executorPerfScore: candidate?.perfScore ?? null,
+        projectedCostPerCallUsd: cost2
+      });
+      assumptions.push(
+        `step '${step.role}' (${step.archetype}): no executor clears the perf floor ${cfg.executorPerfFloor} \u2014 kept on the incumbent`
+      );
+      continue;
+    }
+    const cost = perCall(candidate, stepTokensIn, stepTokensOut);
+    splitCostPerCallUsd += cost;
+    steps.push({
+      ...step,
+      executorModel: candidate.modelId,
+      executorGrounding: candidate.grounding,
+      executorPerfScore: candidate.perfScore,
+      projectedCostPerCallUsd: cost
+    });
+    if (candidate.grounding === "judgment") {
+      assumptions.push(
+        `step '${step.role}': ${candidate.modelId} perf ${candidate.perfScore}/10 on ${step.archetype} is JUDGMENT-grounded (no measured portfolio outcomes for the tuple yet)`
+      );
+    }
+  }
+  const savingPerCallUsd = monolithCostPerCallUsd - splitCostPerCallUsd;
+  const monthlyCalls = stats.nCalls / stats.windowDays * cfg.daysPerMonth;
+  const projectedMonthlySavingUsd = savingPerCallUsd * monthlyCalls;
+  const breakEvenMonthlyCalls = savingPerCallUsd > 0 ? cfg.minMonthlySavingUsd / savingPerCallUsd : null;
+  let verdict;
+  let verdictReason;
+  if (savingPerCallUsd <= 0) {
+    verdict = "keep-monolith";
+    verdictReason = "the split costs MORE per call than the monolith at current pricing \u2014 no volume makes it pay";
+  } else if (projectedMonthlySavingUsd < cfg.minMonthlySavingUsd) {
+    verdict = "keep-monolith";
+    verdictReason = `the split pays $${projectedMonthlySavingUsd.toFixed(2)}/mo at your ~${Math.round(monthlyCalls)} calls/mo \u2014 below the $${cfg.minMonthlySavingUsd} felt-utility floor. Break-even is ~${Math.ceil(breakEvenMonthlyCalls ?? 0)} calls/mo; revisit when volume gets there. Decomposition adds moving parts, and a saving you can't feel doesn't buy them`;
+  } else {
+    verdict = "split-pays";
+    verdictReason = `projected $${projectedMonthlySavingUsd.toFixed(2)}/mo saving at ~${Math.round(monthlyCalls)} calls/mo (monolith $${monolithCostPerCallUsd.toFixed(4)}/call \u2192 split $${splitCostPerCallUsd.toFixed(4)}/call)`;
+  }
+  return {
+    appId: stats.appId,
+    archetype: String(stats.archetype),
+    incumbentModel: stats.incumbentModel,
+    template,
+    steps,
+    monolithCostPerCallUsd,
+    splitCostPerCallUsd,
+    savingPerCallUsd,
+    monthlyCalls,
+    projectedMonthlySavingUsd,
+    breakEvenMonthlyCalls,
+    verdict,
+    verdictReason,
+    assumptions
+  };
+}
+
 // src/index.ts
 function compile2(ir, opts) {
   const result = compile(ir, opts);
@@ -6450,7 +6690,10 @@ export {
   ALL_ARCHETYPES,
   ARCHETYPE_FAMILY_FITS,
   ARCHETYPE_FLOOR_DEFAULT,
+  COACH_CFG,
   CallError,
+  DECOMPOSITION_TEMPLATES,
+  DECOMPOSITION_TEMPLATES_VERSION,
   DEFAULT_FINDINGS_ENDPOINT,
   DEFAULT_MEASURED_FAILURE_ENDPOINT,
   DEFAULT_PROMOTIONS_ENDPOINT,
@@ -6550,6 +6793,7 @@ export {
   parseGoldenCaptureRate,
   parseJudgeVerdict,
   peekBrainDeadLetter,
+  planDecomposition,
   prefetchMeasuredFailure,
   probeShadow,
   profileToRow,