npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

us-tax-advantaged-params

v0.7.0

Published

Historical and current U.S. tax-advantaged account parameters. Retirement accounts are covered today: contribution limits, phase-outs, shared-limit allocation, and Roth-conversion tax effects.

Readme

us-tax-advantaged-params

CI License: MIT

us-tax-advantaged-params is a dependency-free calculation engine for historical and current U.S. tax-advantaged account parameters. It calculates account-level and household-level contribution capacity, IRA phase-outs, shared statutory limits, federal income effects, and Roth-conversion taxability for retirement accounts, and contribution capacity for health savings accounts under IRC §223.

The repository contains two native implementations with the same behavior:

  • TypeScript for npm, exported as USTaxAdvantagedParams.
  • PHP 8.4+ for Packagist, in the USTaxAdvantagedParams namespace.

Annual legal parameters are maintained once, in the retirement, HSA, FSA, payroll-tax, education, ABLE, adoption, HRA and commuter JSON files under data/, and generated into each single-file runtime. Shared conformance vectors and a full-output parity check keep the TypeScript and PHP engines synchronized.

Tax-software scope, not tax advice. This package calculates statutory parameters from caller-supplied facts. It does not determine whether a plan document permits a contribution, perform ERISA nondiscrimination testing, classify self-employment earnings or apply optional SECA methods, replace Form 8606, provide an actuarial valuation, or prepare a tax return. Review material results against the governing plan document and current primary authority.

Supported tax years

The encoded range is 1975 through 2027. The package does not extrapolate a future year. Calling a year outside the range throws UnsupportedTaxYearError in TypeScript or UnsupportedTaxYearException in PHP.

The 1975 starting point corresponds to the first generally available IRA contribution year. Some early employer-plan years cannot be reduced to a universal modern dollar ceiling from tax year alone. In those cases the engine returns an explicit indeterminate status and diagnostic rather than inventing a value.

USTaxAdvantagedParams.supportedTaxYears();
// { minimum: 1975, maximum: 2027 }

Health savings accounts have their own range, 2004 through 2027, because IRC §223 was added by the Medicare Prescription Drug, Improvement, and Modernization Act of 2003 effective for taxable years beginning after 2003. A year before 2004 returns an unavailable HSA result rather than an extrapolated one.

The IRS publishes the HSA Revenue Procedure in the spring, months before the retirement cost-of-living notice, so the HSA table can run a year past the retirement table between the two. Both now end at 2027: the HSA amounts come from Rev. Proc. 2026-24 and the retirement amounts from Notice 2026-66. A scenario for a year past the retirement table throws UnsupportedTaxYearError even when the HSA table already has it.

USTaxAdvantagedParams.supportedHsaTaxYears();
// { minimum: 2004, maximum: 2027 }

Flexible spending arrangements have their own range, 1982 through 2026. It starts at 1982 because Pub. L. 97-34 §124 added §129 for taxable years beginning after December 31, 1981. Each program carries a state for each year. Dependent care has no statutory dollar limit until 1987, when the Tax Reform Act of 1986 §1163 added the §129(a)(2)(A) limitation. The §125(i) health FSA limit starts at 2013, because the Affordable Care Act §9005 added it for plan years beginning after December 31, 2012. A year before a program's limit returns the available_without_statutory_dollar_limit state with a null amount.

USTaxAdvantagedParams.supportedFsaTaxYears();
// { minimum: 1982, maximum: 2026 }
USTaxAdvantagedParams.fsaParametersForYear(2012)?.healthFsa;
// { state: "available_without_statutory_dollar_limit", salaryReductionLimit: null, carryoverLimit: null }

Education parameters have their own range, 1996 through 2026. It starts at 1996 because §529 applies to taxable years ending after August 20, 1996. A year lookup cannot say whether a 1996 taxable year ended after that date, so §529 is indeterminate for 1996 and applies from 1997. §530 Coverdell accounts are unavailable for 1996 and 1997, and §127 educational assistance applies throughout. These figures are reported, not applied; see Education savings and educational assistance parameters.

USTaxAdvantagedParams.supportedEducationTaxYears();
// { minimum: 1996, maximum: 2026 }

ABLE accounts have their own range, 2015 through 2026, because the ABLE Act of 2014 applies §529A to taxable years beginning after December 31, 2014. See ABLE account parameters.

USTaxAdvantagedParams.supportedAbleTaxYears();
// { minimum: 2015, maximum: 2026 }

Adoption parameters have their own range, 1997 through 2026, because the Small Business Job Protection Act of 1996 added the §23 credit and the §137 exclusion for taxable years beginning after December 31, 1996. See Adoption parameters.

USTaxAdvantagedParams.supportedAdoptionTaxYears();
// { minimum: 1997, maximum: 2026 }

HRA parameters have their own range, 2017 through 2026, because the 21st Century Cures Act added the §9831(d) qualified small employer HRA for years beginning after December 31, 2016. See HRA parameters.

USTaxAdvantagedParams.supportedHraTaxYears();
// { minimum: 2017, maximum: 2026 }

Commuter parameters have their own range, 1999 through 2026. It starts at the first year of the §132(f)(2) amounts set by the Transportation Equity Act for the 21st Century. §132(f) itself is older, so in this table alone a year before 1999 is not encoded, rather than unavailable. See Commuter parameters.

USTaxAdvantagedParams.supportedCommuterTaxYears();
// { minimum: 1999, maximum: 2026 }

Installation

npm

npm install us-tax-advantaged-params

The npm package provides ESM, CommonJS, and TypeScript declarations and supports Node.js 22 or later.

// ESM
import USTaxAdvantagedParams from "us-tax-advantaged-params";

// CommonJS — the class is the module's default export
const USTaxAdvantagedParams = require("us-tax-advantaged-params").default;

Composer / Packagist

composer require bherila/us-tax-advantaged-params

The PHP package requires PHP 8.4 or later and loads the native single-file implementation through Composer.

Upgrading to 0.7.0

0.7.0 adds tax year 2027 to the retirement and payroll tables. No result for 2026 or an earlier year changes.

Additions:

  • The retirement table runs through 2027, from Notice 2026-66. supportedTaxYears() returns a maximum of 2027, and a 2027 scenario now calculates instead of throwing UnsupportedTaxYearError / UnsupportedTaxYearException.
  • The payroll table runs through 2027. The OASDI contribution and benefit base is $192,300, from the Social Security Administration's 2027 determination (91 FR 67380). Every other 2027 payroll figure is the unchanged statutory rate or threshold.

Check before upgrading:

  • Code that treated 2027 as unsupported now gets a row: parametersForYear(2027) and payrollParametersForYear(2027) return data, and 2028 is the first unsupported year for both tables.
  • From 2027, saversCredit25B.retirementPlanAndIraContributionsQualify is false. Pub. L. 119-21 §70116(a)(1) ends the Saver's Credit for retirement-plan and IRA contributions after 2026, and footnote 2 of Notice 2026-66 confirms that the Saver's Match under §6433 replaces it for them. ABLE contributions still qualify. The package doesn't model the Saver's Match.
  • The FSA, HRA, ABLE, adoption, commuter and education tables still end at 2026. The HSA table already ran through 2027.

Upgrading to 0.6.0

0.6.0 adds provenance and changes no calculation result. Nothing needs to change in existing code.

Additions:

  • Every parameter-table lookup has a provenance twin, such as parameterSourcesForYear and hsaParameterSourcesForYear. For each figure it returns the provision it is set under, the primary documents that publish or fix it, and the evidence's note where those documents don't print it. See Where each figure came from.
  • payrollSourceMetadata(), matching the other tables.

