@retiregolden/engine 0.1.0

package/dist/insights/detectors/annuitizationHeadroom.js

@@ -0,0 +1,77 @@
+import { spiaPayoutRate } from '../../decisions/spiaQuotes.js';
+/**
+ * "You plan for a long life but hold no guaranteed income — annuitization
+ * headroom" (annuity-pension-and-home-equity, step 5). Fires for
+ * longevity-anxious plans (a planning age of 95+) with meaningful liquid
+ * savings, no annuity on the books, and no pension income covering the same
+ * ground. The action previews a cover-the-floor SPIA as a scenario so the
+ * ledger — not the card — prices the liquidity/estate tradeoff; the Monte
+ * Carlo annuitization sweep is the full solver view.
+ */
+export const annuitizationHeadroom = {
+    id: 'annuitization-headroom',
+    category: 'longevity-insurance-geography',
+    screen(ctx) {
+        const plan = ctx.plan;
+        const startYear = ctx.projection.startYear;
+        const primary = plan.household.people[0];
+        if (!primary)
+            return null;
+        // Longevity-anxious: someone plans to 95+.
+        const maxPlanningAge = Math.max(...plan.household.people.map((p) => p.longevity.planningAge));
+        if (maxPlanningAge < 95)
+            return null;
+        // Headroom is *unused*: any annuity (owned or purchased) or pension income
+        // stream means the household already holds lifetime income beyond SS.
+        if (plan.accounts.some((a) => a.type === 'annuity' || (a.type === 'pension' && !a.lumpSumElection)))
+            return null;
+        const liquid = plan.accounts
+            .filter((a) => a.type === 'cash' || a.type === 'taxable')
+            .sort((a, b) => ('balance' in b ? b.balance : 0) - ('balance' in a ? a.balance : 0))[0];
+        if (!liquid || !('balance' in liquid) || liquid.balance < 100_000)
+            return null;
+        const currentAge = startYear - Number(primary.dob.slice(0, 4));
+        const startAge = Math.min(95, Math.max(currentAge, 65));
+        const premium = Math.min(liquid.balance * 0.25, 250_000);
+        const monthly = (premium * spiaPayoutRate(startAge)) / 12;
+        const spia = {
+            id: `annuitization-headroom-preview-${startYear}-${liquid.id}`,
+            type: 'annuity',
+            name: 'SPIA (preview)',
+            ownerPersonId: primary.id,
+            annualReturnPct: null,
+            startAge,
+            monthlyAmount: monthly,
+            colaPct: 0,
+            taxablePct: 100,
+            purchase: { year: startYear, premium, fundingAccountId: liquid.id, taxQualification: 'nonQualified' },
+        };
+        return {
+            id: 'annuitization-headroom',
+            category: 'longevity-insurance-geography',
+            title: 'Planning to 95+ with no lifetime income beyond Social Security',
+            rationale: `Your plan runs to ${maxPlanningAge} with no pension or annuity income. ` +
+                `Trading $${Math.round(premium).toLocaleString()} of liquid savings for a life annuity (~$${Math.round(monthly).toLocaleString()}/mo) ` +
+                'insures the years past life expectancy — the exact risk a long planning age worries about — at the cost of liquidity and estate. ' +
+                'The Monte Carlo page\'s annuitization sweep shows the full success-vs-legacy frontier.',
+            impact: {
+                qualitative: 'Preview the SPIA against your full plan: guaranteed lifetime income and steadier late-life funding, priced against the liquidity and estate it costs.',
+            },
+            exact: false,
+            confidence: 'medium',
+            learnSlug: 'pensions-and-annuities',
+            plannerRoute: 'monte-carlo',
+            action: {
+                kind: 'preview-scenario',
+                scenarioName: 'Buy a cover-the-floor SPIA',
+                patch: { accounts: [...plan.accounts, spia] },
+            },
+        };
+    },
+    evaluate(ctx) {
+        const card = this.screen(ctx);
+        if (!card)
+            throw new Error('Annuitization headroom not eligible');
+        return { action: card.action, impact: card.impact };
+    },
+};

