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

package/dist/{chunk-WP22F3CX.mjs → chunk-WZZCW6NA.mjs}

@@ -1,5 +1,5 @@
 // src/version.ts
-var LIBRARY_VERSION = "2.0.0-alpha.75";
+var LIBRARY_VERSION = "2.0.0-alpha.76";
 
 // src/key-health.ts
 var JSON_HEADERS = { "Content-Type": "application/json" };

package/dist/index.d.mts

@@ -1119,7 +1119,7 @@ declare function runStrategyEvalWithAttribution(opts: Omit<GoldenEvalOptions, 'a
  * guard in `tests/version.test.ts` fails the suite (and therefore
  * `prepublishOnly`) when they diverge — a stale constant cannot reach npm.
  */
-declare const LIBRARY_VERSION = "2.0.0-alpha.75";
+declare const LIBRARY_VERSION = "2.0.0-alpha.76";
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -3222,6 +3222,142 @@ declare function getMeasuredFailureVerdict(opts: GetMeasuredFailureOpts): Measur
 declare function _testResetMeasuredFailure(): void;
 declare function _testWaitForMeasuredFailureRefresh(): Promise<void>;
 
+/**
+ * Release C (Rung 1) — the decomposition coach's planning engine.
+ *
+ * Design contract §5.1: evidence-backed advisories on the existing surface —
+ * "you're paying frontier prices for grunt work; here's the measured split."
+ * No contract change; nothing here executes a fan-out. This module is PURE:
+ * templates + arithmetic. The operator script feeds it measured surface
+ * stats and evidence-picked executors; Release D's `delegate` primitive will
+ * consume the SAME templates, so they live in the library, versioned.
+ *
+ * Honesty posture (the roster-with-receipts rule, applied to ourselves):
+ *
+ *   - The per-step token SHARES are JUDGMENT v1 numbers — labelled as such
+ *     in every plan (`assumptions[]`), versioned so a future measured
+ *     replacement invalidates nothing silently. No consumer has fan-out
+ *     traffic yet (R0 shipped alpha.68, zero adopters), so there is nothing
+ *     to measure them from; the moment branch traffic exists, these
+ *     graduate per surface.
+ *   - Executor grounding is carried per step: 'measured' when the portfolio
+ *     corpus has real outcomes for (model, sub-archetype), 'judgment' when
+ *     the roster's archetypePerf is all we have.
+ *   - The coach's most credible output at low volume is "KEEP THE MONOLITH"
+ *     with the break-even volume stated — the never-worse floor in coach
+ *     form. The advisory only files when the split is MATERIAL (same $5/mo
+ *     felt-utility floor as promotions); the demo report renders every
+ *     analysis either way.
+ */
+
+declare const DECOMPOSITION_TEMPLATES_VERSION = "decomposition-templates-v1";
+interface DecompositionStep {
+    /** Human-readable step name (stable — appears in advisories/recipes). */
+    role: string;
+    /** The sub-archetype this step runs as (its own learning_key downstream). */
+    archetype: IntentArchetypeName;
+    /**
+     * Which tier runs the step. 'delegate' steps are the grunt work the coach
+     * proposes moving to a cheap executor; 'anchor' steps stay on the
+     * incumbent (composition is where fan-outs die — §7a — so the composer
+     * anchors on the strong model by design).
+     */
+    tier: 'delegate' | 'anchor';
+    /** Share of the monolith's INPUT tokens this step reads. JUDGMENT v1. */
+    inputShare: number;
+    /**
+     * Tokens this step EMITS, as a share of the monolith's input (for
+     * intermediate artifacts like extraction notes) — the next anchor step
+     * reads these instead of the raw input. JUDGMENT v1.
+     */
+    emitsShareOfInput: number;
+    /** Share of the monolith's OUTPUT tokens this step produces (0 for
+     * intermediate steps; the anchor composer typically carries 1). */
+    outputShare: number;
+}
+interface DecompositionTemplate {
+    archetype: IntentArchetypeName;
+    steps: DecompositionStep[];
+    rationale: string;
+    version: typeof DECOMPOSITION_TEMPLATES_VERSION;
+}
+/**
+ * v1 covers the three judgment-heavy archetypes with a clear split shape.
+ * Every share number below is a judgment estimate, stated in the plan's
+ * assumptions — they exist to make the ARITHMETIC honest, not to claim
+ * precision the corpus doesn't have yet.
+ */
+declare const DECOMPOSITION_TEMPLATES: Partial<Record<IntentArchetypeName, DecompositionTemplate>>;
+interface SurfaceStats {
+    appId: string;
+    archetype: IntentArchetypeName | string;
+    /** The model serving the monolith today (most-served in the window). */
+    incumbentModel: string;
+    nCalls: number;
+    windowDays: number;
+    avgTokensIn: number;
+    avgTokensOut: number;
+}
+interface ExecutorCandidate {
+    modelId: string;
+    /** archetypePerf score on the STEP's archetype. */
+    perfScore: number;
+    grounding: 'measured' | 'judgment';
+    costInputPer1m: number;
+    costOutputPer1m: number;
+}
+interface ModelPricing {
+    costInputPer1m: number;
+    costOutputPer1m: number;
+}
+interface PlannedStep extends DecompositionStep {
+    /** The picked executor ('delegate' steps) or the incumbent ('anchor'). */
+    executorModel: string;
+    executorGrounding: 'measured' | 'judgment';
+    executorPerfScore: number | null;
+    projectedCostPerCallUsd: number;
+}
+interface DecompositionPlan {
+    appId: string;
+    archetype: string;
+    incumbentModel: string;
+    template: DecompositionTemplate;
+    steps: PlannedStep[];
+    monolithCostPerCallUsd: number;
+    splitCostPerCallUsd: number;
+    savingPerCallUsd: number;
+    monthlyCalls: number;
+    projectedMonthlySavingUsd: number;
+    /** Monthly calls at which the split clears the materiality floor. null
+     * when the split doesn't save per-call at all (then no volume helps). */
+    breakEvenMonthlyCalls: number | null;
+    verdict: 'split-pays' | 'keep-monolith';
+    verdictReason: string;
+    /** Judgment inputs, stated. Every number that is not measured is here. */
+    assumptions: string[];
+}
+declare const COACH_CFG: {
+    /** Same felt-utility floor as promotions (alpha.67 family). */
+    minMonthlySavingUsd: number;
+    /** Executor must clear this archetypePerf on the step's archetype —
+     * same floor as the translator/advisor (ARCHETYPE_FLOOR_DEFAULT). */
+    executorPerfFloor: number;
+    daysPerMonth: number;
+};
+interface PlanDecompositionArgs {
+    stats: SurfaceStats;
+    incumbentPricing: ModelPricing;
+    /**
+     * Evidence-picked executor per step archetype. Return undefined when no
+     * candidate clears the perf floor — the plan then keeps that step on the
+     * incumbent and says so (a coach must not route grunt work to a model
+     * that can't do it just because it is cheap).
+     */
+    pickExecutor: (archetype: IntentArchetypeName) => ExecutorCandidate | undefined;
+    cfg?: Partial<typeof COACH_CFG>;
+}
+declare function planDecomposition(args: PlanDecompositionArgs): DecompositionPlan | undefined;
+
 /**
  * @warmdrift/kgauto v2 — prompt compiler + central learning brain.
  *
@@ -3268,4 +3404,4 @@ declare function _testWaitForMeasuredFailureRefresh(): Promise<void>;
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, ArchetypeConvention, type ArchetypeFamilyFit, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainDeadLetterEntry, type BrainHealthSnapshot, type BrainQueryConfig, type BrainReadEnv, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, DEFAULT_FINDINGS_ENDPOINT, DEFAULT_MEASURED_FAILURE_ENDPOINT, DEFAULT_PROMOTIONS_ENDPOINT, DISCIPLINE_GATES_V1_ALT_HEADER, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetApplicablePromotionOpts, type GetDefaultFallbackChainOpts, type GetMeasuredFailureOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, type GoldenEvalAxis, type GoldenEvalCase, type GoldenEvalOptions, type GoldenEvalRunResult, type GoldenEvalStrategyId, type GoldenIrRecordInput, Grounding, IntentArchetypeName, JUDGE_RUBRICS, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_FAILURE_CFG, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type MeasuredFailureRuntime, type MeasuredFailureVerdict, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, OutputMode, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, type PromotionRow, type PromotionsRuntime, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_DISCIPLINE_GATES_V1, RULE_DISCIPLINE_GATES_V1_STRUCTURED, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, STRATEGY_AUTHORSHIP_LIMITATION, SectionRewrite, type ShadowProbeRecordInput, type StrategyAttribution, type StrategyAttributionResult, type StrategyOutcome, type SupportedProvider, type SurfaceFailureRow, SystemModelMessage, TRANSLATOR_FLOOR, _testResetMeasuredFailure, _testResetPromotions, _testWaitForMeasuredFailureRefresh, _testWaitForPromotionsRefresh, altGatesBlockFor, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, awaitMeasuredFailureReady, brainHealth, buildGoldenIrRow, buildLLMJudge, buildPairwiseJudgePrompt, buildShadowProbeRow, call, classifyStrategyOutcome, clearBrain, combineOrderSwappedVerdicts, compile, compileForAISDKv6, configureBrain, configureMeasuredFailureBrain, configurePromotionsBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, flushBrainDeadLetter, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getApplicablePromotion, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getMeasuredFailureVerdict, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isAutoPromoteEnabledFromEnv, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isMeasuredFailureBrainActive, isMeasuredFailureGateEnabledFromEnv, isModelReachable, isPromotionsBrainActive, isProviderReachable, judgeMeasuredFailure, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, parseJudgeVerdict, peekBrainDeadLetter, prefetchMeasuredFailure, probeShadow, profileToRow, readBrainReadEnv, record, recordGoldenIr, recordOutcome, recordShadowProbe, renderIrForJudge, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, rubricFor, runAdvisor, runGoldenEval, runStrategyEvalWithAttribution, setTokenizer, wilsonLowerBound, withAltDisciplineContract, withDisciplineContract };
+export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, ArchetypeConvention, type ArchetypeFamilyFit, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainDeadLetterEntry, type BrainHealthSnapshot, type BrainQueryConfig, type BrainReadEnv, COACH_CFG, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, DECOMPOSITION_TEMPLATES, DECOMPOSITION_TEMPLATES_VERSION, DEFAULT_FINDINGS_ENDPOINT, DEFAULT_MEASURED_FAILURE_ENDPOINT, DEFAULT_PROMOTIONS_ENDPOINT, DISCIPLINE_GATES_V1_ALT_HEADER, type DecompositionPlan, type DecompositionStep, type DecompositionTemplate, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type ExecutorCandidate, type FallbackPosture, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetApplicablePromotionOpts, type GetDefaultFallbackChainOpts, type GetMeasuredFailureOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, type GoldenEvalAxis, type GoldenEvalCase, type GoldenEvalOptions, type GoldenEvalRunResult, type GoldenEvalStrategyId, type GoldenIrRecordInput, Grounding, IntentArchetypeName, JUDGE_RUBRICS, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_FAILURE_CFG, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type MeasuredFailureRuntime, type MeasuredFailureVerdict, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, OutputMode, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PlannedStep, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, type PromotionRow, type PromotionsRuntime, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_DISCIPLINE_GATES_V1, RULE_DISCIPLINE_GATES_V1_STRUCTURED, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, STRATEGY_AUTHORSHIP_LIMITATION, SectionRewrite, type ShadowProbeRecordInput, type StrategyAttribution, type StrategyAttributionResult, type StrategyOutcome, type SupportedProvider, type SurfaceFailureRow, type SurfaceStats, SystemModelMessage, TRANSLATOR_FLOOR, _testResetMeasuredFailure, _testResetPromotions, _testWaitForMeasuredFailureRefresh, _testWaitForPromotionsRefresh, altGatesBlockFor, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, awaitMeasuredFailureReady, brainHealth, buildGoldenIrRow, buildLLMJudge, buildPairwiseJudgePrompt, buildShadowProbeRow, call, classifyStrategyOutcome, clearBrain, combineOrderSwappedVerdicts, compile, compileForAISDKv6, configureBrain, configureMeasuredFailureBrain, configurePromotionsBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, flushBrainDeadLetter, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getApplicablePromotion, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getMeasuredFailureVerdict, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isAutoPromoteEnabledFromEnv, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isMeasuredFailureBrainActive, isMeasuredFailureGateEnabledFromEnv, isModelReachable, isPromotionsBrainActive, isProviderReachable, judgeMeasuredFailure, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, parseJudgeVerdict, peekBrainDeadLetter, planDecomposition, prefetchMeasuredFailure, probeShadow, profileToRow, readBrainReadEnv, record, recordGoldenIr, recordOutcome, recordShadowProbe, renderIrForJudge, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, rubricFor, runAdvisor, runGoldenEval, runStrategyEvalWithAttribution, setTokenizer, wilsonLowerBound, withAltDisciplineContract, withDisciplineContract };

package/dist/index.d.ts

@@ -1119,7 +1119,7 @@ declare function runStrategyEvalWithAttribution(opts: Omit<GoldenEvalOptions, 'a
  * guard in `tests/version.test.ts` fails the suite (and therefore
  * `prepublishOnly`) when they diverge — a stale constant cannot reach npm.
  */
-declare const LIBRARY_VERSION = "2.0.0-alpha.75";
+declare const LIBRARY_VERSION = "2.0.0-alpha.76";
 
 /**
  * Oracle contract — how an app tells the brain whether a response was good.
@@ -3222,6 +3222,142 @@ declare function getMeasuredFailureVerdict(opts: GetMeasuredFailureOpts): Measur
 declare function _testResetMeasuredFailure(): void;
 declare function _testWaitForMeasuredFailureRefresh(): Promise<void>;
 
+/**
+ * Release C (Rung 1) — the decomposition coach's planning engine.
+ *
+ * Design contract §5.1: evidence-backed advisories on the existing surface —
+ * "you're paying frontier prices for grunt work; here's the measured split."
+ * No contract change; nothing here executes a fan-out. This module is PURE:
+ * templates + arithmetic. The operator script feeds it measured surface
+ * stats and evidence-picked executors; Release D's `delegate` primitive will
+ * consume the SAME templates, so they live in the library, versioned.
+ *
+ * Honesty posture (the roster-with-receipts rule, applied to ourselves):
+ *
+ *   - The per-step token SHARES are JUDGMENT v1 numbers — labelled as such
+ *     in every plan (`assumptions[]`), versioned so a future measured
+ *     replacement invalidates nothing silently. No consumer has fan-out
+ *     traffic yet (R0 shipped alpha.68, zero adopters), so there is nothing
+ *     to measure them from; the moment branch traffic exists, these
+ *     graduate per surface.
+ *   - Executor grounding is carried per step: 'measured' when the portfolio
+ *     corpus has real outcomes for (model, sub-archetype), 'judgment' when
+ *     the roster's archetypePerf is all we have.
+ *   - The coach's most credible output at low volume is "KEEP THE MONOLITH"
+ *     with the break-even volume stated — the never-worse floor in coach
+ *     form. The advisory only files when the split is MATERIAL (same $5/mo
+ *     felt-utility floor as promotions); the demo report renders every
+ *     analysis either way.
+ */
+
+declare const DECOMPOSITION_TEMPLATES_VERSION = "decomposition-templates-v1";
+interface DecompositionStep {
+    /** Human-readable step name (stable — appears in advisories/recipes). */
+    role: string;
+    /** The sub-archetype this step runs as (its own learning_key downstream). */
+    archetype: IntentArchetypeName;
+    /**
+     * Which tier runs the step. 'delegate' steps are the grunt work the coach
+     * proposes moving to a cheap executor; 'anchor' steps stay on the
+     * incumbent (composition is where fan-outs die — §7a — so the composer
+     * anchors on the strong model by design).
+     */
+    tier: 'delegate' | 'anchor';
+    /** Share of the monolith's INPUT tokens this step reads. JUDGMENT v1. */
+    inputShare: number;
+    /**
+     * Tokens this step EMITS, as a share of the monolith's input (for
+     * intermediate artifacts like extraction notes) — the next anchor step
+     * reads these instead of the raw input. JUDGMENT v1.
+     */
+    emitsShareOfInput: number;
+    /** Share of the monolith's OUTPUT tokens this step produces (0 for
+     * intermediate steps; the anchor composer typically carries 1). */
+    outputShare: number;
+}
+interface DecompositionTemplate {
+    archetype: IntentArchetypeName;
+    steps: DecompositionStep[];
+    rationale: string;
+    version: typeof DECOMPOSITION_TEMPLATES_VERSION;
+}
+/**
+ * v1 covers the three judgment-heavy archetypes with a clear split shape.
+ * Every share number below is a judgment estimate, stated in the plan's
+ * assumptions — they exist to make the ARITHMETIC honest, not to claim
+ * precision the corpus doesn't have yet.
+ */
+declare const DECOMPOSITION_TEMPLATES: Partial<Record<IntentArchetypeName, DecompositionTemplate>>;
+interface SurfaceStats {
+    appId: string;
+    archetype: IntentArchetypeName | string;
+    /** The model serving the monolith today (most-served in the window). */
+    incumbentModel: string;
+    nCalls: number;
+    windowDays: number;
+    avgTokensIn: number;
+    avgTokensOut: number;
+}
+interface ExecutorCandidate {
+    modelId: string;
+    /** archetypePerf score on the STEP's archetype. */
+    perfScore: number;
+    grounding: 'measured' | 'judgment';
+    costInputPer1m: number;
+    costOutputPer1m: number;
+}
+interface ModelPricing {
+    costInputPer1m: number;
+    costOutputPer1m: number;
+}
+interface PlannedStep extends DecompositionStep {
+    /** The picked executor ('delegate' steps) or the incumbent ('anchor'). */
+    executorModel: string;
+    executorGrounding: 'measured' | 'judgment';
+    executorPerfScore: number | null;
+    projectedCostPerCallUsd: number;
+}
+interface DecompositionPlan {
+    appId: string;
+    archetype: string;
+    incumbentModel: string;
+    template: DecompositionTemplate;
+    steps: PlannedStep[];
+    monolithCostPerCallUsd: number;
+    splitCostPerCallUsd: number;
+    savingPerCallUsd: number;
+    monthlyCalls: number;
+    projectedMonthlySavingUsd: number;
+    /** Monthly calls at which the split clears the materiality floor. null
+     * when the split doesn't save per-call at all (then no volume helps). */
+    breakEvenMonthlyCalls: number | null;
+    verdict: 'split-pays' | 'keep-monolith';
+    verdictReason: string;
+    /** Judgment inputs, stated. Every number that is not measured is here. */
+    assumptions: string[];
+}
+declare const COACH_CFG: {
+    /** Same felt-utility floor as promotions (alpha.67 family). */
+    minMonthlySavingUsd: number;
+    /** Executor must clear this archetypePerf on the step's archetype —
+     * same floor as the translator/advisor (ARCHETYPE_FLOOR_DEFAULT). */
+    executorPerfFloor: number;
+    daysPerMonth: number;
+};
+interface PlanDecompositionArgs {
+    stats: SurfaceStats;
+    incumbentPricing: ModelPricing;
+    /**
+     * Evidence-picked executor per step archetype. Return undefined when no
+     * candidate clears the perf floor — the plan then keeps that step on the
+     * incumbent and says so (a coach must not route grunt work to a model
+     * that can't do it just because it is cheap).
+     */
+    pickExecutor: (archetype: IntentArchetypeName) => ExecutorCandidate | undefined;
+    cfg?: Partial<typeof COACH_CFG>;
+}
+declare function planDecomposition(args: PlanDecompositionArgs): DecompositionPlan | undefined;
+
 /**
  * @warmdrift/kgauto v2 — prompt compiler + central learning brain.
  *
@@ -3268,4 +3404,4 @@ declare function _testWaitForMeasuredFailureRefresh(): Promise<void>;
  */
 declare function compile(ir: PromptIR, opts?: CompileOptions): CompileResult;
 
-export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, ArchetypeConvention, type ArchetypeFamilyFit, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainDeadLetterEntry, type BrainHealthSnapshot, type BrainQueryConfig, type BrainReadEnv, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, DEFAULT_FINDINGS_ENDPOINT, DEFAULT_MEASURED_FAILURE_ENDPOINT, DEFAULT_PROMOTIONS_ENDPOINT, DISCIPLINE_GATES_V1_ALT_HEADER, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type FallbackPosture, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetApplicablePromotionOpts, type GetDefaultFallbackChainOpts, type GetMeasuredFailureOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, type GoldenEvalAxis, type GoldenEvalCase, type GoldenEvalOptions, type GoldenEvalRunResult, type GoldenEvalStrategyId, type GoldenIrRecordInput, Grounding, IntentArchetypeName, JUDGE_RUBRICS, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_FAILURE_CFG, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type MeasuredFailureRuntime, type MeasuredFailureVerdict, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, OutputMode, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, type PromotionRow, type PromotionsRuntime, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_DISCIPLINE_GATES_V1, RULE_DISCIPLINE_GATES_V1_STRUCTURED, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, STRATEGY_AUTHORSHIP_LIMITATION, SectionRewrite, type ShadowProbeRecordInput, type StrategyAttribution, type StrategyAttributionResult, type StrategyOutcome, type SupportedProvider, type SurfaceFailureRow, SystemModelMessage, TRANSLATOR_FLOOR, _testResetMeasuredFailure, _testResetPromotions, _testWaitForMeasuredFailureRefresh, _testWaitForPromotionsRefresh, altGatesBlockFor, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, awaitMeasuredFailureReady, brainHealth, buildGoldenIrRow, buildLLMJudge, buildPairwiseJudgePrompt, buildShadowProbeRow, call, classifyStrategyOutcome, clearBrain, combineOrderSwappedVerdicts, compile, compileForAISDKv6, configureBrain, configureMeasuredFailureBrain, configurePromotionsBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, flushBrainDeadLetter, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getApplicablePromotion, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getMeasuredFailureVerdict, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isAutoPromoteEnabledFromEnv, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isMeasuredFailureBrainActive, isMeasuredFailureGateEnabledFromEnv, isModelReachable, isPromotionsBrainActive, isProviderReachable, judgeMeasuredFailure, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, parseJudgeVerdict, peekBrainDeadLetter, prefetchMeasuredFailure, probeShadow, profileToRow, readBrainReadEnv, record, recordGoldenIr, recordOutcome, recordShadowProbe, renderIrForJudge, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, rubricFor, runAdvisor, runGoldenEval, runStrategyEvalWithAttribution, setTokenizer, wilsonLowerBound, withAltDisciplineContract, withDisciplineContract };
+export { ABSOLUTE_FLOOR, type AISDKConvertedMessage, ARCHETYPE_FAMILY_FITS, ARCHETYPE_FLOOR_DEFAULT, type ActionableAdvisory, Adapter, type AdvisoryResolutionSource, type AdvisorySeverity, type AdvisoryStatus, type AdvisorySuggestedFix, ApiKeys, type AppOracle, type ApplySectionRewritesArgs, type ApplySectionRewritesResult, ArchetypeConvention, type ArchetypeFamilyFit, type ArchetypePerfMap, type ArchetypePerfNMap, type ArchetypePerfScoreResult, type AttachCacheControlResult, BestPracticeAdvisory, type BrainConfig, type BrainDeadLetterEntry, type BrainHealthSnapshot, type BrainQueryConfig, type BrainReadEnv, COACH_CFG, CallOptions, CallResult, ChainEntry, type CompatibilityIntent, type CompileForAISDKv6Result, type CompileOptions, CompilePolicy, CompileResult, CompiledRequest, DECOMPOSITION_TEMPLATES, DECOMPOSITION_TEMPLATES_VERSION, DEFAULT_FINDINGS_ENDPOINT, DEFAULT_MEASURED_FAILURE_ENDPOINT, DEFAULT_PROMOTIONS_ENDPOINT, DISCIPLINE_GATES_V1_ALT_HEADER, type DecompositionPlan, type DecompositionStep, type DecompositionTemplate, type ExclusionFindingRow, type ExclusionResolutionSource, type ExecuteErr, type ExecuteOk, type ExecuteOptions, type ExecuteResult, type ExecutorCandidate, type FallbackPosture, FamilyResolutionError, type GetActionableAdvisoriesOptions, type GetApplicablePromotionOpts, type GetDefaultFallbackChainOpts, type GetMeasuredFailureOpts, type GetPerAxisMetricsOpts, type GetRecommendedPrimaryOptions, type GoldenEvalAxis, type GoldenEvalCase, type GoldenEvalOptions, type GoldenEvalRunResult, type GoldenEvalStrategyId, type GoldenIrRecordInput, Grounding, IntentArchetypeName, JUDGE_RUBRICS, LIBRARY_VERSION, type LLMJudgeOptions, MEASURED_FAILURE_CFG, MEASURED_GROUNDING_MIN_N, type MarkAdvisoryResolvedOptions, type MarkExclusionFindingHandledOptions, type MarkPromoteReadyHandledOptions, type MeasuredFailureRuntime, type MeasuredFailureVerdict, type ModelBrainRow, type ModelCompatibility, ModelProfile, NormalizedResponse, type OracleContext, OracleScore, type OutcomePayload, OutcomeResult, OutputMode, PRODUCER_OWNED_RULE_CODES, PROVIDER_ENV_KEYS, PerAxisMetrics, type PlannedStep, type PricingRow, type ProbeShadowOptions, type ProbeShadowServed, type ProfileToRowOptions, type PromoteReadyFindingRow, type PromoteReadyResolution, type PromotionRow, type PromotionsRuntime, PromptIR, Provider, ProviderOverrides, type ProviderReachability, RULE_DISCIPLINE_GATES_V1, RULE_DISCIPLINE_GATES_V1_STRUCTURED, RULE_SEQUENTIAL_TOOL_CLIFF, type ReachabilityOpts, RecordInput, RecordOutcomeInput, type RunAdvisorPhase2Context, STRATEGY_AUTHORSHIP_LIMITATION, SectionRewrite, type ShadowProbeRecordInput, type StrategyAttribution, type StrategyAttributionResult, type StrategyOutcome, type SupportedProvider, type SurfaceFailureRow, type SurfaceStats, SystemModelMessage, TRANSLATOR_FLOOR, _testResetMeasuredFailure, _testResetPromotions, _testWaitForMeasuredFailureRefresh, _testWaitForPromotionsRefresh, altGatesBlockFor, applyArchetypeConvention, applySectionRewrites, attachCacheControlToStreamTextInput, awaitMeasuredFailureReady, brainHealth, buildGoldenIrRow, buildLLMJudge, buildPairwiseJudgePrompt, buildShadowProbeRow, call, classifyStrategyOutcome, clearBrain, combineOrderSwappedVerdicts, compile, compileForAISDKv6, configureBrain, configureMeasuredFailureBrain, configurePromotionsBrain, countTokens, deriveFamilyFromModelId, deriveOwnership, execute, findBetterFit, flushBrainDeadLetter, getActionableAdvisories, getAllStarterChains, getAllStarterChainsWithGrounding, getApplicablePromotion, getArchetypePerfScore, getDefaultFallbackChain, getDefaultFallbackChainWithGrounding, getMeasuredFailureVerdict, getModelCompatibility, getPerAxisMetrics, getReachabilityDiagnostic, getRecommendedPrimary, getSequentialStarterChain, getSequentialStarterChainWithGrounding, getStaleExclusionFindings, getStarterChain, getStarterChainWithGrounding, isAutoPromoteEnabledFromEnv, isBrainQueryActiveFor, isBrainSync, isExclusionFindingsBrainActive, isMeasuredFailureBrainActive, isMeasuredFailureGateEnabledFromEnv, isModelReachable, isPromotionsBrainActive, isProviderReachable, judgeMeasuredFailure, loadAliasesFromBrain, loadArchetypePerfFromBrain, loadArchetypePerfNFromBrain, loadChainsFromBrain, loadModelsFromBrain, loadPricingFromBrain, markAdvisoryResolved, markExclusionFindingHandled, markPromoteReadyHandled, parseJudgeVerdict, peekBrainDeadLetter, planDecomposition, prefetchMeasuredFailure, probeShadow, profileToRow, readBrainReadEnv, record, recordGoldenIr, recordOutcome, recordShadowProbe, renderIrForJudge, resetTokenizer, resolveConventionsForProfile, resolvePricingAt, resolveProviderKey, rubricFor, runAdvisor, runGoldenEval, runStrategyEvalWithAttribution, setTokenizer, wilsonLowerBound, withAltDisciplineContract, withDisciplineContract };

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,
@@ -9039,7 +9043,7 @@ function createBrainForwardRoutes(config) {
 }
 
 // src/version.ts