Source metadata changes:

  • The retirement source list gains the 51 documents its evidence cites.
  • Records that pointed at uscode.house.gov now point at the matching govinfo editions.
  • Payroll records that were titled with file names now carry their Federal Register titles.

Fixes since 0.5.0:

  • PHP validates a table-lookup year before coercing it, as TypeScript does. A fractional or non-finite year now throws INVALID_TAX_YEAR in both engines.
  • Payroll results normalize numeric-key lists identically in both engines.
  • Cents-normalized payroll rate products round exactly at half-cent ties.

Upgrading to 0.5.0

0.5.0 removes the account-level HSA inputs that were really facts about a person or a couple, and it makes several result fields nullable so an unestablished figure is reported as unknown rather than as zero. Both engines change identically.

Inputs that are now rejected. Each still-supplied field throws ParameterError / ParameterException, whether it appears on planRules.hsa or on persons[].hsaCoverage:

| Remove from planRules.hsa | Replace with | Builder (TS and PHP) | |---|---|---| | useLastMonthRule | nothing; §223(b)(8) applies automatically as a greater-of | AccountBuilder.hsaLastMonthRule() removed | | testingPeriodSatisfied | persons[].hsaLastMonthRuleTestingPeriod.satisfied | PersonBuilder.hsaTestingPeriodSatisfied() | | testingPeriodFailureByDeathOrDisability | persons[].hsaLastMonthRuleTestingPeriod.failureByDeathOrDisability | moved from AccountBuilder to PersonBuilder | | familyLimitShare | hsaFamilyLimitDivision on the scenario | ScenarioBuilder.hsaFamilyLimitDivision() / hsaFamilyLimitDivisionUnsettled(); AccountBuilder.hsaFamilyLimitShare() removed |

The error codes and the reasoning are in The division is one fact about the couple and The last-month rule is a greater-of, not an election. In TypeScript, HsaRulesInput is now an alias of HsaCoverageInput.

Result fields that changed type or name:

  • An account's hsa detail can be null. See The hsa detail is withheld, never completed.
  • On HsaAccountDetail, proratedContributionLimit, contributionLimitWithoutLastMonthRule, archerMsaLimitReduction, qualifiedHsaFundingLimitReduction and amountAttributableToLastMonthRule can be null. See A share nobody established is not a zero.
  • HsaAccountDetail.lastMonthRuleApplied is renamed fullContributionCandidateSelected, because nothing is elected. It is true when the December-coverage candidate set the ceiling.
  • In sharedLimits, usedBeforeAccount and usedByAccount can be null where the ceiling is known but the draw against it is not. The feasible range is in the new possibleUsedBeforeAccount, possibleUsedByAccount and possibleRemainingAfterAccount intervals. See HSA usage describes feasible attribution.

Answers that can change for input that is still accepted:

  • An HSA owner eligible in December gets the §223(b)(8) ceiling whenever it is greater, without opting in.
  • On a married return, an owner with no stated spousal coverage is indeterminate with HSA_SPOUSE_COVERAGE_FACTS_REQUIRED in 2004–2006 even when every month is a family month, because the lowest-deductible comparison could lower the limitation. State persons[].hsaCoverage: {} for a spouse with no HDHP coverage. See When the other spouse's coverage is required.
  • A stated HDHP deductible below the year's statutory minimum is inconsistent input (HSA_HDHP_DEDUCTIBLE_BELOW_STATUTORY_MINIMUM), not a lower ceiling.
  • An existing pre-tax age-based catch-up that §414(v)(7)(A) did not permit, given the participant's prior-year FICA wages, is diagnosed. Its attribution among the shared limits is reported as an interval.
  • A designated-Roth account whose rules permit a Roth catch-up no longer needs priorYearFicaWagesByEmployer.

Additions that need no change:

  • section457PlanGroupId, which lets a governmental §457(b) host and its PLESA share one plan (records that disagree are rejected with SECTION_457_PLAN_GROUP_FACTS_CONFLICT).
  • The §401(a)(17) grandfathered governmental ceiling.
  • Opt-in FICA/SECA effects.
  • 2027 HSA amounts.
  • New parameter tables for education, ABLE, adoption, HRA and commuter benefits.

TypeScript builder example

import USTaxAdvantagedParams, {
  AccountType,
  ConversionType,
  FilingStatus,
} from "us-tax-advantaged-params";

const result = USTaxAdvantagedParams.forTaxYear(2026)
  .filingStatus(FilingStatus.MARRIED_FILING_JOINTLY)
  .taxpayer("taxpayer", (person) => {
    person
      .bornIn(1963)
      .iraCompensation(180_000)
      .w2Compensation(180_000)
      .rothIraMagi(240_000)
      .traditionalIraDeductionMagi(240_000)
      .coveredByEmployerPlan(true)
      .priorYearFicaWages("employer-a", 180_000)
      .aggregateTraditionalSepSimpleIraBasis(20_000)
      .yearEndTraditionalSepSimpleIraValue(80_000);
  })
  .spouse("spouse", (person) => {
    person
      .bornIn(1970)
      .iraCompensation(0)
      .rothIraMagi(240_000)
      .traditionalIraDeductionMagi(240_000)
      .coveredByEmployerPlan(false);
  })
  .account(
    "taxpayer-401k",
    "taxpayer",
    AccountType.TRADITIONAL_401K,
    (account) => {
      account
        .employer("employer-a")
        .annualAdditionsGroup("employer-a")
        .planCompensation(180_000)
        .permitsRothContributions()
        .permitsRothCatchUp()
        .permitsAfterTaxContributions()
        .expectedEmployerContribution(9_000)
        .priority(10);
    },
  )
  .account("taxpayer-roth-ira", "taxpayer", AccountType.ROTH_IRA, (account) => {
    account.priority(20);
  })
  .account("spouse-traditional-ira", "spouse", AccountType.TRADITIONAL_IRA, (account) => {
    account.priority(30);
  })
  .conversion(
    "ira-conversion",
    "taxpayer",
    ConversionType.IRA_TO_ROTH_IRA,
    10_000,
  )
  .calculate();

console.log(result.accounts[0].maximumAnnualContributionBasedOnInputs);
console.log(result.totals.federalAgiReduction);
console.log(result.conversions[0].taxableAmount);

A built scenario can be inspected and calculated repeatedly:

const scenario = USTaxAdvantagedParams.forTaxYear(2026)
  .filingStatus("MFJ")
  .taxpayer("taxpayer", (person) => person.bornIn(1980).w2Compensation(200_000))
  .build();

const input = scenario.toInput();
const result = scenario.calculate();

PHP builder example

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use USTaxAdvantagedParams\AccountType;
use USTaxAdvantagedParams\FilingStatus;
use USTaxAdvantagedParams\PersonBuilder;
use USTaxAdvantagedParams\AccountBuilder;
use USTaxAdvantagedParams\USTaxAdvantagedParams as TaxAdvantagedParams;