package/dist/insights/detectors/assetLocation.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Asset-location detector (asset-allocation-and-return-model-v2, step 5).
+ *
+ * Surfaces the shared `assetLocationGenerator` when a plan opts into static
+ * allocation on multiple accounts. `screen()` is cheap and pure; `evaluate()`
+ * prices every bounded swap on the exact ledger and previews the winner.
+ */
+import type { Detector } from '../types.js';
+export declare const assetLocation: Detector;

package/dist/insights/detectors/assetLocation.js

@@ -0,0 +1,86 @@
+/**
+ * Asset-location detector (asset-allocation-and-return-model-v2, step 5).
+ *
+ * Surfaces the shared `assetLocationGenerator` when a plan opts into static
+ * allocation on multiple accounts. `screen()` is cheap and pure; `evaluate()`
+ * prices every bounded swap on the exact ledger and previews the winner.
+ */
+import { planUsesAssetAllocation } from '../../allocation/assetClasses.js';
+import { createDecisionContext, evaluateCandidate } from '../../decisions/evaluateCandidate.js';
+import { assetLocationGenerator } from '../../decisions/generators.js';
+import { combineTaxCalculators, createFederalTaxCalculator } from '../../tax/federalTax.js';
+import { createStateTaxCalculator } from '../../tax/stateTax.js';
+function decisionContextFromDetector(ctx) {
+    const taxCalculator = combineTaxCalculators(createFederalTaxCalculator(), createStateTaxCalculator({
+        overridePct: ctx.plan.assumptions.stateEffectiveTaxPct,
+        localPct: ctx.plan.assumptions.localIncomeTaxPct,
+    }));
+    return createDecisionContext(ctx.plan, { startYear: ctx.projection.startYear, taxCalculator }, { result: ctx.projection.result, summary: ctx.projection.summary });
+}
+function pickBestBeneficialCandidate(decisionCtx, candidates) {
+    let best = null;
+    for (const candidate of candidates) {
+        const evaluation = evaluateCandidate(decisionCtx, candidate);
+        if (evaluation.recommendationState !== 'beneficial')
+            continue;
+        const delta = evaluation.deltas.endingAfterTaxEstate;
+        if (best === null || delta > best.delta)
+            best = { candidate, delta };
+    }
+    return best;
+}
+export const assetLocation = {
+    id: 'asset-location',
+    category: 'accounts-contributions',
+    screen(ctx) {
+        if (!planUsesAssetAllocation(ctx.plan))
+            return null;
+        const candidates = assetLocationGenerator.generate({ plan: ctx.plan });
+        if (candidates.length === 0)
+            return null;
+        const preferred = candidates.find((candidate) => candidate.id === 'asset-location-bonds-to-traditional') ?? candidates[0];
+        const swapped = preferred.metadata?.swappedDollars ?? 0;
+        return {
+            id: 'asset-location',
+            category: 'accounts-contributions',
+            title: 'Improve asset location across accounts',
+            rationale: 'Your plan uses class-level allocation on multiple accounts. Preview moving bonds toward tax-deferred wrappers and stocks toward taxable or Roth accounts while keeping the household stock/bond mix unchanged.',
+            impact: {
+                qualitative: swapped > 0
+                    ? `Up to $${Math.round(swapped).toLocaleString()} of class exposure could be relocated; expand to preview the exact after-tax estate impact.`
+                    : 'Preview bounded location swaps priced on your full projection.',
+            },
+            exact: false,
+            confidence: 'medium',
+            learnSlug: 'assumption-investment-returns',
+            plannerRoute: 'accounts',
+            action: {
+                kind: 'preview-scenario',
+                scenarioName: preferred.label,
+                patch: preferred.planPatch,
+            },
+        };
+    },
+    evaluate(ctx) {
+        const card = this.screen(ctx);
+        if (!card || card.action.kind !== 'preview-scenario')
+            throw new Error('Asset location not eligible');
+        const decisionCtx = decisionContextFromDetector(ctx);
+        const candidates = assetLocationGenerator.generate(decisionCtx);
+        const best = pickBestBeneficialCandidate(decisionCtx, candidates);
+        if (!best) {
+            throw new Error('No beneficial asset-location swap was found once taxes, taxable drag, and rebalancing were priced in.');
+        }
+        return {
+            action: {
+                kind: 'preview-scenario',
+                scenarioName: best.candidate.label,
+                patch: best.candidate.planPatch,
+            },
+            impact: {
+                qualitative: `Exact ledger: "${best.candidate.label}" improves after-tax estate by about $${Math.round(best.delta).toLocaleString()} (today's dollars).`,
+                endingAfterTaxEstateDelta: best.delta,
+            },
+        };
+    },
+};

