Trust & data provenance

"Show me your model" → here's the IRS PDF and the exact row. Every kept-current number we return traces to a frozen, checksummed primary source.

Financial-planning answers are only as trustworthy as the tables behind them. Most APIs ask you to take the numbers on faith. We commit the source — so any value can be re-verified, forever, even after a government URL moves.

How we show our work

For every year-keyed table (tax brackets, IRMAA, contribution limits, RMD factors, Social Security figures, …), three things live in the repository next to the engine:

• The primary source file — the government PDF/HTML the table came from.
• A MANIFEST.md — dataset, source URL, publisher, effective year, page/section, and a SHA-256 checksum.
• A diffable extract — just the values used, so the annual update is a clean diff and tests compare it against the in-code table.

A number enters a table only after it's confirmed against a committed primary source (US federal works — IRS, CFR, Federal Register, SSA, HHS — are public domain). If a source ever disagrees with the code, that's a finding to surface — never a silent edit.

Sources behind the numbers

A sample of what's committed under data/sources/ (checksums abbreviated; full SHA-256 in each MANIFEST.md):

Plus more under data/sources/: healthcare/ACA, IRA eligibility, state brackets, mortality, and Social Security benefit taxation — each with the same source + manifest + checksum.

Determinism is part of the trust story

Sourced data answers "where did the numbers come from?". Determinism answers "will I get the same answer twice?" — yes. Same inputs and seed produce the same result and the same result_id, byte for byte, so a result is reproducible and auditable long after it was computed. See determinism & result_id.

Plain-English explainers

RMD — Required Minimum Distribution

Once you reach your required beginning age (73 for those born 1951–1959), the IRS makes you withdraw a minimum each year from tax-deferred accounts: prior-year-end balance ÷ a distribution-period factor from the Uniform Lifetime Table. Miss it and the penalty is steep. Source: 26 CFR §1.401(a)(9)-9.

IRMAA — the Medicare income surcharge

Higher earners pay an Income-Related Monthly Adjustment Amount on top of standard Medicare Part B and D premiums, based on MAGI from two years prior. It's a cliff: one dollar over a threshold triggers the full tier surcharge — which is why planning around the brackets matters. Source: CMS Part B premium notices (Federal Register) and SSA POMS HI 01101.020.

Sequence-of-returns risk

In retirement, the order of returns matters as much as the average. A few bad years early — while you're withdrawing — can permanently impair a portfolio even if the long-run average is fine. A single average-return projection hides this; a Monte Carlo simulation surfaces it as a distribution of outcomes (see the retirement readiness guide).

Security & compliance

• SOC 2: we're building toward it. The provenance standard above and the deterministic, reproducible engine are exactly the processing-integrity evidence a SOC 2 audit asks for.
• Informational, not advice: every response carries a disclaimer. Numeratica returns calculation-engine output — not financial, tax, or investment advice. See the advice boundary.
• Report a vulnerability: privately to security@numeratica.com (see SECURITY.md). Please don't open public issues for security bugs.
• Live status: api.numeratica.com/readyz. Terms of Service and a Privacy Policy are in progress.

Next

• Core concepts — determinism, seeds, errors, versioning.
• Guides — runnable recipes with rendered outputs.
• API Reference — every endpoint, from the spec.