@retiregolden/engine 0.1.0

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

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

package/dist/insights/detectors/spendingGuardrails.js

@@ -0,0 +1,77 @@
+import { probabilityBandSpendingGuardrailGenerator } from '../../decisions/generators.js';
+function guardrailPatchFromGenerator(plan) {
+    const ctx = { plan };
+    const candidates = probabilityBandSpendingGuardrailGenerator().generate(ctx);
+    if (candidates.length === 0)
+        return null;
+    const candidate = candidates[0];
+    const patch = candidate.planPatch;
+    if (!patch || typeof patch !== 'object')
+        return null;
+    const expenses = patch.expenses;
+    if (!expenses || typeof expenses !== 'object')
+        return null;
+    const requiredAnnual = expenses.requiredAnnual;
+    if (typeof requiredAnnual !== 'number' || !Number.isFinite(requiredAnnual))
+        return null;
+    const spendingPolicy = expenses.spendingPolicy;
+    if (!spendingPolicy ||
+        typeof spendingPolicy !== 'object' ||
+        spendingPolicy.mode !== 'withdrawalRateGuardrails') {
+        return null;
+    }
+    return { requiredAnnual, patch: patch };
+}
+export const spendingGuardrails = {
+    id: 'spending-guardrails',
+    category: 'sequence-risk',
+    screen(ctx) {
+        const firstYear = ctx.projection.result.years[0];
+        if (!firstYear)
+            return null;
+        // Any active guardrail policy (withdrawal-rate or risk-based) means the
+        // plan already has dynamic spending rules — nothing to recommend.
+        const mode = ctx.plan.expenses.spendingPolicy?.mode;
+        if (mode !== undefined && mode !== 'fixedTarget')
+            return null;
+        const hasDepletion = ctx.projection.summary.depletionYear !== null;
+        const hasAssets = firstYear.investableTotal > 100_000;
+        if (!hasDepletion && !hasAssets)
+            return null;
+        const generated = guardrailPatchFromGenerator(ctx.plan);
+        if (!generated)
+            return null;
+        const { requiredAnnual, patch } = generated;
+        return {
+            id: 'spending-guardrails',
+            category: 'sequence-risk',
+            title: 'Use dynamic spending guardrails',
+            rationale: `Your plan currently assumes fixed inflation-adjusted spending. Preview a rules-based guardrail scenario with a $${Math.round(requiredAnnual).toLocaleString()} required floor and 10% spending adjustments when the withdrawal-rate band is crossed.`,
+            impact: {
+                qualitative: 'Preview to compare the projected and Monte Carlo impact of flexible spending rules.',
+                successRateDeltaPct: 12,
+            },
+            exact: false,
+            confidence: 'medium',
+            learnSlug: 'dynamic-spending-guardrails',
+            plannerRoute: 'spending',
+            action: {
+                kind: 'preview-scenario',
+                scenarioName: 'Dynamic spending guardrails',
+                patch,
+            },
+        };
+    },
+    evaluate(ctx) {
+        const card = this.screen(ctx);
+        if (!card || card.action.kind !== 'preview-scenario')
+            throw new Error('Spending guardrails not eligible');
+        return {
+            action: card.action,
+            impact: {
+                qualitative: 'Exact preview applies the guardrail policy inside the same annual ledger used by Results and Monte Carlo.',
+                successRateDeltaPct: card.impact.successRateDeltaPct,
+            },
+        };
+    },
+};

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

@@ -0,0 +1,12 @@
+/**
+ * Spending-headroom detector (sustainable-spending plan, Step 6).
+ *
+ * Two-phase per the detector contract: `screen()` is cheap and pure — it only
+ * reads the baseline projection (never depleting + a large ending estate above
+ * the bequest target ⇒ the plan is leaving lifestyle on the table) and offers
+ * a ROUGH estimate. `evaluate()` runs the exact-ledger sustainable-spending
+ * solver under the same fixed budget the "How much can I spend?" page uses,
+ * so the card and that surface report the same solved level.
+ */
+import type { Detector } from '../types.js';
+export declare const spendingHeadroom: Detector;

package/dist/insights/detectors/spendingHeadroom.js