$result = TaxAdvantagedParams::forTaxYear(2026)
    ->filingStatus(FilingStatus::MARRIED_FILING_JOINTLY)
    ->taxpayer('taxpayer', static function (PersonBuilder $person): void {
        $person
            ->bornIn(1963)
            ->iraCompensation(180_000)
            ->w2Compensation(180_000)
            ->rothIraMagi(240_000)
            ->traditionalIraDeductionMagi(240_000)
            ->coveredByEmployerPlan(true)
            ->priorYearFicaWages('employer-a', 180_000);
    })
    ->spouse('spouse', static function (PersonBuilder $person): void {
        $person
            ->bornIn(1970)
            ->iraCompensation(0)
            ->rothIraMagi(240_000)
            ->traditionalIraDeductionMagi(240_000)
            ->coveredByEmployerPlan(false);
    })
    ->account(
        'taxpayer-401k',
        'taxpayer',
        AccountType::TRADITIONAL_401K,
        static function (AccountBuilder $account): void {
            $account
                ->employer('employer-a')
                ->annualAdditionsGroup('employer-a')
                ->planCompensation(180_000)
                ->permitsRothContributions()
                ->permitsRothCatchUp()
                ->permitsAfterTaxContributions()
                ->expectedEmployerContribution(9_000)
                ->priority(10);
        },
    )
    ->account('spouse-ira', 'spouse', AccountType::TRADITIONAL_IRA)
    ->calculate();

var_dump($result['totals']);

The PHP result is an associative-array equivalent of the TypeScript result. Enum values serialize to the same snake-case strings.

Direct unified interface

Builders are optional. Both engines accept the same language-neutral scenario shape, which is useful for services, fixtures, database records, and cross-runtime integrations.

const result = USTaxAdvantagedParams.calculate({
  taxYear: 2026,
  filingStatus: "HOH",
  persons: [
    {
      id: "taxpayer",
      role: "taxpayer",
      birthYear: 1975,
      compensation: { iraCompensation: 140_000, w2Compensation: 140_000 },
      magi: { rothIra: 158_000, traditionalIraDeduction: 158_000 },
      coveredByEmployerRetirementPlan: true,
    },
  ],
  accounts: [
    {
      id: "401k",
      ownerId: "taxpayer",
      type: "traditional_401k",
      employerId: "employer-a",
      planRules: {
        planCompensation: 140_000,
        annualAdditionsGroupId: "employer-a",
        expectedEmployerContribution: 7_000,
      },
    },
    { id: "roth-ira", ownerId: "taxpayer", type: "roth_ira", priority: 20 },
  ],
});

Filing-status aliases include S, SINGLE, MFJ, MFS, HOH, QSS, and QW. The alias M is accepted as MFJ but emits an ambiguity diagnostic. Canonical values are preferred in persisted data.

Input rejection

The unified interface is where stale, mistyped, and cross-runtime data arrives, so an input it cannot honour is rejected rather than coerced. Both engines throw the same error code and the same message for the same bad input.

| Code | Raised for | |---|---| | INVALID_TAX_YEAR | A taxYear that is not an integer | | INVALID_FILING_STATUS | A missing filingStatus, a non-string, or an unrecognized alias | | PERSON_REQUIRED | persons missing, not a list, or empty | | INVALID_ACCOUNTS / INVALID_CONVERSIONS | accounts or conversions present but not a list | | INVALID_PERSON / INVALID_ACCOUNT / INVALID_CONVERSION | An entry of persons, accounts, or conversions that is not an object | | PERSON_ID_REQUIRED / ACCOUNT_ID_REQUIRED / CONVERSION_ID_REQUIRED | An id that is missing, blank, or not a string | | ACCOUNT_OWNER_REQUIRED / CONVERSION_OWNER_REQUIRED | An ownerId that is missing, blank, or not a string | | UNKNOWN_ACCOUNT_OWNER / UNKNOWN_CONVERSION_OWNER | An ownerId that names no supplied person | | INVALID_ACCOUNT_TYPE / INVALID_CONVERSION_TYPE | A type that is not a string, or an unrecognized one | | INVALID_INPUT_OBJECT | A structured field — planRules, existingContributions, compensation, magi, priorYearFicaWagesByEmployer, hsa, hsaCoverage, special403bCatchUp, section457SpecialCatchUp — holding something other than an object | | INVALID_CONTRIBUTION_PREFERENCE | A contributionPreference outside account_type, pretax_first, roth_first (a valid preference that a pension-linked emergency savings account cannot honour is reported as a diagnostic, not rejected — see Pension-linked emergency savings accounts) | | INVALID_EMPLOYER_CONTRIBUTION_TAX_TREATMENT | An employerContributionTaxTreatment outside pretax, roth | | INVALID_SIMPLE_EMPLOYER_CONTRIBUTION_METHOD | A simpleEmployerContributionMethod outside match_3_percent, nonelective_2_percent, custom | | INVALID_EMPLOYER_ID / INVALID_ANNUAL_ADDITIONS_GROUP_ID / INVALID_SECTION_457_PLAN_GROUP_ID | An identifier field holding something other than a non-empty string | | INVALID_MONEY / INVALID_RATE | A negative or non-finite amount, or a rate outside 0 through 1 | | INVALID_BOOLEAN | A flag field holding something other than true or false |

Enum-valued fields in particular are checked rather than compared loosely: a stale or camel-cased value such as "rothFirst" would otherwise fall through to a different branch and return a plausible but wrong allocation. Structured fields are checked for the same reason — a scalar where an object belongs used to be ignored in silence, taking every rule it carried with it. Flag fields must be actual booleans, because JavaScript and PHP disagree about the truthiness of "0" and of an empty array.

Two shapes are deliberately not rejected. A missing accounts or conversions key, and an explicit null in its place, both mean an empty list. And a JSON object whose keys are exactly "0", "1", … is accepted wherever a list is expected, because json_decode cannot tell it apart from a JSON array, so neither engine may.

Account coverage

| Family | Account types | |---|---| | Individual retirement arrangements | Traditional IRA, Roth IRA, rollover IRA, payroll-deduction IRA, deemed traditional/Roth IRA, inherited traditional/Roth IRA | | Small-employer arrangements | SEP IRA, Roth SEP IRA, SIMPLE IRA, Roth SIMPLE IRA, grandfathered SARSEP | | Qualified elective plans | Traditional/Roth 401(k), Solo/Roth Solo 401(k), SIMPLE/Roth SIMPLE 401(k), starter 401(k), pension-linked emergency savings account (PLESA) | | Tax-sheltered annuities | Traditional/Roth 403(b), safe-harbor deferral-only 403(b) — see the §403(b)(2) note below for tax years 1987-2001 | | Deferred compensation | Governmental/Roth governmental 457(b), nongovernmental eligible 457(b), 457(f), governmental 457(b)-hosted PLESA | | Federal plan | Traditional and Roth TSP | | Employer-only defined-contribution plans | 401(a), profit-sharing, money-purchase, Keogh, ESOP | | Pension arrangements | Defined-benefit and cash-balance plans | | Health accounts | Health savings account (HSA), health flexible spending arrangement (health FSA) | | Dependent care | Dependent care assistance program (dependent care FSA) |

Defined-benefit and cash-balance contributions are deliberately returned as indeterminate; their funding requires the plan formula, census, assets, actuarial assumptions, and funding rules. The §415(b)(1)(A) limitation on the annual benefit is a different thing — a flat statutory ceiling published in the same annual notice as the defined-contribution figures, requiring no actuary — so it is reported alongside that indeterminate contribution status:

const result = USTaxAdvantagedParams.calculate({
  taxYear: 2026,
  filingStatus: "S",
  persons: [{ id: "t", birthYear: 1970 }],
  accounts: [{ id: "db", ownerId: "t", type: "defined_benefit_plan", employerId: "e" }],
});
result.accounts[0].status;                             // "indeterminate"
result.accounts[0].statutoryMaximumAnnualContribution; // null
result.accounts[0].definedBenefit?.annualBenefitLimit; // 290000

