@markcolabs/mcp 0.1.0 → 0.3.0

package/dist/engines/data/stateTax2026.js

@@ -0,0 +1,348 @@
+/**
+ * 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 const STATE_TAX_2026_META = {
+    source: "Tax Foundation 2026 State Individual Income Tax Rates",
+    lastVerified: "2026-05-27",
+    taxYear: 2026,
+    methodology: "Top-of-bracket effective rate selected by income tier. Not a full " +
+        "per-state bracket simulation — see methodology page for full rates.",
+};
+/**
+ * Pick the income tier appropriate for a given taxable income.
+ * Uses left-inclusive boundaries.
+ */
+export function pickIncomeTier(taxableIncome) {
+    if (taxableIncome < 50_000)
+        return "under50k";
+    if (taxableIncome < 100_000)
+        return "under100k";
+    if (taxableIncome < 250_000)
+        return "under250k";
+    if (taxableIncome < 500_000)
+        return "under500k";
+    return "over500k";
+}
+/**
+ * 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 const STATE_EFFECTIVE_RATES_2026 = {
+    AL: {
+        stateCode: "AL",
+        stateName: "Alabama",
+        rates: { under50k: 0.04, under100k: 0.045, under250k: 0.05, under500k: 0.05, over500k: 0.05 },
+    },
+    AZ: {
+        stateCode: "AZ",
+        stateName: "Arizona",
+        rates: { under50k: 0.025, under100k: 0.025, under250k: 0.025, under500k: 0.025, over500k: 0.025 },
+        notes: "Flat 2.5% post-2023 reform.",
+    },
+    AR: {
+        stateCode: "AR",
+        stateName: "Arkansas",
+        rates: { under50k: 0.038, under100k: 0.039, under250k: 0.039, under500k: 0.039, over500k: 0.039 },
+    },
+    CA: {
+        stateCode: "CA",
+        stateName: "California",
+        rates: { under50k: 0.04, under100k: 0.065, under250k: 0.093, under500k: 0.103, over500k: 0.123 },
+        notes: "Excludes 1% Mental Health Services Tax above $1M and SDI.",
+    },
+    CO: {
+        stateCode: "CO",
+        stateName: "Colorado",
+        rates: { under50k: 0.044, under100k: 0.044, under250k: 0.044, under500k: 0.044, over500k: 0.044 },
+        notes: "Flat 4.4% (2026 estimate post-TABOR refund).",
+    },
+    CT: {
+        stateCode: "CT",
+        stateName: "Connecticut",
+        rates: { under50k: 0.045, under100k: 0.055, under250k: 0.06, under500k: 0.063, over500k: 0.0699 },
+    },
+    DE: {
+        stateCode: "DE",
+        stateName: "Delaware",
+        rates: { under50k: 0.045, under100k: 0.052, under250k: 0.066, under500k: 0.066, over500k: 0.066 },
+    },
+    GA: {
+        stateCode: "GA",
+        stateName: "Georgia",
+        rates: { under50k: 0.0539, under100k: 0.0539, under250k: 0.0539, under500k: 0.0539, over500k: 0.0539 },
+        notes: "Flat 5.39% (2026, scheduled to drop annually toward 4.99%).",
+    },
+    HI: {
+        stateCode: "HI",
+        stateName: "Hawaii",
+        rates: { under50k: 0.07, under100k: 0.08, under250k: 0.0925, under500k: 0.10, over500k: 0.11 },
+        notes: "Has many narrow brackets; effective rate approximation.",
+    },
+    ID: {
+        stateCode: "ID",
+        stateName: "Idaho",
+        rates: { under50k: 0.058, under100k: 0.058, under250k: 0.058, under500k: 0.058, over500k: 0.058 },
+        notes: "Flat 5.8% post-2023 reform.",
+    },
+    IL: {
+        stateCode: "IL",
+        stateName: "Illinois",
+        rates: { under50k: 0.0495, under100k: 0.0495, under250k: 0.0495, under500k: 0.0495, over500k: 0.0495 },
+        notes: "Flat 4.95%.",
+    },
+    IN: {
+        stateCode: "IN",
+        stateName: "Indiana",
+        rates: { under50k: 0.0305, under100k: 0.0305, under250k: 0.0305, under500k: 0.0305, over500k: 0.0305 },
+        notes: "Flat 3.05% (2026). Local county taxes (LIT) NOT included.",
+    },
+    IA: {
+        stateCode: "IA",
+        stateName: "Iowa",
+        rates: { under50k: 0.038, under100k: 0.038, under250k: 0.038, under500k: 0.038, over500k: 0.038 },
+        notes: "Flat 3.8% (2026 reform).",
+    },
+    KS: {
+        stateCode: "KS",
+        stateName: "Kansas",
+        rates: { under50k: 0.031, under100k: 0.0525, under250k: 0.057, under500k: 0.057, over500k: 0.057 },
+    },
+    KY: {
+        stateCode: "KY",
+        stateName: "Kentucky",
+        rates: { under50k: 0.04, under100k: 0.04, under250k: 0.04, under500k: 0.04, over500k: 0.04 },
+        notes: "Flat 4% (2026). Local occupational taxes NOT included.",
+    },
+    LA: {
+        stateCode: "LA",
+        stateName: "Louisiana",
+        rates: { under50k: 0.03, under100k: 0.03, under250k: 0.03, under500k: 0.03, over500k: 0.03 },
+        notes: "Flat 3% (2025 reform).",
+    },
+    ME: {
+        stateCode: "ME",
+        stateName: "Maine",
+        rates: { under50k: 0.058, under100k: 0.0675, under250k: 0.0715, under500k: 0.0715, over500k: 0.0715 },
+    },
+    MD: {
+        stateCode: "MD",
+        stateName: "Maryland",
+        rates: { under50k: 0.0475, under100k: 0.0525, under250k: 0.0555, under500k: 0.0575, over500k: 0.0575 },
+        notes: "Local county taxes (2.25%–3.2%) NOT included.",
+    },
+    MA: {
+        stateCode: "MA",
+        stateName: "Massachusetts",
+        rates: { under50k: 0.05, under100k: 0.05, under250k: 0.05, under500k: 0.05, over500k: 0.09 },
+        notes: "Flat 5% + 4% millionaire surtax above $1M.",
+    },
+    MI: {
+        stateCode: "MI",
+        stateName: "Michigan",
+        rates: { under50k: 0.0425, under100k: 0.0425, under250k: 0.0425, under500k: 0.0425, over500k: 0.0425 },
+        notes: "Flat 4.25%. Local city taxes NOT included.",
+    },
+    MN: {
+        stateCode: "MN",
+        stateName: "Minnesota",
+        rates: { under50k: 0.0535, under100k: 0.068, under250k: 0.0785, under500k: 0.0985, over500k: 0.0985 },
+    },
+    MS: {
+        stateCode: "MS",
+        stateName: "Mississippi",
+        rates: { under50k: 0.044, under100k: 0.044, under250k: 0.044, under500k: 0.044, over500k: 0.044 },
+        notes: "Flat 4.4% (2026, phasing toward 4%).",
+    },
+    MO: {
+        stateCode: "MO",
+        stateName: "Missouri",
+        rates: { under50k: 0.038, under100k: 0.047, under250k: 0.047, under500k: 0.047, over500k: 0.047 },
+    },
+    MT: {
+        stateCode: "MT",
+        stateName: "Montana",
+        rates: { under50k: 0.047, under100k: 0.059, under250k: 0.059, under500k: 0.059, over500k: 0.059 },
+    },
+    NE: {
+        stateCode: "NE",
+        stateName: "Nebraska",
+        rates: { under50k: 0.0246, under100k: 0.0464, under250k: 0.052, under500k: 0.052, over500k: 0.052 },
+    },
+    NJ: {
+        stateCode: "NJ",
+        stateName: "New Jersey",
+        rates: { under50k: 0.0175, under100k: 0.05525, under250k: 0.0637, under500k: 0.0897, over500k: 0.1075 },
+        notes: "Excludes SDI/UI/FLI payroll deductions.",
+    },
+    NM: {
+        stateCode: "NM",
+        stateName: "New Mexico",
+        rates: { under50k: 0.032, under100k: 0.047, under250k: 0.049, under500k: 0.059, over500k: 0.059 },
+    },
+    NY: {
+        stateCode: "NY",
+        stateName: "New York",
+        rates: { under50k: 0.045, under100k: 0.0585, under250k: 0.0685, under500k: 0.0685, over500k: 0.0882 },
+        notes: "Excludes NYC local tax (additional ~3-3.876%) and Yonkers piggyback. " +
+            "NYC residents should add ~3% to effective rate.",
+    },
+    NC: {
+        stateCode: "NC",
+        stateName: "North Carolina",
+        rates: { under50k: 0.0425, under100k: 0.0425, under250k: 0.0425, under500k: 0.0425, over500k: 0.0425 },
+        notes: "Flat 4.25% (2026, phasing toward 3.99%).",
+    },
+    ND: {
+        stateCode: "ND",
+        stateName: "North Dakota",
+        rates: { under50k: 0.0195, under100k: 0.0195, under250k: 0.025, under500k: 0.025, over500k: 0.025 },
+    },
+    OH: {
+        stateCode: "OH",
+        stateName: "Ohio",
+        rates: { under50k: 0.0275, under100k: 0.035, under250k: 0.035, under500k: 0.035, over500k: 0.035 },
+        notes: "Local municipal income taxes NOT included.",
+    },
+    OK: {
+        stateCode: "OK",
+        stateName: "Oklahoma",
+        rates: { under50k: 0.0375, under100k: 0.0475, under250k: 0.0475, under500k: 0.0475, over500k: 0.0475 },
+    },
+    OR: {
+        stateCode: "OR",
+        stateName: "Oregon",
+        rates: { under50k: 0.0875, under100k: 0.0875, under250k: 0.099, under500k: 0.099, over500k: 0.099 },
+        notes: "High effective rate at all tiers; metro/transit taxes NOT included.",
+    },
+    PA: {
+        stateCode: "PA",
+        stateName: "Pennsylvania",
+        rates: { under50k: 0.0307, under100k: 0.0307, under250k: 0.0307, under500k: 0.0307, over500k: 0.0307 },
+        notes: "Flat 3.07%. Local municipal EIT (1-4%) NOT included.",
+    },
+    RI: {
+        stateCode: "RI",
+        stateName: "Rhode Island",
+        rates: { under50k: 0.0375, under100k: 0.0475, under250k: 0.0599, under500k: 0.0599, over500k: 0.0599 },
+    },
+    SC: {
+        stateCode: "SC",
+        stateName: "South Carolina",
+        rates: { under50k: 0.03, under100k: 0.062, under250k: 0.062, under500k: 0.062, over500k: 0.062 },
+    },
+    UT: {
+        stateCode: "UT",
+        stateName: "Utah",
+        rates: { under50k: 0.0455, under100k: 0.0455, under250k: 0.0455, under500k: 0.0455, over500k: 0.0455 },
+        notes: "Flat 4.55%.",
+    },
+    VT: {
+        stateCode: "VT",
+        stateName: "Vermont",
+        rates: { under50k: 0.0335, under100k: 0.066, under250k: 0.076, under500k: 0.0875, over500k: 0.0875 },
+    },
+    VA: {
+        stateCode: "VA",
+        stateName: "Virginia",
+        rates: { under50k: 0.0475, under100k: 0.0575, under250k: 0.0575, under500k: 0.0575, over500k: 0.0575 },
+    },
+    WV: {
+        stateCode: "WV",
+        stateName: "West Virginia",
+        rates: { under50k: 0.0436, under100k: 0.0482, under250k: 0.0482, under500k: 0.0482, over500k: 0.0482 },
+    },
+    WI: {
+        stateCode: "WI",
+        stateName: "Wisconsin",
+        rates: { under50k: 0.0354, under100k: 0.053, under250k: 0.0765, under500k: 0.0765, over500k: 0.0765 },
+    },
+    DC: {
+        stateCode: "DC",
+        stateName: "District of Columbia",
+        rates: { under50k: 0.06, under100k: 0.065, under250k: 0.085, under500k: 0.0925, over500k: 0.1075 },
+        notes: "DC included for full HCOL coverage even though not a state.",
+    },
+};
+/**
+ * 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 function getStateEffectiveRate(stateCode, taxableIncome) {
+    const upper = stateCode.trim().toUpperCase();
+    const entry = STATE_EFFECTIVE_RATES_2026[upper];
+    if (!entry)
+        return 0;
+    const tier = pickIncomeTier(Math.max(0, taxableIncome));
+    return entry.rates[tier];
+}
+/**
+ * Get the full state data entry (for surfacing `notes` in the tool envelope).
+ */
+export function getStateEntry(stateCode) {
+    return STATE_EFFECTIVE_RATES_2026[stateCode.trim().toUpperCase()];
+}
+//# sourceMappingURL=stateTax2026.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stateTax2026.js","sourceRoot":"","sources":["../../../src/engines/data/stateTax2026.ts"],"names":[],"mappings":"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"}

