Source: https://guthlabs.ai/docs/instruments/irs-contribution-limit-lookup-401k-ira-hsa/mechanism/

instrument mechanism / verified-clean

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

The inspectable method record for IRS Contribution Limit Lookup (401k/IRA/HSA), kept separate from implementation and qualification.

Status: **VERIFIED_CLEAN**Lifecycle: **verified-clean**

## 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

[01**Overview**](<https://guthlabs.ai/docs/instruments/irs-contribution-limit-lookup-401k-ira-hsa/>)[03**Implementation**](<https://guthlabs.ai/docs/instruments/irs-contribution-limit-lookup-401k-ira-hsa/implementation/>)[04**Qualification**](<https://guthlabs.ai/docs/instruments/irs-contribution-limit-lookup-401k-ira-hsa/qualification/>)

## 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`