| Rule | Treatment | |---|---| | §415(b)(1)(A) annual benefit | Reported on definedBenefit.annualBenefitLimit for both defined-benefit and cash-balance accounts, with an info diagnostic stating it | | §415(b)(2) and §415(b)(5) adjustments | Not applied. The published figure assumes a straight life annuity beginning between ages 62 and 65; adjusting it for another benefit form, another starting age, or fewer than ten years of participation or service is participant-specific | | Years with no transcribed figure | null. The encoded figures are those transcribed from the notices committed under evidence/retirement-limits/, which cover 2009, 2010, and 2013 onward. A year outside that set reports null rather than a carried-forward or extrapolated amount | | Contribution and funding | Still indeterminate; a benefit ceiling is not a contribution ceiling, and nothing here computes a funding requirement |

Pension-linked emergency savings accounts (IRC §402A(e))

SECURE 2.0 §127 added §402A(e), effective for plan years beginning after December 31, 2023. §402A(e)(1)(A)(i) treats a PLESA "for purposes of this title as a designated Roth account", so its contributions are always Roth.

That is a characteristic of the account rather than an election, so it precedes the caller's: planRules.contributionPreference, permitsRothContributions and permitsRothCatchUp are disregarded on a PLESA — with an INFO PENSION_LINKED_EMERGENCY_SAVINGS_CONTRIBUTIONS_ARE_ALWAYS_ROTH saying so — rather than honoured into a pre-tax contribution the statute leaves no capacity for. No accepted input produces a pre-tax contribution to a PLESA. On every other account type, including an ordinary designated Roth 401(k) or 403(b), those fields keep their ordinary effect: §402A(b)(1) offers the designated Roth election in addition to pre-tax deferrals, so there the split is a plan and participant choice.

§402A(f)(1) names three plans that may host one, and which limits apply turns on the host, so the third is a distinct account type:

| Host | Account type | Deferral limit | §415(c) | |---|---|---|---| | §401(a) trust — §402A(f)(1)(A) | pension_linked_emergency_savings | §402(g) | Yes | | §403(b) plan — §402A(f)(1)(B) | pension_linked_emergency_savings | §402(g) | Yes | | Governmental §457(b) — §402A(f)(1)(C) | governmental_457b_pension_linked_emergency_savings | §457(e)(15) | No |

For the first two, model the account inside the plan with the same annualAdditionsGroupId as the plan's other accounts. For the third, use the same section457PlanGroupId as its host §457(b) account, so that one record's §457(b)(3) provision and includible compensation cover both — see One eligible plan, several records. The third shares no §415(c) pool with them: §402(g)(3) enumerates elective deferrals exhaustively and lists no §457(b) deferral, so its contributions run against the §457(e)(15) applicable dollar amount through §457(b)(2)(A); and §415(a)(1)–(2) enumerates the plans the annual-additions limit reaches without naming §457(b), so it joins no annual-additions group at all. One person may hold a PLESA on more than one host in the same year, and the ceilings then stand side by side rather than as one — §402A(e)(3)(A) caps "the portion of the account balance", so each account has its own.

The §402A(e)(3)(A)(i) figure is a cap on a balance, not an annual allowance. The statute bars a contribution "to the extent such contribution would cause the portion of the account balance attributable to participant contributions to exceed" the lesser of that figure and an amount the plan sponsor sets. That portion of the balance carries across years, and §402A(e)(7) — which requires the plan to permit withdrawal at least monthly — moves it back down. So the balance must be supplied; the year alone does not determine what is left:

const result = USTaxAdvantagedParams.calculate({
  taxYear: 2026,
  filingStatus: "S",
  persons: [{ id: "t", compensation: { w2Compensation: 90000 } }],
  accounts: [{
    id: "plesa",
    ownerId: "t",
    type: "pension_linked_emergency_savings",
    employerId: "e",
    planRules: { pensionLinkedEmergencySavingsParticipantContributionBalance: 1000 },
  }],
});
result.accounts[0].statutoryMaximumAnnualContribution; // 1600 — 2600 less the 1000 balance
result.accounts[0].contributionComponents.employeeRothDeferral; // 1600

Because the cap is on a balance, a year's gross contributions may exceed it. A participant who contributed $600, withdrew $400 under §402A(e)(7), and so holds $200 attributable to participant contributions has $2,400 of room left and may reach $3,000 for the year — the Department of Labor's PLESA guidance is explicit that a plan may not impose a separate annual PLESA contribution limit, precisely so the account can be replenished.

| Rule | Treatment | |---|---| | §402A(e)(3)(A)(i) dollar figure | parameters.pensionLinkedEmergencySavingsBalanceCap402A. $2,500 for 2024 and 2025, $2,600 for 2026, $2,700 for 2027 | | §402A(e)(3)(A)(ii) plan sponsor amount | Supplied as planRules.planDocumentEmployeeDeferralLimit; it lowers the contributable amount but not the reported statutory maximum | | Participant-contribution balance | Required. Supplied as planRules.pensionLinkedEmergencySavingsParticipantContributionBalance: the portion of the balance attributable to participant contributions immediately before the proposed allocation — including amounts contributed earlier in the same year that are still in the account, net of withdrawals under the plan's accounting, excluding earnings. Pass 0 for a new account. Omitted — or supplied as an explicit null, which states the absence of the fact in exactly the same way — the account is indeterminate with PENSION_LINKED_EMERGENCY_SAVINGS_PRIOR_BALANCE_REQUIRED (whose "prior" means immediately prior to the allocation, not an opening or prior-year figure) rather than defaulted to an empty account. This differs from the optional §402A(e)(3)(A)(ii) sponsor amount above, where a null means the sponsor set none | | §402(g) and §415(c) | On a §401(a)- or §403(b)-hosted account, base deferrals are consumed like any other elective deferral and annual addition, in the owner's and the employer group's shared pools; a §414(v) catch-up draws the owner's catch-up pool and, per §414(v)(3)(A)(i), not the annual-additions group. A governmental §457(b)-hosted account consumes neither: it draws the owner's §457(e)(15) pool and joins no annual-additions group, whatever annualAdditionsGroupId the caller supplies | | §457(b)(2)(B) includible compensation | Applies to a §457(b)-hosted account, capped at 100 percent of includible compensation like any other deferral under that plan | | §457(b)(3) last-three-years catch-up | Available on a §457(b)-hosted account, within the balance cap, on the same reasoning as §414(v): it raises "the ceiling set forth in paragraph (2)", a limit on deferrals under the plan, while §402A(e)(3)(A) gates the account balance. §457(e)(18) gives the participant the greater of it and the §414(v) catch-up, never their sum, and that choice is made once for the participant across every eligible plan — see Choosing between the two §457 catch-ups. Reported as special457RothCatchUp, since a PLESA contribution is Roth whatever limitation supplied its capacity | | §402A(e)(3)(A) room | An account-local pool, reported in sharedLimits as plesa402Ae3:{accountId}, seeded with the supplied balance and drawn by base deferrals and catch-up alike | | Age-based catch-up | Available, within the balance cap. §402A(e)(3)(A) gates a balance, while §414(v) relieves a plan- or employee-level deferral limit — 26 CFR §1.414(v)-1(b)(1)(i) lists them and none is account-level — so the two compose and both bind. Once the host's §402(g) pool is spent, remaining room may be filled from the §414(v) catch-up; a catch-up is outside §415(c) under §414(v)(3)(A)(i). As elsewhere in this package, capacity follows from age rather than a plan-document election, under the standing assumption that the plan permits and so characterises it. A birth year is required only where a catch-up could reach unfilled room — not where the host's base capacity already covers it, and not on a §457(b) host where the §457(b)(3) catch-up exceeds the largest age-based catch-up the year offers at any age, since §414(v)(6)(C) then removes the age-based one whatever the participant's age. An equal §457(b)(3) amount is not enough: §414(v)(6)(C) speaks of a higher limitation, so the age still decides which route applies. Where the route is unresolved, no catch-up is allocated under either heading — §457(e)(18) chooses between pools that are reported separately, so a figure known to be reachable one way or the other is still not attributable to either | | Employer contributions | Never allocated here. §402A(e)(6)(A) directs any match earned on PLESA contributions to the participant's other account under the plan, and §402A(e)(8)(B) bars transfers in | | 2023 and earlier | unavailable, on every host. Pub. L. 117-328 §127(g) applies §127 to plan years beginning after December 31, 2023 |

