Anatomy of a Facts Registry Row

Every constant a Worthune model consumes lives in one public registry, and every row answers the same four questions: what is the value, when does it apply, who says so, and when did a human last check.

A financial model is only as current as its constants, and constants have a failure mode code review cannot catch: a number that was right when it was typed and wrong by the time it was read. Worthune's answer is a registry — one file of sourced, dated, versioned constants that the engine imports and the public can read at /facts and at /api/v1/facts. The public registry page states the contract plainly: this is the registry our engine imports — we publish what we run. This piece walks the anatomy of a row, because the fields are where the trust lives.

The nine published fields

Three of the nine deserve a closer look. The id encodes the year where the value is year-bound — irs.401k.elective-deferral.2026 can never silently become the 2027 value, because the 2027 value is a different row. The period distinguishes tax years from calendar years from statutory permanence: the HSA rows say "TY2026 (calendar year)," the NIIT rows say "2013+ (IRC §1411, permanent)," and the HSA catch-up says "statutory (IRC §223(b)(3), not indexed)" — three different kinds of time, named instead of implied. And status is the registry's honesty mechanism: verified means confirmed against the cited primary source, repo-asserted means pending human re-confirmation, and historical means superseded but kept for the record — because a registry that deletes its past cannot explain an answer computed under it. (A fourth status, stale-in-use, exists for the case the registry was built to catch — a past-period value still running in production; today it is empty.)

Who actually reads the rows

The registry is not documentation that hopes to match the code — the code imports it. The RMD model's divisors come from the Uniform Lifetime Table rows. The capital-gains model reads the 0 percent and 15 percent thresholds and the net-investment-income-tax rate. The employer-match model reads the elective-deferral and compensation limits. The SBA loan-cost model reads the statutory guaranty percentages and the FY2026 fee tiers. In the source file, each row also carries a usedBy field naming its consumers — an internal tenth field the JSON API strips — which means the registry can answer the reverse question too: change this constant, and here is everything that moves.

That wiring surfaces in the API. When a model that consumes registry constants returns an answer, its response envelope carries a facts array — the id, label, value, period, and source name of each constant the computation used. The user-facing calculator, the API caller, and the auditor reading a stored envelope all see the same citation, because there is only one registry to cite.

• ✓Read a row before trusting a number — the id, period, and source are the claim.
• ✓Treat verifiedOn as freshness, not correctness — the source is the authority, the date is the audit.
• ✓Never copy a value out of the registry into code — reference the row, or you have rebuilt the problem the registry solves.
• ✓Use the API at /api/v1/facts for programmatic access — same rows, same fields, machine-readable.
• ✓Expect historical rows — they are the registry keeping its receipts.

What a registry deliberately is not

The registry holds government-defined constants: IRS limits and brackets, SSA claiming factors, statutory rates, SBA fee schedules. It is scoped to US-federal rules, and the jurisdiction field says so on every row rather than leaving the scope to inference. It does not hold market data, rate forecasts, or anything that changes by the hour — constants of that kind belong to a different discipline with different freshness mechanics. A registry earns trust by being narrow enough that every row can carry a primary source and a verification date; the narrowness is the design.

The quiet argument

Most calculator bugs that matter are not arithmetic bugs; they are constants that aged. A registry with ids, periods, sources, verification dates, and an honest status field converts that entire failure class from silent to visible. The number is no longer an assertion in code — it is a claim with a citation, checkable by anyone, consumed by the engine, and echoed in every answer it touches.