HSA Contribution Limits, Registry Facts, and the Model on the Roadmap

An HSA projection model does not ship. The HSA contribution and coverage limits do — as sourced rows in the facts registry, ready for any caller to read.

The HSA is the most tax-advantaged account most consumers can access, and one of the least modeled in general retirement planning tools. A projection model that treats the HSA as a retirement account — contributing to it, investing it, and withdrawing from it for medical costs pre-65 and any purpose post-65 — is a real and useful piece of software. Worthune does not ship it today. What Worthune does ship, as of TY2026, is a set of HSA-related constants in the public facts registry, ready for any caller to compose into their own model.

What is in the registry today

The facts registry at /facts contains the TY2026 HSA family and self-only contribution limits, the catch-up contribution amount for accountholders age 55 and over, the HDHP minimum deductible and maximum out-of-pocket thresholds that qualify a plan as HSA-compatible, and the IRS source citation for each. Every row includes the value, the source URL (IRS Rev. Proc. 2025-19, the annual §223 HSA revenue procedure^[1]), the revision date, and a stable slug that a caller can reference in code.

The registry is meant to be read. A caller building an HSA capacity check today can query the registry and produce a correct contribution limit response without a Worthune model, because the constants are all that is needed for the contribution-capacity question. The registry updates each tax year when the IRS publishes new figures; callers pin to a specific tax year or read live, at their choice.

Why a full HSA model does not ship yet

A defensible HSA projection model has to model several interactions that the current catalog does not compose cleanly. Investment growth on the portion of the HSA that is invested (versus the portion held in cash for near-term medical use) is a bimodal projection. Medical-cost inflation runs at a different rate than general inflation and varies by category (Rx, hospital, long-term care). Post-65, the HSA changes character — non-medical withdrawals become taxable but not penalized, which changes its effective tax treatment relative to a traditional IRA. Each of these is tractable individually; a general HSA-projection spec that treats them all cleanly is a design problem the roadmap notes but does not commit to a date on.

The pattern is deliberate. A spec that under-models an important interaction is worse than no spec at all, because callers who trust the model take on the interaction as their problem without knowing they have. The alternative — publishing the constants in the registry and gating the model — lets callers who need only the arithmetic proceed today, while callers who need the projection know exactly what to wait for.

How to cite the registry facts

A caller reading the registry for the TY2026 family contribution limit sees a row with the value, the source URL (a live IRS revenue procedure), and the revision date. The recommended citation format in caller-facing UI is to display the value with a small link to the source, in the form the /facts page itself uses. This preserves the discipline that every displayed constant resolves to a primary document, and it lets a user or a compliance reviewer verify currency without leaving the caller's UI.

“The registry is a model in miniature: named constants, sourced values, dated revisions. It is what to use when a full projection model is not yet what to reach for.”

The response shape when the projection model ships

When the HSA-projection model ships, the response envelope will follow the standard Worthune shape: projected balance at retirement age, projected retirement-eligible portion, tax-adjusted equivalent, spec version, assumptions array, facts array (which will always include the TY-year contribution limit and the HDHP thresholds), and a record.sha256 over model, spec version, inputs, and outputs. Callers can build a UI today against the constants and swap in the model when the spec is available, without changing the field names on the display.

What a caller can build today, with only the registry

A defensible HSA capacity check is a five-line integration against the facts registry. Read the TY2026 family or self-only contribution limit; read the catch-up amount if the user is 55 or over; sum the caller-supplied prior-year contributions; return the remaining capacity and a citation to the registry rows used. The response can display the value with a link to the IRS revenue procedure, which is the citation format the /facts page itself uses. This is enough for a contribution-tracking UI, a benefits-enrollment tool, or a payroll-side eligibility check to be complete against current law, without any Worthune model call at all.

The projection question the registry cannot answer

What the registry cannot do is project. A user who wants to know whether contributing the family maximum to an HSA for the next twenty years will leave them meaningfully better off than contributing the same amount to a taxable brokerage account is asking a model question, not a constant question. The projection depends on investment growth, the invested-versus-cash split, the timing and magnitude of medical withdrawals, and the tax treatment of any non-medical withdrawals post-65. Each is a real input; encoding all of them cleanly is the design problem the roadmap notes but does not commit to a date on. Until that model ships, the caller layer answers projection questions with adjacent models — general compound-growth math, the shipped retirement models — and discloses the composition it used.

Why the registry-first pattern is not a compromise

There is a temptation to treat a registry-only implementation as a placeholder for a real model. It is not. The registry is a first-class artifact of the verified-computation approach; it is the answer to a class of questions that do not need a model, because the answer is a constant with a source. Every properly maintained financial UI in the country reads constants like these from somewhere; the difference is whether the somewhere is a versioned, sourced, dated public registry or a hard-coded value in a codebase whose original author no longer works at the firm. Callers who integrate the registry rather than duplicate the constants inherit the maintenance calendar Worthune runs — which is the actual work of financial calculator maintenance and always has been.

The post-65 rule the future projection model will encode

After age 65, HSA withdrawals for non-medical purposes are treated as ordinary income — taxable but no longer subject to the twenty-percent penalty that applies before age 65. This gives the HSA the same tax treatment as a traditional IRA for non-medical withdrawals in retirement, plus the advantage of tax-free medical withdrawals for qualified medical expenses.^[2] The future projection model will encode this rule; today, a caller building a UI around post-65 HSA use can present it in prose and cite the IRC section directly. The registry does not contain the rule because the rule is a treatment, not a value — the kind of thing a model encodes, not a constant a registry stores.