The 2024 figure comes from the Code rather than from a notice: Notice 2023-75 does not state one, and the flush text of §402A(e)(3)(A) adjusts the $2,500 only "[i]n the case of contributions made in taxable years beginning after December 31, 2024", leaving the first effective year on the unadjusted statutory amount.

Health savings accounts (IRC §223)

HSA contribution capacity is calculated from caller-supplied coverage facts. Whether a person is an eligible individual under §223(c)(1) — including Medicare entitlement under §223(b)(7) — is an input, not something the engine infers.

| Rule | Treatment | |---|---| | §223(b)(2) monthly limitation | The limit is the sum of the monthly amounts divided by 12, so partial-year eligibility prorates by month of coverage | | §223(b)(3) age-55 additional amount | Per spouse and not shareable; each spouse's catch-up must be contributed to that spouse's own HSA | | §223(b)(5) family coverage | Spouses share a single family limit, divided equally or as agreed. Only the family-months portion is divided; self-only months stay with the individual | | §223(b)(5)(B)(ii) agreed division | One scenario-level taxpayerShare gives the taxpayer that share and the spouse its complement, including when either spouse owns no HSA (see below) | | §223(b)(5)(A) | If either spouse has family coverage, both are treated as having family coverage for those months — whether or not that spouse owns an HSA (see below) | | §223(b)(8) last-month rule | Applied automatically, never elected. An individual eligible on December 1 takes the greater of the month-by-month sum and December's tier for the whole year; where the greater one is the second, the difference carries a 13-month testing-period obligation (see below) | | Testing-period failure | The attributable amount is included in income in the following year and carries a 10% additional tax, unless failure is by death or disability | | Pre-2007 years | §223(b)(2) capped the monthly limitation at 1/12 of the lesser of the plan's annual deductible and the dollar amount, until the Tax Relief and Health Care Act of 2006 §303 removed it | | §106(d) employer contributions | Excluded from income rather than deducted, reducing W-2 box 1 and FICA wages and reducing the §223(b)(4)(B) deduction | | §223(b)(4)(A) Archer MSA reduction | The aggregate amount paid for the year to that individual's Archer MSAs reduces the whole subsection (b) limitation — the §223(b)(3) increase included — but not below zero | | §223(b)(5)(B)(i) Archer MSA reduction | For a married individual to whom §223(b)(5) applies, both spouses' aggregate reduces the single family limitation before §223(b)(5)(B)(ii) divides it, and never touches the §223(b)(3) amount | | §223(b)(4)(C) qualified HSA funding distribution | The amount contributed under §408(d)(9) reduces that individual's own subsection (b) limitation — the §223(b)(3) increase included — but not below zero. It is never withdrawn by the flush text and never taken before the §223(b)(5)(B)(ii) division |

The testing period spans two tax years, so a caller who has not yet resolved it receives an explicit obligation in the result rather than an assumed outcome.

Spousal coverage: persons[].hsaCoverage

§223(b)(5)(A) turns on whether either spouse has family coverage, not on whether either spouse owns a health savings account. A spouse with family HDHP coverage and no HSA of their own still changes the other spouse's limitation, so that coverage is stated on the person:

const result = USTaxAdvantagedParams.forTaxYear(2026)
  .filingStatus(FilingStatus.MARRIED_FILING_JOINTLY)
  .taxpayer("taxpayer", (person) => person.bornIn(1985))
  // The spouse has family HDHP coverage but no HSA of their own.
  .spouse("spouse", (person) => person.bornIn(1986).hsaCoverage("family"))
  .account("taxpayer-hsa", "taxpayer", AccountType.HSA, (account) => {
    account.hsaCoverage("self_only");
  })
  .calculate();

persons[].hsaCoverage takes the same coverage fields as planRules.hsa (coverageTier, eligibleMonths, monthlyCoverage, hdhpAnnualDeductible). Where a person owns an HSA, planRules.hsa already carries these facts; supplying both is allowed but they must be identical, and a contradiction returns HSA_PERSON_AND_ACCOUNT_COVERAGE_FACTS_CONFLICT.

An empty object explicitly states no coverage. The shape { id: "s", hsaCoverage: {} }, or .noHsaCoverage() on the builder — records that the spouse held no high deductible health plan coverage in any month. A nonempty object without a usable tier/month schedule leaves coverage unknown, even if a deductible is supplied.

An accountless spouse's coverage is read like anyone else's. Whose coverage builds the limitation and where the money may be put are separate questions: §223(c)(1) does not mention accounts, and Notice 2008-52 Example 14 takes the §223(b)(8) greater-of on the couple's combined figures. So a spouse who states coverage on persons[].hsaCoverage takes part in that comparison and in the §223(b)(5)(B)(ii) division whether or not they own an HSA. Adding an HSA to a spouse whose coverage facts are unchanged never changes the other spouse's limit.

The hsa223b5 shared pool is narrower, and deliberately: it is a capacity guard for the represented HSA accounts, not a complete calculation of every accountless spouse's personal allowance. An accountless spouse's own capacity reaches no account in the scenario, so it stays out of the guard — except where an Archer aggregate can consume it, since §223(b)(5)(B)(i) subtracts that aggregate once from the family-month union plus undivided self-only portions and it has to come out of the whole household's capacity. A known household residue does not establish which spouse's undivided months absorbed it; those owner limits remain indeterminate. A separately established age-55 amount remains outside that reduction. Where the spouses paid into an Archer MSA and an accountless spouse's coverage statement is nonempty but unusable, the household amount itself is withheld rather than computed as though that spouse had no capacity.

Archer MSA contributions: persons[].archerMsaContributions

§223(b)(4)(A) reduces the §223(b) limitation by "the aggregate amount paid for such taxable year to Archer MSAs of such individual", and §223(b)(5)(B)(i) reduces the single family limitation by "the aggregate amount paid to Archer MSAs of such spouses". Both take an amount paid, not a §220 limitation, so the amount is a caller-supplied fact in the same way eligible-individual status is, and no part of §220 is modelled or checked against it.

const result = USTaxAdvantagedParams.forTaxYear(2026)
  .filingStatus(FilingStatus.SINGLE)
  .taxpayer("taxpayer", (person) => person.bornIn(1986).archerMsaContributions(1200))
  .account("taxpayer-hsa", "taxpayer", AccountType.HSA, (account) => {
    account.hsaCoverage("self_only");
  })
  .calculate();