package/dist/insights/detectors/hecmBufferCandidate.d.ts

@@ -0,0 +1,12 @@
+import type { Detector } from '../types.js';
+/**
+ * "House-rich, portfolio-thin: a HECM line of credit could buffer sequence
+ * risk" (annuity-pension-and-home-equity, step 5). Fires when a primary
+ * residence's value rivals the investable portfolio, the youngest borrower is
+ * 62+, and no HECM is modeled. Pfau's research: opening the line early and
+ * drawing after down years lets the portfolio recover — the line's unused
+ * credit grows regardless of home value. The action previews a coordinated
+ * line as a scenario; deterministic runs price only the last-resort backstop,
+ * so the Monte Carlo comparison is where the coordinated policy shows up.
+ */
+export declare const hecmBufferCandidate: Detector;

package/dist/insights/detectors/hecmBufferCandidate.js

@@ -0,0 +1,76 @@
+import { hecmPrincipalLimitFactorPct } from '../../params/index.js';
+/**
+ * "House-rich, portfolio-thin: a HECM line of credit could buffer sequence
+ * risk" (annuity-pension-and-home-equity, step 5). Fires when a primary
+ * residence's value rivals the investable portfolio, the youngest borrower is
+ * 62+, and no HECM is modeled. Pfau's research: opening the line early and
+ * drawing after down years lets the portfolio recover — the line's unused
+ * credit grows regardless of home value. The action previews a coordinated
+ * line as a scenario; deterministic runs price only the last-resort backstop,
+ * so the Monte Carlo comparison is where the coordinated policy shows up.
+ */
+export const hecmBufferCandidate = {
+    id: 'hecm-buffer-candidate',
+    category: 'longevity-insurance-geography',
+    screen(ctx) {
+        const plan = ctx.plan;
+        const startYear = ctx.projection.startYear;
+        if (plan.household.people.length === 0)
+            return null;
+        const youngestAge = Math.min(...plan.household.people.map((p) => startYear - Number(p.dob.slice(0, 4))));
+        if (youngestAge < 62)
+            return null;
+        const home = plan.accounts.find((a) => a.type === 'property' && a.primaryResidence === true && a.hecm === undefined && a.value > 100_000 &&
+            // A planned sale makes the buffer moot (the line closes at sale).
+            (a.plannedSaleYear === null || a.plannedSaleYear === undefined));
+        if (!home)
+            return null;
+        let investable = 0;
+        for (const a of plan.accounts) {
+            if (a.type === 'cash' || a.type === 'taxable' || a.type === 'equityComp' ||
+                a.type === 'traditional' || a.type === 'roth' || a.type === 'hsa') {
+                investable += 'balance' in a ? a.balance : 0;
+            }
+        }
+        // House-rich / portfolio-thin: the home is a major share of net worth.
+        if (investable <= 0 || home.value < investable * 0.75)
+            return null;
+        const pack = ctx.params;
+        const plfPct = hecmPrincipalLimitFactorPct(pack, youngestAge);
+        const lineSize = (plfPct / 100) * home.value;
+        const patchedHome = {
+            ...home,
+            hecm: {
+                openYear: startYear,
+                growthRatePct: pack.hecm.defaultGrowthRatePct,
+                drawPolicy: 'coordinated',
+            },
+        };
+        return {
+            id: 'hecm-buffer-candidate',
+            category: 'longevity-insurance-geography',
+            title: 'Your home equity could backstop market downturns',
+            rationale: `${home.name} (~$${Math.round(home.value).toLocaleString()}) rivals your $${Math.round(investable).toLocaleString()} portfolio. ` +
+                `A HECM line of credit opened now would start near $${Math.round(lineSize).toLocaleString()} (${plfPct.toFixed(1)}% of value at age ${youngestAge}, published factor tables) ` +
+                `and grow ~${pack.hecm.defaultGrowthRatePct}%/yr regardless of home value. Drawing tax-free after down years — instead of selling depressed assets — is the coordinated buffer strategy; ` +
+                'costs are real (financed fees, a growing loan) and the loan is repaid from the home, non-recourse.',
+            impact: {
+                qualitative: 'Preview the line against your full plan (best seen on the Monte Carlo page, where down-year draws actually trigger): steadier bad-path spending at the cost of home equity in the estate.',
+            },
+            exact: false,
+            confidence: 'medium',
+            plannerRoute: 'accounts',
+            action: {
+                kind: 'preview-scenario',
+                scenarioName: 'Open a HECM line of credit (coordinated draws)',
+                patch: { accounts: plan.accounts.map((a) => (a.id === home.id ? patchedHome : a)) },
+            },
+        };
+    },
+    evaluate(ctx) {
+        const card = this.screen(ctx);
+        if (!card)
+            throw new Error('HECM buffer not eligible');
+        return { action: card.action, impact: card.impact };
+    },
+};