@@ -0,0 +1,92 @@
+/**
+ * Spending-headroom detector (sustainable-spending plan, Step 6).
+ *
+ * Two-phase per the detector contract: `screen()` is cheap and pure — it only
+ * reads the baseline projection (never depleting + a large ending estate above
+ * the bequest target ⇒ the plan is leaving lifestyle on the table) and offers
+ * a ROUGH estimate. `evaluate()` runs the exact-ledger sustainable-spending
+ * solver under the same fixed budget the "How much can I spend?" page uses,
+ * so the card and that surface report the same solved level.
+ */
+import { createDecisionContext, solveMaxSustainableSpending, SPENDING_SOLVER_UI_BUDGET, } from '../../decisions/index.js';
+import { combineTaxCalculators, createFederalTaxCalculator } from '../../tax/federalTax.js';
+import { createStateTaxCalculator } from '../../tax/stateTax.js';
+/** Screen only when the excess estate could fund a meaningful lifestyle bump. */
+const MIN_EXCESS_ESTATE_TODAY_DOLLARS = 250_000;
+const MIN_ROUGH_HEADROOM_PER_YEAR = 2_000;
+export const spendingHeadroom = {
+    id: 'spending-headroom',
+    category: 'sequence-risk',
+    screen(ctx) {
+        const summary = ctx.projection.summary;
+        if (summary.depletionYear !== null)
+            return null;
+        // Amortized spending (ABW) already spends the portfolio down by design; a
+        // "raise your fixed baseline" headroom card (and the base-spending solver
+        // behind it) doesn't apply — the solver refuses ABW plans with a diagnostic.
+        if (ctx.plan.expenses.spendingPolicy?.mode === 'abw')
+            return null;
+        const endYear = ctx.projection.result.endYear;
+        const yearsRemaining = Math.max(1, endYear - ctx.projection.startYear);
+        const bequestTarget = ctx.plan.expenses.bequestTargetDollars ?? 0;
+        const endingEstateToday = ctx.projection.deflate(endYear, summary.endingAfterTaxEstate);
+        const excessEstateToday = endingEstateToday - bequestTarget;
+        if (excessEstateToday < MIN_EXCESS_ESTATE_TODAY_DOLLARS)
+            return null;
+        // Rough (pre-tax, straight-line) reading of the excess: what spreading it
+        // evenly over the remaining years would add to annual spending. The exact
+        // answer needs the solver — taxes, cliffs, and sequencing always shrink it.
+        const roughHeadroomPerYear = excessEstateToday / yearsRemaining;
+        if (roughHeadroomPerYear < MIN_ROUGH_HEADROOM_PER_YEAR)
+            return null;
+        const baseAnnual = ctx.plan.expenses.baseAnnual;
+        return {
+            id: 'spending-headroom',
+            category: 'sequence-risk',
+            title: 'Your plan may support more spending',
+            rationale: `Your plan is projected to end with roughly $${Math.round(endingEstateToday).toLocaleString()} of after-tax estate in today's dollars${bequestTarget > 0 ? ` — well above your $${Math.round(bequestTarget).toLocaleString()} bequest target` : ' with no bequest target set'}. Previewing the max-sustainable spending level shows how much lifestyle that margin could fund.`,
+            impact: {
+                qualitative: `≈ $${Math.round(roughHeadroomPerYear).toLocaleString()}/yr of rough headroom before taxes; preview for the precise answer.`,
+            },
+            exact: false,
+            confidence: 'medium',
+            learnSlug: 'building-a-retirement-spending-budget',
+            plannerRoute: 'spending-solver',
+            action: {
+                kind: 'preview-scenario',
+                scenarioName: 'Spend closer to plan capacity',
+                // Conservative placeholder — evaluate() replaces it with the solved level.
+                patch: { expenses: { baseAnnual: Math.round(baseAnnual + roughHeadroomPerYear / 2) } },
+            },
+        };
+    },
+    evaluate(ctx) {
+        const card = this.screen(ctx);
+        if (!card)
+            throw new Error('Spending headroom not eligible');
+        const taxCalculator = combineTaxCalculators(createFederalTaxCalculator(), createStateTaxCalculator({
+            overridePct: ctx.plan.assumptions.stateEffectiveTaxPct,
+            localPct: ctx.plan.assumptions.localIncomeTaxPct,
+        }));
+        const decisionCtx = createDecisionContext(ctx.plan, { startYear: ctx.projection.startYear, taxCalculator }, { result: ctx.projection.result, summary: ctx.projection.summary });
+        const solved = solveMaxSustainableSpending(decisionCtx, {
+            maxSimulations: SPENDING_SOLVER_UI_BUDGET,
+            estateFloorTodayDollars: ctx.plan.expenses.bequestTargetDollars ?? 0,
+        });
+        const maxBaseAnnual = solved.maxBaseAnnual;
+        const slack = solved.spendingSlackDollars ?? 0;
+        if (maxBaseAnnual === null || slack < 1_000) {
+            throw new Error('The spending solver found no meaningful headroom once taxes, healthcare cliffs, and sequencing were priced in.');
+        }
+        return {
+            action: {
+                kind: 'preview-scenario',
+                scenarioName: `Spend $${Math.round(maxBaseAnnual).toLocaleString()}/yr (max sustainable)`,
+                patch: { expenses: { baseAnnual: maxBaseAnnual } },
+            },
+            impact: {
+                qualitative: `Exact ledger sustains about $${Math.round(maxBaseAnnual).toLocaleString()}/yr of baseline spending — $${Math.round(slack).toLocaleString()}/yr above your current level (today's dollars).`,
+            },
+        };
+    },
+};

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

