@markcolabs/mcp 0.1.0 → 0.3.0

package/dist/engines/data/irs2026.d.ts

@@ -1,12 +1,14 @@
 /**
  * Self-contained 2026 IRS retirement-plan limits subset for the MCP package's
- * 401(k) projection engine.
+ * retirement engines (401k, IRA, Roth conversion).
  *
- * Mirrored from site/src/data/annual-limits.js LIMITS_401K_2026. See
- * engines/data/ssa.ts for full rationale on the mirror pattern.
+ * Mirrored from site/src/data/annual-limits.js LIMITS_401K_2026 / LIMITS_IRA_2026
+ * / ROTH_PHASE_OUT_2026 / TRADITIONAL_PHASE_OUT_2026. See engines/data/ssa.ts
+ * for full rationale on the mirror pattern.
  *
  * Source: IRS Notice 2025-67 (2026 retirement-plan limits) +
  *         SECURE 2.0 Act §109 (super catch-up provision for ages 60-63).
+ *         IRA limits re-affirmed AL-2026-001 / ARCH-BRIEF-20260504.
  * Last verified: 2026-05-09.
  */
 export declare const LIMITS_401K_2026: {
@@ -27,4 +29,109 @@ export declare const LIMITS_401K_2026: {
     /** End of super catch-up window. */
     readonly superCatchUpAgeEnd: 63;
 };
+/**
+ * 2026 IRA Contribution Limits.
+ * Mirrored from site/src/data/annual-limits.js `LIMITS_IRA_2026`.
+ *
+ * Source: IRS Notice 2025-67 (2026 retirement plan limits); SECURE 2.0 Act §107
+ *         (catch-up indexing). Re-affirmed AL-2026-001 / ARCH-BRIEF-20260504.
+ */
+export declare const LIMITS_IRA_2026: {
+    /** Base IRA contribution limit (under age 50). */
+    readonly standard: 7500;
+    /** Catch-up amount for age 50+ (SECURE 2.0 indexed). */
+    readonly catchUp: 1100;
+    /** Total contribution limit for age 50+ (standard + catchUp). */
+    readonly total50Plus: 8600;
+    /** Minimum age for catch-up eligibility. */
+    readonly catchUpAge: 50;
+};
+/**
+ * 2026 Roth IRA Income (MAGI) Phase-Out Thresholds.
+ * Mirrored from site/src/data/annual-limits.js `ROTH_PHASE_OUT_2026`.
+ *
+ * Source: IRS Notice 2025-67; IRC §408A(c)(3) phase-out methodology.
+ * Filing-status keys are camelCase to match the MCP package's `FilingStatus`
+ * convention; mapping vs. site keys: single=single, mfj=marriedFilingJointly,
+ * mfs=marriedFilingSeparately. (Head-of-household uses the single thresholds
+ * per IRS rules.)
+ */
+export declare const ROTH_PHASE_OUT_2026: {
+    readonly single: {
+        readonly start: 153000;
+        readonly end: 168000;
+    };
+    readonly marriedFilingJointly: {
+        readonly start: 242000;
+        readonly end: 252000;
+    };
+    readonly marriedFilingSeparately: {
+        readonly start: 0;
+        readonly end: 10000;
+    };
+    readonly headOfHousehold: {
+        readonly start: 153000;
+        readonly end: 168000;
+    };
+};
+/**
+ * 2026 Traditional IRA Deduction Phase-Out (contributor covered by workplace plan).
+ * Mirrored from site/src/data/annual-limits.js `TRADITIONAL_PHASE_OUT_2026`.
+ *
+ * Source: IRS Notice 2025-67; IRC §219(g) deduction phase-out methodology.
+ * NOTE: This phase-out governs the DEDUCTIBILITY of traditional IRA
+ * contributions, not the contribution limit itself. The IRA contributionLimit
+ * tool returns the eligibleContribution (= base limit for Traditional regardless
+ * of MAGI, since non-deductible contributions are always permitted). The
+ * Traditional phase-out is exposed via a separate field for clients that need
+ * the deduction-phase-out signal.
+ */
+export declare const TRADITIONAL_PHASE_OUT_2026: {
+    readonly single: {
+        readonly start: 81000;
+        readonly end: 91000;
+    };
+    readonly marriedFilingJointly: {
+        readonly start: 129000;
+        readonly end: 149000;
+    };
+    readonly marriedFilingSeparately: {
+        readonly start: 0;
+        readonly end: 10000;
+    };
+    readonly headOfHousehold: {
+        readonly start: 81000;
+        readonly end: 91000;
+    };
+};
+/**
+ * 2026 HSA Contribution Limits.
+ * Mirrored from site/src/data/annual-limits.js `LIMITS_HSA_2026`.
+ *
+ * Source: IRS Rev. Proc. 2025-19 (2026 HSA inflation adjustments under IRC §223);
+ *         IRC §223(b)(3)(B) ($1,000 catch-up is statutory and NOT inflation-indexed).
+ *         Last verified: 2026-05-27 (mirrored from site/src/data/annual-limits.js,
+ *         site _meta.last_verified_date: 2026-05-07).
+ *
+ * Notes:
+ *   - `medicareAge`: HSA contributions are prohibited once enrolled in Medicare
+ *     (typically age 65). Surfaced as an informational threshold; the HSA
+ *     contribution-limit tool does not zero out the limit at this age, it just
+ *     reports it (parallel to how the site shows a Medicare warning badge).
+ *   - Employer contributions REDUCE the employee's eligible payroll deduction
+ *     dollar-for-dollar because the IRS limit is a TOTAL annual limit, not a
+ *     per-source limit. See engines/hsa.ts for the clamp.
+ */
+export declare const LIMITS_HSA_2026: {
+    /** Self-only HDHP coverage base limit. */
+    readonly selfOnly: 4400;
+    /** Family HDHP coverage base limit. */
+    readonly family: 8750;
+    /** Catch-up amount for age 55+ (statutory, not indexed). */
+    readonly catchUp: 1000;
+    /** Minimum age for catch-up eligibility. */
+    readonly catchUpAge: 55;
+    /** Age at which Medicare enrollment typically begins (informational only). */
+    readonly medicareAge: 65;
+};
 //# sourceMappingURL=irs2026.d.ts.map

package/dist/engines/data/irs2026.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"irs2026.d.ts","sourceRoot":"","sources":["../../../src/engines/data/irs2026.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,gBAAgB;IAC3B,oCAAoC;;IAEpC,qDAAqD;;IAErD,yDAAyD;;IAEzD,kDAAkD;;IAElD,gDAAgD;;IAEhD,oCAAoC;;IAEpC,sCAAsC;;IAEtC,oCAAoC;;CAE5B,CAAC"}
+{"version":3,"file":"irs2026.d.ts","sourceRoot":"","sources":["../../../src/engines/data/irs2026.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,gBAAgB;IAC3B,oCAAoC;;IAEpC,qDAAqD;;IAErD,yDAAyD;;IAEzD,kDAAkD;;IAElD,gDAAgD;;IAEhD,oCAAoC;;IAEpC,sCAAsC;;IAEtC,oCAAoC;;CAE5B,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,eAAe;IAC1B,kDAAkD;;IAElD,wDAAwD;;IAExD,iEAAiE;;IAEjE,4CAA4C;;CAEpC,CAAC;AAEX;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;CAKtB,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;CAK7B,CAAC;AAEX;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,eAAe;IAC1B,0CAA0C;;IAE1C,uCAAuC;;IAEvC,4DAA4D;;IAE5D,4CAA4C;;IAE5C,8EAA8E;;CAEtE,CAAC"}

package/dist/engines/data/irs2026.js

@@ -1,12 +1,14 @@
 /**
  * Self-contained 2026 IRS retirement-plan limits subset for the MCP package's
- * 401(k) projection engine.
+ * retirement engines (401k, IRA, Roth conversion).
  *
- * Mirrored from site/src/data/annual-limits.js LIMITS_401K_2026. See
- * engines/data/ssa.ts for full rationale on the mirror pattern.
+ * Mirrored from site/src/data/annual-limits.js LIMITS_401K_2026 / LIMITS_IRA_2026
+ * / ROTH_PHASE_OUT_2026 / TRADITIONAL_PHASE_OUT_2026. See engines/data/ssa.ts
+ * for full rationale on the mirror pattern.
  *
  * Source: IRS Notice 2025-67 (2026 retirement-plan limits) +
  *         SECURE 2.0 Act §109 (super catch-up provision for ages 60-63).
+ *         IRA limits re-affirmed AL-2026-001 / ARCH-BRIEF-20260504.
  * Last verified: 2026-05-09.
  */
 export const LIMITS_401K_2026 = {
@@ -27,4 +29,85 @@ export const LIMITS_401K_2026 = {
     /** End of super catch-up window. */
     superCatchUpAgeEnd: 63,
 };
+/**
+ * 2026 IRA Contribution Limits.
+ * Mirrored from site/src/data/annual-limits.js `LIMITS_IRA_2026`.
+ *
+ * Source: IRS Notice 2025-67 (2026 retirement plan limits); SECURE 2.0 Act §107
+ *         (catch-up indexing). Re-affirmed AL-2026-001 / ARCH-BRIEF-20260504.
+ */
+export const LIMITS_IRA_2026 = {
+    /** Base IRA contribution limit (under age 50). */
+    standard: 7_500,
+    /** Catch-up amount for age 50+ (SECURE 2.0 indexed). */
+    catchUp: 1_100,
+    /** Total contribution limit for age 50+ (standard + catchUp). */
+    total50Plus: 8_600,
+    /** Minimum age for catch-up eligibility. */
+    catchUpAge: 50,
+};
+/**
+ * 2026 Roth IRA Income (MAGI) Phase-Out Thresholds.
+ * Mirrored from site/src/data/annual-limits.js `ROTH_PHASE_OUT_2026`.
+ *
+ * Source: IRS Notice 2025-67; IRC §408A(c)(3) phase-out methodology.
+ * Filing-status keys are camelCase to match the MCP package's `FilingStatus`
+ * convention; mapping vs. site keys: single=single, mfj=marriedFilingJointly,
+ * mfs=marriedFilingSeparately. (Head-of-household uses the single thresholds
+ * per IRS rules.)
+ */
+export const ROTH_PHASE_OUT_2026 = {
+    single: { start: 153_000, end: 168_000 },
+    marriedFilingJointly: { start: 242_000, end: 252_000 },
+    marriedFilingSeparately: { start: 0, end: 10_000 },
+    headOfHousehold: { start: 153_000, end: 168_000 },
+};
+/**
+ * 2026 Traditional IRA Deduction Phase-Out (contributor covered by workplace plan).
+ * Mirrored from site/src/data/annual-limits.js `TRADITIONAL_PHASE_OUT_2026`.
+ *
+ * Source: IRS Notice 2025-67; IRC §219(g) deduction phase-out methodology.
+ * NOTE: This phase-out governs the DEDUCTIBILITY of traditional IRA
+ * contributions, not the contribution limit itself. The IRA contributionLimit
+ * tool returns the eligibleContribution (= base limit for Traditional regardless
+ * of MAGI, since non-deductible contributions are always permitted). The
+ * Traditional phase-out is exposed via a separate field for clients that need
+ * the deduction-phase-out signal.
+ */
+export const TRADITIONAL_PHASE_OUT_2026 = {
+    single: { start: 81_000, end: 91_000 },
+    marriedFilingJointly: { start: 129_000, end: 149_000 },
+    marriedFilingSeparately: { start: 0, end: 10_000 },
+    headOfHousehold: { start: 81_000, end: 91_000 },
+};
+/**
+ * 2026 HSA Contribution Limits.
+ * Mirrored from site/src/data/annual-limits.js `LIMITS_HSA_2026`.
+ *
+ * Source: IRS Rev. Proc. 2025-19 (2026 HSA inflation adjustments under IRC §223);
+ *         IRC §223(b)(3)(B) ($1,000 catch-up is statutory and NOT inflation-indexed).
+ *         Last verified: 2026-05-27 (mirrored from site/src/data/annual-limits.js,
+ *         site _meta.last_verified_date: 2026-05-07).
+ *
+ * Notes:
+ *   - `medicareAge`: HSA contributions are prohibited once enrolled in Medicare
+ *     (typically age 65). Surfaced as an informational threshold; the HSA
+ *     contribution-limit tool does not zero out the limit at this age, it just
+ *     reports it (parallel to how the site shows a Medicare warning badge).
+ *   - Employer contributions REDUCE the employee's eligible payroll deduction
+ *     dollar-for-dollar because the IRS limit is a TOTAL annual limit, not a
+ *     per-source limit. See engines/hsa.ts for the clamp.
+ */
+export const LIMITS_HSA_2026 = {
+    /** Self-only HDHP coverage base limit. */
+    selfOnly: 4_400,
+    /** Family HDHP coverage base limit. */
+    family: 8_750,
+    /** Catch-up amount for age 55+ (statutory, not indexed). */
+    catchUp: 1_000,
+    /** Minimum age for catch-up eligibility. */
+    catchUpAge: 55,
+    /** Age at which Medicare enrollment typically begins (informational only). */
+    medicareAge: 65,
+};
 //# sourceMappingURL=irs2026.js.map

package/dist/engines/data/irs2026.js.map

@@ -1 +1 @@
-{"version":3,"file":"irs2026.js","sourceRoot":"","sources":["../../../src/engines/data/irs2026.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,oCAAoC;IACpC,IAAI,EAAE,MAAM;IACZ,qDAAqD;IACrD,OAAO,EAAE,KAAK;IACd,yDAAyD;IACzD,YAAY,EAAE,MAAM;IACpB,kDAAkD;IAClD,gBAAgB,EAAE,MAAM;IACxB,gDAAgD;IAChD,qBAAqB,EAAE,MAAM;IAC7B,oCAAoC;IACpC,UAAU,EAAE,EAAE;IACd,sCAAsC;IACtC,oBAAoB,EAAE,EAAE;IACxB,oCAAoC;IACpC,kBAAkB,EAAE,EAAE;CACd,CAAC"}
+{"version":3,"file":"irs2026.js","sourceRoot":"","sources":["../../../src/engines/data/irs2026.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,oCAAoC;IACpC,IAAI,EAAE,MAAM;IACZ,qDAAqD;IACrD,OAAO,EAAE,KAAK;IACd,yDAAyD;IACzD,YAAY,EAAE,MAAM;IACpB,kDAAkD;IAClD,gBAAgB,EAAE,MAAM;IACxB,gDAAgD;IAChD,qBAAqB,EAAE,MAAM;IAC7B,oCAAoC;IACpC,UAAU,EAAE,EAAE;IACd,sCAAsC;IACtC,oBAAoB,EAAE,EAAE;IACxB,oCAAoC;IACpC,kBAAkB,EAAE,EAAE;CACd,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,kDAAkD;IAClD,QAAQ,EAAE,KAAK;IACf,wDAAwD;IACxD,OAAO,EAAE,KAAK;IACd,iEAAiE;IACjE,WAAW,EAAE,KAAK;IAClB,4CAA4C;IAC5C,UAAU,EAAE,EAAE;CACN,CAAC;AAEX;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,MAAM,EAAoB,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE;IAC1D,oBAAoB,EAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE;IAC1D,uBAAuB,EAAG,EAAE,KAAK,EAAE,CAAC,EAAQ,GAAG,EAAE,MAAM,EAAG;IAC1D,eAAe,EAAW,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE;CAClD,CAAC;AAEX;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,MAAM,EAAoB,EAAE,KAAK,EAAE,MAAM,EAAG,GAAG,EAAE,MAAM,EAAG;IAC1D,oBAAoB,EAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE;IAC1D,uBAAuB,EAAG,EAAE,KAAK,EAAE,CAAC,EAAQ,GAAG,EAAE,MAAM,EAAG;IAC1D,eAAe,EAAW,EAAE,KAAK,EAAE,MAAM,EAAG,GAAG,EAAE,MAAM,EAAG;CAClD,CAAC;AAEX;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,0CAA0C;IAC1C,QAAQ,EAAE,KAAK;IACf,uCAAuC;IACvC,MAAM,EAAI,KAAK;IACf,4DAA4D;IAC5D,OAAO,EAAG,KAAK;IACf,4CAA4C;IAC5C,UAAU,EAAE,EAAE;IACd,8EAA8E;IAC9E,WAAW,EAAE,EAAE;CACP,CAAC"}

package/dist/engines/data/rmd2026.d.ts

@@ -0,0 +1,59 @@
+/**
+ * IRS Uniform Lifetime Table (Pub. 590-B Table III, post-2022 version) and
+ * SECURE 2.0 RMD-start-age tiers for the MCP `rmd` engine.
+ *
+ * Mirrored from site/src/utils/rmd-engine.js — `UNIFORM_LIFETIME_TABLE` and
+ * `getRMDStartAge`. Following the same mirror pattern as other data modules
+ * (engines/data/ssa.ts, engines/data/irs2026.ts): keep self-contained so the
+ * npm package has no runtime dependency on the site `src/` tree.
+ *
+ * NOTE: The site rmd-engine.js currently uses ONLY the Uniform Lifetime
+ * Table — the Joint Life Expectancy Table (Pub. 590-B Table II, applied
+ * when spouse is sole beneficiary AND 10+ years younger) is NOT implemented
+ * in the site source. To stay 1:1 with the site for parity-test correctness,
+ * the MCP RMD tool also exposes ONLY the Uniform Lifetime path. The
+ * `tableUsed` field in the result is always `"uniform-lifetime"` for v1.
+ * If Joint Life is added to the site engine later, both sides bump in
+ * lockstep.
+ *
+ * Source: IRS Publication 590-B (2024/2025) + SECURE 2.0 Act §107 (RMD age
+ *         tier: pre-1951 → 70.5, 1951-1959 → 73, 1960+ → 75).
+ *         SECURE 2.0 §302 reduced the missed-RMD excise tax from 50% to 25%
+ *         (and to 10% if corrected within the IRS correction window).
+ * Last verified: 2026-05-27.
+ */
+/**
+ * IRS Uniform Lifetime Table (Table III) — post-2022 version per Pub. 590-B.
+ * Keys are integer ages 72-120; values are distribution-period factors (years).
+ * RMD = balance / distributionPeriod.
+ */
+export declare const UNIFORM_LIFETIME_TABLE_2026: Readonly<Record<number, number>>;
+/**
+ * Lowest age in the Uniform Lifetime Table. RMD requests below this age are
+ * either pre-RMD (caller error) or use the lower bound (72) clamp matching
+ * the site's `getDistributionPeriod` behavior. The MCP tool prefers an
+ * INPUT_VALIDATION error for ages below the SECURE-2.0 floor (73 for the
+ * common 1951-1959 cohort).
+ */
+export declare const UNIFORM_LIFETIME_MIN_AGE = 72;
+/** Highest age in the Uniform Lifetime Table — clamps lookups for age > 120. */
+export declare const UNIFORM_LIFETIME_MAX_AGE = 120;
+/**
+ * SECURE 2.0 RMD-start-age tiers (verbatim port of site `getRMDStartAge`).
+ *   - Born ≤ 1950 → 70.5 (legacy, pre-SECURE-Act)
+ *   - Born 1951-1959 → 73 (SECURE 2.0 §107 phase 1)
+ *   - Born ≥ 1960 → 75 (SECURE 2.0 §107 phase 2, effective 2033)
+ */
+export declare function getRmdStartAge(birthYear: number): number;
+/**
+ * SECURE 2.0 §302 missed-RMD excise tax (reduced from 50% pre-2023).
+ *   - 25% on the under-distributed amount (default)
+ *   - 10% if corrected within the IRS correction window (typically 2 years)
+ * Surfaced as an informational field in the RMD result so callers can warn
+ * users about the cost of missing the deadline.
+ */
+export declare const RMD_MISSED_EXCISE_RATE = 0.25;
+export declare const RMD_MISSED_EXCISE_RATE_IF_CORRECTED = 0.1;
+/** Stable provenance string for `result.meta.source`. */
+export declare const RMD_TABLE_SOURCE = "IRS Publication 590-B (Uniform Lifetime Table III, post-2022); SECURE 2.0 Act \u00A7107 (RMD age tiers); \u00A7302 (25% excise tax)";
+//# sourceMappingURL=rmd2026.d.ts.map

package/dist/engines/data/rmd2026.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rmd2026.d.ts","sourceRoot":"","sources":["../../../src/engines/data/rmd2026.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAU/D,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAE3C,gFAAgF;AAChF,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAC3C,eAAO,MAAM,mCAAmC,MAAO,CAAC;AAExD,yDAAyD;AACzD,eAAO,MAAM,gBAAgB,wIACgG,CAAC"}

package/dist/engines/data/rmd2026.js

@@ -0,0 +1,75 @@
+/**
+ * IRS Uniform Lifetime Table (Pub. 590-B Table III, post-2022 version) and
+ * SECURE 2.0 RMD-start-age tiers for the MCP `rmd` engine.
+ *
+ * Mirrored from site/src/utils/rmd-engine.js — `UNIFORM_LIFETIME_TABLE` and
+ * `getRMDStartAge`. Following the same mirror pattern as other data modules
+ * (engines/data/ssa.ts, engines/data/irs2026.ts): keep self-contained so the
+ * npm package has no runtime dependency on the site `src/` tree.
+ *
+ * NOTE: The site rmd-engine.js currently uses ONLY the Uniform Lifetime
+ * Table — the Joint Life Expectancy Table (Pub. 590-B Table II, applied
+ * when spouse is sole beneficiary AND 10+ years younger) is NOT implemented
+ * in the site source. To stay 1:1 with the site for parity-test correctness,
+ * the MCP RMD tool also exposes ONLY the Uniform Lifetime path. The
+ * `tableUsed` field in the result is always `"uniform-lifetime"` for v1.
+ * If Joint Life is added to the site engine later, both sides bump in
+ * lockstep.
+ *
+ * Source: IRS Publication 590-B (2024/2025) + SECURE 2.0 Act §107 (RMD age
+ *         tier: pre-1951 → 70.5, 1951-1959 → 73, 1960+ → 75).
+ *         SECURE 2.0 §302 reduced the missed-RMD excise tax from 50% to 25%
+ *         (and to 10% if corrected within the IRS correction window).
+ * Last verified: 2026-05-27.
+ */
+/**
+ * IRS Uniform Lifetime Table (Table III) — post-2022 version per Pub. 590-B.
+ * Keys are integer ages 72-120; values are distribution-period factors (years).
+ * RMD = balance / distributionPeriod.
+ */
+export const UNIFORM_LIFETIME_TABLE_2026 = {
+    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,
+};
+/**
+ * Lowest age in the Uniform Lifetime Table. RMD requests below this age are
+ * either pre-RMD (caller error) or use the lower bound (72) clamp matching
+ * the site's `getDistributionPeriod` behavior. The MCP tool prefers an
+ * INPUT_VALIDATION error for ages below the SECURE-2.0 floor (73 for the
+ * common 1951-1959 cohort).
+ */
+export const UNIFORM_LIFETIME_MIN_AGE = 72;
+/** Highest age in the Uniform Lifetime Table — clamps lookups for age > 120. */
+export const UNIFORM_LIFETIME_MAX_AGE = 120;
+/**
+ * SECURE 2.0 RMD-start-age tiers (verbatim port of site `getRMDStartAge`).
+ *   - Born ≤ 1950 → 70.5 (legacy, pre-SECURE-Act)
+ *   - Born 1951-1959 → 73 (SECURE 2.0 §107 phase 1)
+ *   - Born ≥ 1960 → 75 (SECURE 2.0 §107 phase 2, effective 2033)
+ */
+export function getRmdStartAge(birthYear) {
+    if (birthYear <= 1950)
+        return 70.5;
+    if (birthYear <= 1959)
+        return 73;
+    return 75;
+}
+/**
+ * SECURE 2.0 §302 missed-RMD excise tax (reduced from 50% pre-2023).
+ *   - 25% on the under-distributed amount (default)
+ *   - 10% if corrected within the IRS correction window (typically 2 years)
+ * Surfaced as an informational field in the RMD result so callers can warn
+ * users about the cost of missing the deadline.
+ */
+export const RMD_MISSED_EXCISE_RATE = 0.25;
+export const RMD_MISSED_EXCISE_RATE_IF_CORRECTED = 0.10;
+/** Stable provenance string for `result.meta.source`. */
+export const RMD_TABLE_SOURCE = "IRS Publication 590-B (Uniform Lifetime Table III, post-2022); SECURE 2.0 Act §107 (RMD age tiers); §302 (25% excise tax)";
+//# sourceMappingURL=rmd2026.js.map

package/dist/engines/data/rmd2026.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rmd2026.js","sourceRoot":"","sources":["../../../src/engines/data/rmd2026.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAqC;IAC3E,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI;IAC1D,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI;IAC1D,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI;IAC1D,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG;IACxD,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG;IACtD,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG;IAC1D,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG;IAC1D,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG;IAC1D,GAAG,EAAE,GAAG;CACA,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,EAAE,CAAC;AAE3C,gFAAgF;AAChF,MAAM,CAAC,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,IAAI,SAAS,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,SAAS,IAAI,IAAI;QAAE,OAAO,EAAE,CAAC;IACjC,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAC3C,MAAM,CAAC,MAAM,mCAAmC,GAAG,IAAI,CAAC;AAExD,yDAAyD;AACzD,MAAM,CAAC,MAAM,gBAAgB,GAC3B,2HAA2H,CAAC"}

package/dist/engines/data/stateTax2026.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Self-contained 2026 state-income-tax effective-rate table for the
+ * `@markcolabs/mcp` paycheck engine (MCP-AUDIT-011 fix, S141 Item #5).
+ *
+ * ## Why this exists
+ *
+ * v0.2.x of the paycheck engine returned a flat 5% state-tax estimate for
+ * every income-tax state. For HCOL states (CA top 13.3%, NY top 10.9%, HI
+ * top 11%) this was materially wrong — a $1M earner in CA was under-taxed by
+ * ~$85k. Documented as a known limitation but YMYL exposure was significant.
+ *
+ * v0.3.0 replaces the flat estimate with a state-aware effective-rate lookup
+ * using marginal-bracket simplification: for each state we precompute a
+ * **top-of-bracket effective rate** for several income tiers and pick the
+ * tier that brackets the caller's taxable income. This is not a full per-state
+ * bracket simulation (out of scope per kickoff) but materially correct for
+ * the common HCOL cases that drove the original finding.
+ *
+ * The site source for the rate data is `site/src/data/tax-tables/` for the
+ * three states the site engine models (CA, NY, TX). For the remaining 38
+ * income-tax states this module is the canonical mirror — the data is
+ * sourced from the Tax Foundation 2026 State Individual Income Tax Rates
+ * report (a citable, annually-updated authority).
+ *
+ * ## Simplification per kickoff
+ *
+ * Income tiers used for effective-rate lookup:
+ *   - tier 1: taxable < $50,000   (most filers)
+ *   - tier 2: taxable < $100,000  (median-to-upper-middle)
+ *   - tier 3: taxable < $250,000  (HCOL professionals)
+ *   - tier 4: taxable < $500,000  (high earners)
+ *   - tier 5: taxable >= $500,000 (top-bracket)
+ *
+ * The rate at each tier is the **effective** rate (not the marginal top rate)
+ * for a hypothetical filer at the top of that tier, accounting for the
+ * weighted average across the state's progressive brackets. Flat-rate states
+ * use the same rate at every tier. No-income-tax states are omitted (handled
+ * by `NO_TAX_STATES` in `federalTax.ts`).
+ *
+ * ## Source
+ *
+ * Tax Foundation 2026 State Individual Income Tax Rates and Brackets,
+ * effective Jan 1 2026 (with 2026 inflation adjustments where applicable).
+ *
+ * Last verified: 2026-05-27 (S141 Item #5).
+ *
+ * @see MCP-AUDIT-011 — Paycheck flat 5% state-tax estimate
+ * @see docs/Claude/Architecture/ADR/ADR-0039 § 5 — engine SemVer policy
+ */
+export interface StateTaxDataMeta {
+    /** Citable source for the rate data (annual Tax Foundation report). */
+    source: string;
+    /** ISO date of last verification against the source. */
+    lastVerified: string;
+    /** Effective tax year these rates apply to. */
+    taxYear: number;
+    /** Methodology note for callers. */
+    methodology: string;
+}
+export declare const STATE_TAX_2026_META: StateTaxDataMeta;
+/** Income tiers for effective-rate lookup. */
+export type StateTaxIncomeTier = "under50k" | "under100k" | "under250k" | "under500k" | "over500k";
+/** Effective rates by income tier for one state. */
+export interface StateEffectiveRates {
+    /** Two-letter state code. */
+    stateCode: string;
+    /** Full state name (for diagnostics). */
+    stateName: string;
+    /** Effective rates expressed as decimals (0.093 = 9.3%). */
+    rates: Record<StateTaxIncomeTier, number>;
+    /**
+     * Notes about quirks (local-tax piggybacks excluded, SDI excluded, etc.).
+     * Surface in `_meta` if non-empty.
+     */
+    notes?: string;
+}
+/**
+ * Pick the income tier appropriate for a given taxable income.
+ * Uses left-inclusive boundaries.
+ */
+export declare function pickIncomeTier(taxableIncome: number): StateTaxIncomeTier;
+/**
+ * 2026 state effective tax rates (decimals) by income tier.
+ *
+ * NOT INCLUDED (handled by NO_TAX_STATES in federalTax.ts):
+ *   AK, FL, NV, NH, SD, TN, TX, WA, WY
+ *
+ * NH currently taxes only interest/dividends (phased out for wages 2025+),
+ * treated as no-tax for wage income.
+ *
+ * Rates rounded to four decimal places. Local-income-tax piggybacks (NYC,
+ * Yonkers, PA municipal EIT) NOT included — surfaced as a `notes` warning
+ * for impacted states. State Disability Insurance (CA SDI, NY SDI, NJ SDI)
+ * is not income tax and is NOT included.
+ */
+export declare const STATE_EFFECTIVE_RATES_2026: Record<string, StateEffectiveRates>;
+/**
+ * Look up the effective state income-tax rate for a given state and taxable income.
+ *
+ * Returns 0 for no-income-tax states (caller should also check NO_TAX_STATES).
+ * Returns 0 for unknown state codes (defensive fallback — caller already validated
+ * 2-letter format at the Zod schema layer; this guards against typos that pass
+ * Zod but aren't in our table).
+ *
+ * @param stateCode 2-letter US state code (uppercase)
+ * @param taxableIncome Annual taxable income in USD (post-federal-standard-deduction basis)
+ * @returns Decimal effective rate (e.g., 0.093 for 9.3%); 0 if state not modeled
+ */
+export declare function getStateEffectiveRate(stateCode: string, taxableIncome: number): number;
+/**
+ * Get the full state data entry (for surfacing `notes` in the tool envelope).
+ */
+export declare function getStateEntry(stateCode: string): StateEffectiveRates | undefined;
+//# sourceMappingURL=stateTax2026.d.ts.map

package/dist/engines/data/stateTax2026.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateTax2026.d.ts","sourceRoot":"","sources":["../../../src/engines/data/stateTax2026.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IACrB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,mBAAmB,EAAE,gBAOjC,CAAC;AAEF,8CAA8C;AAC9C,MAAM,MAAM,kBAAkB,GAC1B,UAAU,GACV,WAAW,GACX,WAAW,GACX,WAAW,GACX,UAAU,CAAC;AAEf,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;IAC1C;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,kBAAkB,CAMxE;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CA4O1E,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,MAAM,GACpB,MAAM,CAMR;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,GAChB,mBAAmB,GAAG,SAAS,CAEjC"}