Where Haven explains its math

Every number Haven shows traces back to a formula, a tax bracket, or a published source. If you ever want to know exactly how a calculation works — what bracket Haven used, what the OAS clawback formula looks like, where currency rates come from — the place to go is the Methodology page.

You can find it at /app/methodology. It lives behind the same login as the rest of the app and is organized into six sections. Each topic on the page expands to show the source citation, the actual formula where one applies, the tolerance band Haven targets, and a link to the engine module that implements it.

What's in each section

Taxes — Canada. Federal and provincial brackets (BC, Ontario, and more), capital gains inclusion, dividend gross-up, CPP claiming adjustments, OAS clawback, RRIF mandatory minimums, and RRSP / TFSA / FHSA contribution room.

Taxes — United States. Federal ordinary brackets, qualified dividends and long-term capital gains, NIIT, IRMAA, RMDs, Social Security claiming and benefit taxation, Roth conversions, 72(t) SEPP, ACA premium tax credit, and stepped-up basis at death.

Cross-border & Strategy. The math that applies on both sides of the border — Monte Carlo simulation, Guyton-Klinger withdrawal rules, the bond glide path, inflation and year alignment, and charitable carryforward.

Currency Conversion. How Haven sources rates from the European Central Bank (via frankfurter.dev), how long they're cached, and the fallback chain when the live API is unreachable.

Cashflow — Safe-to-Spend. The three Cashflow modes — Strict, Balanced (recommended), and Flexible — with the exact formula for each.

Projections & Plan Engine. The orchestrator that composes every tax, benefit, and asset surface into the year-by-year plan output, plus real-asset appreciation.

Deep links

Every section has its own anchor, so you can link straight to it. For example, the cashflow section jumps you directly to the three Safe-to-Spend formulas. The same pattern works for #taxes-ca, #taxes-us, #cross-border, #currency, and #projections.

When to send yourself there

• You doubt a number on the dashboard and want to see where it came from.
• You want to cite a calculation when you're making a real financial decision.
• You're curious why a Monte Carlo run lands in a particular band — the tolerance and source for the model are both there.
• You're explaining a Haven number to your accountant or advisor and want a paper trail.

The Methodology page isn't a marketing page. It's the engineering source of truth, written in plain English with the formulas and citations attached. If you can't find what you're looking for there, that's a bug worth telling us about.