@@ -0,0 +1,9 @@
+import type { Detector } from '../types.js';
+/**
+ * "Your gap years are unfunded — consider a bridge"
+ * (social-security-bridge-and-tips-ladder, step 4). Fires when someone delays
+ * Social Security past retirement with no TIPS ladder covering the gap years,
+ * and liquid savings could fund one. The action previews the sized bridge as
+ * a scenario, so the ledger (not the card) prices it.
+ */
+export declare const ssBridgeGap: Detector;

package/dist/insights/detectors/ssBridgeGap.js

@@ -0,0 +1,92 @@
+import { EMBEDDED_REAL_YIELD_CURVE } from '../../params/index.js';
+import { BRIDGE_FUNDING_MIN_FRACTION, sizeBridge } from '../../ladder/bridge.js';
+/**
+ * "Your gap years are unfunded — consider a bridge"
+ * (social-security-bridge-and-tips-ladder, step 4). Fires when someone delays
+ * Social Security past retirement with no TIPS ladder covering the gap years,
+ * and liquid savings could fund one. The action previews the sized bridge as
+ * a scenario, so the ledger (not the card) prices it.
+ */
+export const ssBridgeGap = {
+    id: 'ss-bridge-gap',
+    category: 'social-security',
+    screen(ctx) {
+        const plan = ctx.plan;
+        const startYear = ctx.projection.startYear;
+        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))
+            return null;
+        const ladders = [];
+        let totalCost = 0;
+        let firstYear = Number.POSITIVE_INFINITY;
+        let lastYear = 0;
+        let annualTotal = 0;
+        for (const stream of plan.incomes) {
+            if (stream.type !== 'socialSecurity' || stream.piaMonthly === null || stream.piaMonthly <= 0)
+                continue;
+            const person = plan.household.people.find((p) => p.id === stream.personId);
+            if (!person)
+                continue;
+            const dobYear = Number(person.dob.slice(0, 4));
+            const sized = sizeBridge({
+                piaMonthly: stream.piaMonthly,
+                dob: { year: dobYear, month: Number(person.dob.slice(5, 7)), day: Number(person.dob.slice(8, 10)) },
+                claimAge: stream.claimAge,
+                currentYear: startYear,
+                retirementYear: person.retirementAge !== null ? dobYear + person.retirementAge : startYear,
+                curve: EMBEDDED_REAL_YIELD_CURVE,
+            });
+            if (!sized)
+                continue;
+            const covered = plan.incomeFloor?.ladders.some((l) => l.startYear <= sized.startYear && l.endYear >= sized.endYear);
+            if (covered)
+                continue;
+            totalCost += sized.ladderCost;
+            firstYear = Math.min(firstYear, sized.startYear);
+            lastYear = Math.max(lastYear, sized.endYear);
+            annualTotal += sized.annualRealAmount;
+            ladders.push({
+                id: `ss-bridge-preview-${stream.personId}`,
+                name: `SS bridge (${person.name})`,
+                purpose: 'bridge',
+                startYear: sized.startYear,
+                endYear: sized.endYear,
+                annualRealAmount: sized.annualRealAmount,
+                purchase: { year: startYear, fundingAccountId: liquid.id },
+            });
+        }
+        if (ladders.length === 0)
+            return null;
+        // Don't suggest a bridge the plan clearly cannot buy (shared threshold).
+        if (liquid.balance < totalCost * BRIDGE_FUNDING_MIN_FRACTION)
+            return null;
+        return {
+            id: 'ss-bridge-gap',
+            category: 'social-security',
+            title: 'Fund your Social Security gap years with a bridge',
+            rationale: `You delay Social Security but retire earlier, leaving ${firstYear}–${lastYear} without your benefit. ` +
+                `A TIPS bridge ladder (≈$${Math.round(totalCost).toLocaleString()} today) pays you the forgone age-62 benefit ` +
+                `(~$${Math.round(annualTotal).toLocaleString()}/yr, inflation-protected) until your claim starts — the delayed claim's longevity insurance without the lifestyle gap.`,
+            impact: {
+                qualitative: 'Preview the bridge against your full plan: guaranteed gap-year income and steadier withdrawals, at the cost of locking up liquid savings.',
+            },
+            exact: false,
+            confidence: 'medium',
+            learnSlug: 'social-security-bridge',
+            plannerRoute: 'income-floor',
+            action: {
+                kind: 'preview-scenario',
+                scenarioName: 'Add a Social Security bridge ladder',
+                patch: { incomeFloor: { ladders: [...(plan.incomeFloor?.ladders ?? []), ...ladders] } },
+            },
+        };
+    },
+    evaluate(ctx) {
+        const card = this.screen(ctx);
+        if (!card)
+            throw new Error('SS bridge gap not eligible');
+        return { action: card.action, impact: card.impact };
+    },
+};

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