package/dist/engines/hsa.d.ts

@@ -0,0 +1,110 @@
+/**
+ * HSA (Health Savings Account) contribution-limit engine — lifted from
+ * site/src/utils/hsa-limits.js (functions `getMaxContribution`,
+ * `isCatchUpEligible`).
+ *
+ * Per ADR-0039 § 5: pure synchronous function, ENGINE_VERSION constant,
+ * parity test against the site source as the gate.
+ *
+ * Scope (S141 Wave 1B Item #3): contribution-LIMIT and employer-reduction
+ * math. Does NOT compute long-term HSA growth projection (the site calc's
+ * `generateGrowthProjection`) or split federal/state/FICA tax-savings
+ * breakdown (the site calc's `calculateTotalTaxSavings` returns a 3-component
+ * breakdown). For v1 this tool exposes a single `payrollDeductionTaxSavings`
+ * convenience field — combined federal+state+FICA at the caller-provided
+ * marginal rate — as the simplest useful tax-impact answer. Detailed
+ * breakdowns are a future tool: `dc.calculator.hsa.taxSavingsBreakdown`.
+ *
+ * Math reference (per IRC §223 + IRS Rev. Proc. 2025-19):
+ *   baseLimit = coverageTier === "family" ? family : selfOnly
+ *   catchUpAmount = age ≥ 55 ? 1000 : 0
+ *   totalContributionLimit = baseLimit + catchUpAmount
+ *   employeeMaxRemaining = max(0, totalContributionLimit − employerContribution)
+ *   payrollDeductionTaxSavings = marginalRate provided
+ *                              ? employeeMaxRemaining × (marginalRate / 100)
+ *                              : 0
+ *
+ * Why employer contributions reduce employee max dollar-for-dollar: the IRS
+ * §223(b) limit is a TOTAL annual limit across all funding sources, not a
+ * per-source limit. An employer that contributes $2,000 to a family-tier HSA
+ * leaves $6,750 of room for employee payroll deductions ($8,750 − $2,000).
+ *
+ * Source: IRS Rev. Proc. 2025-19 (2026 HSA inflation adjustments) +
+ *         IRC §223(b)(3)(B) (statutory $1,000 catch-up, NOT inflation-indexed).
+ * Last verified: 2026-05-27.
+ */
+/**
+ * SemVer of the HSA engine. Per ADR-0039 § 5 (reaffirmed in ADR-0041
+ * Position #4a): major bump = math change; minor = additive output; patch =
+ * numerical correction. NOT bumped for cosmetic refactors.
+ * - 1.0.0: initial v1 lift from hsa-limits.js (S141 Wave 1B).
+ */
+export declare const ENGINE_VERSION = "1.0.0";
+/**
+ * HDHP coverage tier. IRS canonical names per Rev. Proc. 2025-19:
+ *   - `"self-only"` (≈ site's `"individual"` spelling)
+ *   - `"family"` (matches site)
+ */
+export type HsaCoverageTier = "self-only" | "family";
+/** Inputs to the HSA contribution-limit engine. */
+export interface HsaContributionLimitInput {
+    /** Current age (drives age-55+ catch-up eligibility). */
+    age: number;
+    /** HDHP coverage tier. */
+    coverageTier: HsaCoverageTier;
+    /**
+     * Annual employer HSA contribution, USD. Reduces the employee's eligible
+     * payroll-deduction room dollar-for-dollar. Defaults to 0.
+     */
+    employerContribution?: number;
+    /**
+     * Estimated marginal federal tax rate, whole-number percent (e.g., 22 for
+     * 22%). Optional — when omitted, `payrollDeductionTaxSavings` returns 0.
+     * Combined federal+state+FICA is a future tool; for v1 this is treated as
+     * the user's effective marginal rate against the remaining employee
+     * contribution.
+     */
+    estimatedMarginalRatePercent?: number;
+}
+/** Result payload returned by the engine. */
+export interface HsaContributionLimitResult {
+    /** Base IRS limit for the selected coverage tier (without catch-up), USD. */
+    contributionLimit: number;
+    /** Whether the user qualifies for the age 55+ catch-up. */
+    catchUpEligible: boolean;
+    /** Catch-up amount applied ($1,000 if eligible, else 0), USD. */
+    catchUpAmount: number;
+    /** Total annual limit (contributionLimit + catchUpAmount), USD. */
+    totalContributionLimit: number;
+    /** Echoes the input employer contribution, USD. */
+    employerContribution: number;
+    /**
+     * Remaining room the EMPLOYEE can contribute via payroll after subtracting
+     * the employer contribution. Clamped at 0 (an over-the-cap employer
+     * contribution does not produce negative employee room). USD.
+     */
+    employeeMaxRemaining: number;
+    /**
+     * Estimated tax savings if the employee contributes employeeMaxRemaining
+     * via payroll, at the provided marginal rate. 0 when marginal rate is not
+     * provided. USD.
+     */
+    payrollDeductionTaxSavings: number;
+    /** Provenance metadata. */
+    meta: {
+        /** IRS tax year these limits apply to. */
+        tableYear: number;
+        /** Source authority (IRS revenue procedure / IRC citation). */
+        source: string;
+    };
+}
+/**
+ * Compute the HSA contribution limit + employer-reduction + payroll-deduction
+ * tax savings for the given inputs.
+ *
+ * 1-to-1 logic port of site/src/utils/hsa-limits.js `getMaxContribution` +
+ * `isCatchUpEligible`, extended with the explicit employer-reduction math
+ * and an optional payroll-deduction tax-savings convenience field.
+ */
+export declare function contributionLimit(input: HsaContributionLimitInput): HsaContributionLimitResult;
+//# sourceMappingURL=hsa.d.ts.map