package/dist/insights/detectors/incomeFloorFunded.d.ts

@@ -0,0 +1,8 @@
+import type { Detector } from '../types.js';
+/**
+ * "Your floor is X% funded" (social-security-bridge-and-tips-ladder, step 4):
+ * the Pfau funded-ratio lens as an advisory card. Fires when the household has
+ * distinguished a required floor from lifestyle spending and guaranteed income
+ * covers less than ~90% of its present value on the TIPS curve.
+ */
+export declare const incomeFloorFunded: Detector;

package/dist/insights/detectors/incomeFloorFunded.js

@@ -0,0 +1,52 @@
+import { EMBEDDED_REAL_YIELD_CURVE } from '../../params/index.js';
+import { computeFundedRatio } from '../../ladder/fundedRatio.js';
+/**
+ * "Your floor is X% funded" (social-security-bridge-and-tips-ladder, step 4):
+ * the Pfau funded-ratio lens as an advisory card. Fires when the household has
+ * distinguished a required floor from lifestyle spending and guaranteed income
+ * covers less than ~90% of its present value on the TIPS curve.
+ */
+export const incomeFloorFunded = {
+    id: 'income-floor-funded',
+    category: 'longevity-insurance-geography',
+    screen(ctx) {
+        const plan = ctx.plan;
+        // Only meaningful once the user has said what "essential" means: without
+        // requiredAnnual the floor equals the whole lifestyle and the card would
+        // just restate the success rate.
+        if (plan.expenses.requiredAnnual === undefined)
+            return null;
+        const primary = plan.household.people[0];
+        if (!primary)
+            return null;
+        const retirementYear = primary.retirementAge !== null ? Number(primary.dob.slice(0, 4)) + primary.retirementAge : ctx.projection.startYear;
+        const fr = computeFundedRatio({
+            years: ctx.projection.result.years,
+            startYear: ctx.projection.startYear,
+            deflate: ctx.projection.deflate,
+            curve: EMBEDDED_REAL_YIELD_CURVE,
+            fromYear: Math.max(retirementYear, ctx.projection.startYear),
+        });
+        if (!fr || fr.fundedRatioPct >= 90)
+            return null;
+        const pct = Math.round(fr.fundedRatioPct);
+        return {
+            id: 'income-floor-funded',
+            category: 'longevity-insurance-geography',
+            title: `Your essential-spending floor is ${pct}% funded`,
+            rationale: `Discounted on today's TIPS curve, your essential retirement spending is worth ` +
+                `$${Math.round(fr.essentialSpendingPv).toLocaleString()} in today's dollars, and guaranteed income ` +
+                `(Social Security, pensions, annuities, TIPS ladders) covers $${Math.round(fr.guaranteedIncomePv).toLocaleString()} of it (${pct}%). ` +
+                `The $${Math.round(fr.unfundedPv).toLocaleString()} gap rides on the portfolio; a TIPS ladder can lock some of it in at ~` +
+                `${EMBEDDED_REAL_YIELD_CURVE.points[EMBEDDED_REAL_YIELD_CURVE.points.length - 1].realYieldPct}% real.`,
+            impact: {
+                qualitative: 'The funded ratio is a risk lens, not a verdict: a portfolio can fund the gap in most markets — the question is how much of the floor you want guaranteed regardless of markets.',
+            },
+            exact: false,
+            confidence: 'medium',
+            learnSlug: 'funded-ratio',
+            plannerRoute: 'income-floor',
+            action: { kind: 'advisory' },
+        };
+    },
+};