@@ -0,0 +1,12 @@
+/**
+ * State-relocation detector (extended by the relocation-compare plan —
+ * DOCS/enhancements/state-relocation-compare.md, step 3).
+ *
+ * `screen()` keeps its original cheap conditions: a taxed state, no planned
+ * moves. `evaluate()` now quantifies the lifetime tax drag by running the
+ * relocation-compare sweep over the modeled zero-income-tax shortlist and
+ * previews the top candidate as a scenario. Copy stays neutral — income tax
+ * is one relocation factor, so the card says "worth a look", never "move".
+ */
+import type { Detector } from '../types.js';
+export declare const stateRelocation: Detector;

package/dist/insights/detectors/stateRelocation.js

@@ -0,0 +1,99 @@
+/**
+ * State-relocation detector (extended by the relocation-compare plan —
+ * DOCS/enhancements/state-relocation-compare.md, step 3).
+ *
+ * `screen()` keeps its original cheap conditions: a taxed state, no planned
+ * moves. `evaluate()` now quantifies the lifetime tax drag by running the
+ * relocation-compare sweep over the modeled zero-income-tax shortlist and
+ * previews the top candidate as a scenario. Copy stays neutral — income tax
+ * is one relocation factor, so the card says "worth a look", never "move".
+ */
+import { stateParamsFor } from '../../params/state/index.js';
+import { compareRelocationCandidates, relocationScenarioPatch, } from '../../projection/relocation.js';
+/** Modeled zero-income-tax candidates the evaluate() sweep prices. */
+const ZERO_TAX_SHORTLIST = ['FL', 'TX', 'WA'];
+export const stateRelocation = {
+    id: 'state-relocation',
+    category: 'longevity-insurance-geography',
+    screen(ctx) {
+        const startYear = ctx.projection.startYear;
+        const currentState = ctx.plan.household.state;
+        // If already in a tax-free state and no flat override, it's not applicable
+        const params = stateParamsFor(currentState, startYear);
+        const currentHasIncomeTax = ctx.plan.assumptions.stateEffectiveTaxPct > 0 || (params ? params.hasIncomeTax : true);
+        if (!currentHasIncomeTax) {
+            return null;
+        }
+        if (currentState === 'FL') {
+            return null;
+        }
+        // Only suggest if they haven't planned any moves yet
+        if (ctx.plan.household.stateMoves && ctx.plan.household.stateMoves.length > 0) {
+            return null;
+        }
+        return {
+            id: 'state-relocation',
+            category: 'longevity-insurance-geography',
+            title: 'State residence is a tax lever worth a look',
+            rationale: `Your plan is based in ${currentState}, which levies an income tax, with no relocation modeled. If a move is ever on the table for other reasons, the state-tax difference is worth quantifying — the Relocation Compare page prices candidate states on your actual plan. Income tax is one factor among many; nothing here says you should move.`,
+            impact: { qualitative: 'Preview to quantify the lifetime state-tax drag vs modeled zero-income-tax states on your own plan.' },
+            exact: false,
+            confidence: 'medium',
+            learnSlug: 'state-income-taxes-in-retirement',
+            plannerRoute: 'relocation',
+            action: {
+                kind: 'preview-scenario',
+                scenarioName: 'Relocate to a tax-free state',
+                // Rough placeholder — evaluate() replaces it with the sweep's top candidate.
+                patch: relocationScenarioPatch(ctx.plan, { state: 'FL', moveYear: startYear }, startYear),
+            },
+        };
+    },
+    evaluate(ctx) {
+        const card = this.screen(ctx);
+        if (!card) {
+            throw new Error('State relocation not eligible');
+        }
+        const startYear = ctx.projection.startYear;
+        try {
+            // Deterministic sweep (no Monte Carlo) over the zero-income-tax
+            // shortlist, each as a split-year move this July — the same engine the
+            // Relocation Compare page runs, so the card and the page can never
+            // disagree. Four ledger runs, on par with other detectors' evaluate().
+            const comparison = compareRelocationCandidates(ctx.plan, ZERO_TAX_SHORTLIST.map((state) => ({ state, moveYear: startYear })), { startYear });
+            const baseline = comparison.rows.find((r) => r.id === 'baseline');
+            const candidates = comparison.rows.filter((r) => r.id !== 'baseline' && r.error === null);
+            if (!baseline || candidates.length === 0)
+                throw new Error('Relocation sweep produced no valid candidates');
+            const best = candidates.reduce((a, b) => (b.lifetimeTaxesAndPenalties < a.lifetimeTaxesAndPenalties ? b : a));
+            // Lifetime state-tax drag in today's dollars: deflate the per-year
+            // state+local tax delta between staying and the best candidate. This is
+            // deliberately qualitative-only — the preview grid's numeric deltas come
+            // from the shared exact-ledger evaluator on a different basis (total
+            // taxes, nominal), and two numbers on two bases would collide.
+            const baseByYear = new Map(baseline.stateTaxByYear.map((l) => [l.year, l.tax]));
+            const bestByYear = new Map(best.stateTaxByYear.map((l) => [l.year, l.tax]));
+            const years = new Set([...baseByYear.keys(), ...bestByYear.keys()]);
+            let lifetimeStateTaxDeltaToday = 0;
+            for (const year of years) {
+                lifetimeStateTaxDeltaToday += ctx.projection.deflate(year, (bestByYear.get(year) ?? 0) - (baseByYear.get(year) ?? 0));
+            }
+            const savings = Math.max(0, -lifetimeStateTaxDeltaToday);
+            return {
+                action: {
+                    kind: 'preview-scenario',
+                    scenarioName: `Relocate to ${best.destinationState} (illustrative)`,
+                    patch: relocationScenarioPatch(ctx.plan, { state: best.destinationState, moveYear: startYear }, startYear),
+                },
+                impact: {
+                    qualitative: `Exact ledger: staying in ${ctx.plan.household.state} costs about $${Math.round(savings).toLocaleString()} of lifetime state+local income tax (today's dollars) vs ${best.destinationState}, the best of ${ZERO_TAX_SHORTLIST.join('/')} on your plan. Income tax is one relocation factor — compare your own shortlist on the Relocation Compare page.`,
+                },
+            };
+        }
+        catch {
+            // Degrade to the rough screen-level card instead of erroring the
+            // preview; the Relocation Compare page remains the exact surface.
+            return { action: card.action, impact: card.impact };
+        }
+    },
+};

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