package/dist/engines/hsa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hsa.d.ts","sourceRoot":"","sources":["../../src/engines/hsa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH;;;;;GAKG;AACH,eAAO,MAAM,cAAc,UAAU,CAAC;AAEtC;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,QAAQ,CAAC;AAErD,mDAAmD;AACnD,MAAM,WAAW,yBAAyB;IACxC,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,0BAA0B;IAC1B,YAAY,EAAE,eAAe,CAAC;IAC9B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;;;OAMG;IACH,4BAA4B,CAAC,EAAE,MAAM,CAAC;CACvC;AAED,6CAA6C;AAC7C,MAAM,WAAW,0BAA0B;IACzC,6EAA6E;IAC7E,iBAAiB,EAAE,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,eAAe,EAAE,OAAO,CAAC;IACzB,iEAAiE;IACjE,aAAa,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,sBAAsB,EAAE,MAAM,CAAC;IAC/B,mDAAmD;IACnD,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,0BAA0B,EAAE,MAAM,CAAC;IACnC,2BAA2B;IAC3B,IAAI,EAAE;QACJ,0CAA0C;QAC1C,SAAS,EAAE,MAAM,CAAC;QAClB,+DAA+D;QAC/D,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,yBAAyB,GAC/B,0BAA0B,CAiD5B"}