-var LIBRARY_VERSION = "2.0.0-alpha.75";
+var LIBRARY_VERSION = "2.0.0-alpha.76";
 
 // src/key-health.ts
 var JSON_HEADERS2 = { "Content-Type": "application/json" };
@@ -9657,6 +9661,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 +9879,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 +9982,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-WZZCW6NA.mjs";
 import {
   ABSOLUTE_FLOOR,
   ARCHETYPE_FLOOR_DEFAULT,
@@ -6438,6 +6438,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 +6655,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 +6758,7 @@ export {
   parseGoldenCaptureRate,
   parseJudgeVerdict,
   peekBrainDeadLetter,
+  planDecomposition,
   prefetchMeasuredFailure,
   probeShadow,
   profileToRow,

package/dist/key-health.js

@@ -25,7 +25,7 @@ __export(key_health_exports, {
 module.exports = __toCommonJS(key_health_exports);
 
 // src/version.ts
-var LIBRARY_VERSION = "2.0.0-alpha.75";
+var LIBRARY_VERSION = "2.0.0-alpha.76";
 
 // src/key-health.ts
 var JSON_HEADERS = { "Content-Type": "application/json" };

package/dist/key-health.mjs

@@ -1,6 +1,6 @@
 import {
   createKeyHealthRoute
-} from "./chunk-WP22F3CX.mjs";
+} from "./chunk-WZZCW6NA.mjs";
 export {
   createKeyHealthRoute
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmdrift/kgauto-compiler",
-  "version": "2.0.0-alpha.75",
+  "version": "2.0.0-alpha.76",
   "description": "Prompt compiler with executable provider knowledge for multi-model AI apps: normalized multi-provider transport with fallback chains, compile-time cliff guards, a curated model registry, and a telemetry flight recorder. Swap models without rewriting prompts.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",