@@ -0,0 +1,12 @@
+import type { Detector } from '../types.js';
+/**
+ * The widow's-penalty lever (extended by survivor-widowhood-and-irmaa-relief,
+ * step 3): screens trad-heavy MFJ couples without conversions — the original
+ * gate is unchanged — and now quantifies the survivor bracket jump on the
+ * plan's own first single-FILED survivor year (same MAGI priced single vs
+ * joint, a cheap pack calculation, exact:false; QSS interlude years keep the
+ * joint tables and are narrated, not priced), flags survivor-year IRMAA tiers
+ * with an SSA-44 pointer when the plan isn't modeling the relief, and previews
+ * the conversion-acceleration scenario the caller prices on the exact ledger.
+ */
+export declare const widowsPenalty: Detector;

package/dist/insights/detectors/widowsPenalty.js

@@ -0,0 +1,145 @@
+import { computeFederalTax } from '../../tax/federalTax.js';
+/**
+ * The widow's-penalty lever (extended by survivor-widowhood-and-irmaa-relief,
+ * step 3): screens trad-heavy MFJ couples without conversions — the original
+ * gate is unchanged — and now quantifies the survivor bracket jump on the
+ * plan's own first single-FILED survivor year (same MAGI priced single vs
+ * joint, a cheap pack calculation, exact:false; QSS interlude years keep the
+ * joint tables and are narrated, not priced), flags survivor-year IRMAA tiers
+ * with an SSA-44 pointer when the plan isn't modeling the relief, and previews
+ * the conversion-acceleration scenario the caller prices on the exact ledger.
+ */
+export const widowsPenalty = {
+    id: 'widows-penalty-roth',
+    category: 'social-security',
+    screen(ctx) {
+        if (ctx.plan.household.filingStatus !== 'marriedFilingJointly') {
+            return null;
+        }
+        if (ctx.plan.strategies.rothConversion.mode !== 'none') {
+            return null;
+        }
+        // Check if there are traditional assets
+        const firstYear = ctx.projection.result.years[0];
+        if (!firstYear) {
+            return null;
+        }
+        const tradBalance = ctx.plan.accounts
+            .filter((a) => a.type === 'traditional')
+            .reduce((sum, a) => sum + (firstYear.balances[a.id] ?? 0), 0);
+        if (tradBalance < 50000) {
+            return null;
+        }
+        // Find the first year where only one spouse remains alive
+        const singleYearObj = ctx.projection.result.years.find((y) => {
+            const living = y.people.filter((p) => p.alive);
+            return living.length === 1;
+        });
+        if (!singleYearObj) {
+            return null;
+        }
+        const firstSingleYear = singleYearObj.year;
+        const lastJointYear = firstSingleYear - 1;
+        if (lastJointYear < ctx.projection.startYear) {
+            return null;
+        }
+        // Survivor bracket jump, quantified on the plan's own numbers: the first
+        // survivor year that truly files SINGLE (a qualifying surviving spouse
+        // keeps the joint tables for up to two years, so QSS years have no bracket
+        // jump to price), with that year's MAGI compared single vs joint. Rough by
+        // design (taxable SS itself shifts with filing status), so the card stays
+        // exact:false; the preview scenario is what the exact ledger prices.
+        const singleFiledYearObj = ctx.projection.result.years.find((y) => y.year >= firstSingleYear && y.filingStatus === 'single');
+        let bracketJumpToday = 0;
+        if (singleFiledYearObj) {
+            const jumpYear = singleFiledYearObj.year;
+            const survivorMagi = singleFiledYearObj.magi;
+            const jointAges65Plus = ctx.plan.household.people.filter((p) => jumpYear - Number(p.dob.slice(0, 4)) >= 65).length;
+            const bracketJump = Math.max(0, computeFederalTax({
+                year: jumpYear,
+                filingStatus: 'single',
+                ordinaryIncome: survivorMagi,
+                capitalGains: 0,
+                ssBenefits: 0,
+                peopleAged65Plus: singleFiledYearObj.people.filter((p) => p.alive && p.ageAttained >= 65).length,
+            }).totalTax -
+                computeFederalTax({
+                    year: jumpYear,
+                    filingStatus: 'marriedFilingJointly',
+                    ordinaryIncome: survivorMagi,
+                    capitalGains: 0,
+                    ssBenefits: 0,
+                    peopleAged65Plus: jointAges65Plus,
+                }).totalTax);
+            bracketJumpToday = Math.round(ctx.projection.deflate(jumpYear, bracketJump));
+        }
+        // SSA-44 awareness: the two years after the death are redeterminable when
+        // their premiums land in an IRMAA tier the plan isn't already relieving
+        // (QSS years already price IRMAA on the single table, so a flagged tier is
+        // real regardless of the income-tax filing status).
+        const ssa44Window = ctx.projection.result.years.filter((y) => y.year >= firstSingleYear && y.year <= firstSingleYear + 1 && y.irmaaTier > 0);
+        const modelsSsa44 = ctx.plan.expenses.healthcare.ssa44?.survivorYears === true;
+        const ssa44Note = ssa44Window.length > 0 && !modelsSsa44
+            ? ` The survivor's Medicare premiums also land in an IRMAA surcharge tier in ${ssa44Window
+                .map((y) => y.year)
+                .join(' and ')}: Form SSA-44 can re-price those years on the survivor's own income (model it under Spending → Healthcare).`
+            : '';
+        // The death is projected in the last joint year (the death year still
+        // files MFJ); the survivor's own filing starts the year after — as
+        // qualifying surviving spouse first when the plan opts into it.
+        const isQss = singleYearObj.filingStatus === 'qualifyingSurvivingSpouse';
+        const filingStory = isQss
+            ? singleFiledYearObj
+                ? `the survivor files as qualifying surviving spouse (joint tables) through ${singleFiledYearObj.year - 1}, then as Single from ${singleFiledYearObj.year}`
+                : `the survivor files as qualifying surviving spouse (joint tables) for up to two years, then as Single`
+            : `the survivor files as Single from ${firstSingleYear}`;
+        const rationale = `When one spouse passes away (projected in ${lastJointYear}), ${filingStory}. ` +
+            (bracketJumpToday > 100
+                ? `On the survivor's projected income in ${singleFiledYearObj.year}, single brackets and the smaller deduction cost about $${bracketJumpToday.toLocaleString('en-US')} more (today's $) than the same income filed jointly. `
+                : `Single filing cuts tax bracket ceilings in half, raising their tax rate. `) +
+            `Converting traditional assets to Roth before ${firstSingleYear} utilizes joint brackets.` +
+            ssa44Note;
+        const card = {
+            id: 'widows-penalty-roth',
+            category: 'social-security',
+            title: "Avoid the 'widow's penalty' tax cliff",
+            rationale,
+            impact: {
+                // The bracket jump is a size-of-problem number, not this action's
+                // delta, so it lives in the rationale; the preview scenario supplies
+                // the exact deltas when evaluated.
+                qualitative: 'Proactively convert assets while filing Married Jointly to protect the survivor from higher tax brackets.',
+            },
+            exact: false,
+            confidence: 'high',
+            learnSlug: 'widows-penalty-and-survivor-brackets',
+            plannerRoute: 'strategy',
+            action: {
+                kind: 'preview-scenario',
+                scenarioName: 'Pre-emptive conversions (MFJ)',
+                patch: {
+                    strategies: {
+                        rothConversion: {
+                            mode: 'fillToTarget',
+                            target: 'topOfBracket',
+                            targetValue: 12,
+                            startYear: ctx.projection.startYear,
+                            endYear: lastJointYear,
+                        },
+                    },
+                },
+            },
+        };
+        return card;
+    },
+    evaluate(ctx) {
+        const card = this.screen(ctx);
+        if (!card) {
+            throw new Error('Widows penalty not eligible');
+        }
+        return {
+            action: card.action,
+            impact: card.impact,
+        };
+    },
+};