package/dist/engines/hsa.js

@@ -0,0 +1,83 @@
+/**
+ * HSA (Health Savings Account) contribution-limit engine — lifted from
+ * site/src/utils/hsa-limits.js (functions `getMaxContribution`,
+ * `isCatchUpEligible`).
+ *
+ * Per ADR-0039 § 5: pure synchronous function, ENGINE_VERSION constant,
+ * parity test against the site source as the gate.
+ *
+ * Scope (S141 Wave 1B Item #3): contribution-LIMIT and employer-reduction
+ * math. Does NOT compute long-term HSA growth projection (the site calc's
+ * `generateGrowthProjection`) or split federal/state/FICA tax-savings
+ * breakdown (the site calc's `calculateTotalTaxSavings` returns a 3-component
+ * breakdown). For v1 this tool exposes a single `payrollDeductionTaxSavings`
+ * convenience field — combined federal+state+FICA at the caller-provided
+ * marginal rate — as the simplest useful tax-impact answer. Detailed
+ * breakdowns are a future tool: `dc.calculator.hsa.taxSavingsBreakdown`.
+ *
+ * Math reference (per IRC §223 + IRS Rev. Proc. 2025-19):
+ *   baseLimit = coverageTier === "family" ? family : selfOnly
+ *   catchUpAmount = age ≥ 55 ? 1000 : 0
+ *   totalContributionLimit = baseLimit + catchUpAmount
+ *   employeeMaxRemaining = max(0, totalContributionLimit − employerContribution)
+ *   payrollDeductionTaxSavings = marginalRate provided
+ *                              ? employeeMaxRemaining × (marginalRate / 100)
+ *                              : 0
+ *
+ * Why employer contributions reduce employee max dollar-for-dollar: the IRS
+ * §223(b) limit is a TOTAL annual limit across all funding sources, not a
+ * per-source limit. An employer that contributes $2,000 to a family-tier HSA
+ * leaves $6,750 of room for employee payroll deductions ($8,750 − $2,000).
+ *
+ * Source: IRS Rev. Proc. 2025-19 (2026 HSA inflation adjustments) +
+ *         IRC §223(b)(3)(B) (statutory $1,000 catch-up, NOT inflation-indexed).
+ * Last verified: 2026-05-27.
+ */
+import { LIMITS_HSA_2026 } from "./data/irs2026.js";
+/**
+ * SemVer of the HSA engine. Per ADR-0039 § 5 (reaffirmed in ADR-0041
+ * Position #4a): major bump = math change; minor = additive output; patch =
+ * numerical correction. NOT bumped for cosmetic refactors.
+ * - 1.0.0: initial v1 lift from hsa-limits.js (S141 Wave 1B).
+ */
+export const ENGINE_VERSION = "1.0.0";
+/**
+ * Compute the HSA contribution limit + employer-reduction + payroll-deduction
+ * tax savings for the given inputs.
+ *
+ * 1-to-1 logic port of site/src/utils/hsa-limits.js `getMaxContribution` +
+ * `isCatchUpEligible`, extended with the explicit employer-reduction math
+ * and an optional payroll-deduction tax-savings convenience field.
+ */
+export function contributionLimit(input) {
+    const { age, coverageTier, employerContribution = 0, estimatedMarginalRatePercent, } = input;
+    // Base contribution limit per coverage tier (IRS Rev. Proc. 2025-19).
+    const baseLimit = coverageTier === "family"
+        ? LIMITS_HSA_2026.family
+        : LIMITS_HSA_2026.selfOnly;
+    // Catch-up: $1,000 if age ≥ 55 (statutory, IRC §223(b)(3)(B)).
+    const catchUpEligible = age >= LIMITS_HSA_2026.catchUpAge;
+    const catchUpAmount = catchUpEligible ? LIMITS_HSA_2026.catchUp : 0;
+    const totalContributionLimit = baseLimit + catchUpAmount;
+    // Employer contribution reduces employee max dollar-for-dollar; clamp at 0.
+    const employeeMaxRemaining = Math.max(0, totalContributionLimit - employerContribution);
+    // Payroll-deduction tax savings (combined federal + state + FICA proxy).
+    // Pre-tax payroll deduction reduces taxable income → marginal-rate savings.
+    const payrollDeductionTaxSavings = typeof estimatedMarginalRatePercent === "number"
+        ? Math.round(employeeMaxRemaining * (estimatedMarginalRatePercent / 100) * 100) / 100
+        : 0;
+    return {
+        contributionLimit: baseLimit,
+        catchUpEligible,
+        catchUpAmount,
+        totalContributionLimit,
+        employerContribution,
+        employeeMaxRemaining,
+        payrollDeductionTaxSavings,
+        meta: {
+            tableYear: 2026,
+            source: "IRS Rev. Proc. 2025-19; IRC §223(b)(3)(B) (statutory $1,000 catch-up)",
+        },
+    };
+}
+//# sourceMappingURL=hsa.js.map

