@nestpilot/mcp-app 1.0.0

package/dist/tools/optimize-roth-tools.js

@@ -0,0 +1,818 @@
+/**
+ * Roth conversion optimization MCP tool — FEAT-0066
+ *
+ * Composes existing backend APIs to produce a multi-year Roth conversion
+ * strategy with tax impact analysis, IRMAA warnings, and break-even estimates.
+ *
+ * Pipeline:
+ *   1. POST /api/tax/roth/max-conversion — bracket headroom per year
+ *   2. POST /api/plan/forecast (with Roth conversions) — conversion forecast
+ *   3. POST /api/plan/forecast (baseline, no conversion) — baseline forecast
+ *   4. Compute deltas, break-even age, evidence packet
+ *
+ * @feature FEAT-0066
+ */
+import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
+import { nestpilotClient } from "../nestpilot-client.js";
+import { toCallToolResult } from "./mcp-helpers.js";
+// ── IRMAA thresholds (2025) ─────────────────────────────────────────────
+const IRMAA_THRESHOLDS = {
+    SINGLE: 103_000,
+    MFJ: 206_000,
+    MFS: 103_000,
+    HOH: 103_000,
+};
+// ── Conversion policy defaults ──────────────────────────────────────────
+const POLICY_TARGET_BRACKETS = {
+    conservative: 0.12,
+    moderate: 0.22,
+    aggressive: 0.24,
+    integrated: 0.24,
+};
+// ── Tool registration ───────────────────────────────────────────────────
+export function registerRothTools(server, authCtx) {
+    console.log("registerRothTools: Starting registration...");
+    try {
+        registerAppTool(server, "optimize_roth_conversion", {
+            title: "Optimize Roth Conversion",
+            description: `Analyzes and optimizes a multi-year Roth conversion strategy. Returns a year-by-year conversion schedule with tax costs, bracket headroom usage, IRMAA threshold warnings, RMD impact comparison, break-even age estimate, and lifetime tax savings.
+
+USE THIS TOOL WHEN THE USER:
+- Wants to optimize Roth conversions across multiple years
+- Asks "How much should I convert to Roth each year?"
+- Wants to minimize lifetime taxes through strategic conversions
+- Asks about filling tax brackets before RMDs begin
+- Wants to evaluate the tax impact of Roth conversion laddering
+
+DO NOT USE for general tax questions — use coach instead.
+DO NOT USE for basic forecasting — use run_forecast instead.`,
+            inputSchema: {
+                filingStatus: z
+                    .enum(["SINGLE", "MFJ", "MFS", "HOH"])
+                    .describe("Tax filing status"),
+                currentAge: z
+                    .number()
+                    .int()
+                    .min(18)
+                    .max(100)
+                    .describe("Current age of the user"),
+                retirementAge: z
+                    .number()
+                    .int()
+                    .min(50)
+                    .max(100)
+                    .describe("Target retirement age"),
+                traditionalIraBalance: z
+                    .number()
+                    .min(0)
+                    .describe("Current balance of Traditional IRA / 401k (pre-tax) in dollars"),
+                rothIraBalance: z
+                    .number()
+                    .min(0)
+                    .optional()
+                    .describe("Current Roth IRA balance in dollars"),
+                annualIncome: z
+                    .number()
+                    .min(0)
+                    .describe("Current annual gross income in dollars"),
+                otherIncome: z
+                    .number()
+                    .min(0)
+                    .optional()
+                    .describe("Other annual income (pensions, rental, etc.) in dollars"),
+                socialSecurityAnnual: z
+                    .number()
+                    .min(0)
+                    .optional()
+                    .describe("Expected annual Social Security benefit in dollars (if currently receiving or projected)"),
+                conversionPolicy: z
+                    .enum(["conservative", "moderate", "aggressive", "integrated"])
+                    .optional()
+                    .describe("Conversion aggressiveness: conservative (fill 12% bracket), moderate (fill 22%), aggressive (fill 24%), integrated (all-in externality-aware)"),
+                guardrails: z
+                    .object({
+                    avoidIrmaaTierJump: z.boolean().optional(),
+                    maxAcaFplPct: z.number().min(0).optional(),
+                    maxAllInMarginalRate: z.number().min(0).optional(),
+                    annualCap: z.number().min(0).optional(),
+                    lookaheadYears: z.number().int().min(1).max(40).optional(),
+                })
+                    .optional()
+                    .describe("Optional integrated-policy guardrails"),
+                planId: z
+                    .string()
+                    .optional()
+                    .describe("Plan ID for context linking"),
+            },
+            _meta: {
+                ui: {
+                    visibility: ["model", "app"],
+                },
+            },
+        }, async (args) => {
+            const { filingStatus, currentAge, retirementAge, traditionalIraBalance, rothIraBalance = 0, annualIncome, otherIncome = 0, socialSecurityAnnual = 0, conversionPolicy = "moderate", guardrails, planId, } = args;
+            try {
+                const reqHeaders = buildRequestHeaders(authCtx);
+                if (conversionPolicy === "integrated") {
+                    const integratedResult = await runIntegratedPolicyOptimization({
+                        filingStatus,
+                        currentAge,
+                        retirementAge,
+                        traditionalIraBalance,
+                        rothIraBalance,
+                        annualIncome,
+                        otherIncome,
+                        socialSecurityAnnual,
+                        guardrails,
+                        planId,
+                        reqHeaders,
+                    });
+                    if ("error" in integratedResult) {
+                        return toCallToolResult({
+                            error: true,
+                            code: integratedResult.code,
+                            message: integratedResult.message,
+                        }, true);
+                    }
+                    return toCallToolResult(integratedResult);
+                }
+                const targetBracket = POLICY_TARGET_BRACKETS[conversionPolicy];
+                const rmdStartAge = 73; // SECURE Act 2.0
+                const horizonAge = 95;
+                const currentYear = new Date().getFullYear();
+                // ── Step 1: Get max conversion per bracket from tax API ────────
+                const maxConversionResult = await nestpilotClient.post("/api/tax/roth/max-conversion", {
+                    year: 2025,
+                    filingStatus,
+                    wages: annualIncome,
+                    interest: 0,
+                    iraDistributions: 0,
+                    rothConversion: 0,
+                    socialSecurityAnnual,
+                    qualifiedDividends: 0,
+                    ltCapitalGains: 0,
+                    taxExemptInterest: 0,
+                    adjustments: 0,
+                    itemizedDeductions: null,
+                    age65OrOlderCount: currentAge >= 65 ? 1 : 0,
+                    livedWithSpouse: null,
+                    targetBracket,
+                    guardrailMode: "TI_TOP",
+                }, { headers: reqHeaders });
+                if (maxConversionResult.error) {
+                    return toCallToolResult({
+                        error: true,
+                        code: maxConversionResult.code,
+                        message: maxConversionResult.message ??
+                            "Failed to calculate max Roth conversion",
+                    }, true);
+                }
+                const maxConversion = maxConversionResult;
+                // ── Step 2: Build year-by-year conversion schedule ─────────────
+                const conversionSchedule = [];
+                const irmaaWarnings = [];
+                let remainingTraditional = traditionalIraBalance;
+                let cumulativeConverted = 0;
+                let totalTaxCost = 0;
+                // Conversion window: from now until RMD start age (or retirement, whichever is later)
+                const conversionEndAge = Math.max(retirementAge, rmdStartAge);
+                const yearsOfConversions = conversionEndAge - currentAge;
+                for (let yearOffset = 0; yearOffset < yearsOfConversions; yearOffset++) {
+                    const age = currentAge + yearOffset;
+                    const year = currentYear + yearOffset;
+                    // Income changes at retirement
+                    const incomeForYear = age >= retirementAge ? otherIncome : annualIncome + otherIncome;
+                    const ssForYear = age >= 62 ? socialSecurityAnnual : 0;
+                    // Scale conversion room by income changes relative to baseline
+                    const baseIncome = annualIncome + otherIncome;
+                    const incomeRatio = baseIncome > 0 ? (incomeForYear + ssForYear) / baseIncome : 1;
+                    // Conversion amount = bracket headroom adjusted for income changes
+                    let conversionAmount = Math.max(0, maxConversion.maxConversion * (1 - incomeRatio + 1));
+                    // In retirement years with lower income, there's more room to convert
+                    if (age >= retirementAge && incomeForYear < annualIncome) {
+                        const incomeGap = annualIncome - incomeForYear;
+                        conversionAmount = Math.min(maxConversion.maxConversion + incomeGap, remainingTraditional);
+                    }
+                    else {
+                        conversionAmount = Math.min(conversionAmount, remainingTraditional);
+                    }
+                    if (guardrails?.annualCap != null && guardrails.annualCap > 0) {
+                        conversionAmount = Math.min(conversionAmount, guardrails.annualCap);
+                    }
+                    if (conversionAmount <= 0)
+                        break;
+                    // Check IRMAA thresholds
+                    const totalIncomeWithConversion = incomeForYear + ssForYear + conversionAmount;
+                    const irmaaThreshold = IRMAA_THRESHOLDS[filingStatus];
+                    let irmaaWarning = null;
+                    const guardrailsTriggered = [];
+                    if (guardrails?.avoidIrmaaTierJump &&
+                        totalIncomeWithConversion > irmaaThreshold) {
+                        conversionAmount = Math.max(0, irmaaThreshold - incomeForYear - ssForYear);
+                        guardrailsTriggered.push("irmaa_tier_jump");
+                    }
+                    if (conversionAmount <= 0)
+                        break;
+                    // Estimate tax + externality cost decomposition
+                    const estimatedTaxRate = targetBracket;
+                    const taxCost = conversionAmount * estimatedTaxRate;
+                    const deltaFederalTax = Math.round(taxCost);
+                    const deltaStateTax = 0;
+                    const deltaAcaPremium = 0;
+                    const deltaMedicarePremium = totalIncomeWithConversion > irmaaThreshold ? 1200 : 0;
+                    const deltaTaxableSocialSecurity = age >= 62 && ssForYear > 0 ? Math.round(conversionAmount * 0.15) : 0;
+                    const allInCost = deltaFederalTax +
+                        deltaStateTax +
+                        deltaAcaPremium +
+                        deltaMedicarePremium;
+                    const lookaheadYears = guardrails?.lookaheadYears ?? 15;
+                    const futureBenefitPv = Math.round(conversionAmount * 0.08 * Math.min(1, lookaheadYears / 15));
+                    const allInMarginalRate = conversionAmount > 0 ? allInCost / conversionAmount : 0;
+                    const maxAllIn = guardrails?.maxAllInMarginalRate != null
+                        ? guardrails.maxAllInMarginalRate > 1
+                            ? guardrails.maxAllInMarginalRate / 100
+                            : guardrails.maxAllInMarginalRate
+                        : null;
+                    if (maxAllIn != null && allInMarginalRate > maxAllIn) {
+                        guardrailsTriggered.push("all_in_marginal_cap");
+                    }
+                    const primaryDriver = deltaMedicarePremium > deltaFederalTax ? "medicare" : "tax";
+                    totalTaxCost += taxCost;
+                    cumulativeConverted += conversionAmount;
+                    remainingTraditional -= conversionAmount;
+                    if (totalIncomeWithConversion > irmaaThreshold) {
+                        irmaaWarning = `Year ${year}: Income with conversion ($${Math.round(totalIncomeWithConversion).toLocaleString()}) exceeds IRMAA threshold ($${irmaaThreshold.toLocaleString()}). Medicare Part B/D premiums will increase.`;
+                        irmaaWarnings.push(irmaaWarning);
+                    }
+                    else if (totalIncomeWithConversion > irmaaThreshold * 0.9) {
+                        irmaaWarning = `Year ${year}: Income with conversion ($${Math.round(totalIncomeWithConversion).toLocaleString()}) is within 10% of IRMAA threshold ($${irmaaThreshold.toLocaleString()}). Consider reducing conversion.`;
+                        irmaaWarnings.push(irmaaWarning);
+                    }
+                    const bracketPercent = `${Math.round(targetBracket * 100)}%`;
+                    conversionSchedule.push({
+                        year,
+                        age,
+                        conversionAmount: Math.round(conversionAmount),
+                        taxCost: Math.round(taxCost),
+                        bracketFilled: bracketPercent,
+                        bracketHeadroomUsed: Math.round(maxConversion.maxConversion > 0
+                            ? (conversionAmount / maxConversion.maxConversion) * 100
+                            : 0),
+                        cumulativeConverted: Math.round(cumulativeConverted),
+                        irmaaWarning,
+                        deltaFederalTax,
+                        deltaStateTax,
+                        deltaAcaPremium,
+                        deltaMedicarePremium,
+                        deltaTaxableSocialSecurity,
+                        allInCost,
+                        futureBenefitPv,
+                        primaryDriver,
+                        guardrailsTriggered,
+                    });
+                }
+                // ── Step 3: Estimate RMD impact ────────────────────────────────
+                const rmdFactor = 26.5; // Uniform Lifetime Table factor at age 73
+                const growthRate = 1.06; // Assumed 6% real return
+                const yearsToRmd = rmdStartAge - currentAge;
+                const traditionalAtRmdNoConversion = traditionalIraBalance * Math.pow(growthRate, yearsToRmd);
+                const traditionalAtRmdWithConversion = remainingTraditional * Math.pow(growthRate, yearsToRmd);
+                const rmdWithoutConversions = traditionalAtRmdNoConversion / rmdFactor;
+                const rmdWithConversions = traditionalAtRmdWithConversion / rmdFactor;
+                // ── Step 4: Estimate break-even age ────────────────────────────
+                // Break-even: when Roth tax-free growth exceeds the upfront tax cost
+                let breakEvenAge = null;
+                if (totalTaxCost > 0 && cumulativeConverted > 0) {
+                    // Tax savings per year in retirement from tax-free Roth withdrawals
+                    const annualTaxSavings = (cumulativeConverted * 0.04 * targetBracket); // 4% withdrawal rate
+                    if (annualTaxSavings > 0) {
+                        const yearsToBreakEven = totalTaxCost / annualTaxSavings;
+                        breakEvenAge = Math.round(retirementAge + yearsToBreakEven);
+                        if (breakEvenAge > horizonAge)
+                            breakEvenAge = null;
+                    }
+                }
+                // ── Step 5: Estimate lifetime tax savings ──────────────────────
+                const yearsInRetirement = horizonAge - retirementAge;
+                const annualWithdrawalFromConverted = cumulativeConverted * 0.04;
+                const lifetimeTaxSavings = annualWithdrawalFromConverted * targetBracket * yearsInRetirement -
+                    totalTaxCost;
+                // ── Step 6: Package evidence packet ────────────────────────────
+                const result = {
+                    conversionSchedule,
+                    summary: {
+                        totalConverted: Math.round(cumulativeConverted),
+                        totalTaxCost: Math.round(totalTaxCost),
+                        estimatedLifetimeTaxSavings: Math.round(Math.max(0, lifetimeTaxSavings)),
+                        breakEvenAge,
+                        yearsOfConversions: conversionSchedule.length,
+                    },
+                    irmaaWarnings,
+                    rmdImpact: {
+                        withConversions: {
+                            estimatedAnnualRmd: Math.round(rmdWithConversions),
+                        },
+                        withoutConversions: {
+                            estimatedAnnualRmd: Math.round(rmdWithoutConversions),
+                        },
+                        rmdReduction: Math.round(rmdWithoutConversions - rmdWithConversions),
+                    },
+                    evidencePacket: {
+                        assumptions: [
+                            `Filing status: ${filingStatus}`,
+                            `Current age: ${currentAge}, Retirement age: ${retirementAge}`,
+                            `Conversion policy: ${conversionPolicy} (fill ${Math.round(targetBracket * 100)}% bracket)`,
+                            "Legacy mode uses bracket-fill tax optimization.",
+                            `Traditional IRA balance: $${traditionalIraBalance.toLocaleString()}`,
+                            `Annual income: $${annualIncome.toLocaleString()}`,
+                            `Assumed real return: 6%`,
+                            `RMD start age: ${rmdStartAge} (SECURE Act 2.0)`,
+                            `Withdrawal rate: 4%`,
+                            `Planning horizon: age ${horizonAge}`,
+                            `Tax year: 2025 brackets`,
+                            `IRMAA thresholds: $${irmaaThreshold(filingStatus).toLocaleString()} (${filingStatus})`,
+                        ],
+                        calculationSteps: [
+                            "1. Called POST /api/tax/roth/max-conversion to determine bracket headroom",
+                            `2. Max conversion in ${Math.round(targetBracket * 100)}% bracket: $${Math.round(maxConversion.maxConversion).toLocaleString()}`,
+                            `3. Built ${conversionSchedule.length}-year conversion schedule from age ${currentAge} to ${currentAge + conversionSchedule.length - 1}`,
+                            `4. Total converted: $${Math.round(cumulativeConverted).toLocaleString()} at tax cost of $${Math.round(totalTaxCost).toLocaleString()}`,
+                            `5. RMD at ${rmdStartAge}: $${Math.round(rmdWithConversions).toLocaleString()} (vs. $${Math.round(rmdWithoutConversions).toLocaleString()} without conversions)`,
+                            breakEvenAge
+                                ? `6. Break-even age: ${breakEvenAge}`
+                                : "6. Break-even age: beyond planning horizon or not applicable",
+                        ],
+                        disclaimers: [
+                            "This analysis is for educational purposes only and does not constitute tax advice.",
+                            "Consult a qualified tax professional before making Roth conversion decisions.",
+                            "Tax brackets and IRMAA thresholds are based on 2025 values and may change.",
+                            "Actual results will vary based on future tax law changes, investment returns, and personal circumstances.",
+                            "State income taxes are not included in this analysis.",
+                        ],
+                        inputs: {
+                            filingStatus,
+                            currentAge,
+                            retirementAge,
+                            traditionalIraBalance,
+                            rothIraBalance,
+                            annualIncome,
+                            otherIncome,
+                            socialSecurityAnnual,
+                            conversionPolicy,
+                            guardrails: guardrails ?? null,
+                            planId: planId ?? null,
+                        },
+                        generatedAt: new Date().toISOString(),
+                    },
+                };
+                return toCallToolResult(result);
+            }
+            catch (err) {
+                return toCallToolResult({
+                    error: true,
+                    message: err instanceof Error
+                        ? err.message
+                        : "Unexpected error during Roth optimization",
+                }, true);
+            }
+        });
+        console.log("registerRothTools: Registration successful!");
+    }
+    catch (error) {
+        console.error("registerRothTools: FAILED to register optimize_roth_conversion:", error);
+        throw error;
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────────────
+function irmaaThreshold(filingStatus) {
+    return IRMAA_THRESHOLDS[filingStatus];
+}
+function buildRequestHeaders(authCtx) {
+    const headers = {};
+    if (authCtx?.bearerToken) {
+        headers.Authorization = `Bearer ${authCtx.bearerToken}`;
+    }
+    if (authCtx?.userId) {
+        headers["X-User-ID"] = authCtx.userId;
+    }
+    return headers;
+}
+async function runIntegratedPolicyOptimization(params) {
+    const { filingStatus, currentAge, retirementAge, traditionalIraBalance, rothIraBalance, annualIncome, otherIncome, socialSecurityAnnual, guardrails, planId, reqHeaders, } = params;
+    const withConversionsPayload = buildIntegratedForecastPayload({
+        filingStatus,
+        currentAge,
+        retirementAge,
+        traditionalIraBalance,
+        rothIraBalance,
+        annualIncome,
+        otherIncome,
+        socialSecurityAnnual,
+        guardrails,
+        planId,
+        enableRothConversions: true,
+    });
+    const baselinePayload = buildIntegratedForecastPayload({
+        filingStatus,
+        currentAge,
+        retirementAge,
+        traditionalIraBalance,
+        rothIraBalance,
+        annualIncome,
+        otherIncome,
+        socialSecurityAnnual,
+        guardrails,
+        planId,
+        enableRothConversions: false,
+    });
+    const withConversionsResult = await nestpilotClient.post("/api/plan/forecast", withConversionsPayload, { headers: reqHeaders });
+    if (withConversionsResult.error) {
+        return {
+            error: true,
+            code: withConversionsResult.code,
+            message: withConversionsResult.message ??
+                "Integrated optimization failed while running conversion forecast.",
+        };
+    }
+    const baselineResult = await nestpilotClient.post("/api/plan/forecast", baselinePayload, { headers: reqHeaders });
+    if (baselineResult.error) {
+        return {
+            error: true,
+            code: baselineResult.code,
+            message: baselineResult.message ??
+                "Integrated optimization failed while running baseline forecast.",
+        };
+    }
+    const withForecast = withConversionsResult;
+    const baselineForecast = baselineResult;
+    const withYears = Array.isArray(withForecast.yearly)
+        ? withForecast.yearly
+        : [];
+    const baselineYears = Array.isArray(baselineForecast.yearly)
+        ? baselineForecast.yearly
+        : [];
+    const conversionSchedule = [];
+    const irmaaWarningSet = new Set();
+    let cumulativeConverted = 0;
+    let totalTaxCost = 0;
+    const currentYear = new Date().getFullYear();
+    for (let i = 0; i < withYears.length; i += 1) {
+        const yearEntry = withYears[i];
+        const conversionAmount = normalizeNumber(yearEntry.rothConversion);
+        if (conversionAmount <= 0) {
+            continue;
+        }
+        const age = normalizeInteger(yearEntry.age, currentAge + i);
+        const year = normalizeInteger(yearEntry.year, currentYear + Math.max(0, age - currentAge));
+        const taxCost = Math.max(0, normalizeNumber(yearEntry.rothConversionTax));
+        totalTaxCost += taxCost;
+        cumulativeConverted += conversionAmount;
+        const detail = yearEntry.rothOptimization;
+        const deltaFederalTax = normalizeNumber(detail?.deltaFederalTax);
+        const deltaStateTax = normalizeNumber(detail?.deltaStateTax);
+        const deltaAcaPremium = normalizeNumber(detail?.deltaAcaPremium);
+        const deltaMedicarePremium = normalizeNumber(detail?.deltaMedicarePremium);
+        const deltaTaxableSocialSecurity = normalizeNumber(detail?.deltaTaxableSocialSecurity);
+        const allInCost = normalizeNumber(detail?.allInCost, deltaFederalTax + deltaStateTax + deltaAcaPremium + deltaMedicarePremium);
+        const futureBenefitPv = normalizeNumber(detail?.futureBenefitPv);
+        const primaryDriver = normalizePrimaryDriver(detail?.primaryDriver);
+        const guardrailsTriggered = toStringArray(detail?.guardrailsTriggered);
+        const effectiveMarginalRate = optionalNumber(detail?.effectiveMarginalRate);
+        const futurePainThreshold = optionalNumber(detail?.futurePainThreshold);
+        const ceilingBracket = optionalString(detail?.ceilingBracket);
+        const rationale = optionalString(detail?.rationale);
+        let irmaaWarning = extractIrmaaWarning(year, yearEntry.healthInsuranceWarnings);
+        if (!irmaaWarning) {
+            const estimatedIncomeWithConversion = estimateIncomeWithConversion(yearEntry);
+            const threshold = irmaaThreshold(filingStatus);
+            if (estimatedIncomeWithConversion > threshold) {
+                irmaaWarning = `Year ${year}: Income with conversion ($${Math.round(estimatedIncomeWithConversion).toLocaleString()}) exceeds IRMAA threshold ($${threshold.toLocaleString()}). Medicare Part B/D premiums may increase.`;
+            }
+            else if (estimatedIncomeWithConversion > threshold * 0.9) {
+                irmaaWarning = `Year ${year}: Income with conversion ($${Math.round(estimatedIncomeWithConversion).toLocaleString()}) is within 10% of IRMAA threshold ($${threshold.toLocaleString()}).`;
+            }
+        }
+        if (irmaaWarning) {
+            irmaaWarningSet.add(irmaaWarning);
+        }
+        conversionSchedule.push({
+            year,
+            age,
+            conversionAmount: Math.round(conversionAmount),
+            taxCost: Math.round(taxCost),
+            bracketFilled: ceilingBracket ??
+                (effectiveMarginalRate != null
+                    ? `${Math.round(effectiveMarginalRate * 100)}%`
+                    : "n/a"),
+            bracketHeadroomUsed: 0,
+            cumulativeConverted: Math.round(cumulativeConverted),
+            irmaaWarning,
+            deltaFederalTax: Math.round(deltaFederalTax),
+            deltaStateTax: Math.round(deltaStateTax),
+            deltaAcaPremium: Math.round(deltaAcaPremium),
+            deltaMedicarePremium: Math.round(deltaMedicarePremium),
+            deltaTaxableSocialSecurity: Math.round(deltaTaxableSocialSecurity),
+            allInCost: Math.round(allInCost),
+            futureBenefitPv: Math.round(futureBenefitPv),
+            primaryDriver,
+            guardrailsTriggered,
+            rationale: rationale ?? undefined,
+            effectiveMarginalRate: effectiveMarginalRate ?? undefined,
+            futurePainThreshold: futurePainThreshold ?? undefined,
+            ceilingBracket: ceilingBracket ?? undefined,
+        });
+    }
+    const rmdStartAge = 73;
+    const rmdFactor = 26.5;
+    const traditionalAtRmdWithConversions = findTraditionalBalanceAtOrAfterAge(withYears, rmdStartAge);
+    const traditionalAtRmdWithoutConversions = findTraditionalBalanceAtOrAfterAge(baselineYears, rmdStartAge);
+    const rmdWithConversions = traditionalAtRmdWithConversions / rmdFactor;
+    const rmdWithoutConversions = traditionalAtRmdWithoutConversions / rmdFactor;
+    const breakEvenAge = calculateBreakEvenAge(withYears, baselineYears, retirementAge);
+    const withTotalTax = normalizeNumber(withForecast.totalTaxAmount);
+    const baselineTotalTax = normalizeNumber(baselineForecast.totalTaxAmount);
+    const estimatedLifetimeTaxSavings = Math.round(Math.max(0, baselineTotalTax - withTotalTax));
+    const conversionWindow = conversionSchedule.length > 0
+        ? `from age ${conversionSchedule[0].age} to age ${conversionSchedule[conversionSchedule.length - 1].age}`
+        : "with no conversion years recommended";
+    return {
+        conversionSchedule,
+        summary: {
+            totalConverted: Math.round(cumulativeConverted),
+            totalTaxCost: Math.round(totalTaxCost),
+            estimatedLifetimeTaxSavings,
+            breakEvenAge,
+            yearsOfConversions: conversionSchedule.length,
+        },
+        irmaaWarnings: Array.from(irmaaWarningSet),
+        rmdImpact: {
+            withConversions: {
+                estimatedAnnualRmd: Math.round(rmdWithConversions),
+            },
+            withoutConversions: {
+                estimatedAnnualRmd: Math.round(rmdWithoutConversions),
+            },
+            rmdReduction: Math.round(rmdWithoutConversions - rmdWithConversions),
+        },
+        evidencePacket: {
+            assumptions: [
+                "Integrated policy uses backend forecast engine valley-fill routing.",
+                `Filing status: ${filingStatus}`,
+                `Current age: ${currentAge}, retirement age: ${retirementAge}`,
+                `Traditional IRA balance: $${Math.round(traditionalIraBalance).toLocaleString()}`,
+                `Roth IRA balance: $${Math.round(rothIraBalance).toLocaleString()}`,
+                `Annual earned income: $${Math.round(annualIncome).toLocaleString()}`,
+                `Additional annual income: $${Math.round(otherIncome).toLocaleString()}`,
+                `Annual Social Security (if applicable): $${Math.round(socialSecurityAnnual).toLocaleString()}`,
+                "Synthetic forecast payload uses targetMonthlySpending = 0 to isolate conversion policy behavior.",
+                `IRMAA thresholds: $${irmaaThreshold(filingStatus).toLocaleString()} (${filingStatus})`,
+            ],
+            calculationSteps: [
+                "1. Called POST /api/plan/forecast with enableRothConversions=true and rothConversionStrategy=integrated",
+                "2. Called POST /api/plan/forecast baseline with enableRothConversions=false",
+                `3. Extracted yearly rothConversion and rothOptimization detail ${conversionWindow}`,
+                `4. Summed converted amount ($${Math.round(cumulativeConverted).toLocaleString()}) and conversion tax ($${Math.round(totalTaxCost).toLocaleString()})`,
+                `5. Estimated RMD impact at age ${rmdStartAge} using forecasted traditional balances`,
+                breakEvenAge != null
+                    ? `6. Break-even age identified at ${breakEvenAge} from cumulative tax deltas`
+                    : "6. Break-even age not reached within forecast horizon",
+            ],
+            disclaimers: [
+                "This analysis is for educational purposes only and does not constitute tax advice.",
+                "Consult a qualified tax professional before making Roth conversion decisions.",
+                "Tax law, brackets, IRMAA thresholds, and premium rules may change.",
+                "Actual results vary based on returns, legislation, and personal circumstances.",
+            ],
+            inputs: {
+                filingStatus,
+                currentAge,
+                retirementAge,
+                traditionalIraBalance,
+                rothIraBalance,
+                annualIncome,
+                otherIncome,
+                socialSecurityAnnual,
+                conversionPolicy: "integrated",
+                guardrails: guardrails ?? null,
+                planId: planId ?? null,
+            },
+            generatedAt: new Date().toISOString(),
+        },
+    };
+}
+function buildIntegratedForecastPayload(params) {
+    const { filingStatus, currentAge, retirementAge, traditionalIraBalance, rothIraBalance, annualIncome, otherIncome, socialSecurityAnnual, guardrails, planId, enableRothConversions, } = params;
+    const horizonAge = 95;
+    const incomeStreams = [];
+    if (annualIncome > 0 && currentAge < retirementAge) {
+        incomeStreams.push({
+            type: "salary",
+            amountMonthly: annualIncome / 12,
+            startAge: currentAge,
+            endAge: Math.max(currentAge, retirementAge - 1),
+            owner: "primary",
+        });
+    }
+    if (otherIncome > 0) {
+        incomeStreams.push({
+            type: "other",
+            amountMonthly: otherIncome / 12,
+            startAge: currentAge,
+            endAge: horizonAge,
+            owner: "primary",
+        });
+    }
+    if (socialSecurityAnnual > 0) {
+        incomeStreams.push({
+            type: "social_security",
+            amountMonthly: socialSecurityAnnual / 12,
+            startAge: Math.max(62, currentAge),
+            endAge: horizonAge,
+            owner: "primary",
+        });
+    }
+    if (incomeStreams.length === 0) {
+        incomeStreams.push({
+            type: "other",
+            amountMonthly: 0,
+            startAge: currentAge,
+            endAge: horizonAge,
+            owner: "primary",
+        });
+    }
+    const payload = {
+        currentAge,
+        retirementAge,
+        horizonAge,
+        targetMonthlySpending: 0,
+        filingStatus: mapFilingStatusToPlanInput(filingStatus),
+        withdrawalStrategy: "taxable_first",
+        wages: annualIncome,
+        enableRothConversions,
+        rothConversionStrategy: "integrated",
+        accounts: [
+            {
+                id: "trad-1",
+                owner: "primary",
+                type: "traditional",
+                balance: Math.max(0, traditionalIraBalance),
+                annualContribution: 0,
+                realReturn: 0.05,
+                taxDrag: 0,
+            },
+            {
+                id: "roth-1",
+                owner: "primary",
+                type: "roth",
+                balance: Math.max(0, rothIraBalance),
+                annualContribution: 0,
+                realReturn: 0.05,
+                taxDrag: 0,
+            },
+            {
+                id: "taxable-1",
+                owner: "primary",
+                type: "taxable",
+                balance: 0,
+                annualContribution: 0,
+                realReturn: 0.05,
+                taxDrag: 0.01,
+            },
+        ],
+        incomeStreams,
+    };
+    if (guardrails) {
+        payload.rothConversionGuardrails = normalizeGuardrailsForForecast(guardrails);
+    }
+    if (planId) {
+        payload.planId = planId;
+    }
+    return payload;
+}
+function mapFilingStatusToPlanInput(status) {
+    switch (status) {
+        case "MFJ":
+            return "mfj";
+        case "MFS":
+            return "mfs";
+        case "HOH":
+            return "hoh";
+        case "SINGLE":
+        default:
+            return "single";
+    }
+}
+function normalizeGuardrailsForForecast(guardrails) {
+    const maxAllInMarginalRate = typeof guardrails.maxAllInMarginalRate === "number" &&
+        Number.isFinite(guardrails.maxAllInMarginalRate) &&
+        guardrails.maxAllInMarginalRate > 1
+        ? guardrails.maxAllInMarginalRate / 100
+        : guardrails.maxAllInMarginalRate;
+    return {
+        avoidIrmaaTierJump: guardrails.avoidIrmaaTierJump,
+        maxAcaFplPct: guardrails.maxAcaFplPct,
+        maxAllInMarginalRate,
+        annualCap: guardrails.annualCap,
+        lookaheadYears: guardrails.lookaheadYears,
+    };
+}
+function normalizeNumber(value, fallback = 0) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string") {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+    return fallback;
+}
+function normalizeInteger(value, fallback) {
+    return Math.round(normalizeNumber(value, fallback));
+}
+function optionalNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string") {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+    return null;
+}
+function optionalString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+function toStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => typeof entry === "string");
+}
+function normalizePrimaryDriver(value) {
+    switch (value) {
+        case "aca":
+        case "medicare":
+        case "ss_tax":
+        case "state_tax":
+        case "tax":
+            return value;
+        default:
+            return "tax";
+    }
+}
+function estimateIncomeWithConversion(year) {
+    const income = year.income;
+    const baseIncome = normalizeNumber(income?.ss) +
+        normalizeNumber(income?.spouseSS) +
+        normalizeNumber(income?.rental) +
+        normalizeNumber(income?.pension) +
+        normalizeNumber(income?.annuity) +
+        normalizeNumber(income?.other);
+    return baseIncome + normalizeNumber(year.rothConversion);
+}
+function extractIrmaaWarning(year, warnings) {
+    if (!Array.isArray(warnings)) {
+        return null;
+    }
+    for (const warning of warnings) {
+        if (typeof warning === "string" && warning.toUpperCase().includes("IRMAA")) {
+            return `Year ${year}: ${warning}`;
+        }
+        if (warning && typeof warning === "object") {
+            const maybeMessage = warning.message;
+            if (typeof maybeMessage === "string" &&
+                maybeMessage.toUpperCase().includes("IRMAA")) {
+                return `Year ${year}: ${maybeMessage}`;
+            }
+        }
+    }
+    return null;
+}
+function findTraditionalBalanceAtOrAfterAge(years, targetAge) {
+    for (const year of years) {
+        const age = normalizeInteger(year.age, -1);
+        if (age >= targetAge) {
+            return normalizeNumber(year.balances?.traditional);
+        }
+    }
+    return 0;
+}
+function calculateBreakEvenAge(withYears, baselineYears, retirementAge) {
+    const years = Math.min(withYears.length, baselineYears.length);
+    let cumulativeTaxDelta = 0;
+    for (let i = 0; i < years; i += 1) {
+        const withTax = normalizeNumber(withYears[i].taxAmount);
+        const baselineTax = normalizeNumber(baselineYears[i].taxAmount);
+        cumulativeTaxDelta += withTax - baselineTax;
+        const age = normalizeInteger(withYears[i].age, -1);
+        if (age >= retirementAge && cumulativeTaxDelta <= 0) {
+            return age;
+        }
+    }
+    return null;
+}