The planner is a single HTML page. Everything it needs, its code, styles, tax tables, market history and lessons, is inside that one file. It makes no network requests: a household's numbers are entered, simulated and stored in the browser that has the page open, and they leave it only as a file the person chooses to download.
The page is assembled from about source parts by a small Python script, build.py, and tested by test suites before each version is published. Each version adds a section to the developer notes, HACKING.md, and a test of its own.
The same source also makes a website, with dist.py (versions 382 to 384): the page split into files named by their contents (assets/style-…css, engine-…js, data-…js, app-…js) that browsers may keep for good, a service worker so the planner opens without a connection, a web app manifest and icons so it can be installed, welcome, privacy and terms pages, a sitemap, and a one-file copy beside them. The website still sends nothing anywhere: its pages load only their own files.
There is no bundler and no package to install. build.py reads every folder under src/ in sorted order and joins the files; a file's three-digit prefix alone decides where it goes, and numbers go up in tens to leave room. Nothing is named in the script, so adding a file never means editing it.
head.html, then one <style> block: app.css and every file in css/.shell.html (top bar, sidebar and an empty navigation that the tab registry fills), one file per tab in views/, then the dialogs.engine/*.js, as plain functions that the node tests can also load.BUILD_ID (a hash of every source file), the data tables, and the app modules in app/, wrapped in one closure that 000-prelude.js opens and 260-start.js closes.Data files become variables: data/NAME.json becomes var NAME, and data/NAME.csv becomes the string NAME_DATA, parsed at start-up. The same run writes two test pages beside the published one: view.html starts from a simple example plan, view-sample.html from the sample household.
A first visit shows the sample household's result at once, without waiting for the simulation. precomp.js opens the built page in headless Chromium, lets it run the sample at full size, and stores the result in data/precomp.json under a key made of the version, the BUILD_ID, the calendar year, the number of futures and a hash of the plan. The page uses it only when that key matches its own.
Order matters: build, run precomp.js, build again. A stale file does no harm; the page simply runs the simulation.
The runtime diagram groups the code by what it does. Each module is one file; the tables below list the main ones. The whole app shares one scope, so a module can use any function defined in another.
| Part | What it does | Files |
|---|---|---|
| The plan | One object, cfg, built from defaults and the saved copy, every field cleaned on the way in. Saved on each change, with 40 steps of undo. | 000-prelude, 060-inherit-data, 150-rail |
| Plans and backups | Up to 20 named plans; a plan file in JSON; a whole-browser backup with a fingerprint, optionally encrypted (PBKDF2 and AES-GCM through Web Crypto). | 234-mod-plans, 249-mod-settings, 249-mod-sec |
| CSV | Account balances in; the whole plan, the results and progress snapshots in and out. Cells are guarded against spreadsheet formulas. | 030-csvimp, 235-mod-import, 246-mod-datacsv, 110-downloads |
| Reference tables | Yearly tax and benefit figures, state rules, life tables, market history since 1871 and more. Each can be replaced on the Actual Data tab. | 006-data, 253-mod-data, engine 005-datayr |
One registry, TABS in 005-tabs.js, lists every tab with its group, icon, search words and what runs when it opens. The navigation, keyboard order and search are all built from it. A view (Easy, Client, Enterprise, Planner or Learn) decides which tabs show and how much is said. The page opens in Easy, which runs every plan on the market's history with the guardrails and flat spending and keeps the plan's own choices for the other views; the others never change the plan or its result.
| Group | Tabs |
|---|
The engine lives apart in src/engine: plain functions with no page code, so the node tests load them directly. Most of the model is in 010-engine.js.
| Piece | How it works |
|---|---|
| Timeline | timeline(c): the working years, then up to 60 years of retirement, capped at age 120. |
| Markets | makeShocks draws correlated yearly shocks for stocks, bonds and cash from a seeded generator, so the same plan always gives the same answer. One year in about seven is turbulent (fat tails), with the overall volatility unchanged. Returns are lognormal with the mean and spread entered. Historical cycles since 1871 and five named crashes can replace the random futures. |
| Inflation and mix | Steady, high for a stretch, or history replayed. The stock share can follow a glide path, rising, falling or a bond tent. |
| Spending rules | Fourteen, from fixed spending (with an optional skipped raise after a losing year) to Guyton-Klinger guardrails (the default), risk-based guardrails, Vanguard's dynamic rule, variable percentage withdrawal, TIPS amortization (ARVA), Kitces' ratchet and the RMD method. |
| Two models | simulate runs one portfolio. makeTaxSim runs the accounts as four tax pools (each person's pre-tax money, Roth and HSA, taxable), in a withdrawal order, and returns a job the page runs in slices, or splits over Web Workers: raw() and merge() carry each future's figures from a worker's range into the page's run (version 372). |
| A tax year | yearTax: federal brackets and deductions, capital-gains rates, each state's rules, the 3.8% investment tax, Social Security taxation, required distributions, the early-withdrawal penalty, Medicare surcharges with their two-year look-back, the marketplace subsidy, payroll tax and Roth conversions. |
| Three futures | repPicks ranks every future (those that run out first by the year they do, then by what is left) and returns the 5th, 10th, 15th, 50th, 85th, 90th and 95th, year by year and by kind of account, for the Plan tab. pickShocks takes futures out of the full set so they can be run again alone, exactly as before; lastingScale uses that to find the spending that would carry one to the end, and repDetail to keep each retirement year of the futures shown in detail: taxes by kind, the tax on the next $1,000 of income, and health costs with the Medicare surcharge tier and the marketplace line, for the tax and health care dashboards. Each future also carries what it can spend a year (sp), for the spending card. |
| Everything else | Social Security with spousal and survivor benefits and the earnings test; pensions, annuities, a TIPS ladder, rental and home sales; debts; 529 plans; inheritances; long-term care events; dependents. |
The engine's other modules are small and focused: the Tools calculators (020-calc.js), Medicare, state rules, life tables, Social Security from an earnings record, insurance needs, debt, student aid and credits.
A run reduces each year of every future to five percentiles and adds the chance the money runs out, how often spending hits its floor or ceiling, the balance at the end and a read on the futures that fail. render draws the Plan tab from it, including three single futures side by side (102-mod-futures.js) and the chance of lasting year by year as bars in the same style, with its details beside In Plain Words on a wide screen (107-mod-lasting.js, versions 402 and 403); the result is kept under a key of the plan and the build, so reopening the page shows it again without a run.
| Part | What it does | Files |
|---|---|---|
| Insights, Cash Flow | Read the result, and re-run the plan on the same futures for withdrawal detail, what moves the result most, and the early years. | 210-insights-tab, 220-bridge, 236-mod-sens, 240-mod-flow |
| Tools | 231-mod-tools2a, 232-mod-*, 233-mod-tools2b | |
| Reports | A PDF writer written for the planner (no library, vector charts), branded client reports, meeting packs, Current vs Proposed, Spanish client reports, CSV and a calendar file of key dates. | 120-pdf, 241-mod-rep, 251-mod-reports, 252-mod-cvp, 249-mod-dates |
| Lessons | 248-mod-learn, 248-mod-learnpdf, lessons_src.py | |
| Planner Guide | The user guide's stories, copied from the published guide into data/guide.json by docs/guide2app.js, in every view; each tab or tool a story names opens from it (version 335). | 249-mod-uguide, guide.json |
| Finding Your Way | Home, the plan at a glance when you come back, first under Results and with a picture on each tile (versions 404 and 405); Start Here, which narrows the menu and the tools to one goal; pinned and recent tools; a search that also runs actions, explains about fifty terms and finds close matches; the way back from a tool (versions 369 to 376). | 211-mod-home, 259-mod-nav, 249-mod-gloss, 250-search |
| Month by Month | Envelopes and sinking funds from the budget; bills with a calendar, the cash they leave and a calendar file; bank files (CSV and OFX) with rules, repeats left out and recurring payments found; the path of the money in the futures that last (versions 377 to 380). | 202-mod-envelope, 202-mod-bills, 207-mod-bankx, 207-mod-progviz, 107-mod-lasting |
| Easy View | A calmer first screen with one next step, the menu and first screen in Spanish (machine-translated), a reminder to back up, and installing the planner as an app (versions 373 to 386). | 258-mod-ezcalm, 249-mod-esui, 249-mod-bknag, 249-mod-pwa |
| Sharing | A read-only copy of the Plan Summary to send (version 387). | 112-mod-share |
| Accounts and Net Worth | Outside Easy, Your Accounts in foldable groups by what each account is for, with a drawn picture for each kind; then what else is owned and what is owed, below zero, each row read from where it is entered (the Liabilities, Insights, Income and Statements tabs) and changed in place or there; Net Worth Today with the balance sheet's totals, and Net Worth Over Time from the Progress tab's snapshots (versions 393 to 396). | 153-mod-acgrp, 154-mod-acicons, 155-mod-acnet, 156-mod-nwhist |
| Budget, Accounts and Social Security | Pets in the budget: a dog's or a cat's yearly costs (ASPCA) as lines that end when it reaches the typical lifespan of its kind (version 406). Treasury notes in a bonds account, each with its term, dates, amount and rate, pasted the way TreasuryDirect lists them, with a ladder of the years they come due; card cash back and a crypto wallet as kinds of account (version 407). A Social Security benefit that starts from a statement and grows with the covered pay the plan still has, and jobs outside Social Security (version 408). | 046-pets-data, 203-mod-pets, 010-tsy-data, 157-mod-tsy, 095-ssearn |
| Spending Lines, Tables and Rules | The spending card's draggable lines are three: the first year, the floor and a ceiling. They cannot cross: the floor runs up to the first year, the ceiling down to it. Each has its own handle, side by side; where lines meet, a press on the shared line waits for the first move, and up takes the ceiling, then the first year, then the floor, whichever can still go that way. A switch puts the first year's health care on top of each line, the setting moving by the line less its data-off (version 410). A column's title sits on the side its figures do, checked on every table of every tab and tool (version 411). Compare the Spending Rules runs every rule in the model field's list on the plan and the same futures, one after another, and shows them in one table with Use and Save on each row; it is kept while the plan stays the same but for its rule (version 412). | 104-mod-dash, 105-mod-spend, 190-thalign, 131-mod-rules |
| Floors Over the Years | On the spending card the middle future is a little wider than the other two (version 413). Made larger, it sets up to four floors, the plan's and three more, each from its year until the next (cfg.floorSteps). Both engines take the floor in force each year (floorByYear): the rules stop their cuts at it, the ceiling is never under it, and a floor above the spending raises the spending to it in its years. Without later floors the engines run as before. The floor line is drawn in stretches, each a slider (version 414). | 106-mod-floors, 105-mod-spend, 104-mod-dash, 010-engine |
| What If | On the Scenarios tab, fifteen turns of life in three groups, each with its own numbers and published defaults named on its tile: a layoff, a child, a new car, a health care bill, retiring earlier, helping family, a home repair, long-term care, a partner's death, living longer, a crash, lower returns, higher inflation, a Social Security cut, a smaller or later inheritance. Each is a change to a copy of the plan (WI[k].apply), run on the plan's futures beside the plan; it can be saved as a scenario. A cost in a working year goes into cfg.saveAdj (versions 416 and 417). | 132-mod-whatif, 133-mod-whatif2, 010-engine |
| The Plan in One Picture | Version 451: one future followed age by age, in two charts on one age scale: the portfolio as a line, and under it each retirement year’s costs (spending, health care, other costs and taxes) stacked by what pays for them: pensions, each person’s Social Security, pay, other income and the portfolio for the rest. The middle future or the portfolio card’s hard or strong one, from the three run again in detail; the Retire line dragged or moved with the keys sets the retirement year. On the Plan tab in Enterprise and Planner and in the Client view’s Plan Summary. | |
| Share This Plan Button | Version 450: a button at the foot of the menu, under Start a Blank Plan, opens one window, Share This Plan, with Share by Link, Copy for Your AI and Open a Plan Someone Sent. It shows in Easy, Enterprise, Planner and Client (without the start-over buttons there), not in Learn. The menu’s tightest rows now apply up to 895 pixels (800 before), so the whole menu still fits every window 768 to 940 pixels high; above that its rows stay 24 pixels or more (WCAG 2.5.8). | |
| Loading Cover | Version 449: the page no longer flashes the Enterprise layout before the saved view. The first thing drawn is a cover in the top bar’s purple with the mark and “Loading the planner”; the saved view is set before anything is drawn, and the cover fades once the first tab is laid out (at once with reduced motion), lifting by itself after eight seconds if the code stopped short. | |
| If Work Stopped | Version 447: a card on the Expenses tab runs the plan’s budget, accounts and income month by month as if a paycheck stopped, through the Between Jobs engine, which now takes the money in the order that keeps the 10% penalty away longest: cash, taxable accounts and Roth contributions, then a 457(b), a 401(k) under the rule of 55, 72(t) payments and everything after 59½, then the penalty, Roth growth last. Side income, a partner’s pay, a severance and health insurance count; a second run has a bad first year. On request the whole plan runs again with the What If tool’s layoff to show the chance of running out before and after. | |
| Landing Page | Version 446: the website opens on a landing page (index.html, built by site_landing.py) and the planner is planner.html. The page says what the planner does, how a plan stays in the browser and is shared, lists guides and videos (landing-links.json: a YouTube link with a picture kept on the site, nothing loaded from YouTube) and links the Discord. Its figures are read from the source at build time. One inline script, named in the security policy by its hash, passes old share links, tab links and the installed app on to planner.html; #lessons opens the Learn view. | |
| Locked Links | Version 445: a locked share link names the rounds that locked it. The first byte 1 means 600,000 rounds, fixed, as versions 439 to 444 wrote it and as is still written while the setting stays there; 2 means the rounds follow in four bytes and are part of the additional data. The head is checked before the passphrase is asked for: rounds outside 100,000 to 5,000,000 are a damaged link, a later first byte a newer version’s. Raising the rounds later no longer turns older locked links into a wrong passphrase. | |
| Merged Cards | Version 444: cards that showed the same thing twice are one card with views. Taxes Over the Retirement Years takes in Taxes and Penalties Each Year (Three Futures and All Futures, the typical year as a line); Year by Year on the Cash Flow tab takes in One Future, Year by Year (Typical and seven futures, Table or Chart); Net Worth Over Time on Progress (By Kind, Against the Plan); Fees on Plan Settings (the funds, the advisory fee and its cost); Spending by Year on Expenses; the Debt Calculator’s two what-ifs; the life spans on People. A moved card leaves one that opens it (151-mod-ptr.js: data-tab with data-card and data-then), and Insights keeps short summaries that link to the full cards. | |
| Samples and Badges | Version 442: thirteen sample households (059-samples.js), eight of them new: a widow at 74, new retirees, a single worker at 59 with little saved, an unmarried couple, a sandwich-generation couple, a self-employed electrician, a couple retiring at 42 and a family with a disabled son, each a plan with its published figures linked in SMP_SRC. Every sample has a stage, tags and a line of what it shows; the Settings tab groups them by age, filters them by tag (smpFilter) and reads each card’s ages, state, pay and savings from its own plan (smpFacts). License badges (249-mod-lic.js) now cover 60 tools (TOOL_LIC) and the tab cards that do licensed work (CARD_LIC, put first in the card by licCard), the Retirement Analysis heading (HEAD_LIC) and the Strategy tab’s decisions (GD_LIC). | |
| Blocks of History | Version 440: a fourth way to draw the markets. Each future strings together runs of ten years (1 to 20) from the record since 1871, as standard draws the engine turns into returns at the plan's own averages and swings (blockShocks); Treasury bills from 1928 to 2023 for cash in the historical cycles when the plan asks (c.histCash). | |
| Share and AI | Version 439: the Social Security statement file (XML) read into Social Security From Earnings; the plan as Markdown and JSON for an AI assistant, names left out by default; a link with the plan inside it after #share=, compressed, sealed with AES-GCM when a passphrase is set, opened as a copy that saves nothing. | |
| Quick Start | Version 438: five questions in a dialog (household, retirement age and state, savings, spending, Social Security from the statement or from pay) make a plan from the blank one, with one pre-tax account, the guardrails and health care as the samples have it; a card on the Plan tab lists what was assumed until it is hidden (cfg.quick). | |
| Retirement Paycheck | Version 437: the first retired year's spending a month, with the portfolio values that would cut or raise it (the middle future's sweep, shared with the Withdrawals tab), a one-time cost against them, and across every future the share that cuts more than 10% and 25%, the deepest cut, years below the plan, goal completion and spending too little (cutStats in both engines); on Easy's first screen and on Home. | |
| Other Assumptions | Version 436: beside the headline, the plan run again on the 2026 forecasts, on the other way of drawing markets and with Social Security at 78% from 2033 (108-mod-other.js: lean runs, 2,000 simulated futures with the plan on the same ones, started when the card is in view); health costs 1.5 points faster than prices by default; the care tools on 2025 costs; the TIPS curve of 2 October 2026; SHA256SUMS.txt in the website package. | |
| Find Realistic Spending | Version 435: a button on What You Could Spend Each Year that sets the first year, the floor (the essentials) and the ceiling (110%, 125% or 150%) as high as the limits allow: on history at most 4% run out and the worst 5% keep the larger of $100,000 and 5% of the money invested today; on Monte Carlo at most 15% run out (spfRun, spfFirst, spfEval on the plan's own futures, 2,000 of them for the search when there are more, then checked on all). | |
| Between Jobs | Version 434: a tool, month by month from next month, for how long the cash lasts after a layoff, what the 401(k) and IRA add and cost taken early (the 10% with the $1,000 exception, the federal tax on top of benefits and new pay), what buys time and tax timing (rwRun, rwSteps, rwLow); Kimberly, a single parent between jobs, as a fifth sample; pre-tax money a working year's cost takes out grossed up for its tax and the 10% (OUTR in makeTaxSim); the Monthly Money Check counts money the plan takes from savings. | |
| Withdrawals Preview | Version 433: the Withdrawals tab's first card for any year of the median, worst-10% or best-10% future (wdNextPaint, a detail per future kept until the plan changes); the spending rule chosen on its card there; the sample on historical cycles with Guyton-Klinger at a 2% failure rate, with a German pension taxed like Social Security. | |
| Inflation by Future | Version 432: inflation that varies from one future to the next (inflPaths: a persistent surprise correlated with the year's returns, or a cycle's own CPI), scaling only what is fixed in dollars per future in simulate and runPath; the retirement month and an income's first and last month (incSpan's s and e, incShare); life insurance as an Expenses row whose benefit reaches the survivor through inheritModel (lifeCover); and a credit shelter trust against portability, with lifetime gifts, in the Estate and Heirs tool. | |
| Months, Local Tax, Harvest | Version 431: Social Security claimed by the month (ssFactor in months, the claim year paid from the claim month); the claiming tool weighted by the life table (one run per death age, ssExp); a local income tax at a flat rate on income or pay (_loc, counted as state tax); gains harvested up to the 0% line, under the 3.8% tax and Medicare lines (hvY, raising the basis); and a year's tax return on the Withdrawals tab from new detail keys. | |
| Orders by Stage | Version 430: a withdrawal order for each stage of retirement (until Social Security, until required withdrawals, after), worked out per year in the tax engine (orderByYear); the Strategy tab searches Roth conversion lines and years on the whole plan, ranked on what heirs keep after tax, tests an income annuity at retirement, and tries the orders by stage. | |
| Claiming Ages, Each | Version 429: the Strategy tab searches each spouse’s Social Security age on the whole plan, every pair of 62, 65, 67 and 70 not yet past, then the years around the best pair, one person at a time; the plan’s own pair takes its base run. The Capabilities tab is brought up to date, with what could still be added. | |
| Spending in All | Version 428: on What You Could Spend Each Year, Add other costs and taxes puts the Expenses tab’s other costs and the taxes on each future’s bars, from the futures’ own year-by-year detail, so a bar is all the year pays out, as the Withdrawals tab lists it. A future made larger can set the spending ceiling to the marketplace line less 2 points (398% of the poverty line), with a note on the years its marketplace income still passes the line. | |
| Whole-Planner Review | Version 427: ten reviewers, one slice each (the engine twice, helpers and data, the run and results, the data tabs, the tools twice, the planning tabs, security, UI and text), 150 findings each reproduced, each fixed by its finder in a copy of the site with a patch script and a suite of its own (v427Atest.js to v427Utest.js). The tax now converges each year and nothing unpaid is dropped; unmarried partners have their own fill, conversion and marketplace lines; the Roth basis is kept in dollars; an income fixed, capped or rising by a set percentage is its first payment in the dollars of its year; a home sale in a working year that costs money is charged; the kept result follows the data table in use; downloads wait for the run; the site lists script hashes instead of unsafe-inline; no text is under 12px. | |
| Withdrawals | A tab under Planning, not in Easy (237-mod-wdplan.js). The first year the accounts pay for the plan, read from the middle future run again alone with its detail (repDetail): each kind of account split over the accounts by today’s balances, what it pays for, the required withdrawal, the conversion, what is put back; month by month with the four estimated tax payments. Marketplace years with the hold under the line: cfg.acaHold makes makeTaxSim redo a marketplace year the order would take over the line, taxable money first (only its gain counts), pre-tax in the room left, then HSA money for medical bills and Roth money; a year that still cannot fit goes as the order says. The result carries acaLife, the typical lifetime premiums, and the detail held and wdM; the Strategy tab ranks the hold as a decision of its own. The spending rule is explained with a ladder the engine works out: the middle future again with its first retirement year’s stock return moved, next year’s spending against next year’s portfolio, each step found by halving the gap twelve times. The 2027 figures published so far (HSA and HDHP, Rev. Proc. 2026-24; the marketplace percentages, Rev. Proc. 2026-26; the marketplace out-of-pocket limits) are in the table; refAuto never takes a year later than the calendar year, so they take over on January 1, 2027, and limFor(y) checks a contribution against its own year’s limits. A budget is read one calendar year at a time (budYearTotals): the pay a lifestyle needs had added up every line, whatever its years. | |
| Review Fixes | A review of versions 410 to 424, every finding tried before it was fixed: a later floor raises its own years only and the spending rule keeps its path; a working-year cost comes out of the year's savings in both engines; Solve keeps the later floors it tested; Save with no name, the rules table after Undo, names with % and :, and a what-if never taken for the sample plan; the tax guess files unmarried partners apart with the plan's deductions; a statement loaded on the Statements tab is not counted twice in net worth; a snapshot applied back adds nothing twice (version 425). | 010-engine, 080-solve, 130-compare, 132/133-mod-whatif, 171-mod-inctax, 155-mod-acnet, 207-mod-prog |
| One Figure Everywhere | Net worth today is one balance sheet (nwBS): the start of the plan's first year, the accounts whenever there are any, every line kept on the Statements tab, nothing that arrives later. Home, Insights, the Overview's first year, Net Worth Today and Over Time, a snapshot taken from the plan, the reports and the Planner view all read it. The main run keeps each working year's typical portfolio, so the Overview's working years are filled in, and retired years split the typical portfolio so the kinds add up to it. Emergency months (emFig), the savings rate and the chance the money lasts (lastsPct) are each worked out once (version 424). | 155-mod-acnet, 249-mod-first, 243-mod-map, 090-run, 100-render |
| Cards, Sources and Family Loans | Every tool has the plain-words card the Easy view's tools had, in every view: the question, what you enter, what you get, the words to know and a picture drawn from six templates, every word of it measured inside its shape (version 421). On the spending card, a switch colours each future's bars by what pays the year (income, each pre-tax pool, Roth and HSA, taxable and cash), from the three futures run again with their detail; a future made larger lists the amounts year by year, a withdrawal plan (version 422). Family Loan sets up money lent by family as a real loan: the AFR for its length, the schedule against a bank, what each side gains, the below-market rules of section 7872 and the gift on the day, and forgiving some each year against the annual exclusion (version 423). | 236-mod-toolez1, 236-mod-toolez2, 106-mod-spsrc, 232-mod-famloan, 236-mod-toolez3 |
| Lists and Guesses | The table of every spending rule draws up to five ticked rules year by year on the Scenarios tab's chart, typical spending or the typical portfolio (version 418). Each job and self-employment row on Your Income opens the taxes its pay may cost this year, a guess from the household's pay and profits that year: federal and state shared by the row's share, Social Security and Medicare its own (version 419). Your Income sorts by type or year and Your Accounts by balance, name, owner or type, a one-time reorder with Undo (version 420). | 131-mod-rulestl, 171-mod-inctax, 172-mod-sort |
| Goals | Outside Easy, a Goals tab under Your Data, moved from a small card on Insights: goals the plan checks (retire on time, money lasts, leave an amount) and savings goals with a target, a month to reach it, what is saved (typed in or read from accounts), a monthly amount and a rate; each with a progress bar, what remains and a badge (Ahead, On track, At risk, Behind, Past due, Reached); suggestions such as an emergency fund from the plan's own numbers; and a chart of how each savings goal grows (versions 398 to 401). Kept in the plan as goals. | 013-goals-data, 214-mod-goals, 215-mod-golsave, 216-mod-golsug, 217-mod-golproj |
The runtime diagram's numbered flow, in more detail.
setFromUI, which writes cfg and brings every control into line (syncAll).changed() cancels anything running, marks the derived results stale, saves the plan, keeps an undo step, and schedules a run 160 ms later, so fast typing starts one run, not many.run() calls ensureSH: the yearly figures and any law changes are applied, and the market futures are drawn with seed 11.091-workers.js, version 372). The engine's settings reach them as the page last set them (001-engrec.js). Meanwhile the page works out 2,000 of the futures itself and shows that first estimate, faded (version 370). Without workers (a policy that blocks them, an error) it runs on the page in slices of about 35 ms, handed back through a MessageChannel, so the page stays responsive and a progress bar moves.render updates the headline, charts and tables, and the result is stored.Every calculator on the Tools tab is one object in a registry, TT, described rather than coded by hand. The framework builds the form, checks the numbers, saves them, and draws the result, chart and tables.
| Key | What it holds |
|---|---|
def, F | The default values, and the fields: key, label, prefix or unit, limits, whole numbers, a list of options, or a condition for showing. |
calc(S) | The arithmetic: takes the field values and returns the result, or a message about what is missing. |
res, chart, table, extra | The words, the chart, the table and an optional last card, each drawn from the result. |
acts, fill | Buttons such as "Use My Plan's Numbers", and what they do: read the plan in, or write a choice back into it. |
Adding one is a new 232-mod-name.js, its id and name in 233-mod-tools2b.js, a place in one of the ten groups, a row in the Capabilities list, and a test.
eval. On the website it also allows scripts, styles, the manifest and workers only from the site itself.x, or its own check.wcag.js, run inside the page against WCAG 2.2 AA: text contrast, names for controls and images, charts as images with a text alternative, focus order, duplicate ids and target size (version 385; the axe-core package could not be installed here).usability-script.md is a five-task think-aloud session for real people.A full run takes about 29 minutes on two cores (versions 296 and 297, from about 32). The runner starts one browser for the whole run and the suites connect to it (L.browser()); suites whose checks need no exact figure run 10,000 futures instead of 30,000 (L.fast(ctx), window.PT_SIM), and the sample's result at that size ships precomputed; steps whose redraw is quick wait for the page to be still (L.settle) instead of a fixed sleep; and a stale precomputed result is remade before the suites start. The CPU, not waiting, is now the limit.
The published sample changed in version 409, but the suites were written around the household before it, which has the debts, the child and the home the new one lacks. So the test pages (and only they) carry that household as a fixture with its own precomputed result, and the new sample has suites of its own on a page without it.
A file's own var lines run when the browser reaches them, but its functions can be called before: a saved plan is read (sanitizeExtras, from 060-inherit-data.js) before 106-mod-floors.js has run, so a constant set there is still undefined then. Version 414's first draft took a later floor's amount as NaN that way. A function used while a plan is read keeps its numbers inside it.
The app is one function, so a name declared at the top of two files is one name, and the later file wins without a word. Version 412's first draft took RL and rlKey from the Spanish reports this way and broke them; v412test.js now reads every app file and fails on a name declared in two.
Every test file names the source files it covers in a /* covers: */ line, and a quick mode runs only the suites whose files changed. The structure suite guards the layout itself: file naming, a view for every tab and a tab for every view, a build script that names no file, and, in a copy of the source, that adding a tab takes one view file and one registry entry.
The tests cover the plans they were written for; a plan someone brings may find what they missed. The Plan tab's Technical Report (MD) and Technical Data (CSV), in the Enterprise and Planner views, hold everything needed to find it, for a person or a program.
trData(r) builds the report once: where it came from (version, build, view, futures, returns, stress test, yearly figures, data tables replaced), every field of the plan with its key, stored value and whether it is in use, each list with every field of every row, every other key the plan holds, every number of the result with its key, the year-by-year percentiles, the seven futures ranked both ways, and the other series the result holds.buildTechReport writes Markdown tables and the plan as JSON at the end; buildTechCSV writes one line per value, section,row,column,value, so the two always hold the same numbers.trChecks(r) puts section 0 at the top: every figure a number, a row for each year, percentiles in order, nothing below zero, chances between 0 and 1, the run-out count adding up, the futures in their ranked order and running out when their place says they should, and the rows of the plan the engine leaves out. Each is "flag" (cannot be right), "look" (may be fine) or "ok".The test for version 281 breaks a result on purpose, one fault at a time, and each check must flag it; and it runs every retirement path of version 273 through the page, where none may.
The spending card's charts carry three sliders (versions 285 and 286): the Retire line, across the years, and the first-year and floor lines, up and down. Each is an SVG group with role slider and the chart's scale in data attributes, so the card's handlers turn a pointer or a key into a year or a dollar amount without the chart's code. While it moves, the line moves on all three charts; when it is let go (or 700 ms after the last key) it sets the plan's field through setFromUI, the way typing in Plan Settings does, so the plan runs again and Undo takes it back.
| To add | What it takes |
|---|---|
| A tab | A view file in src/views and one entry in TABS. |
| A tool | A TT spec, its id, name and group, a Capabilities row, a test. A field that needs explaining takes tip, the "?" beside its label (version 338). |
| The Easy view's look | Rules in 167-easy.css, every one under html[data-mode="easy"] and every colour a theme token, so the other views keep their look and Easy follows the device's light or dark setting: the numbered tabs to fill in, the Plan tab's jump bar (ezJump) and a next-step bar at the foot of each data tab (EZ_NEXT) (versions 343 to 345). |
| A tool's card | A card in TOOL_EASY and a picture in TZ_PIC, from a file that loads after 236-mod-toolez.js (the objects do not exist before it): the question, what you enter, what you get and the words to know, each sentence at grade 12 or below, the picture made with the templates in 236-mod-toolez1.js and its words at 12px or more and inside their shapes. Every tool has one since version 421; checkez.js checks a file of cards before it goes in. |
| A lesson | An entry in lessons_src.py, which writes the JSON. Every figure in its text must be what its calculator shows at the defaults, and the tests check it. |
| A setting | A default, a field entry and, if it is not a plain number, a line in the cleaner. |
| A spending rule | Both engine models, the settings, and a test pinned to the rule's published example. |
| A data table | A file in src/data; a table people may replace also needs a year column and an entry on the Actual Data tab. |
| Words in the Easy view | Short, plain sentences, none past grade 12 by Flesch-Kincaid (tests measure every Easy tab). Code writes ez(full, plain); a view's HTML writes both halves, .ez-f and .ez-e; a note that only explains the model carries .ez-hide. |
| A card out of the Easy view | An id on the card and a line in 139-modes.css under html[data-mode="easy"]. A setting Easy decides for the household (the market history, the guardrails, flat spending, no stress test) goes in EASY_RUN, which keeps the plan's own in cfg.easyWas for the other views. |
| A version | The version and date in 000-prelude.js, a section in HACKING.md, and a test named after it. |
Headings, buttons and field labels are in Title Case (AP style), options and hints in sentence case, and a test enforces it. All money colours come from shared tokens, and destructive buttons share one style.
This part lists the formulas the planner uses, in the order a plan runs: the markets, a year in the portfolio, the spending rules and the results, then taxes, health costs, Social Security, retirement accounts, lifetimes, pensions, credits and the Tools calculators. The last part lists what the check found. Each one gives the formula as the code computes it, where it lives, and what it was checked against.
All amounts are in today's dollars and all returns are real (after inflation), unless a formula says otherwise. t is the year on the plan's timeline, P the portfolio at the start of a year, s the spending level the rule sets.
makeShocks · mulberry32
A small seeded generator. The main run uses seed 11 and 30,000 futures (10,000 in the faster setting), so the same plan always gives the same answer, and every plan is compared on the same futures.
makeShocks · goldZ
The Box–Muller transform, cosine branch. Box–Muller transform.
makeShocks · goldZ
e₁…e₄ are independent normal shocks; the weights are the Cholesky factor of the correlations stocks–bonds 0.1, bonds–cash 0.3, stocks–cash 0, and gold–bonds 0.1. The factorisation is standard; the correlations are the planner's assumptions.
lnParams · zFor
Lognormal returns matched to the average μ and volatility σ entered, so the mean of r is exactly μ and its standard deviation exactly σ, and no year can lose more than everything. Defaults: stocks 7% and 18% (a median year of 5.52%), bonds 1.8% and 7%, cash 0.8% and 2.5%, gold 2.8% and 20%. Log-normal parameters from mean and variance.
TURB_P · TURB_M · CALM_M
With fat tails on, about one year in seven is turbulent for every asset at once. The mixture keeps each asset's average and its overall variance, so only the shape changes: more calm years and more large moves.
FEE
Taken from every asset's real return every year, including historical and stress-test years. Default 0.1% and 0%.
histSeries
Price change plus dividends, made real with the Fisher relation, from one January to the next. The data is Robert Shiller's S&P Composite, dividend, CPI and ten-year Treasury series since 1871. Fisher equation.
bondYear
A ten-year par bond bought at the January yield y₀, priced a year later as a nine-year bond at the new yield y₁, plus its coupon: the standard price of a bond from its yield. Bond valuation.
histShocks
Each future starts in a different year since 1871 and follows the record in order. The file has no Treasury bill series, so cash keeps its lognormal median (about 0.77% at the defaults) in these futures.
inflModel · dfl
π is steady (2.5% by default), high for a stretch then steady, or a replay of the CPI from a chosen year. Because returns are real, inflation matters only for amounts fixed in dollars (divided by dfl), for Guyton-Klinger's inflation rule, and for tax on nominal interest.
glidePath
A glide path or bond tent moves the stock share in straight lines. d is the number of saving years, a and b the start and end shares, n the years it takes.
cmpd
The usual approximation of the compound return, shown next to the settings only; the simulation itself uses the exact lognormal above. Geometric and arithmetic means.
ev
Half of a year's withdrawal w leaves at the start and half at the end, which stands in for money taken through the year. A saving is a negative w. Money that arrives in month m counts as (1 + (1 − e) r) ÷ (1 + r) of its amount at the start of the year, e = (m − 1) ÷ 12, so it earns only the part of the year it is invested.
saveByYear
r_mix is the stock share times the stock return plus the rest times the bond return (and gold, if held). In the accounts model the saving is split among pre-tax, Roth and taxable by the shares set.
simulate
The cash target is a number of years of withdrawals or a share of the portfolio. Withdrawals come from cash, then bonds, then gold, then stocks.
plan · takeFree
The default, tax-smart order. "Taxable first" skips step 2, and "proportional" takes from every pool in proportion. The fill line is the top of the 12% bracket plus the standard deduction unless another is chosen.
makeTaxSim
Only stocks carry gains, and all gains are long-term. Dividends are 1.6% of the stocks a year, all qualified; bond and cash interest is taxed at its nominal yield.
makeTaxSim
Tax depends on what is raised, so each year is solved by repeating it three times (five with a marketplace plan or a conversion) until it changes by less than 50 cents. A year that cannot be met ends the future: it has run out.
Every rule sets a spending level s each year after the first. What is spent is s × mult_t, where mult_t carries the fall after a death and the change with age. Every rule except fixed stays between the floor and the ceiling.
base1 · base2 · XR
The withdrawal rate is the share of the portfolio that spending needs once income is counted. XR is the Expenses tab's regular rows, certain long-term care and pre-Medicare health costs; one-time, education, charity from an IRA, marketplace and uncertain care rows are left out. V is that future's portfolio at retirement.
saveAdjByYear · ADJ
Before retirement the planner adds the savings and pays no costs: pay is taken to cover them. A what-if's cost in a working year is therefore a change to that year's savings (cfg.saveAdj, today's dollars), and only what is more than the savings comes out of the portfolio; no tax or penalty on it is counted. Years in retirement are left out: a cost then is an expense row (version 416).
floorByYear · FLY
Up to three later floors, each from its year on (version 414). They are in the units of s, before mult_t, as the plan's floor is. Only the plan's floor is held at or under the starting spending; a later one may be above it, and then the spending rises to it in its years. Without later floors FLY is null and nothing changes.
model 'gk'
Guyton and Klinger's withdrawal, capital preservation and prosperity rules with their published 20% guardrails and 10% steps. The planner's changes: the rate counts the expense rows and income as above, the planned fall with age is taken out before comparing, the floor and ceiling bind, and a raise is skipped if it would trigger a cut the next year. The original decision rules.
model 'gkp'
A simpler variant several online tools use: the test is the portfolio against its value at retirement, and a step replaces that year's inflation raise.
model 'rbg' · rbgTable · rbgRate
Start at an 80% chance of success, raise back to 80% when it reaches 100%, cut back to 45% when it falls to 25%: the settings in Kitces's 2024 comparison. R is read from a table solved once on the plan's own futures (90 rates from 0.2% to 20%, a stock and bond mix, 2,000 futures), with n the years left. Why Guyton-Klinger guardrails are too risky.
model 'vg'
A share of this year's portfolio, held within a 5% ceiling and a 2.5% floor on last year's real spending. Vanguard's dynamic spending strategy (AAII).
model 'endow'
The Yale rule's blend of last year's spending and a share of the portfolio. Yale weights them 80% and 20% with a 5.25% target on the value two years earlier; the planner uses 70% and 30% on this year's value, and both weights can be changed. The Yale spending rule.
model 'vz'
Spending follows part of the portfolio's change from one year to the next.
model 'pct'
The constant-percentage method, at the plan's own starting rate.
capeRate · capeNext
Early Retirement Now's rule. ERN's current recommendation is a = 1.75% with his adjusted CAPE; the planner defaults to 1.0% with Shiller's plain CAPE (40.9 in August 2026), and both can be changed. The CAPE moves with each future's price change against real earnings growth of 2.6% a year (AQR, 1950–2023). ERN, part 54.
vpwRate
One over an annuity-due factor to age 100, at VPW's own growth rates for stocks and bonds (from the Credit Suisse yearbook), with w the stock share. At 65 with half in stocks the rate is 4.80%. Bogleheads VPW; VPW's return assumptions.
model 'heb' · singleLife
A blend of last year's real spending and an RMD-style amount, with LE from the IRS Single Life Table; both weights can be changed. This is the Autopilot as blended spending and RMD tools describe it; Hebeler's later Autopilot II uses 75% of last year and 25% of an annuity payment at 5%. cFIREsim methods; Autopilot II.
model 'ratchet' · rtTrig · rtUp · rtGap
Fixed spending that is raised by 10% whenever the portfolio, in today's dollars, is half again what it was when spending started, at most every three years, and never cut. All three numbers can be changed (version 366). Kitces, the ratcheting safe withdrawal rate.
model 'rmd' · singleLife
The Hebeler code with all the weight on the life-expectancy share, as a rule of its own: each year the portfolio over the IRS Single Life Table's expectancy at the person's age (version 366). IRS Publication 590-B.
fixSkip · negY
An option on Fixed spending: the year after a loss the dollar amount is not raised for inflation, so its real value falls by that year's inflation; one of the flexible ways Morningstar's retirement income research tests. Vanguard's rule may now rise without a limit, which with a 5% fall is Clyatt's 95% rule (version 366). Morningstar: flexibility pays.
model 'arva' · arvaFactor · arvaY · arvaRate
Waring and Siegel's annually recalculated virtual annuity, the Bogleheads' amortization-based withdrawal: each January the portfolio buys, on paper, a ladder of TIPS paying a level real amount in every year left, and spends that amount. yk is the TIPS yield for k years from the yearly figures, or one real rate set by hand, when the sum makes s Excel's PMT(r, n, −P, 0, 1); the test checks it against that formula in both engines (version 389). Waring and Siegel, Financial Analysts Journal, 2015; Bogleheads: amortization based withdrawal.
ageStep · AGE_SMILE
Blanchett's "retirement spending smile" regression for the yearly change in real spending, applied each year after retirement at the older person's age. The steady option instead falls 1% a year after 75. Blanchett, Journal of Financial Planning, 2014.
spendMult
One person's share of spending stops when they die; a move can raise or lower spending from its year.
dep
Shown as "less than 0.1%" below 0.05%. The words run from very low (under 1%) to very high (15% or more).
pct · quantiles
Linear interpolation between sorted values, the method of Excel's PERCENTILE.INC. The bands use the 5th, 25th, 50th, 75th and 95th. Percentile.
LIFE.weighted · LIFE.plan
Each future that runs out counts by the chance that one of you is still alive that year, with q from the Social Security period life table (details with Social Security, below). The two lives are treated as independent.
lastingCounts · lyDetails
depBy counts the futures by the year they first run out, so a future that still has money after the last of them keeps it to the end. The strip under the bars puts each year's share on the same scale as the headline.
repPicks
Futures that run out rank below every one that lasts, earliest first.
endA
The heirs' rate is 15% by default. The chance of leaving a goal is the share of futures ending at or above it.
lastingScale · tuneRun
Both search by halving; the floor and ceiling keep their ratio to spending.
The accounts model works out a tax year for every future and year. Tax-year figures are the 2026 law unless the yearly figures on the Actual Data tab give another year's. Amounts the law indexes stay constant in today's dollars; amounts the law fixes in dollars (the Social Security thresholds, the investment tax, the SALT cap, the senior deduction and others) shrink each year by inflation, as they do in real terms.
makeTaxSim · SOLO · TBy
The investment tax, senior deduction and Medicare surcharge use the single thresholds whenever the return is not joint.
tax2 · twoBook · niit2 · aca2 · inhRmd
No spousal or survivor's Social Security for a partner (versions 358 and 359). The equal split of shared income assumes a jointly owned taxable account. IRS: required minimum distributions.
ordTax · TAXBOOK
The tops of each bracket for 2026. IRS 2026 inflation adjustments; head-of-household brackets.
DED
yearTax · CALC.ssTaxable
The IRS worksheet in two lines. The thresholds are fixed in law and never indexed. Tax-exempt interest, which the law adds to PI, is not modelled. How Social Security is taxed.
makeTaxSim · pass
Interest is the nominal yield (real return plus inflation) on the taxable account's bonds and cash. Every dividend is qualified and every gain long-term.
yearTax · SENIOR_*
2025 through 2028, whether or not the return itemizes; each spouse's $6,000 shrinks by 6% of the excess, so a couple's is gone at $250,000. IRS, deduction for seniors; Schedule 1-A steps.
saltAt · SALT_*
Both the cap and the income line where it starts to shrink rise 1% a year through 2029 (fixed in version 242; the line had been held at $505,000). SALT changes in the 2025 law.
yearTax · ITEM_HAIRCUT
The 0.5% charity floor and the 2/37 limit that holds itemized deductions to 35 cents on the dollar start in 2026. The planner's changes: mortgage interest is the loan balance times its rate on up to $750,000, AGI stands in for taxable income plus itemized deductions, and the 60%-of-AGI charity limit is not applied. Charitable changes in the 2025 law.
charStdAt
From 2026, fixed in dollars, so worth a little less each year in today's dollars (fixed in version 242). Tax Foundation.
workDed · WD_*
2025 through 2028, as Schedule 1-A works them: whole thousands for tips and overtime, a thousand or part of one for car loan interest (fixed in version 242; tips and overtime had shrunk by 10% of the excess). IRS, tips and overtime; Schedule 1-A steps.
yearTax · QBI_*
The 2026 thresholds and the 2025 law's wider ranges and $400 minimum. The planner treats every business as a service business with no wage or property limit, so the deduction is gone above the range. Rev. Proc. 2025-32; QBI under the 2025 law.
yearTax
Gains stack on top of ordinary income. A deduction larger than ordinary income spills onto the gains. 2026 capital gains thresholds.
childCredit
2026 amounts. The alternative refund for three or more children is not modelled. Tax Foundation, 2026.
yearTax · stRateOf
Default 0%. One-time sales use the state's top rate, or this rate.
makeTaxSim · mrg · brkRate
The marginal rate on the tax dashboard includes every knock-on effect: more Social Security taxed, a lost senior deduction, the investment tax.
makeTaxSim · NIIT_*
The thresholds are fixed in law. The planner counts the taxable account's interest, dividends and gains; the law also counts rental income and the taxable part of a home sale, which the planner leaves out. IRS Topic 559.
payrollTax
Half the self-employment tax is deducted from income. The 2026 wage base is $184,500. SSA 2026 figures.
stateTaxOf · STATES · states.csv
One row per state in states.csv, with its brackets, Social Security rule, retirement exclusion, age and limits, and gains rule (Arizona's 25% exclusion, Hawaii's 7.25% cap, Montana's gains rates, Washington's gains tax, and others). Brackets stay constant in today's dollars; local income taxes are not modelled.
makeTaxSim · earlyPre · seppLevel
Exceptions: the rule of 55 (50 for public safety), 457(b) plans and equal payments (SEPP). The penalty age is 60 by default, standing in for 59½ with whole years. IRS, exceptions to the 10% tax.
homeSale
The exclusion is fixed in law. A surviving spouse keeps $500,000 for two years after the death. The planner uses 15% throughout; a very large gain could reach 20% and the 3.8% tax.
rentalModel
Residential property is depreciated over 27.5 years and depreciation is taxed at up to 25% on sale. Losses carry forward; the $25,000 allowance for active owners is not modelled. IRS Publication 527.
preRate · endA
A flat rate for the income tax heirs pay on inherited pre-tax money.
expenseModel · HEALTH_KIND
An Expenses row per person from 65, $5,300 a year by default. Before Medicare, the pre-Medicare health amount on the Expenses tab is paid each year until the younger person reaches 65.
irmaaExtra · irmaaTier
The Part B and Part D amounts for 2026 ($81.20 to $487.00 and $14.50 to $91.00 a month), charged for each person on Medicare, on income from two years before. CMS 2026 premiums; Kiplinger IRMAA tiers.
MEDICARE.premiums · outOfPocket
2026 figures: Part A $311 or $565 a month without 40 quarters, Part B $202.90 with a $283 deductible, $1,736 a hospital stay, and the drug plan's $615 deductible and $2,100 cap. Late penalties are 10% of Part B for each full year late and 1% of the base drug premium for each month. CMS 2026 premiums and deductibles.
acaNet · acaPct · ACA_BANDS
The percentage rises in straight lines within each band. MAGI here is AGI plus the Social Security that is not taxed. The enhanced credits of 2021–2025 expired, so the 400% cliff is back. The planner assumes the plan bought is the benchmark and leaves out cost-sharing reductions. 2026 and 2027 applicable percentages; status of the enhanced credits.
refdata.csv · aca.b*
Rev. Proc. 2026-26 raises every band for 2027. The planner has only the 2026 table and carries it forward, so a 2027 marketplace year shows the credit a little too high. Adding these alone would make 2027 the year in use while every other figure is 2026's, so they go in with the rest of 2027's yearly figures when the IRS and SSA publish them (October and November). Rev. Proc. 2026-26.
ACAL · FILLT
In marketplace years, Roth conversions (and a "fill to the marketplace line" order) stop $1,000 under the chosen line: 150%, 200%, 250% or the 400% cliff.
expenseModel · ltcU
Default from 82 for three years. Certain care counts in the guardrails; uncertain care does not.
Benefits are entered as the monthly amount at full retirement age (the PIA) in today's dollars, and the plan assumes cost-of-living raises equal inflation, so a benefit is constant in today's dollars.
FRA_BY_BIRTH · fraMonths
The Social Security Administration's table. People born on January 1 use the year before, which the planner does not model. SSA, retirement age and benefit reduction.
ssFac · ssFactor
Claiming at 62 with full retirement at 67 gives 70%, at 70 gives 124%. The planner claims at whole ages and pays the whole first calendar year. SSA Handbook §724.
streamsByYear · spouseFactor
No delayed credits on the top-up; at 62 with full retirement at 67 it is 65%. Spousal benefits.
survBase · survFactor
71.5% at 60, rising evenly to 100% at the survivor's full retirement age (the table two birth years later). The survivor takes the reduced amount early only when it beats their own benefit, otherwise the full amount from their full retirement age. The widow(er)'s limit; SSA Handbook §724.
etHold · RET_LO · RET_HI
$1 for every $2 and $1 for every $3 over the 2026 limits ($2,040 and $5,430 a month). The spousal part is not recomputed at full retirement age. 2026 determinations; SSA, retirement earnings test.
SSEARN.compute · bends
The formula for people turning 62 in 2026 and the wage index through 2024 ($69,846.57). 2026 determinations.
SSE.grow · ssGrowInfo
The statement's benefit stands for the record; the years the plan still works are added in today's wages, as Social Security's own statement shows them. Without the record itself the lowest year is not known, so a year that replaces one is taken against the average, which understates the gain a little. SSA: retirement benefit calculation examples.
ssCutOf · ssPay
The 2026 Trustees Report projects the retirement fund to run dry in late 2032, after which income pays 78% of benefits (83% for the combined funds in 2034). The planner pays 100% by default; the setting applies a cut to every year or from a chosen year. 2026 Trustees Report.
CALC.ssCouple · ssFactor · spouseFactor · survFactor
The calculator takes the year you were born and uses that full retirement age and its factors, as the plan does: a 1959 birth gets 70.83% at 62 (fixed in version 242; it had assumed 67 for everyone).
RMDV · RMD_DIV · rmdAgeOf
The IRS Uniform Lifetime Table and the SECURE 2.0 ages. A survivor takes over the other's pre-tax money on their own age. The joint table for a much younger spouse is not modelled. RMDs under SECURE 2.0.
QCD_LIMIT · QCD_AGE
Qualified charitable distributions count toward the RMD and are not income. The law allows them from 70½; the planner starts at 71. 2026 QCD limit.
seppLevel · SEPP_ULT
The amortization method under IRS Notice 2022-6, which allows a rate up to the greater of 5% and 120% of the federal mid-term rate. $1,000,000 at 50 pays $55,177 a year. Substantially equal periodic payments.
convOf · CVT
From the retirement year to the year before required distributions, unless set. Brackets to 10, 12, 22, 24 or 32%, or the first two Medicare surcharge lines.
run529 · R529_CAP
The SECURE 2.0 rollover. The $35,000 lifetime limit is fixed in dollars. An adult beneficiary must still be working; a dependent's moves are grown to their 65 for the row (version 249). 529 to Roth rules.
paSplit · paFromCurrent · paByAcct
The split is for the card only: the plan still runs on each account's stocks, bonds, gold and cash, so changing it runs nothing (versions 287 to 289).
ctbByYear
On top of the plan's savings a year and an employer's contributions. The row's hint warns above the 2026 limits: $24,500 for a 401(k), 403(b) or 457(b) ($32,500 from 50), $7,500 for IRAs ($8,600 from 50), $4,400 or $8,750 for an HSA (version 301).
The rows add up per person (version 322); the match counts pay only up to the limit (version 325).
ltcSpans · ltcLast
The cost estimates are the 2025 national medians of CareScout's Cost of Care Survey (March 2026): assisted living $74,400, a nursing home $114,975 semi-private and $129,575 private, care at home 44 hours a week $80,080, adult day care $24,700 (versions 302 and 303).
aumRateOn · aumFee · aumShares · aumCompare
The accounts marked managed pay it; the schedule defaults to 1% up to $1 million and 0.75% above, billed quarterly. The Expenses tab's card runs the drawn futures again with no account managed, and the whole plan once more for the chance with and without (versions 309 and 310). Its typical amount each year, the median across the futures (aumYears), shows on Expenses by Year, in the cash flow table and on the one-year flow, paid from the managed accounts (version 334); Accounts shows the managed and self-managed shares in a bar under the overall mix (version 336).
raVars · raCfg · raRun · raSolve
Nothing changes until Apply to the Plan, which Undo takes back; each proposed plan's result is kept by its key, so a slider moved back is instant (versions 304 to 308, and the advisory fee among the strategies in 311).
LIFE.q · lifetable.csv
The Social Security Administration's 2023 period life table from the 2026 Trustees Report. At the average setting the planner's life expectancy at 65 is 18.12 years for men and 20.66 for women, the table's own figures. SSA actuarial life table.
LIFE.alive · expect · ageAt
The standard life-table calculation, counting half of the year of death.
LIFE.plan · alone
The two lives are treated as independent. A death age set on the People tab replaces the table for that person. The simulation itself assumes each person lives to the plan's end or that set age; the table is used to weight results.
LIFE.raceK · RACE_E
Each factor is found by halving between 0.1 and 6.
incValue
The FERS "diet" COLA and its age-62 rule for regular retirees. The FERS COLA.
survShare
The survivor share chosen on the Income tab, paid while the survivor lives.
pnCalc · pnSpia
The expected present value of the payments over the table's survival chances, compared with the lump sum; also the cost of the same income from an immediate annuity.
govCalc · govMRA
OPM, FERS computation; OPM, CSRS computation; Military retirement.
annuity.json · annBuys
Payout rates per $100,000 at 60, 65, 70, 75 and 80, in straight lines between (Annuity.org and Cannex, April 2026). A fixed payment loses value with inflation; a cost-of-living payment keeps it.
tipsLadder · tipsYield · TIPS_CURVE
The present value of each year's real payment at the real yield for its maturity (the curve of 21 September 2026). Present value.
loanLevel · DEBTS.level · rfPay
The standard level payment, with i the monthly rate and n the months. The plan adds up each year's twelve payments; student loans can be forgiven after a set number of years. Mortgage calculator.
The credits tools on the Tools tab, for tax year 2026 unless noted. They work out the credits from income, filing status and family; the plan itself models only the child tax credit (above).
CRED.eitc
The IRS table works in $50 steps; the formula is continuous, so it can differ from the table by a few dollars. The credits end at $19,540, $51,593, $58,629 and $62,974 single. Tax Foundation, 2026; Rev. Proc. 2025-32.
CRED.saver
Withdrawals in the look-back period, which the law subtracts, are not modelled. IRS 2026 limits; Saver's Credit guide.
CRED.match
SECURE 2.0's replacement for the Saver's Credit, from 2027, before any inflation update. Saver's Match.
CRED.college
CRED.adopt
CRED.all
A quick tax for the credits tool: ordinary rates only, without capital-gains rates or the senior deduction.
The calculators on the Tools tab, grouped. Most are standard finance; the rules of thumb are named as such.
230-mod-tools · goalPlan · viIrr
Rates that have no closed form are found by halving between limits. Time value of money.
215-mod-golsave · golProject · golNeed · golSaveEval
Saved is what the user types in, or the balance of the accounts the goal draws on. The chart's second line is the same balance in today's dollars, at the plan's inflation; the dashed line is what was put in. Compound interest (Investor.gov).
DEBTS.run · minPay · compare
The standard month-by-month schedule; the card minimum follows the common "1% plus interest" rule.
slRun · slRapM · slFpl
hafCalc · carCalc · rfCalc
The usual lender and personal-finance guidelines (28/36 and 20/4/10), stated as guidelines.
ebCalc · bzYear · 232-mod-bizsale
An installment sale taxes each year's principal in the ratio of gain to price, and its interest as income.
loiCalc
Put This in My Plan adds the part sold as a business sale in the year of closing and the rollover as a second sale (versions 332 and 333).
qsPct · qsFed · bizSale
The tool checks the five conditions; the plan's business sale uses the same limit, the $10 million fixed in dollars and so lower in today's the later the sale (versions 323 and 324). 26 U.S.C. 1202.
eqAmt · eqPayroll · eqRange
The 2026 AMT figures with the 2025 law's faster 50% phase-out. The price range uses lognormal percentiles. 2026 AMT; IRS 2026.
rtCalc · brCalc · nuRun
The pro-rata rule of Form 8606 and the 2026 limits. IRS 2026 limits; Notice 2025-67.
hsaCalc
The tax drag is points off the return a year, 0.5 by default (fixed in version 242; it had been taken as a share of the return). Fidelity's 2026 estimate for one 65-year-old is $185,500. Fidelity 2026 estimate.
ngTax · ngCalc
With pay from work, there is no Social Security and no tax-free share, whatever the hidden fields hold (fixed in version 242).
204-mod-need · budTotals
The 50/30/20 split is a rule of thumb.
FAFSA.sai
The 2027–28 formula for a dependent student. Federal Register, 2027–28 methodology.
INSURE.need · pvDue
The needs method and the DIME rule, both standard ways to size cover.
232-mod-annuity
How the crediting methods work, and the 2026 QLAC limit. Notice 2025-67.
ofrRun · ofrIrr
The fee is a prepaid finance charge, so the APR counts it and the rate does not; paid off early, the APR comes from the cash flows actually paid. 12 CFR 1026.22; the 20/10 rule.
startRun · startCalc
Monthly compounding of a yearly return, as Investment Growth does. With $100 from 20, doubling each decade to 65, the break-even is 6.6%.
ppDebt
The standard amortization, with the big-check rule's share for the debt added whenever pay rises above the cushion (version 246).
l529Calc
Each move takes what was put in and growth in proportion. The IRS has not said whether a new beneficiary restarts the 15 years; the cautious reading is used (version 248). IRS Publication 970; 529 to Roth rules.
prBank · prMonths · renderPrMon
Transfers, card payments and money coming in are left out, as for the year's totals (version 247).
floorCover
The safety-first view of the RICP program: are the essentials paid by income that does not depend on the markets? Before tax, today's dollars (version 253).
styScore
The two preferences and four strategies taught in the RICP program, from Pfau and Murguía's research. The questions are the planner's own, not the trademarked RISA® profile (version 254). Kitces: the RISA framework.
gwRun
The risk wrap, run at the rate entered, at 0%, and without the rider. Typical 2026 rider fees 0.95% to 1.25% of the base, roll-ups 5% to 8% (version 255). Annuity.org.
hecmRun
The Sacks rule for a coordinated line, as tested in the research the AAII summarizes; the 2026 HECM limit is $1,249,125 (version 256). AAII.
nqRun
Section 409A payouts, taxed as ordinary income when paid (version 257). Fidelity: NQDC and state taxes.
lpCalc
Death rates from Social Security's life table; the sale's split follows Rev. Rul. 2020-5 (version 258). Rev. Rul. 2020-5.
rsIps
The CFA Institute's elements of a policy statement, written from the plan's own figures, with lines to sign (version 260). CFA Institute.
trCalc
The CRPC program's emotional and financial transition; the phases are Robert Atchley's (version 261).
cnCalc
The CFP retirement needs analysis (topic F.44); the test reproduces a published worked example to the cent, $6,987,586.22 and $19,954.85 a year (version 263). CentPotential.
bpCalc
IRS Publication 560's reduced rate and the 2026 limits of Notice 2025-67 (version 264). IRS Publication 560.
abRun
The 2026 ABLE limit (Rev. Proc. 2025-32), SSI's resource rules, and the age of onset before 46 (version 265). SSA: SSI resources.
ihRun
The SECURE Act beneficiary rules and the 2024 final regulations, with the IRS Single Life Table of 26 CFR 1.401(a)(9)-9 (version 266). IRS: beneficiary.
TT.bz.res
Business succession in Selling a Business (version 267). NCEO.
lfCalc
CLTC and CSA: the CMS 2026 spousal impoverishment standards and the AALTCI 2026 prices (version 268). CMS.
dvWorth
CDFA: section 1041 carryover basis and the QDRO penalty exception (version 269). IRS Publication 504.
sfMax, sfRun
NSSA, and retiring with children at home (version 270). SSA: family maximum.
rlCalc
Retiring before 59½, with Publication 590-B's ordering rules (version 271). IRS Publication 590-B.
mnCalc
Partners who are not married, which the plan itself treats as a married couple (version 272). IRS: filing status.
spHead
A planner can show another measure than the typical year (version 274).
repPicksBy
Ranked by what is left, a future whose early markets raised its spending and whose late ones drained the portfolio can land among the hard ones while spending more than the middle one (version 278).
ccCalc
CSA housing choices; the break-even is the years of nursing care at which life care costs no more (version 276).
s351Div · s351Calc
The year selling pulls ahead is where the extra expense ratio outgrows what the deferred tax earns (version 298). Rev. Rul. 2026-20, 26 U.S.C. 368(a)(2)(F).
rchRun · rchCalc
From a story: a retiree whose money is locked in the TSP until 59½ while this year's bills are due (version 299).
mtCalc · mtSign
Medicare.gov's rules; the premiums come from the yearly figures (2026: $202.90 and $38.99) (version 300). When coverage starts.
swrYears · swrAt
A balance below zero never recovers, so the closed form is exact; the test checks it against a year-by-year run found by halving. Over 1871 to 2025, a 60/40 mix's worst 30-year start is 1966 (version 312). Bengen (1994).
seqPath · seqCorr
Kitces found r = 0.79 for the first ten years' real return and a 60/40 mix's safe rate (version 313).
rbRun · rbDue
Vanguard's study found yearly checks with 5-point bands about as good at controlling risk as frequent trading, with far fewer trades (version 314).
dcaSim · dcaHist
5,000 futures from a fixed seed; on the yearly record, spread over 2, 3 or 5 years. Vanguard (2012): a lump sum won in about two thirds of rolling 10-year periods (version 315).
efStats · efCalc
Markowitz (1952) with history in place of forecasts (version 316).
pcRun · pcIrr
Up to three mixes, with the 30-year safe rate of each over the whole record (version 317).
wdmSolve · wdmPick · wdmPolicy
Stochastic dynamic programming (the Bellman equation) over the returns since 1871, each year of the record equally likely, as Forsyth, Vetzal and Westmacott do with expected withdrawals against shortfall. The map is then run on 2,000 futures drawn a year at a time, 2,000 in five-year runs, and every start year in order, against every fixed withdrawal and stock share (version 337). Forsyth, Vetzal and Westmacott (2021).
mcoCalc · mcoDraw · mcoChol
Resampling the inputs instead of trusting one set of guesses, after Michaud; the growth is the compound rate, with the volatility drag (version 338). Michaud and Michaud.
lcCalc · lcBlocks · lcNext
A circular block bootstrap of the real returns since 1871 (stocks, 20-year bonds, gold, after inflation), with mulberry32 random numbers from a seed (version 360). Block bootstrap.
wbCalc
Company stock, with ESPP shares kept, is set against the 10% FINRA mentions (version 326).
rcuRun
With nothing taxed and no premium the two are equal, which the test checks (version 327).
oxYear · oxRun · oxCalc
Equity Pay spreads an NSO exercise the same way (version 329); Put This in My Plan makes each year's out a one-time cost and the shares a business sale with the 3.8% (versions 330 and 331).
Every formula above was checked against the law, the agency or the author that published it. Most matched. Seven did not; version 242 fixed six, and the seventh is data that comes with the next year's figures.
| Formula | What was different | Now |
|---|---|---|
| SALT cap | The $505,000 phase-out line was held flat; the law raises it 1% a year through 2029. | Fixed in 242. |
| Tips and overtime | Cut by 10% of the excess income; Schedule 1-A cuts $100 per whole $1,000. | Fixed in 242. |
| Charity without itemizing | $1,000 / $2,000 held in today's dollars; the law fixes it in dollars. | Fixed in 242. |
| Claiming tool | Assumed full retirement at 67 for everyone. | Fixed in 242: from the birth year. |
| HSA tool | The tax drag was taken as a share of the return, not in points. | Fixed in 242. |
| After-tax income tool | Hidden Social Security and tax-free fields still counted with "pay from work". | Fixed in 242. |
| Marketplace 2027 | The 2026 percentages are carried into 2027; Rev. Proc. 2026-26 raises them to 2.15%–10.22%. | With the 2027 yearly figures. |