package/dist/engines/hsa.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hsa.js","sourceRoot":"","sources":["../../src/engines/hsa.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AA+DtC;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAgC;IAEhC,MAAM,EACJ,GAAG,EACH,YAAY,EACZ,oBAAoB,GAAG,CAAC,EACxB,4BAA4B,GAC7B,GAAG,KAAK,CAAC;IAEV,sEAAsE;IACtE,MAAM,SAAS,GACb,YAAY,KAAK,QAAQ;QACvB,CAAC,CAAC,eAAe,CAAC,MAAM;QACxB,CAAC,CAAC,eAAe,CAAC,QAAQ,CAAC;IAE/B,+DAA+D;IAC/D,MAAM,eAAe,GAAG,GAAG,IAAI,eAAe,CAAC,UAAU,CAAC;IAC1D,MAAM,aAAa,GAAG,eAAe,CAAC,CAAC,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAEpE,MAAM,sBAAsB,GAAG,SAAS,GAAG,aAAa,CAAC;IAEzD,4EAA4E;IAC5E,MAAM,oBAAoB,GAAG,IAAI,CAAC,GAAG,CACnC,CAAC,EACD,sBAAsB,GAAG,oBAAoB,CAC9C,CAAC;IAEF,yEAAyE;IACzE,4EAA4E;IAC5E,MAAM,0BAA0B,GAC9B,OAAO,4BAA4B,KAAK,QAAQ;QAC9C,CAAC,CAAC,IAAI,CAAC,KAAK,CACR,oBAAoB,GAAG,CAAC,4BAA4B,GAAG,GAAG,CAAC,GAAG,GAAG,CAClE,GAAG,GAAG;QACT,CAAC,CAAC,CAAC,CAAC;IAER,OAAO;QACL,iBAAiB,EAAE,SAAS;QAC5B,eAAe;QACf,aAAa;QACb,sBAAsB;QACtB,oBAAoB;QACpB,oBAAoB;QACpB,0BAA0B;QAC1B,IAAI,EAAE;YACJ,SAAS,EAAE,IAAI;YACf,MAAM,EACJ,uEAAuE;SAC1E;KACF,CAAC;AACJ,CAAC"}