// 4400 - 1200 = 3200

Because §223(b)(5)(B)(i) reads the couple's aggregate, the amount belongs to the person rather than to an account: a spouse who owns no HSA can still carry one, and it still reduces the limitation the other spouse divides.

The ordering is not cosmetic. The §223(b)(4) flush text says "Subparagraph (A) shall not apply with respect to any individual to whom paragraph (5) applies", so a married individual with family coverage is reduced under §223(b)(5)(B)(i) — before the equal division, not after. Two spouses with a 2026 family limitation of 8750 and 3000 of aggregate Archer contributions get (8750 − 3000) ÷ 2 = 2875 each, not 4375 − 3000 = 1375 each, which would subtract the aggregate twice. §223(b)(5)(B) also operates "without regard to any additional contribution amount under paragraph (3)", so a married individual's age-55 amount survives a reduction that would have consumed it under §223(b)(4)(A).

Each account's hsa detail reports archerMsaContributionsApplied, archerMsaReductionPrecedesFamilyDivision, and archerMsaLimitReduction, and an HSA_ARCHER_MSA_CONTRIBUTIONS_REDUCE_LIMIT diagnostic names the paragraph that applied. For a married couple whose division was never settled, archerMsaLimitReduction is null and the diagnostic states the reduction at couple level instead — see A share nobody established is not a zero.

Qualified HSA funding distributions: persons[].qualifiedHsaFundingDistributions

§223(b)(4)(C) reduces the §223(b) limitation by "the aggregate amount contributed to health savings accounts of such individual for such taxable year under section 408(d)(9)" — a once-in-a-lifetime IRA-to-HSA rollover. Like the Archer amount it is a fact about the person, taken as supplied: the §408(d)(9)(C) once-per-lifetime limitation and the separate §408(d)(9)(D) testing period are not modelled, and the amount is not checked against the IRA it came from.

const result = USTaxAdvantagedParams.forTaxYear(2026)
  .filingStatus(FilingStatus.SINGLE)
  .taxpayer("taxpayer", (person) => person.bornIn(1986).qualifiedHsaFundingDistributions(1500))
  .account("taxpayer-hsa", "taxpayer", AccountType.HSA, (account) => {
    account.hsaCoverage("self_only");
  })
  .calculate();
// 4400 - 1500 = 2900

It behaves the opposite way to the Archer reduction for a married couple, and the flush text is why. "Subparagraph (A) shall not apply with respect to any individual to whom paragraph (5) applies" names subparagraph (A) alone, and §223(b)(5)(B)(i) reduces the family limitation only by the Archer amount, so nothing routes (C) through paragraph (5). It stays an amount of "such individual" reducing the limitation applying to that individual under subsection (b) — which for a married spouse is the share left by the §223(b)(5)(B)(ii) division, after the division rather than before it, plus their own §223(b)(3) amount.

Two spouses with the 2026 family limitation of 8750 divide it to 4375 each. A $2,000 rollover by one spouse leaves 2375 and 4375; the same $2,000 paid to an Archer MSA instead leaves 3375 and 3375, because that reduction comes off the 8750 first. And since (C) is not governed by §223(b)(5)(B)'s "without regard to any additional contribution amount under paragraph (3)", it reaches a married individual's age-55 amount where the Archer reduction cannot.

When both reductions apply, §223(b)(4) reduces by "the sum of" them but not below zero. The fall is attributed in subparagraph order, so archerMsaLimitReduction is reported in full and qualifiedHsaFundingLimitReduction reports only what was left for (C) to reach. Each account's hsa detail reports qualifiedHsaFundingDistributionsApplied and qualifiedHsaFundingLimitReduction, and an HSA_QUALIFIED_HSA_FUNDING_DISTRIBUTION_REDUCES_LIMIT diagnostic states which ordering applied.

The last-month rule is a greater-of, not an election

Breaking change in 0.5.0. §223(b)(8) is applied automatically to anyone eligible in December. There is no input for switching it on, and useLastMonthRule is gone.

§223(b)(8)(A) says an individual who is an eligible individual during the last month of the taxable year "shall be treated" as an eligible individual for each month of that year. Notice 2008-52 states the resulting maximum as the greater of

  1. the sum of the monthly limitations on the facts as they stand, "based on eligibility and HDHP coverage on the first day of each month", plus monthly catch-up amounts; and
  2. the whole annual amount for the coverage tier held on December 1, plus the whole §223(b)(3) amount.

Neither limb is conditioned on a taxpayer's choice: there is no election statement, no Form 8889 checkbox and no revocation, and the Form 8889 instructions simply tell a December-eligible taxpayer whose coverage changed to enter the greater amount on line 3. The instructions' "you may consider yourself an eligible individual for the entire year" is the practical decision to fund the extra capacity — and a taxpayer may always contribute less than a statutory maximum without lowering it.

What follows from actually funding it is the testing period, and that is measured on conduct rather than on any flag. §223(b)(8)(B)(i) reaches only contributions "which could not have been made but for" the rule, which is hsa.amountAttributableToLastMonthRule. Where that figure is zero — because the month-by-month candidate won, or because a spousal division left this owner no more room than their own months gave them — no testing-period obligation is reported at all, and hsa.testingPeriod is null.

Two fields report the outcome, and they answer different questions:

| Field | Question | |---|---| | hsa.fullContributionCandidateSelected | Which candidate was the ceiling built from? True means candidate (2) | | hsa.amountAttributableToLastMonthRule | What was the rule worth to this owner, and so what is exposed if the testing period fails? |

Testing-period facts are stated per person, and only the consequence is stateable:

{ id: "t", hsaLastMonthRuleTestingPeriod: { satisfied: true } }
{ id: "t", hsaLastMonthRuleTestingPeriod: { satisfied: false, failureByDeathOrDisability: true } }

Omitting them leaves the period unresolved, which is reported (HSA_LAST_MONTH_RULE_TESTING_PERIOD_UNRESOLVED, status determinate_with_assumptions) rather than assumed satisfied — but only where the attributable amount is positive. The attributable amount measures this individual's potential recapture exposure. It is zero for an owner established ineligible on December 1, even if the household's full candidate increases their ceiling through the other spouse. That owner receives no testing period, income-inclusion amount, additional tax, or testing-period warning.

Conflicting spouse coverage. A complete coverage statement remains one schedule, including its annual deductible. The engine evaluates each coherent spouse statement through both Notice 2008-52 candidates, the household comparison, monthly eligibility, and the family division. An established owner's result can remain determinate when all completions give identical contribution amounts, shared-limit usage, candidate selection, and testing-period state. HSA_COHERENT_COVERAGE_COMPLETIONS_AGREE records that proof; the spouse's own contradictory statements remain unresolved. Varying nullable audit amounts, such as dividedFamilyContributionLimit, are null.

For example, an under-55 owner with family coverage January–November and self-only coverage in December has a monthly candidate of (11 × 8750 + 4400) / 12 = 8387.50 in 2026. With an agreed whole share, contradictory January-only spouse statements (family versus self-only) cannot make the full-year candidate overtake it. The owner retains 8387.50. A December-only self-only owner remains indeterminate: the same statements give 4400 versus 4762.50.