package/dist/insights/detectors/irmaaTierEdge.d.ts

@@ -0,0 +1,2 @@
+import type { Detector } from '../types.js';
+export declare const irmaaTierEdge: Detector;

package/dist/insights/detectors/irmaaTierEdge.js

@@ -0,0 +1,102 @@
+import { irmaaTierForMagi } from '../../params/index.js';
+import { medicareAnnualPremiumPerPerson } from '../../tax/medicare.js';
+function inflationScaleFromPack(ctx, toYear) {
+    if (toYear <= ctx.params.year)
+        return 1;
+    return Math.pow(1 + ctx.plan.assumptions.inflationPct / 100, toYear - ctx.params.year);
+}
+function healthcarePremiumScaleFromPack(ctx, toYear) {
+    if (toYear <= ctx.params.year)
+        return 1;
+    const annualRate = 1 + (ctx.plan.assumptions.inflationPct + ctx.plan.assumptions.healthcareExtraInflationPct) / 100;
+    return Math.pow(annualRate, toYear - ctx.params.year);
+}
+function trimmedConversionPatch(ctx, year, trimAmount) {
+    const conversions = ctx.projection.result.years
+        .map((projectionYear) => ({
+        year: projectionYear.year,
+        amount: Math.max(0, projectionYear.rothConversion - (projectionYear.year === year ? trimAmount : 0)),
+    }))
+        .filter((conversion) => conversion.amount > 1);
+    return {
+        strategies: {
+            rothConversion: {
+                mode: 'manual',
+                conversions,
+            },
+        },
+    };
+}
+export const irmaaTierEdge = {
+    id: 'irmaa-tier-edge',
+    category: 'tax-brackets',
+    screen(ctx) {
+        const filingStatus = ctx.plan.household.filingStatus;
+        // Scan years for an IRMAA cliff proximity
+        for (const y of ctx.projection.result.years) {
+            const premiumYearNumber = y.year + 2;
+            const thresholdScale = inflationScaleFromPack(ctx, premiumYearNumber);
+            const tier = irmaaTierForMagi(ctx.params, y.magi, filingStatus, thresholdScale);
+            if (tier > 0 && tier <= ctx.params.medicare.irmaaTiers.length) {
+                const threshold = ctx.params.medicare.irmaaTiers[tier - 1].magiOver[filingStatus] * thresholdScale;
+                const diff = y.magi - threshold;
+                if (diff > 0 && diff <= 5000) {
+                    const magiStr = '$' + Math.round(y.magi).toLocaleString();
+                    const threshStr = '$' + Math.round(threshold).toLocaleString();
+                    const premiumYear = ctx.projection.result.years.find((candidate) => candidate.year === premiumYearNumber);
+                    if (!premiumYear)
+                        continue;
+                    const medicarePeople = premiumYear.people.filter((p) => p.alive && p.ageAttained >= 65).length;
+                    if (medicarePeople === 0)
+                        continue;
+                    const premiumScale = healthcarePremiumScaleFromPack(ctx, premiumYearNumber);
+                    const premiumAbove = medicareAnnualPremiumPerPerson(ctx.params, y.magi, filingStatus, thresholdScale, premiumScale);
+                    const premiumBelow = medicareAnnualPremiumPerPerson(ctx.params, Math.max(0, threshold - 1), filingStatus, thresholdScale, premiumScale);
+                    const annualPremiumCliff = medicarePeople *
+                        Math.max(0, premiumAbove.partBAnnual +
+                            premiumAbove.partDSurchargeAnnual -
+                            premiumBelow.partBAnnual -
+                            premiumBelow.partDSurchargeAnnual);
+                    const trimAmount = Math.ceil(diff + 250);
+                    const conversionDriven = y.rothConversion > trimAmount;
+                    return {
+                        id: 'irmaa-tier-edge',
+                        category: 'tax-brackets',
+                        title: 'IRMAA tier-edge proximity',
+                        rationale: `Your nominal MAGI of ${magiStr} in ${y.year} is just over the ${premiumYearNumber} IRMAA tier threshold of ${threshStr}. This will trigger higher Medicare premiums in ${premiumYearNumber}.`,
+                        impact: {
+                            endingAfterTaxEstateDelta: annualPremiumCliff > 0 ? annualPremiumCliff : undefined,
+                            qualitative: annualPremiumCliff > 0
+                                ? `Avoiding this tier could save roughly $${Math.round(annualPremiumCliff).toLocaleString()} of Medicare premiums in ${premiumYearNumber}.`
+                                : 'Limit conversion-driven nominal MAGI to stay just under the IRMAA threshold.',
+                        },
+                        exact: false,
+                        confidence: 'high',
+                        learnSlug: 'irmaa-two-year-lookback',
+                        plannerRoute: 'optimize',
+                        action: conversionDriven
+                            ? {
+                                kind: 'preview-scenario',
+                                scenarioName: 'Trim conversion below IRMAA tier',
+                                patch: trimmedConversionPatch(ctx, y.year, trimAmount),
+                            }
+                            : {
+                                kind: 'advisory',
+                            },
+                    };
+                }
+            }
+        }
+        return null;
+    },
+    evaluate(ctx) {
+        const card = this.screen(ctx);
+        if (!card) {
+            throw new Error('IRMAA tier edge not eligible');
+        }
+        return {
+            action: card.action,
+            impact: card.impact,
+        };
+    },
+};

