@retiregolden/engine 0.1.0

package/dist/params/data/year2026.js

@@ -0,0 +1,199 @@
+/**
+ * Tax year 2026 parameter pack (post-OBBBA current law).
+ *
+ * Sources (verified June 2026) — see DOCS/domain/domain-rules-reference.md:
+ * - Brackets/deductions/AMT: IRS inflation adjustments; Tax Foundation 2026 tables
+ * - Capital gains/NIIT: IRS; Kiplinger 2026 LTCG thresholds
+ * - Limits: IRS IR news release (401(k) $24,500; IRA $7,500)
+ * - RMD: IRS Pub 590-B Uniform Lifetime Table (2022+); QCD $111,000 (2026)
+ * - Medicare: CMS 2026 ($202.90 standard Part B); IRMAA tiers per statute
+ * - Social Security: SSA 2026 COLA fact sheet
+ * - FPL: HHS 2025 guidelines (apply to 2026 ACA coverage year)
+ */
+export const year2026 = {
+    year: 2026,
+    federalTax: {
+        brackets: {
+            single: [
+                { lowerBound: 0, ratePct: 10 },
+                { lowerBound: 12_400, ratePct: 12 },
+                { lowerBound: 50_400, ratePct: 22 },
+                { lowerBound: 105_700, ratePct: 24 },
+                { lowerBound: 201_775, ratePct: 32 },
+                { lowerBound: 256_225, ratePct: 35 },
+                { lowerBound: 640_600, ratePct: 37 },
+            ],
+            marriedFilingJointly: [
+                { lowerBound: 0, ratePct: 10 },
+                { lowerBound: 24_800, ratePct: 12 },
+                { lowerBound: 100_800, ratePct: 22 },
+                { lowerBound: 211_400, ratePct: 24 },
+                { lowerBound: 403_550, ratePct: 32 },
+                { lowerBound: 512_450, ratePct: 35 },
+                { lowerBound: 768_700, ratePct: 37 },
+            ],
+        },
+        standardDeduction: { single: 16_100, marriedFilingJointly: 32_200 },
+        age65Addition: { single: 2_050, marriedFilingJointly: 1_650 },
+        // OBBBA SALT cap: $40,000 for 2025, +1%/yr → $40,400 for 2026.
+        saltCap: 40_400,
+        // Net capital loss deductible against ordinary income (IRC §1211(b)); fixed
+        // at $3,000 since 1978, never indexed.
+        capitalLossOrdinaryOffsetLimit: 3_000,
+        // IRC §121 home-sale gain exclusion; statutory since 1997, never indexed.
+        section121Exclusion: { single: 250_000, marriedFilingJointly: 500_000 },
+        seniorDeduction: {
+            amountPerPerson: 6_000,
+            magiPhaseOutStart: { single: 75_000, marriedFilingJointly: 150_000 },
+            phaseOutRatePct: 6,
+            lastApplicableYear: 2028,
+        },
+        amt: {
+            exemption: { single: 90_100, marriedFilingJointly: 140_200 },
+            exemptionPhaseOutStart: { single: 500_000, marriedFilingJointly: 1_000_000 },
+            exemptionPhaseOutRatePct: 50,
+            rate28StartsAbove: 244_500,
+            rate26Pct: 26,
+            rate28Pct: 28,
+        },
+    },
+    capitalGains: {
+        rate15StartsAbove: { single: 49_450, marriedFilingJointly: 98_900 },
+        rate20StartsAbove: { single: 545_500, marriedFilingJointly: 613_700 },
+    },
+    niit: {
+        ratePct: 3.8,
+        magiThreshold: { single: 200_000, marriedFilingJointly: 250_000 },
+    },
+    ssBenefitTaxation: {
+        tier50Start: { single: 25_000, marriedFilingJointly: 32_000 },
+        tier85Start: { single: 34_000, marriedFilingJointly: 44_000 },
+    },
+    contributionLimits: {
+        employee401k: 24_500,
+        catchUp50: 8_000,
+        superCatchUp60to63: 11_250,
+        rothCatchUpWageThreshold: 150_000,
+        ira: 7_500,
+        iraCatchUp50: 1_100,
+        hsaSelfOnly: 4_400,
+        hsaFamily: 8_750,
+        hsaCatchUp55: 1_000,
+        section415cLimit: 72_000,
+    },
+    rmd: {
+        uniformLifetimeTable: {
+            72: 27.4, 73: 26.5, 74: 25.5, 75: 24.6, 76: 23.7, 77: 22.9, 78: 22.0,
+            79: 21.1, 80: 20.2, 81: 19.4, 82: 18.5, 83: 17.7, 84: 16.8, 85: 16.0,
+            86: 15.2, 87: 14.4, 88: 13.7, 89: 12.9, 90: 12.2, 91: 11.5, 92: 10.8,
+            93: 10.1, 94: 9.5, 95: 8.9, 96: 8.4, 97: 7.8, 98: 7.3, 99: 6.8,
+            100: 6.4, 101: 6.0, 102: 5.6, 103: 5.2, 104: 4.9, 105: 4.6, 106: 4.3,
+            107: 4.1, 108: 3.9, 109: 3.7, 110: 3.5, 111: 3.4, 112: 3.3, 113: 3.1,
+            114: 3.0, 115: 2.9, 116: 2.8, 117: 2.7, 118: 2.5, 119: 2.3, 120: 2.0,
+        },
+        qcdAnnualLimit: 111_000,
+    },
+    annuities: {
+        // SECURE 2.0 QLAC dollar cap: $200,000 (2024), indexed to $210,000 (2025).
+        // The 2026 figure is not yet published; the last-confirmed 2025 cap stands
+        // in (projected forward by inflation past the pack year like other indexed
+        // limits). Source: IRS Notice / SECURE 2.0 Act §202.
+        qlacPremiumCap: 210_000,
+        // IRS Pub 939 Table V — Ordinary Life Annuities, One Life — expected-return
+        // multiples (remaining life expectancy in years) by age at the annuity
+        // starting date. Drives the non-qualified exclusion ratio (Pub 939 General
+        // Rule). Source: IRS Publication 939, Table V.
+        expectedReturnMultiples: {
+            50: 33.1, 51: 32.2, 52: 31.3, 53: 30.4, 54: 29.5, 55: 28.6, 56: 27.7,
+            57: 26.8, 58: 25.9, 59: 25.0, 60: 24.2, 61: 23.3, 62: 22.5, 63: 21.6,
+            64: 20.8, 65: 20.0, 66: 19.2, 67: 18.4, 68: 17.6, 69: 16.8, 70: 16.0,
+            71: 15.3, 72: 14.6, 73: 13.9, 74: 13.2, 75: 12.5, 76: 11.9, 77: 11.2,
+            78: 10.6, 79: 10.0, 80: 9.5, 81: 8.9, 82: 8.4, 83: 7.9, 84: 7.4,
+            85: 6.9, 86: 6.5, 87: 6.1, 88: 5.7, 89: 5.3, 90: 5.0, 91: 4.7, 92: 4.4,
+            93: 4.1, 94: 3.9, 95: 3.7,
+        },
+    },
+    hecm: {
+        // HUD HECM principal-limit factors at a 5.875% expected rate, as published
+        // for 2026 (percent of home value available as the initial principal
+        // limit, by age of the youngest borrower). Planning default only — the UI
+        // asks for the lender-quoted line size first. Primary authority: HUD's
+        // HECM PLF tables (https://www.hud.gov/hud-partners/single-family-home-equity-conversion-mortgages,
+        // published as spreadsheets by age × expected rate); values here are the
+        // 2026 chart summarized at https://reverse.mortgage/age-requirements
+        // (net of nothing — upfront costs are modeled separately via
+        // upfrontCostPct). On refresh, prefer reading the HUD tables directly.
+        principalLimitFactorPctByAge: {
+            62: 35.1, 65: 37.2, 70: 40.9, 75: 43.8, 80: 48.2, 85: 54.4, 90: 61.4,
+        },
+        plfExpectedRatePct: 5.875,
+        // Note rate near the 2026 expected rate + 0.5% annual MIP — the "~7–8%
+        // growth at 2026 rates" planning figure (Pfau's buffer-asset articles).
+        defaultGrowthRatePct: 7.5,
+    },
+    medicare: {
+        partBStandardMonthly: 202.9,
+        irmaaTiers: [
+            // CMS 2026 Part D IRMAA surcharges by income tier.
+            {
+                magiOver: { single: 109_000, marriedFilingJointly: 218_000 },
+                applicablePct: 35,
+                partDSurchargeMonthly: 14.5,
+            },
+            {
+                magiOver: { single: 137_000, marriedFilingJointly: 274_000 },
+                applicablePct: 50,
+                partDSurchargeMonthly: 37.5,
+            },
+            {
+                magiOver: { single: 171_000, marriedFilingJointly: 342_000 },
+                applicablePct: 65,
+                partDSurchargeMonthly: 60.4,
+            },
+            {
+                magiOver: { single: 205_000, marriedFilingJointly: 410_000 },
+                applicablePct: 80,
+                partDSurchargeMonthly: 83.3,
+            },
+            {
+                magiOver: { single: 500_000, marriedFilingJointly: 750_000 },
+                applicablePct: 85,
+                partDSurchargeMonthly: 91.0,
+            },
+        ],
+    },
+    socialSecurity: {
+        colaPct: 2.8,
+        taxableWageBase: 184_500,
+        earningsTestBelowFraAnnual: 24_480,
+        earningsTestFraYearAnnual: 65_160,
+        // SSDI Substantial Gainful Activity (non-blind), 2026. Source: SSA SGA.
+        sgaMonthlyNonBlind: 1_620,
+        // Employee-side OASDI payroll tax rate (statutory since 1990). Source: SSA.
+        oasdiEmployeeRatePct: 6.2,
+    },
+    federalPovertyLine: {
+        firstPerson: 15_650,
+        perAdditionalPerson: 5_500,
+    },
+    aca: {
+        // Indexed schedule for 2026 (enhanced credits expired 12/31/2025; cliff
+        // restored). Verified against Rev. Proc. 2025-25 §3.01 (Applicable
+        // Percentage Table for 2026): 2.10% below 133% FPL, then 3.14→4.19 (133–150),
+        // 4.19→6.60 (150–200), 6.60→8.44 (200–250), 8.44→9.96 (250–300), 9.96 flat
+        // through 400%.
+        applicablePctBreakpoints: [
+            // Flat 2.1% through 133% FPL, stepping to the 133–150 band (the step is
+            // encoded as a 1-point ramp because the engine interpolates linearly).
+            { fplPct: 0, applicablePct: 2.1 },
+            { fplPct: 133, applicablePct: 2.1 },
+            { fplPct: 134, applicablePct: 3.14 },
+            { fplPct: 150, applicablePct: 4.19 },
+            { fplPct: 200, applicablePct: 6.6 },
+            { fplPct: 250, applicablePct: 8.44 },
+            { fplPct: 300, applicablePct: 9.96 },
+            { fplPct: 400, applicablePct: 9.96 },
+        ],
+        maxFplPctForCredit: 400,
+    },
+};

