IRS Contribution Limit Lookup (401k/IRA/HSA) mechanism

Model scope

The conditional lookup concept is standard, but the supplied specification needs an explicit schema for coverage type, base versus total limit semantics, account-specific catch-up rules, eligibility, and year-dated table contents. The displayed vectors use exact 2024 IRS table entries and do not require interpolation.

• The lookup structure is appropriate, but limit=table[account_type][year][catch_up_flag] is ambiguous: it does not state whether limit is the base statutory limit or the total including catch-up.
• Account type alone is insufficient for HSA lookup; 2024 HSA limits differ for self-only versus family coverage.
• Catch-up eligibility is not determined solely by age for every account: HSA catch-up begins at age 55, while 401(k) and IRA catch-up generally begin at age 50; plan availability and eligibility constraints also apply.
• FSA has an annual statutory limit but no age-based catch-up, so catch_up_flag must support a not-applicable or zero value.
• The actual year-dated IRS data table is not included in the supplied spec, so the instrument cannot operate offline until the table bundle is provided and versioned.

Units and conventions

• All dollar amounts are annual U.S. federal contribution limits in nominal USD for the specified tax year.
• Age is the taxpayer or participant's age during the tax year; boundary ages are inclusive: 50+ for 401(k)/IRA catch-up and 55+ for HSA catch-up.
• The vectors define annual_limit as the base limit excluding catch-up, catch_up_limit as the additional permitted amount, and total_maximum as their sum.
• The HSA vectors require coverage_type to distinguish self-only from family coverage.
• These are statutory federal limits; an employer plan, eligibility rule, compensation limit, or individual circumstances can impose a lower usable amount.

Inspectable vector

One of 4 source-bound review vectors:

{
  "inputs": {
    "account_type": "401k",
    "tax_year": 2024,
    "age": 49
  },
  "expected_outputs": {
    "annual_limit_usd": 23000,
    "catch_up_limit_usd": 0,
    "total_maximum_usd": 23000
  },
  "reference_data": {
    "account_type": "401k",
    "tax_year": 2024,
    "base_limit_usd": 23000,
    "catch_up_age": 50,
    "catch_up_limit_usd": 7500,
    "source_convention": "IRS 2024 published retirement-plan limits, IRS Notice 2023-75"
  },
  "working": "Age 49 is below the inclusive catch-up threshold of 50, so catch_up_limit = 0. annual_limit = 23,000. total_maximum = 23,000 + 0 = 23,000 USD."
}

Failure boundary

BREAK_CLAIMED · SELF_FLAGGED

An unsupported tax year produces an undefined lookup result, and age-date interpretation can select different catch-up branches unless the convention is explicitly specified.

Other records

Sources and evidence

These pointers bind the page to evidence. They do not grant authority or collapse verification into deployment.

• VERIFIED_LEDGER.json
• evidence-tranche7/tranche7-results.json
• BOUNDARY_HAZARD_CATALOG.json