package/dist/insights/detectors/pensionElectionPending.d.ts

@@ -0,0 +1,11 @@
+import type { Detector } from '../types.js';
+/**
+ * "A pension lump-sum election is on record and undecided"
+ * (annuity-pension-and-home-equity, step 5). Fires when a pension carries a
+ * lump-sum offer with no election and the election year hasn't passed. The
+ * card quotes the PV comparison at the curve-anchored rate (deterministic
+ * math, no simulate calls) and previews the take-the-lump-sum scenario so the
+ * exact ledger prices taxes, survivor interplay, and sequence risk — the
+ * verdict stays a tradeoff, never advice.
+ */
+export declare const pensionElectionPending: Detector;

package/dist/insights/detectors/pensionElectionPending.js

@@ -0,0 +1,62 @@
+import { analyzePensionElections, pensionTakeLumpSumPatch } from '../../decisions/pensionElection.js';
+/**
+ * "A pension lump-sum election is on record and undecided"
+ * (annuity-pension-and-home-equity, step 5). Fires when a pension carries a
+ * lump-sum offer with no election and the election year hasn't passed. The
+ * card quotes the PV comparison at the curve-anchored rate (deterministic
+ * math, no simulate calls) and previews the take-the-lump-sum scenario so the
+ * exact ledger prices taxes, survivor interplay, and sequence risk — the
+ * verdict stays a tradeoff, never advice.
+ */
+export const pensionElectionPending = {
+    id: 'pension-election-pending',
+    category: 'longevity-insurance-geography',
+    screen(ctx) {
+        const plan = ctx.plan;
+        const startYear = ctx.projection.startYear;
+        const pending = plan.accounts.find((a) => a.type === 'pension' &&
+            a.lumpSumOffer !== undefined &&
+            a.lumpSumElection === undefined &&
+            a.lumpSumOffer.electionYear >= startYear);
+        if (!pending || pending.type !== 'pension')
+            return null;
+        const analysis = analyzePensionElections(plan, startYear).find((a) => a.pensionId === pending.id);
+        if (!analysis || analysis.lumpSum <= 0)
+            return null;
+        const pv = analysis.presentValueAtCurveRate;
+        const ratio = pv / analysis.lumpSum;
+        const direction = ratio > 1.05
+            ? `the annuity's discounted value (~$${Math.round(pv).toLocaleString()}) is above the offer`
+            : ratio < 0.95
+                ? `the offer is above the annuity's discounted value (~$${Math.round(pv).toLocaleString()})`
+                : `the offer and the annuity's discounted value (~$${Math.round(pv).toLocaleString()}) are close`;
+        // The concrete take-the-lump-sum patch comes from the shared builder so
+        // the insight and the decision engine can never disagree about mechanics.
+        const patch = pensionTakeLumpSumPatch(plan, pending, startYear);
+        return {
+            id: 'pension-election-pending',
+            category: 'longevity-insurance-geography',
+            title: `Pension election pending: $${Math.round(analysis.lumpSum).toLocaleString()} lump sum vs lifetime annuity`,
+            rationale: `${pending.name} offers a $${Math.round(analysis.lumpSum).toLocaleString()} lump sum in ${analysis.electionYear}. ` +
+                `At the ${analysis.curveRatePct.toFixed(1)}% curve-anchored discount rate to your planning age, ${direction}. ` +
+                'The Accounts section shows the full sensitivity table (discount rate × longevity, survivor option value); ' +
+                'the decision hinges on longevity, survivor needs, and what you would earn on the rollover — tradeoffs, not a verdict.',
+            impact: {
+                qualitative: 'Preview taking the lump sum (tax-free rollover to a traditional IRA) against keeping the annuity, priced on the exact ledger.',
+            },
+            exact: false,
+            confidence: 'high',
+            learnSlug: 'pensions-and-annuities',
+            plannerRoute: 'accounts',
+            action: patch
+                ? { kind: 'preview-scenario', scenarioName: `Take the ${pending.name} lump sum`, patch }
+                : { kind: 'advisory' },
+        };
+    },
+    evaluate(ctx) {
+        const card = this.screen(ctx);
+        if (!card)
+            throw new Error('Pension election not eligible');
+        return { action: card.action, impact: card.impact };
+    },
+};