package/dist/params/index.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Typed access to annual parameter packs.
+ *
+ * Future years resolve to the latest published pack with `isStandIn: true`
+ * (same pattern as v1's ssaWageData "latest published" fallback) — projections
+ * inflate from the latest pack rather than failing on unpublished years.
+ */
+import type { FilingStatus, ParameterPack } from './types.js';
+export { PARAMETER_PROVENANCE } from './provenance.js';
+export type { ParameterSource } from './provenance.js';
+export { REAL_YIELD_CURVE_2026 as EMBEDDED_REAL_YIELD_CURVE } from './data/realYieldCurve2026.js';
+export type { RealYieldCurve, RealYieldCurvePoint } from './types.js';
+export declare const EARLIEST_PACK_YEAR: number;
+export declare const LATEST_PACK_YEAR: number;
+/**
+ * When the tax/limit figures in the parameter packs were last compiled, and the
+ * published rules they reflect. Surfaced in the disclaimer so users know the
+ * data's vintage. Bump on each annual refresh.
+ */
+export declare const PARAMETER_DATA_AS_OF = "June 2026";
+export declare const PARAMETER_DATA_BASIS = "2025 published federal and state rules";
+/**
+ * Default Social Security trust-fund haircut per the OASDI Trustees Report:
+ * the 2026 report projects combined depletion in Q3 2034 with 83% of benefits
+ * payable (a 17% cut). (OASI alone depletes 2032 at 78% payable — RetireGolden's
+ * default follows the combined convention, domain rules §4.)
+ * Single source for the toggle default in Assumptions, the scenario chip, and
+ * example plans; revisit per DOCS/maintenance-schedule.md when the Trustees
+ * projection moves.
+ */
+export declare const TRUSTEES_DEFAULT_SS_HAIRCUT: {
+    readonly fromYear: 2034;
+    readonly cutPct: 17;
+};
+export interface PackLookup {
+    pack: ParameterPack;
+    /** True when `year` has no published pack and a neighboring year is standing in. */
+    isStandIn: boolean;
+}
+export declare function packForYear(year: number): PackLookup;
+/** RMD start age per SECURE 2.0. Pre-1951 cohorts already started under older rules. */
+export declare function rmdStartAgeForBirthYear(birthYear: number): number;
+export declare function uniformLifetimeDivisor(pack: ParameterPack, age: number): number | undefined;
+/**
+ * Expected-return multiple (remaining life expectancy in years) for a
+ * single-life ordinary annuity starting at `ageAtStart`, from IRS Pub 939
+ * Table V. Linear interpolation between whole-age entries; clamped to the
+ * table's endpoints outside its range. Drives the non-qualified exclusion
+ * ratio: exclusion ratio = investment-in-contract ÷ (annual payment × multiple).
+ */
+export declare function annuityExpectedReturnMultiple(pack: ParameterPack, ageAtStart: number): number;
+/**
+ * Planning-default HECM principal-limit factor (percent of home value) for the
+ * youngest borrower's age at open, from the pack's published factor table
+ * (compiled at the pack's expected rate — a lender quote at the actual rate
+ * always wins; this is the fallback approximation). Linear interpolation
+ * between published ages; clamped to the endpoints outside the table.
+ */
+export declare function hecmPrincipalLimitFactorPct(pack: ParameterPack, ageAtOpen: number): number;
+export declare function irmaaTierForMagi(pack: ParameterPack, magiTwoYearsPrior: number, filingStatus: FilingStatus, thresholdScale?: number): number;
+/** Total monthly Part B premium for a MAGI (2-year-lookback) and filing status. */
+export declare function partBMonthlyPremium(pack: ParameterPack, magiTwoYearsPrior: number, filingStatus: FilingStatus): number;
+export declare function standardDeduction(pack: ParameterPack, filingStatus: FilingStatus, peopleAged65Plus: number): number;

package/dist/params/index.js

@@ -0,0 +1,134 @@
+/**
+ * Typed access to annual parameter packs.
+ *
+ * Future years resolve to the latest published pack with `isStandIn: true`
+ * (same pattern as v1's ssaWageData "latest published" fallback) — projections
+ * inflate from the latest pack rather than failing on unpublished years.
+ */
+import { year2026 } from './data/year2026.js';
+export { PARAMETER_PROVENANCE } from './provenance.js';
+export { REAL_YIELD_CURVE_2026 as EMBEDDED_REAL_YIELD_CURVE } from './data/realYieldCurve2026.js';
+const packs = [year2026];
+// Keep sorted ascending by year as packs are added each fall.
+export const EARLIEST_PACK_YEAR = packs[0].year;
+export const LATEST_PACK_YEAR = packs[packs.length - 1].year;
+/**
+ * When the tax/limit figures in the parameter packs were last compiled, and the
+ * published rules they reflect. Surfaced in the disclaimer so users know the
+ * data's vintage. Bump on each annual refresh.
+ */
+export const PARAMETER_DATA_AS_OF = 'June 2026';
+export const PARAMETER_DATA_BASIS = '2025 published federal and state rules';
+/**
+ * Default Social Security trust-fund haircut per the OASDI Trustees Report:
+ * the 2026 report projects combined depletion in Q3 2034 with 83% of benefits
+ * payable (a 17% cut). (OASI alone depletes 2032 at 78% payable — RetireGolden's
+ * default follows the combined convention, domain rules §4.)
+ * Single source for the toggle default in Assumptions, the scenario chip, and
+ * example plans; revisit per DOCS/maintenance-schedule.md when the Trustees
+ * projection moves.
+ */
+export const TRUSTEES_DEFAULT_SS_HAIRCUT = { fromYear: 2034, cutPct: 17 };
+export function packForYear(year) {
+    const exact = packs.find((p) => p.year === year);
+    if (exact)
+        return { pack: exact, isStandIn: false };
+    if (year > LATEST_PACK_YEAR)
+        return { pack: packs[packs.length - 1], isStandIn: true };
+    return { pack: packs[0], isStandIn: true };
+}
+/** RMD start age per SECURE 2.0. Pre-1951 cohorts already started under older rules. */
+export function rmdStartAgeForBirthYear(birthYear) {
+    if (birthYear <= 1950)
+        return 72;
+    if (birthYear <= 1959)
+        return 73;
+    return 75;
+}
+export function uniformLifetimeDivisor(pack, age) {
+    if (age > 120)
+        return pack.rmd.uniformLifetimeTable[120];
+    return pack.rmd.uniformLifetimeTable[age];
+}
+/**
+ * Expected-return multiple (remaining life expectancy in years) for a
+ * single-life ordinary annuity starting at `ageAtStart`, from IRS Pub 939
+ * Table V. Linear interpolation between whole-age entries; clamped to the
+ * table's endpoints outside its range. Drives the non-qualified exclusion
+ * ratio: exclusion ratio = investment-in-contract ÷ (annual payment × multiple).
+ */
+export function annuityExpectedReturnMultiple(pack, ageAtStart) {
+    const table = pack.annuities.expectedReturnMultiples;
+    const ages = Object.keys(table)
+        .map(Number)
+        .sort((a, b) => a - b);
+    if (ages.length === 0)
+        return 0;
+    const lo = ages[0];
+    const hi = ages[ages.length - 1];
+    if (ageAtStart <= lo)
+        return table[lo];
+    if (ageAtStart >= hi)
+        return table[hi];
+    const whole = Math.floor(ageAtStart);
+    const lower = table[whole];
+    const upper = table[whole + 1];
+    if (lower === undefined)
+        return table[hi];
+    if (upper === undefined || ageAtStart === whole)
+        return lower;
+    return lower + (upper - lower) * (ageAtStart - whole);
+}
+/**
+ * Planning-default HECM principal-limit factor (percent of home value) for the
+ * youngest borrower's age at open, from the pack's published factor table
+ * (compiled at the pack's expected rate — a lender quote at the actual rate
+ * always wins; this is the fallback approximation). Linear interpolation
+ * between published ages; clamped to the endpoints outside the table.
+ */
+export function hecmPrincipalLimitFactorPct(pack, ageAtOpen) {
+    const table = pack.hecm.principalLimitFactorPctByAge;
+    const ages = Object.keys(table)
+        .map(Number)
+        .sort((a, b) => a - b);
+    if (ages.length === 0)
+        return 0;
+    if (ageAtOpen <= ages[0])
+        return table[ages[0]];
+    if (ageAtOpen >= ages[ages.length - 1])
+        return table[ages[ages.length - 1]];
+    for (let i = 0; i < ages.length - 1; i++) {
+        const lo = ages[i];
+        const hi = ages[i + 1];
+        if (ageAtOpen >= lo && ageAtOpen <= hi) {
+            return table[lo] + ((table[hi] - table[lo]) * (ageAtOpen - lo)) / (hi - lo);
+        }
+    }
+    return table[ages[ages.length - 1]];
+}
+export function irmaaTierForMagi(pack, magiTwoYearsPrior, filingStatus, thresholdScale = 1) {
+    let tier = 0;
+    for (let i = 0; i < pack.medicare.irmaaTiers.length; i++) {
+        const threshold = pack.medicare.irmaaTiers[i].magiOver[filingStatus] * thresholdScale;
+        const isTopTier = i === pack.medicare.irmaaTiers.length - 1;
+        // CMS publishes lower tiers as "greater than" the floor; the final tier is inclusive.
+        if (isTopTier ? magiTwoYearsPrior >= threshold : magiTwoYearsPrior > threshold)
+            tier = i + 1;
+    }
+    return tier;
+}
+/** Total monthly Part B premium for a MAGI (2-year-lookback) and filing status. */
+export function partBMonthlyPremium(pack, magiTwoYearsPrior, filingStatus) {
+    const base = pack.medicare.partBStandardMonthly;
+    let applicablePct = 25;
+    const tier = irmaaTierForMagi(pack, magiTwoYearsPrior, filingStatus);
+    if (tier > 0)
+        applicablePct = pack.medicare.irmaaTiers[tier - 1].applicablePct;
+    // Standard premium is 25% of program cost; IRMAA tiers pay a higher share.
+    return Math.round(base * (applicablePct / 25) * 100) / 100;
+}
+export function standardDeduction(pack, filingStatus, peopleAged65Plus) {
+    const base = pack.federalTax.standardDeduction[filingStatus];
+    const addition = pack.federalTax.age65Addition[filingStatus] * peopleAged65Plus;
+    return base + addition;
+}

package/dist/params/provenance.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Provenance for the parameter-pack defaults: the source and key figures behind
+ * every tax/limit/benefit number the engine applies. Surfaced in the UI so a
+ * user can see where the assumptions come from and verify any that matter.
+ *
+ * This is a human-maintained summary that travels with the data pack — refresh
+ * it in the same annual data-only PR that bumps `data/year<YYYY>.ts`. The
+ * concise `figures` strings should track the current pack's values.
+ *
+ * Full per-figure detail and additional citations: DOCS/domain/domain-rules-reference.md.
+ */
+export interface ParameterSource {
+    /** Stable id (kebab-case), unique within the list. */
+    id: string;
+    /** Short group name shown in the first column, sentence case. */
+    label: string;
+    /** One-line summary of the key figures this group contributes. */
+    figures: string;
+    /** Publisher / primary authority the figures are drawn from. */
+    publisher: string;
+    /** Link to a citable source for the figures. */
+    url: string;
+}
+/**
+ * One entry per logical assumption group. Order is roughly the order figures
+ * appear in a projection (income tax → gains → SS → limits → RMDs → Medicare →
+ * SS benefits → ACA → state).
+ */
+export declare const PARAMETER_PROVENANCE: ParameterSource[];

package/dist/params/provenance.js

@@ -0,0 +1,123 @@
+/**
+ * Provenance for the parameter-pack defaults: the source and key figures behind
+ * every tax/limit/benefit number the engine applies. Surfaced in the UI so a
+ * user can see where the assumptions come from and verify any that matter.
+ *
+ * This is a human-maintained summary that travels with the data pack — refresh
+ * it in the same annual data-only PR that bumps `data/year<YYYY>.ts`. The
+ * concise `figures` strings should track the current pack's values.
+ *
+ * Full per-figure detail and additional citations: DOCS/domain/domain-rules-reference.md.
+ */
+/**
+ * One entry per logical assumption group. Order is roughly the order figures
+ * appear in a projection (income tax → gains → SS → limits → RMDs → Medicare →
+ * SS benefits → ACA → state).
+ */
+export const PARAMETER_PROVENANCE = [
+    {
+        id: 'federal-brackets',
+        label: 'Federal income tax brackets & standard deduction',
+        figures: 'Seven brackets, 10%–37%. Standard deduction $16,100 single / $32,200 joint; +$2,050 / $1,650 each at 65+.',
+        publisher: 'IRS / Tax Foundation',
+        url: 'https://taxfoundation.org/data/all/federal/2026-tax-brackets/',
+    },
+    {
+        id: 'senior-deduction',
+        label: 'Senior bonus deduction (OBBBA)',
+        figures: '$6,000 per person 65+, phasing out above $75,000 / $150,000 MAGI; temporary, expires after 2028.',
+        publisher: 'Bipartisan Policy Center / IRS',
+        url: 'https://bipartisanpolicy.org/explainer/2026-federal-income-tax-brackets-and-interactive-calculator/',
+    },
+    {
+        id: 'capital-gains-niit',
+        label: 'Long-term capital gains & NIIT',
+        figures: '0 / 15 / 20% gains (15% above $49,450 / $98,900; 20% above $545,500 / $613,700). 3.8% NIIT above $200,000 / $250,000 MAGI.',
+        publisher: 'Kiplinger / IRS',
+        url: 'https://www.kiplinger.com/taxes/irs-updates-capital-gains-tax-thresholds',
+    },
+    {
+        id: 'section-121-exclusion',
+        label: 'Home-sale gain exclusion (§121)',
+        figures: '$250,000 single / $500,000 joint of primary-residence gain excluded on sale (statutory since 1997, never indexed); depreciation after May 6, 1997 is not excludable.',
+        publisher: 'IRS Topic 701 / Publication 523',
+        url: 'https://www.irs.gov/taxtopics/tc701',
+    },
+    {
+        id: 'ss-benefit-taxation',
+        label: 'Social Security benefit taxation',
+        figures: 'Provisional-income thresholds: up to 50% taxable above $25,000 / $32,000, up to 85% above $34,000 / $44,000 (fixed by statute, never indexed).',
+        publisher: 'IRS Publication 915',
+        url: 'https://www.irs.gov/forms-pubs/about-publication-915',
+    },
+    {
+        id: 'contribution-limits',
+        label: 'Contribution limits',
+        figures: '401(k) $24,500 (+$8,000 at 50+, $11,250 ages 60–63); IRA $7,500 (+$1,100); HSA $4,400 self / $8,750 family (+$1,000 at 55+).',
+        publisher: 'IRS',
+        url: 'https://www.irs.gov/newsroom/401k-limit-increases-to-24500-for-2026-ira-limit-increases-to-7500',
+    },
+    {
+        id: 'rmd-qcd',
+        label: 'Required minimum distributions & QCD',
+        figures: 'IRS Uniform Lifetime Table (Pub 590-B, 2022+); RMDs begin at age 73–75 per SECURE 2.0; QCD exclusion limit $111,000.',
+        publisher: 'IRS Publication 590-B',
+        url: 'https://www.irs.gov/retirement-plans/retirement-plan-and-ira-required-minimum-distributions-faqs',
+    },
+    {
+        id: 'annuity-purchase',
+        label: 'Annuity purchase (exclusion ratio & QLAC)',
+        figures: 'Non-qualified exclusion ratio from IRS Pub 939 Table V expected-return multiples (life expectancy by age); QLAC premium cap $210,000 excluded from RMD balances (SECURE 2.0).',
+        publisher: 'IRS Publication 939 / SECURE 2.0 Act §202',
+        url: 'https://www.irs.gov/forms-pubs/about-publication-939',
+    },
+    {
+        id: 'hecm-plf',
+        label: 'HECM reverse-mortgage principal limit',
+        figures: 'Principal-limit factors at a 5.875% expected rate: 35.1% of home value at 62 rising to 61.4% at 90 (planning default — a lender quote always wins); line/loan growth default 7.5%/yr (rate + 0.5% MIP).',
+        publisher: 'HUD HECM PLF tables (as summarized for 2026)',
+        url: 'https://reverse.mortgage/age-requirements',
+    },
+    {
+        id: 'medicare-irmaa',
+        label: 'Medicare Part B & IRMAA',
+        figures: 'Standard Part B $202.90/mo; five IRMAA tiers starting at $109,000 / $218,000 MAGI; Part D IRMAA surcharges $14.50-$91.00/mo.',
+        publisher: 'CMS',
+        url: 'https://www.cms.gov/newsroom/fact-sheets/2026-medicare-parts-b-premiums-deductibles',
+    },
+    {
+        id: 'social-security',
+        label: 'Social Security COLA & wage base',
+        figures: '2.8% COLA; taxable wage base $184,500; earnings-test exempt amounts $24,480 (pre-FRA) / $65,160 (FRA year); SSDI SGA $1,620/mo (non-blind); OASDI payroll tax 6.2% (employee).',
+        publisher: 'SSA',
+        url: 'https://www.ssa.gov/news/en/cola/factsheets/2026.html',
+    },
+    {
+        id: 'federal-poverty-line',
+        label: 'Federal poverty guideline (ACA)',
+        figures: '2025 HHS guideline — $15,650 first person, +$5,500 each additional — applied to the 2026 ACA coverage year.',
+        publisher: 'HHS',
+        url: 'https://aspe.hhs.gov/topics/poverty-economic-mobility/poverty-guidelines',
+    },
+    {
+        id: 'aca-ptc',
+        label: 'ACA premium tax credit',
+        figures: 'Applicable-percentage schedule per Rev. Proc. 2025-25 (2.10% under 133% FPL up to 9.96% at 300–400%), with the 400% FPL subsidy cliff restored (enhanced credits expired 12/31/2025).',
+        publisher: 'IRS',
+        url: 'https://www.irs.gov/pub/irs-drop/rp-25-25.pdf',
+    },
+    {
+        id: 'real-yield-curve',
+        label: 'TIPS real-yield curve (income floor & bridge)',
+        figures: 'Par real yields as of 2026-06-30: 1.85% (5y), 2.05% (7y), 2.25% (10y), 2.55% (20y), 2.70% (30y). Prices TIPS-ladder quotes and the funded-ratio discounting; refreshed annually with the parameter packs.',
+        publisher: 'U.S. Treasury',
+        url: 'https://home.treasury.gov/resource-center/data-chart-center/interest-rates',
+    },
+    {
+        id: 'state-income-tax',
+        label: 'State income tax',
+        figures: 'Brackets, standard deduction, Social Security treatment, and major retirement-income exclusions for all 50 states + DC, from each state revenue department.',
+        publisher: 'Tax Foundation / state revenue departments',
+        url: 'https://taxfoundation.org/data/all/state/state-income-tax-rates/',
+    },
+];

package/dist/params/state/data/year2026.d.ts

@@ -0,0 +1,18 @@
+/**
+ * State income tax pack — all 50 states + DC ("big levers", V5 PR B).
+ *
+ * Transcribed from the cited per-state research docs in
+ * DOCS/domain/state-tax-research/ (see each <CODE>.md for sources and the
+ * simplifications each state's mapping makes). Values are latest-published
+ * (≈2025) individual-income-tax figures; like the federal pack, nominal
+ * brackets are carried forward for future years (bracket creep modeled).
+ *
+ * State taxable income in the engine starts from gross ordinary income (plus
+ * gains, plus the federally taxable SS amount where the state taxes SS), minus
+ * the retirement exclusion and the standard deduction below. For states that
+ * tax *federal taxable income* and have no separate deduction (e.g. CO), the
+ * standard deduction is set to the federal-equivalent so the gross→taxable
+ * conversion matches; noted inline.
+ */
+import type { StateTaxPack } from '../types.js';
+export declare const stateYear2026: StateTaxPack;