package/dist/insights/registry.d.ts

@@ -0,0 +1,4 @@
+import type { Detector, InsightCard } from './types.js';
+export declare const registry: Detector[];
+export declare function computeCardScore(card: InsightCard): number;
+export declare function sortCards(cards: InsightCard[]): InsightCard[];

package/dist/insights/registry.js

@@ -0,0 +1,62 @@
+import { annuitizationHeadroom } from './detectors/annuitizationHeadroom.js';
+import { assetLocation } from './detectors/assetLocation.js';
+import { hecmBufferCandidate } from './detectors/hecmBufferCandidate.js';
+import { incomeFloorFunded } from './detectors/incomeFloorFunded.js';
+import { irmaaTierEdge } from './detectors/irmaaTierEdge.js';
+import { pensionElectionPending } from './detectors/pensionElectionPending.js';
+import { qcdEfficiency } from './detectors/qcdEfficiency.js';
+import { rothBridgeHeadroom } from './detectors/rothBridgeHeadroom.js';
+import { spendingGuardrails } from './detectors/spendingGuardrails.js';
+import { spendingHeadroom } from './detectors/spendingHeadroom.js';
+import { ssBridgeGap } from './detectors/ssBridgeGap.js';
+import { stateRelocation } from './detectors/stateRelocation.js';
+import { widowsPenalty } from './detectors/widowsPenalty.js';
+export const registry = [
+    annuitizationHeadroom,
+    assetLocation,
+    hecmBufferCandidate,
+    incomeFloorFunded,
+    irmaaTierEdge,
+    pensionElectionPending,
+    qcdEfficiency,
+    rothBridgeHeadroom,
+    spendingGuardrails,
+    spendingHeadroom,
+    ssBridgeGap,
+    stateRelocation,
+    widowsPenalty,
+];
+export function computeCardScore(card) {
+    const hasQuantified = card.impact.endingAfterTaxEstateDelta !== undefined ||
+        card.impact.successRateDeltaPct !== undefined ||
+        card.impact.lifetimeTaxDelta !== undefined;
+    if (!hasQuantified) {
+        return -1;
+    }
+    let metricValue = 0;
+    if (card.impact.endingAfterTaxEstateDelta !== undefined) {
+        metricValue = Math.abs(card.impact.endingAfterTaxEstateDelta);
+    }
+    else if (card.impact.successRateDeltaPct !== undefined) {
+        // Heuristic: scale 1% Monte Carlo success rate to $10,000
+        metricValue = Math.abs(card.impact.successRateDeltaPct) * 10000;
+    }
+    else if (card.impact.lifetimeTaxDelta !== undefined) {
+        metricValue = Math.abs(card.impact.lifetimeTaxDelta);
+    }
+    const confidenceWeight = { high: 1.0, medium: 0.7, low: 0.4 }[card.confidence];
+    return metricValue * confidenceWeight;
+}
+export function sortCards(cards) {
+    return [...cards].sort((a, b) => {
+        const scoreA = computeCardScore(a);
+        const scoreB = computeCardScore(b);
+        if (scoreA !== scoreB) {
+            return scoreB - scoreA; // descending
+        }
+        const catComp = a.category.localeCompare(b.category);
+        if (catComp !== 0)
+            return catComp;
+        return a.title.localeCompare(b.title);
+    });
+}

package/dist/insights/runInsights.d.ts

@@ -0,0 +1,6 @@
+import type { Detector, DetectorContext, InsightCard } from './types.js';
+/**
+ * Runs the synchronous screening pass of all registered detectors.
+ * Filters out nulls and ranks the resulting cards.
+ */
+export declare function runScreen(ctx: DetectorContext, detectors?: Detector[]): InsightCard[];

package/dist/insights/runInsights.js

@@ -0,0 +1,15 @@
+import { registry, sortCards } from './registry.js';
+/**
+ * Runs the synchronous screening pass of all registered detectors.
+ * Filters out nulls and ranks the resulting cards.
+ */
+export function runScreen(ctx, detectors = registry) {
+    const cards = [];
+    for (const detector of detectors) {
+        const card = detector.screen(ctx);
+        if (card) {
+            cards.push(card);
+        }
+    }
+    return sortCards(cards);
+}