package/dist/insights/detectors/qcdEfficiency.d.ts

@@ -0,0 +1,2 @@
+import type { Detector } from '../types.js';
+export declare const qcdEfficiency: Detector;

package/dist/insights/detectors/qcdEfficiency.js

@@ -0,0 +1,62 @@
+export const qcdEfficiency = {
+    id: 'qcd-efficiency',
+    category: 'withdrawals-charitable',
+    screen(ctx) {
+        const charitable = ctx.plan.strategies.itemizedDeductions?.charitable ?? 0;
+        if (charitable <= 0) {
+            return null;
+        }
+        if (ctx.plan.strategies.qcdAnnual >= charitable) {
+            return null;
+        }
+        const firstYear = ctx.projection.result.years[0];
+        if (!firstYear) {
+            return null;
+        }
+        // Check if anyone is age-eligible (age attained 71+ in the start year)
+        const hasAgeEligible = firstYear.people.some((p) => p.alive && p.ageAttained >= 71);
+        if (!hasAgeEligible) {
+            return null;
+        }
+        // Check if they have traditional assets to donate from
+        const hasTrad = ctx.plan.accounts.some((a) => a.type === 'traditional' && (firstYear.balances[a.id] ?? 0) > 0);
+        if (!hasTrad) {
+            return null;
+        }
+        const charitableStr = '$' + Math.round(charitable).toLocaleString();
+        return {
+            id: 'qcd-efficiency',
+            category: 'withdrawals-charitable',
+            title: 'Use QCDs for charitable giving',
+            rationale: `You are donating ${charitableStr} per year but not utilizing Qualified Charitable Distributions (QCDs). Since you are over 70½, routing donations directly from your pre-tax IRA is more tax-efficient.`,
+            impact: { qualitative: 'Satisfy RMDs and lower your taxable income by donating pre-tax IRA assets directly to charity.' },
+            exact: false,
+            confidence: 'high',
+            learnSlug: 'qcds-qualified-charitable-distributions',
+            plannerRoute: 'strategy',
+            action: {
+                kind: 'preview-scenario',
+                scenarioName: 'Use QCDs for donations',
+                patch: {
+                    strategies: {
+                        qcdAnnual: charitable,
+                        itemizedDeductions: {
+                            ...ctx.plan.strategies.itemizedDeductions,
+                            charitable: 0,
+                        },
+                    },
+                },
+            },
+        };
+    },
+    evaluate(ctx) {
+        const card = this.screen(ctx);
+        if (!card) {
+            throw new Error('QCD efficiency not eligible');
+        }
+        return {
+            action: card.action,
+            impact: card.impact,
+        };
+    },
+};