Partial statements retain the facts they supply: eligibleMonths: [1] without a tier leaves the common self-only/family tier unresolved, not January eligibility. For entirely unknown schedules with all relevant deductible amounts supplied, or after the 2006 deductible-cap repeal, the evaluator traverses every schedule up to permutations of equivalent January–November months, with December separate. It does not sample or truncate the possibilities. Missing continuous deductible facts in capped years remain conservative. A missing spouse person still leaves the Archer operand unestablished. Coverage may be supplied on the person alone; an absent account statement differs from an explicitly unusable account {}.

Reading the division off the result. sharedFamilyContributionLimit is the whole family limitation an owner refigured for their own family months, and Q&A-31 does not divide all of it: a month only one spouse was eligible for goes to that spouse whole. dividedFamilyContributionLimit is the part familyLimitShare actually multiplies, so with no Archer MSA amount in play

proratedContributionLimit - dividedFamilyContributionLimit * (1 - familyLimitShare)

is the owner's §223(b)(1) limitation. A taxpayer family-covered all year beside a spouse eligible in December alone holds 8750 and divides only December's 729.17 of it: 8750 - 729.17 × 0.5 = 8385.42. Multiplying the share by the whole 8750 instead gives 4375, which is wrong by 4010.42. The published figures are rounded to cents while the engine divides the unrounded monthly amounts, so treat the identity as a description of the composition rather than a way to re-derive the ceiling. The divided portion is also null when an Archer MSA reduction leaves family capacity but its placement between shared and sole-eligible months is unresolved. The total family limitation can remain known in that case; exhausting it establishes a divided portion of zero.

A married spouse's own share can fall while the couple's limitation rises. Notice 2008-52 Example 14 compares the couple's combined candidates and divides the winner, and Form 8889 follows that order — line 3 and line 5 before the spousal division on line 6. So where one spouse holds family coverage in December alone and the other is eligible all year with self-only coverage, the couple's combined candidate (2) of 8750 beats their combined candidate (1) of 4762.50, and the equal division gives 4375 each — below the 4397.92 the all-year spouse's own months would have earned undivided. Nothing is wrong there and nothing is diagnosed: the rule raised the couple's limitation, and §223(b)(5)(A) plus the default equal division moved part of it across. Spouses who would rather not move it may agree a different division under §223(b)(5)(B)(ii). The spouse whose share fell has an attributable amount of zero and no testing-period exposure, because none of their ceiling depends on the rule.

The division is one fact about the couple

Breaking change in 0.5.0. Four fields moved off planRules.hsa. An account that still carries one is rejected rather than read, so a stale call fails loudly instead of quietly using half of what it stated:

| Removed from planRules.hsa | Now | Error code if still supplied | |---|---|---| | familyLimitShare | hsaFamilyLimitDivision on the scenario | HSA_ACCOUNT_LEVEL_FAMILY_LIMIT_SHARE_REMOVED | | useLastMonthRule | nowhere — §223(b)(8) is not an election | HSA_ACCOUNT_LEVEL_LAST_MONTH_RULE_REMOVED | | testingPeriodSatisfied | persons[].hsaLastMonthRuleTestingPeriod.satisfied | HSA_ACCOUNT_LEVEL_LAST_MONTH_RULE_REMOVED | | testingPeriodFailureByDeathOrDisability | persons[].hsaLastMonthRuleTestingPeriod.failureByDeathOrDisability | HSA_ACCOUNT_LEVEL_LAST_MONTH_RULE_REMOVED |

The same four are rejected on persons[].hsaCoverage too. That object is the nearest-looking home for a field you have just been told to move off the account, and reading them there would be the worse of the two failures: an ignored familyLimitShare falls back to the §223(b)(5)(B)(ii) statutory equal split, so acting on the error and moving the field one object sideways would hand you half the limitation you asked for, with nothing saying so.

None of the four was ever a fact about an account. §223(b)(5)(B)(ii) divides the limitation between "them" — the married individuals — and §223(b)(8) operates on "an individual". An owner's two HSAs cannot disagree about any of them, and Pub. 969 is explicit that multiple HSAs do not subdivide their owner's maximum: "If you have more than one HSA in 2005, your total contributions to all the HSAs cannot be more than the limits discussed earlier."

useLastMonthRule did not move: it stated a thing the Code does not have. Delete it — the ceiling it used to unlock is now computed from the coverage facts, so removing it changes no answer except where it was wrongly withholding one.

hsaFamilyLimitDivision is one statement, on the scenario:

{ status: "statutory_equal" }                  // the default; omit it for the same effect
{ status: "agreed", taxpayerShare: 0.25 }      // the spouse takes the remaining 0.75
{ status: "unknown" }                          // whether they agreed anything is not known
{ status: "disputed" }                         // the spouses report different divisions
{ status: "inconsistent" }                     // two records of one division conflict

taxpayerShare is the share belonging to the person whose role is taxpayer; the spouse takes 1 - taxpayerShare. Because there is one number rather than one per account, shares can no longer fail to total 1, and the three diagnostics that policed that (HSA_FAMILY_LIMIT_SHARES_EXCEED_ONE, HSA_FAMILY_LIMIT_SHARES_BELOW_ONE, HSA_FAMILY_LIMIT_SHARE_REQUIRED_FOR_BOTH_SPOUSES) are gone with the states they described.

0 and 1 are both valid. Notice 2004-50 Q&A-32: spouses "can divide the annual HSA contribution in any way they want, including allocating nothing to one spouse". The spouse allocated nothing still keeps their own §223(b)(3) age-55 amount — Notice 2008-59 Q&A-22 holds that an individual eligible for the catch-up "may only make such contributions to his or her own HSA", and §223(b)(5)(B) divides the limitation "without regard to any additional contribution amount under paragraph (3)", so a division cannot reach it either way.

Omitting the field means statutory_equal, not unknown. The statute divides equally "unless they agree on a different division", so silence is the default rule rather than a missing fact, and the Instructions for Form 8889 say the same. The three non-numeric statuses exist because failing to establish the agreement is not the same input state as establishing its absence: contradictory records are equally consistent with "they agreed equally and one is wrong" and "they agreed 25/75 and the other is wrong", and defaulting those to 50/50 would overstate one spouse's limitation in the second case. unknown, disputed and inconsistent differ only in the wording of the diagnostic they produce; they are deliberately identical in effect, and should stay that way.

A spouse who owns the only HSA still gets half — unless they are the only eligible one. §223(b)(5)(B)(ii) divides "equally between them", and them is "individuals who are married to each other" from the opening clause of paragraph (5) — a phrase about a marriage, not about a pair of accounts. Owning an HSA is not a condition of being an eligible individual under §223(c)(1), so a spouse with family coverage and no account still holds their half and simply has nowhere to put it. A sole owner therefore takes $4,375 of an $8,750 limitation, reports HSA_SOLE_SPOUSE_ACCOUNT_TAKES_ONLY_ITS_EQUAL_SHARE, and reaches the whole $8,750 only through an agreement:

{ status: "agreed", taxpayerShare: 1 }   // Notice 2004-50 Q&A-32 permits exactly this