package/dist/insights/detectors/rothBridgeHeadroom.d.ts

@@ -0,0 +1,2 @@
+import type { Detector } from '../types.js';
+export declare const rothBridgeHeadroom: Detector;

package/dist/insights/detectors/rothBridgeHeadroom.js

@@ -0,0 +1,77 @@
+export const rothBridgeHeadroom = {
+    id: 'roth-bridge-headroom',
+    category: 'tax-brackets',
+    screen(ctx) {
+        if (ctx.plan.strategies.rothConversion.mode !== 'none') {
+            return null;
+        }
+        // Check if the plan has owner-convertible traditional balance. Inherited
+        // traditional accounts follow beneficiary distribution rules and cannot be
+        // converted into the beneficiary's Roth IRA.
+        const tradBalance = ctx.plan.accounts
+            .filter((a) => a.type === 'traditional' && !a.inherited)
+            .reduce((sum, a) => sum + (ctx.projection.result.years[0]?.balances[a.id] ?? 0), 0);
+        if (tradBalance < 10000) {
+            return null;
+        }
+        // Find bridge years
+        let firstYear = null;
+        let lastYear = null;
+        for (const y of ctx.projection.result.years) {
+            const allRetired = y.incomes.wages < 10000;
+            const anyPreRmd = y.people.some((p) => p.alive && p.ageAttained < 73);
+            const hasTradFunds = ctx.plan.accounts
+                .filter((a) => a.type === 'traditional' && !a.inherited)
+                .reduce((sum, a) => sum + (y.balances[a.id] ?? 0), 0) > 10000;
+            if (allRetired && anyPreRmd && hasTradFunds) {
+                if (firstYear === null) {
+                    firstYear = y.year;
+                }
+                lastYear = y.year;
+            }
+            else if (firstYear !== null) {
+                // Contiguous block complete
+                break;
+            }
+        }
+        if (firstYear === null || lastYear === null) {
+            return null;
+        }
+        return {
+            id: 'roth-bridge-headroom',
+            category: 'tax-brackets',
+            title: 'Test Roth conversion bridge years',
+            rationale: `You have low-income bridge years from ${firstYear} to ${lastYear} before RMDs begin. A bracket-fill Roth conversion scenario is worth previewing against your full projection before treating it as a recommendation.`,
+            impact: { qualitative: 'Preview a lower-bracket conversion scenario; taxes, healthcare cliffs, and liquidity can still make it unattractive.' },
+            exact: false,
+            confidence: 'medium',
+            learnSlug: 'roth-conversion-basics',
+            plannerRoute: 'strategy',
+            action: {
+                kind: 'preview-scenario',
+                scenarioName: 'Convert to top of 12% bracket',
+                patch: {
+                    strategies: {
+                        rothConversion: {
+                            mode: 'fillToTarget',
+                            target: 'topOfBracket',
+                            targetValue: 12,
+                            startYear: firstYear,
+                            endYear: lastYear,
+                        },
+                    },
+                },
+            },
+        };
+    },
+    evaluate(ctx) {
+        const card = this.screen(ctx);
+        if (!card) {
+            throw new Error('Roth bridge headroom not eligible');
+        }
+        return {
+            action: card.action,
+            impact: card.impact,
+        };
+    },
+};