The distinction is eligibility, not account ownership. Where the other spouse is stated to have held no HDHP coverage in any month (hsaCoverage: {}), they are not an eligible individual under §223(c)(1), take no share, and the owner gets the whole limitation — Notice 2004-50 Q&A-31: "if only one spouse is an eligible individual, only that spouse may contribute to an HSA (notwithstanding the treatment under section 223(b)(5)(A) of both spouses as having only family coverage)", worked by Example (1) of that Q&A. That case reports HSA_SOLE_ELIGIBLE_SPOUSE_TAKES_WHOLE_FAMILY_LIMIT instead. If the other spouse states nothing, eligibility remains unknown: the owner might receive half or the whole. Where those readings change the answer, the engine reports HSA_FAMILY_LIMIT_DIVISION_INDETERMINATE, familyLimitShare: null, and a null maximum. For an MFJ or MFS family-covered HSA owner, supply both person records. An absent partner does not establish either their eligibility or their Archer MSA amount, so HSA_SPOUSE_COVERAGE_FACTS_REQUIRED withholds the result even with an agreed whole share. That agreement settles the eligibility-dependent division but cannot settle the aggregate reduction in §223(b)(5)(B)(i). On a supplied person record an omitted Archer amount defaults to zero. The reduction precedes division and never consumes the separate age-55 amount. A missing spouse deductible can still matter in 2004–2006, and missing coverage can still change self-only months.

Earlier versions assumed a sole HSA owner had agreed to take everything when no account-level share was supplied, reporting HSA_SOLE_SPOUSE_ACCOUNT_ASSUMED_FULL_FAMILY_LIMIT. The scenario-level contract applies the statutory default when the supplied eligibility and coverage establish it; otherwise the division remains unknown. If you relied on that earlier assumption, state the agreement explicitly.

An unknown division of nothing is still determinate. The division is only ever a fact about something: where the limitation left after the §223(b)(5)(B)(i) Archer reduction is zero, every division yields the same zero monetary maximum, so that maximum remains determinate. The division itself is still unestablished and familyLimitShare remains null. What counts as "nothing" depends on the doubt: a doubtful share divides only the family portion, so an exhausted family residue makes it immaterial even where undivided self-only months survive, while an Archer aggregate whose placement among undivided months is open is immaterial only once the whole paragraph (1) residue is gone. The same principle applies one level down — an eligibility doubt about a spouse whose agreed share is already exactly 0 stands aside, because that spouse gets nothing whether they are an eligible individual or not. Both rules exist because an unknown that cannot change an answer is not worth withholding an answer for.

Two shapes are rejected outright, because each states an agreement and denies it in the same object: { status: "agreed" } with no share raises HSA_FAMILY_LIMIT_DIVISION_SHARE_REQUIRED, and a taxpayerShare beside any other status raises HSA_FAMILY_LIMIT_DIVISION_SHARE_NOT_PERMITTED.

The hsa detail is withheld, never completed

account.hsa is an audit trail of one chosen coverage schedule and one chosen winner of the §223(b)(8) comparison — the months, the monthly amounts applied to them, both limitation figures, the selected candidate and the amount attributable to the rule. Where the input leaves several completions open, there is no such trail, and the whole object is null rather than filled in from whichever statement happened to be read first:

  • an owner's two HSAs, or an HSA and persons[].hsaCoverage, stating different coverage months (or, in a capped year, different annual deductibles);
  • no usable coverage statement at all;
  • a spouse's family coverage neither supplied nor reconcilable, where it could rewrite a month of either schedule;
  • a birth year that would decide which candidate wins, because §223(b)(3) is prorated in one and whole in the other;
  • an unapportionable §223(b)(5)(B)(i) Archer reduction, where which spouse's undivided months absorbed it decides the pre-division amount.

Where the couple's combined candidates are what the greater-of compares, one spouse's open candidate withholds the other's detail too. An unsettled §223(b)(5)(B)(ii) division does not: it leaves both candidates exactly as computable, so every figure describing the owner's own undivided months or the couple's limitation stays. What it does null is the four figures that are this owner's share of the result rather than the result — see below.

A share nobody established is not a zero

familyLimitShare is not the only field an unsettled §223(b)(5)(B)(ii) division reaches. Four more report a fall in, or a slice of, this owner's ceiling, and each of them is that owner's share of a couple-level figure:

| Field | Why the share decides it | |---|---| | archerMsaLimitReduction | §223(b)(5)(B)(i) takes the spouses' aggregate off the one limitation before (B)(ii) divides it, so an owner's own fall is their share of that reduction | | qualifiedHsaFundingLimitReduction | §223(b)(4)(C) reduces the share (B)(ii) left them, so how far their ceiling fell is bounded by it | | amountAttributableToLastMonthRule | §223(b)(8)(B)(i) recaptures what "could not have been made but for subparagraph (A)" — the owner's share of the couple's increase | | testingPeriod | it exists only where that attributable amount is positive |

These four, plus familyLimitShare, are also null where the account's ceiling itself was never established — a plan whose stated deductible contradicts §223(c)(2)(A)(i), say. A fall is the difference between two ceilings, so a $100 Archer MSA contribution against no established limitation took an unknown amount off an unknown amount; 0 would say the paragraph applied and cost nothing. archerMsaContributionsApplied and qualifiedHsaFundingDistributionsApplied still report what was supplied, and 0 is still exact where nothing was supplied — the operand settles that without a ceiling.

Each is null where a share is genuinely in question, not 0. Two spouses whose only coverage is family in December 2026 have a couple's limitation of 8750 against a month-by-month 729.17, so each owner's attributable amount is somewhere between nothing and 8020.83 — and a 0 there would say §223(b)(8)(B)(i) has nothing to recapture from them. testingPeriod is null both where no obligation arises and where none can be computed; amountAttributableToLastMonthRule separates the two, being 0 in the first case and null in the second.

A share is only in question where a month is shared. Spouses eligible in disjoint halves of the year each take their own months whole under Notice 2004-50 Q&A-31, so nothing of theirs is divided and all four figures stay numeric while familyLimitShare is still null. And the immateriality that rescues a maximum does not rescue these: where an Archer reduction exhausts the limitation to a zero every division yields alike, both ceilings end at zero, but how far each spouse fell to get there is still their share, so the maximum stays 0 and archerMsaLimitReduction is null.

null here is not the same as the key being absent, which still means "not an HSA account". The account's status, its null maximum, its shared limits and its diagnostics are all reported as before — only the completion is withheld. The point is order-independence: reversing two contradictory account records must not change any fact the engine reports, and a field-by-field completion beside a diagnostic saying the fact was never established is exactly the shape that lets it.

HSA usage describes feasible attribution

IRC §223 and §4973(g) compare aggregate contributions with the owner's combined limitation. They do not specify whether a contribution consumes base capacity before the age-55 increase. The audit pools therefore report feasible attribution, not a base-first convention. For base B, age-55 increase C, counted owner contributions T, and A = min(T, B + C):

base usage     = [max(0, A - C), min(A, B)]
age-55 usage   = [max(0, A - B), min(A, C)]

usedBeforeAccount and remainingAfterAccount are numbers when their range collapses, and otherwise null beside possibleUsedBeforeAccount and possibleRemainingAfterAccount. usedByAccount follows the same rule; possibleUsedByAccount carries the feasible component attribution of a newly allocated amount. These ranges can be open even with an established familyLimitShare. A settled aggregate allocation does not establish its component attribution.

For example, a 2026 owner with base 4,375, age-55 increase 1,000 and existing contributions 2,000 has base usage [1000, 2000] and age-55 usage [0, 1000]. The owner still has exactly 3,375 of additional capacity. Allocation uses that combined capacity and preserves the family guard, including deterministic assignment of its final cent; it does not add independent pool remainders and lose the correlation between them.

An unknown division is evaluated with one common taxpayer-share variable for both spouses. The family range combines feasible usages under the same division. Missing coverage, unknown age and unresolved Archer placement remain unknown when no feasi