Calculation catalog

Display guardrail balance thresholds

The cut and raise balance thresholds of a risk-based guardrail policy in dollars.

Field: Risk-based guardrail dollar thresholds Unit: US dollars Basis: nominal dollars Computed by: UI transformation Status: Relocation pending

Appears in: results-table (Risk-based guardrails callout "cut below $X / raise above $Y")

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/ResultsPage.tsx (ResultsPage).

Display total spending annual

Expenses, taxes, and penalties plotted together as total spending for a projection year.

Field: Displayed total spending Unit: US dollars Basis: as displayed Computed by: UI transformation Status: Relocation pending

Appears in: chart (spending); report (chart-data block spendingPlusTax (expenses.total + tax + penalties))

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/resultsRows.ts (buildResultsRows); planner-ui/src/report/reportModel.ts (chartDataRows).

Display upside shortfall annual

Ideal plus excess spending not funded.

Field: Upside miss Unit: US dollars Basis: nominal dollars Computed by: UI transformation Status: Relocation pending

Appears in: results-table (Layer miss "Upside")

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/ResultsPage.tsx (YearByYearLedger).

Display upside spending annual

Ideal plus excess spending intended above the target layer.

Field: Upside spending Unit: US dollars Basis: nominal dollars Computed by: UI transformation Status: Relocation pending

Appears in: results-table (Upside column (layered spending))

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/ResultsPage.tsx (YearByYearLedger).

Portfolio need annual

The nonnegative annual amount that must be supplied by the portfolio after income.

Field: Net portfolio need Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: results-table (Bucket lens need per year (BucketYearRow.need) and bucket sums); cash-flow-drilldown (needBasedPortfolioWithdrawal sizing)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.netPortfolioNeed).

SEPP distribution annual

Penalty-free 72(t) substantially-equal periodic payment distributed this year (included in traditional withdrawals).

Field: SEPP distribution Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: cash-flow-drilldown (seppDistribution source line)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.sepp).

Solved initial withdrawal rate pct

The solved (rounded) baseline spending as a percent of starting investable assets, shown beside the SWR rule rows.

Field: Solved initial withdrawal rate Unit: percent Basis: no dollar basis Computed by: UI-native Status: Relocation pending

Appears in: solver-page (SWR comparison "Your solved plan" row rate)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/SpendingSolverPage.tsx (SpendingSolverPage).

Solved spending rounded to hundred

Maximum sustainable baseline spending rounded down to the nearest $100, as applied to the plan and shown in the shape table.

Field: Solved spending rounded down Unit: US dollars Basis: today's dollars (real) Computed by: UI transformation Status: Relocation pending

Appears in: solver-page ("sustain about $X of baseline spending", Apply-to-Spending amount, per-shape "$X/yr")

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/SpendingSolverPage.tsx (SpendingSolverPage).

Spending base annual

Base living spending modeled for a projection year.

Field: Base spending Unit: US dollars Basis: nominal dollars Computed by: Engine Status: Partial chain

Appears in: chart (base); csv (baseSpending); cash-flow-drilldown (requiredLifestyle / targetLifestyle use lines (layered))

• Amortization-based withdrawal, growing annuity-due payment Formula record, justified by derivation

  Purpose: This year's ABW payment from a start-of-year balance over the remaining horizon.

  Statement: Given a start-of-year balance B, an expected return r and a planned payment growth g — both in percent per year, as abwAnnualPayment takes them, so the worksheet's 10% is passed as 10 — and a remaining horizon in years including the current year, the function first truncates that horizon to whole years, n = floor(remainingYears), so a fractional horizon such as 4.5 years is amortized over 4. The beginning-of-period payment is P = B(1−x)/(1−x^n) where x = (1 + g/100)/(1 + r/100). P = B/n instead under either guard the code tests: `!Number.isFinite(x) || x <= 0` (x is not finite or not positive; r > −100 and g > −100 keep it finite and positive) and `Math.abs(x - 1) < 1e-9` (x = 1 within that tolerance). Payments are withdrawn before growth. Under the ABW spending policy P is the year's base spending before guardrail adjustments: annualLifestyleLayers writes it as baseAnnualNominal, which annualExpenseSummary publishes as YearResult.expenses.baseSpending. Domain: finite B > 0 (a non-finite or non-positive balance pays 0) and n ≥ 1; n ≤ 1 spends the whole balance. Rounding: the horizon is floored on input; the payment itself is not rounded — the production function returns a binary float.

  Formula: n = floor(remainingYears); x = (1 + g/100)/(1 + r/100); P = B(1-x)/(1-x^n), or P = B/n when x is not finite, x <= 0, or |x - 1| < 1e-9

  • P: This year's beginning-of-period payment (unit: usd) (domain: P ≥ 0)
  • B: Start-of-year portfolio balance (unit: usd) (domain: B > 0 and finite (otherwise the payment is 0))
  • r: Expected return over the period, in percent (10% is 10) (unit: percent) (domain: r > -100, so that 1 + r/100 > 0 and x is finite and positive)
  • g: Planned payment growth over the period, in percent (0% is 0) (unit: percent) (domain: g > -100, so that 1 + g/100 > 0 and x is positive)
  • n: Remaining periods including the current one, n = floor(remainingYears): a fractional horizon is truncated to its whole years before amortizing (unit: count) (domain: integer n ≥ 1 (the floored value); n ≤ 1 pays the whole balance)
  • x: Payment-growth ratio (1 + g/100)/(1 + r/100) (unit: 1) (domain: finite x > 0 with |x − 1| ≥ 1e-9 for the closed form; otherwise P = B/n)

  Timing: beginning of period, annual

  Rounding: none on the payment, a binary float; the horizon is truncated to whole years on input, n = floor(remainingYears)

  Limits:

  • The chosen expected return is an assumption, not proven by the identity
  • The payment is the ABW policy's base spending before guardrail adjustments, written by annualLifestyleLayers as baseAnnualNominal; under other spending policies baseSpending is not this formula

  Provenance: derived by claude-orchestrator, implemented by grok.

  Independent review: none yet

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: abw-annuity-due-payment.md Mutation receipt: abw-annuity-due-payment.mutation.md

  Evidence tests: abw.evidence.test.ts

  Implemented in: abw.ts; annualLifestyleLayers.ts

  Is the number of: spending-base-annual

Spending shape delta vs flat

How much more or less baseline spending each spending shape sustains than the flat shape.

Field: Spending-shape solved delta versus flat Unit: US dollars Basis: today's dollars (real) Computed by: UI-native Status: Relocation pending

Appears in: solver-page (Per-shape table "vs. flat" column)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/SpendingSolverPage.tsx (SpendingSolverPage).

Spending shortfall annual

Unfunded total spending in a projection year.

Field: Spending shortfall Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: chart (shortfall); csv (shortfall); results-table (Shortfall column); scenarios-page (Annual "Total shortfall" and lifetime "Total spending shortfall"); mcp (run_projection.years[].shortfall)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.shortfall).

Spending total annual

All modeled expenses for a projection year before tax and penalties.

Field: Total expenses Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (totalExpenses); report (yearLedger); results-table (expenses); results-table (Expenses column); scenarios-page (Annual "Funded spending" and lifetime "Funded spending")

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.expenses.total).

Withdrawals by category annual

Dollars withdrawn this year from cash, taxable, traditional, Roth and HSA accounts.

Field: Withdrawals by account category Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: scenarios-page (Annual "Traditional withdrawals" / "Roth withdrawals" and lifetime withdrawals by category); cash-flow-drilldown (needBasedPortfolioWithdrawal and retirementActionWithdrawal source lines)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/yearLedger.ts (YearWithdrawals.cash / taxable / traditional / roth / hsa).

Withdrawals total annual

Total account withdrawals used in a projection year.

Field: Total withdrawals Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: cash-flow-drilldown (uses/withdrawals); csv (withdrawals); results-table (Withdrawals column); report (year-ledger block withdrawals); scenarios-page (Annual "Total withdrawals"); mcp (run_projection.years[].withdrawals)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.withdrawals.total).

Display loss carryforward used annual

Capital-loss carryforward applied this year against gains and against ordinary income, combined.

Field: Loss carryforward used Unit: US dollars Basis: nominal dollars Computed by: UI transformation Status: Relocation pending

Appears in: csv (lossCarryforwardUsed)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/resultsRows.ts (buildLedgerCsv).

Display tax free gains room annual

Additional long-term gains realizable at $0 federal tax: remaining loss carryforward plus 0%-bracket headroom.

Field: Tax-free gains room Unit: US dollars Basis: nominal dollars Computed by: UI transformation Status: Relocation pending

Appears in: results-table (Tax-free gains room column)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/ResultsPage.tsx (YearByYearLedger).

Display tax plus penalties annual

Settled tax plus early-withdrawal and RMD-shortfall penalties for the year, as the ledger surfaces print a single "Tax" figure.

Field: Tax plus penalties Unit: US dollars Basis: nominal dollars Computed by: UI transformation Status: Relocation pending

Appears in: results-table (Tax column (y.tax + y.penalties)); report (year-ledger block taxAndPenalties and ReportPage year table); chart (Spending by category "Tax + penalties" series)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/ResultsPage.tsx (YearByYearLedger); planner-ui/src/report/reportModel.ts (yearLedgerRow); planner-ui/src/planner/resultsRows.ts (buildExpenseRows).

Estate heir income tax

Total income tax heirs are assumed to owe on inherited pre-tax balances: per non-spouse traditional account, the taxable pre-tax base (gross net of allocated nondeductible basis) times the class heir rate, plus non-spouse HSA gross times its rate, net of charity carve-outs.

Field: Heir income tax on the estate Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: scenarios-page (Estate table "Estimated heir income tax"); mcp (run_projection.summary.endingEstateHeirTax); mcp (compare_scenarios.a.endingEstateHeirTax); mcp (compare_scenarios.b.endingEstateHeirTax)

No calculation record yet. The number is computed today in engine/src/projection/compare.ts (ProjectionSummary.endingEstateHeirTax).

Projection summary lifetime taxes and penalties

Total taxes and withdrawal penalties paid across all projection years.

Field: lifetimeTaxesAndPenalties Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: results-headline (Lifetime tax + penalties); results-headline (KpiBar "Lifetime tax"); report (headline-results block lifetimeTaxesAndPenalties); scenarios-page (Headline "Lifetime tax plus penalties"); compare-page (Lifetime tax row); solver-page (Evidence lifetime taxes and SWR rule rows); ss-page (Survivor and claim tables lifetime tax); relocation-page (Lifetime tax + penalties column); mcp (run_projection.summary.lifetimeTaxesAndPenalties); mcp (compare_scenarios.a.lifetimeTaxesAndPenalties); mcp (compare_scenarios.b.lifetimeTaxesAndPenalties)

No calculation record yet. The number is computed today in engine/src/projection/compare.ts (ProjectionSummary.lifetimeTaxesAndPenalties).

Relocation lifetime state local tax

Sum over projection years of state plus local income tax for a relocation candidate (or the baseline).

Field: Lifetime state and local income tax Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: relocation-page (Candidate table "State+local tax" column and the drivers panel total); insights (state-relocation evaluate reads stateTaxByYear per candidate)

No calculation record yet. The number is computed today in engine/src/projection/relocation.ts (RelocationCandidateRow.lifetimeStateLocalTax).

Relocation state tax driver savings

For a candidate state, tax with a feature neutralized minus tax as modeled: Social Security treatment, retirement-income exclusion, public-pension exclusion, capital-gains treatment.

Field: State tax driver savings Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: relocation-page (Drivers panel rows)

No calculation record yet. The number is computed today in engine/src/projection/relocation.ts (RelocationDrivers.ssTreatmentSavings / retirementExclusionSavings / publicPensionExclusionSavings / capitalGainsTreatmentSavings).

Scenario lifetime penalties

Sum of penalties over the projection.

Field: Lifetime penalties Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: scenarios-page (Headline "Lifetime penalties")

No calculation record yet. The number is computed today in engine/src/scenarios/comparison.ts (ScenarioHeadlineComparison.lifetimePenalties (sum of YearResult.penalties)).

Scenario lifetime tax

Sum of settled tax over the projection (penalties excluded).

Field: Lifetime tax Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: scenarios-page (Headline "Lifetime tax")

No calculation record yet. The number is computed today in engine/src/scenarios/comparison.ts (ScenarioHeadlineComparison.lifetimeTax (sum of YearResult.tax)).

Tax AMT annual

Alternative minimum tax calculated for a projection year.

Field: Alternative minimum tax Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (amt); results-table (AMT column when any year has AMT)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.amt).

Tax loss carryforward remaining annual

Capital-loss carryforward still available after the projection year tax calculation.

Field: capitalLossCarryforwardRemaining Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (lossCarryforwardRemaining); results-table (Loss carryf'd column and carryforward callout); report (ReportPage year table carryforward column)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.capitalLossCarryforwardRemaining).

Tax loss carryforward used against gains annual

Capital-loss carryforward applied against gains and ordinary income in the projection year.

Field: capitalLossUsedAgainstGains Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: results-table (Capital-loss carryforward callout "offset $X of realized gains")

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.capitalLossUsedAgainstGains).

Tax loss carryforward used against ordinary annual

Capital-loss carryforward applied against ordinary income this year, up to the annual limit.

Field: Loss carryforward used against ordinary income Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: results-table (Capital-loss carryforward callout "and $Y of ordinary income")

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.capitalLossUsedAgainstOrdinary).

Tax penalties annual

Early-withdrawal penalties plus the IRC §4974 RMD-shortfall excise for the year; never part of tax, AGI or MAGI.

Field: Penalties and excise tax Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (penalties); scenarios-page (Annual "Penalties" and lifetime "Lifetime penalties"); cash-flow-drilldown (earlyWithdrawalPenalty use line); mcp (run_projection.years[].penalties)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.penalties).

Tax realized gains annual

Taxable-account capital gains realized during the projection year.

Field: realizedGains Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (realizedGains)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.realizedGains).

Tax total annual

All tax charged for a projection year, excluding penalties.

Field: Total tax Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: chart (tax); csv (tax); report (yearLedger); results-table (tax); survivor-page (Tax around the transition cell "a → b" (death year and first survivor year)); scenarios-page (Annual "Tax" and lifetime "Lifetime tax"); cash-flow-drilldown (settledTax use line); mcp (run_projection.years[].tax)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.tax).

MCP batch cumulative tax objective

Adapter sum of each evaluated projection year's tax plus penalties.

Field: Batch cumulative tax objective Unit: US dollars Basis: nominal dollars Computed by: Adapter Status: No calculation record yet

Appears in: mcp (batch_evaluate.results[].objective)

No calculation record yet. The number is computed today outside the engine, in RetireGolden-MCP/src/adapter.ts in the RetireGolden-MCP repository (batchEvaluate).

Cash flow tax character amount

The dollar amount of one tax characterization attached to a cash-flow line or standing alone (ordinary income, capital gain or loss, QCD exclusion, phantom OID and the other closed kinds); metadata that is never summed into the money identities.

Field: Cash-flow line tax character amount Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: cash-flow-drilldown (YearCashFlowDialog DetailTable 'Tax character' column (kind and amount per line) and the taxCharacter view rows); cash-flow-drilldown (detailCsv.ts taxCharacter column (kind:amount pairs))

No calculation record yet. The number is computed today in engine/src/projection/internal/types/cashFlow.ts (YearCashFlowTaxCharacter.amountPlanDollars (on source, transfer and standalone taxCharacterMetadata lines)).

Claim age co optimization estate gain

After-tax estate gained by the winning joint claim-age combination over the best result at the current claim ages.

Field: Claim-age co-optimization estate gain Unit: US dollars Basis: nominal dollars Computed by: UI-native Status: Relocation pending

Appears in: optimize-page ("$X more projected after-tax estate than the best result at your current claim ages")

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/optimizePageClaim.ts (claimEstateGain).

Social security benefit annual

Social Security benefit income paid in a projection year.

Field: Social Security benefit Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: chart (socialSecurity); csv (socialSecurity); survivor-page (Household Social Security column: incomes.socialSecurity selected from the death year and the first survivor year); results-table (Income by source chart (socialSecurity series)); scenarios-page (Lifetime income "Social Security"); cash-flow-drilldown (socialSecurity source line)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.incomes.socialSecurity / socialSecurityStreams).

Social security break even

Age at which cumulative benefits from one claiming strategy overtake another.

Field: age Unit: age in years Basis: no dollar basis Computed by: UI-native Status: Relocation pending

Appears in: ss-page (claiming break-even age)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/socialSecurity/breakEven.ts (computeBreakEven).

Social security bridge sizing

For a delaying claimant: the forgone age-62 monthly benefit (PIA × claim factor at 62), the annualized bridge amount, the bridge years, and the quoted TIPS-ladder cost on the embedded real-yield curve.

Field: Social Security bridge sizing Unit: US dollars Basis: today's dollars (real) Computed by: Engine Status: No calculation record yet

Appears in: ss-page (Bridge panel rows "$X/yr ($Y/mo, real)" and ladder cost, and the add-ladders total); insights (ss-bridge-gap card via insight-ss-bridge-gap-total)

No calculation record yet. The number is computed today in engine/src/ladder/bridge.ts (sizeBridge (monthlyAge62Benefit, annualRealAmount, ladderCost)).

Social security claiming sweep objective

On the Social Security page's claim-age sweep, the best whole-year strategy's ending after-tax estate minus the estate at the plan's current claim ages (the '+$X' beside the verdict), and the month-refined strategy's ending after-tax estate minus the best whole-year strategy's (the '+$Y' under 'To the month').

Field: Claim-age sweep advantage: best versus current, refined versus best Unit: US dollars Basis: nominal dollars Computed by: UI-native Status: Relocation pending

Appears in: ss-page (Sweep verdict "+$X vs current claim ages" and refinement "+$Y" over the best whole-year strategy); ss-page (Claim-age heatmap and ranked table read engine candidateSummary.endingAfterTaxEstate directly)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/ssAnalysis.ts (sweepClaimingStrategies); planner-ui/src/planner/ssAnalysis.ts (refineClaimingMonthly); planner-ui/src/planner/SsAnalysisPage.tsx (SsAnalysisPage).

Social security computation summary counts

How many years were averaged into AIME and how many of them are $0.

Field: AIME computation year counts Unit: count Basis: no dollar basis Computed by: UI-native Status: Relocation pending

Appears in: ss-page (SocialSecuritySection "Averages your top N earning years ... M of those years are $0")

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/socialSecurity/explain.ts (summarizeComputation).

Social security credit estimate

Estimated Social Security credits (max 40) from the earnings history when the user has not entered a count.

Field: Covered-work credit estimate Unit: count Basis: no dollar basis Computed by: UI-native Status: Relocation pending

Appears in: ss-page (SocialSecuritySection credits hint "Estimated N of 40")

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/socialSecurity/explain.ts (estimateCredits).

Social security expected present value

Present value of expected Social Security benefits after discounting and weighting payments by survival.

Field: expectedPv Unit: US dollars Basis: today's dollars (real) Computed by: UI-native Status: Relocation pending

Appears in: ss-page (expected present value of benefits)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/socialSecurity/expectedPv.ts (expectedPvSingle); planner-ui/src/socialSecurity/expectedPv.ts (expectedPvCouple).

Social security FICA return ratio

Expected present value of lifetime benefits divided by employee OASDI tax paid in.

Field: Benefits-to-contributions ratio Unit: factor Basis: no dollar basis Computed by: UI-native Status: Relocation pending

Appears in: ss-page (Paid-in table "Ratio (get back ÷ paid in)")

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/SsAnalysisPage.tsx (SsAnalysisPage).

Social security OASDI paid in

Employee OASDI payroll tax paid over the earnings history used by the Social Security analysis.

Field: OASDI paid in Unit: US dollars Basis: nominal dollars Computed by: UI-native Status: Relocation pending

Appears in: ss-page (Paid-in table "Paid in (OASDI)" and "Employer paid (context)")

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/socialSecurity/ficaReturn.ts (ficaOasdiPaidIn).

Social security PIA annualized

A claimant's monthly primary insurance amount times twelve, as the survivor-switching explainer prints it.

Field: PIA annualized Unit: US dollars Basis: nominal dollars Computed by: UI transformation Status: Relocation pending

Appears in: ss-page (Survivor switching paragraph "about $X/yr")

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/SsAnalysisPage.tsx (SsAnalysisPage).

Social security survivor switch PV

Expected present value of a survivor strategy that switches between own and survivor benefits.

Field: survivorClaimAge Unit: US dollars Basis: today's dollars (real) Computed by: UI-native Status: Relocation pending

Appears in: ss-page (survivor switching expected PV)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/socialSecurity/survivorSwitching.ts (expectedPvSwitch).

Social security zero year replacement gain

Rough monthly PIA gain from replacing one $0 computation year with a year of indexed earnings.

Field: Zero-year replacement PIA gain Unit: US dollars Basis: nominal dollars Computed by: UI-native Status: Relocation pending

Appears in: ss-page (SocialSecuritySection PIA explainer "would add roughly $X/mo")

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/socialSecurity/explain.ts (replaceZeroYearGain).

Survivor scenario row estate delta

Change in after-tax estate from the convert-early survivor lever versus the same death-timing baseline.

Field: estateDelta Unit: US dollars Basis: nominal dollars Computed by: UI-native Status: Relocation pending

Appears in: survivor-page (convert-early after-tax estate delta)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/survivorAnalysis.ts (buildSurvivorAnalysis).

Survivor scenario row lifetime tax delta

Lifetime taxes and penalties under the pre-death conversion lever minus the base run, for one death timing.

Field: Convert-early lifetime tax delta Unit: US dollars Basis: nominal dollars Computed by: UI-native Status: Relocation pending

Appears in: survivor-page (Convert-early lever cell "(+$X lifetime tax)")

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/survivorAnalysis.ts (buildTimingRow).

Survivor scenario row ssa44premium savings

Medicare premium savings produced by applying SSA-44 relief after the modeled life-changing event.

Field: ssa44PremiumSavings Unit: US dollars Basis: nominal dollars Computed by: UI-native Status: Relocation pending

Appears in: survivor-page (IRMAA relief SSA-44)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/survivorAnalysis.ts (buildSurvivorAnalysis).

Survivor scenario row survivor shortfall years

Number of survivor years in which planned spending is not fully funded.

Field: survivorShortfallYears Unit: count Basis: no dollar basis Computed by: UI-native Status: Relocation pending

Appears in: survivor-page (survivor shortfall years)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/survivorAnalysis.ts (buildSurvivorAnalysis).

ACA applicable SLCSP premium annual

Applicable second-lowest-cost silver plan premium for the year; null when not modeled.

Field: ACA benchmark (SLCSP) premium Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: report (aca-ledger block and ReportPage ACA table "Benchmark premium")

No calculation record yet. The number is computed today in engine/src/projection/internal/types/aca.ts (YearAcaResult.applicableSlcspPremium).

ACA economic net premium annual

Gross enrollment premium net of the modeled allowable credit.

Field: ACA net premium Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: report (aca-ledger block and ReportPage ACA table "Net premium")

No calculation record yet. The number is computed today in engine/src/projection/internal/types/aca.ts (YearAcaResult.economicNetPremium).

ACA gross enrollment premium annual

Gross Marketplace premium for the year before any premium tax credit.

Field: ACA gross enrollment premium Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: report (aca-ledger block and ReportPage ACA table "Gross premium")

No calculation record yet. The number is computed today in engine/src/projection/internal/types/aca.ts (YearAcaResult.grossEnrollmentPremium).

ACA modeled allowable PTC annual

Modeled allowable premium tax credit for the year; null when not modeled.

Field: ACA modeled premium tax credit Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: report (aca-ledger block and ReportPage ACA table "Modeled credit"); insights (aca-threshold-proximity card evidence "Modeled premium tax credit at stake" (evidence is not rendered at pin))

No calculation record yet. The number is computed today in engine/src/projection/internal/types/aca.ts (YearAcaResult.modeledAllowablePtc).

Display net care cost annual

Long-term-care cost remaining after the modeled insurance benefit, floored at zero.

Field: Displayed net care cost Unit: US dollars Basis: as displayed Computed by: UI transformation Status: Relocation pending

Appears in: chart (care)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/resultsRows.ts (buildExpenseRows).

IRMAA surcharge annual

Income-related Medicare premium surcharge charged during the projection year.

Field: irmaaSurcharge Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: scenarios-page (IRMAA surcharge); scenarios-page (Annual ledger comparison "IRMAA surcharge" and lifetime "IRMAA surcharge" sum)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.irmaaSurcharge).

MAGI annual

MAGI realized in a projection year for tax, ACA, and later IRMAA decisions.

Field: Modified adjusted gross income Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: chart (magi); csv (magi); survivor-page (Tax around the transition cell "on MAGI a → b" (death year and first survivor year)); results-table (MAGI column); report (year-ledger block magi); scenarios-page (Annual "MAGI"); mcp (run_projection.years[].magi)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.magi).

Medicare premiums annual

Total Medicare premiums charged to the household during the projection year.

Field: medicarePremiums Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: scenarios-page (Total Medicare premiums); scenarios-page (Annual ledger comparison "Medicare premiums" and lifetime "Total Medicare premiums" sum); survivor-page (SSA-44 premium savings column (difference of two runs of this value)); mcp (run_projection.years[].medicarePremiums)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.medicarePremiums).

Scenario IRMAA surcharge tier years

Count of projection years whose IRMAA tier is above 0.

Field: Years in an IRMAA surcharge tier Unit: count Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: scenarios-page (Medicare table "Years in a surcharge tier")

No calculation record yet. The number is computed today in engine/src/scenarios/comparison.ts (ScenarioIrmaaComparison.surchargeTierYears).

Spending healthcare annual

Healthcare expense charged in a projection year, excluding the separately shown insurance premium channel.

Field: Healthcare expense Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: chart (healthcare); csv (healthcare); cash-flow-drilldown (healthcare use line)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.expenses.healthcare).

Accounts balance per account annual

End-of-year balance of each plan account after flows and growth, keyed by account id.

Field: End-of-year balance per account Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: chart (Investable balances by account type (summed per category by display-balance-by-category-annual)); report (chart-data block per-category series (same category sum)); results-table (Inherited schedule and carryforward callouts read individual balances indirectly; no per-account column is printed)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.balances).

Accounts ending balance by category

End-of-plan balance summed by account category (cash, taxable, traditional, roth, hsa) over the selected logical balance accounts.

Field: Ending balance by category Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: results-headline (KpiBar "ending Roth $X" (endingByCategory.roth)); scenarios-page (Estate table Cash / Taxable / Traditional / Roth / HSA rows); mcp (run_projection.summary.endingByCategory); mcp (compare_scenarios.a.endingByCategory); mcp (compare_scenarios.b.endingByCategory)

No calculation record yet. The number is computed today in engine/src/projection/compare.ts (ProjectionSummary.endingByCategory).

Accounts investable total annual

Cash + taxable + traditional + Roth + HSA (+ unassigned) balances at year end.

Field: Investable total Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (investable); results-table (Investable column); report (year-ledger block investable and ReportPage year table); chart (Path to FI chart investable line); scenarios-page (Annual ledger comparison "Investable assets"); survivor-page (Survivor spending "low point" (minimum over survivor years)); results-table (Bucket lens investableTotal row and bucket sum); insights (spending-guardrails and hecm-buffer cards read year-one investableTotal)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.investableTotal).

Accounts net worth annual

Modeled total net worth at the end of a projection year.

Field: Net worth Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (netWorth); report (headlineResults); results-table (Net worth column); report (year-ledger block netWorth and ReportPage year table); scenarios-page (Annual "Net worth")

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.netWorth).

Display balance by category annual

Per year, the sum of per-account balances within each account category (cash, taxable, equityComp, traditional, roth, hsa).

Field: Balances by account type Unit: US dollars Basis: nominal dollars Computed by: UI transformation Status: Relocation pending

Appears in: chart (Investable balances by account type stacked areas); report (chart-data block cash/taxable/equityComp/traditional/roth/hsa and chartDataCsv)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/accountCategories.ts (categoryBalances); planner-ui/src/report/reportModel.ts (chartDataRows).

Estate to charity

Sum over accounts with a charity destination of gross balance times the charity share.

Field: Estate passing to charity Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: scenarios-page (Estate table "Charitable destination"); mcp (run_projection.summary.endingEstateToCharity); mcp (compare_scenarios.a.endingEstateToCharity); mcp (compare_scenarios.b.endingEstateToCharity)

No calculation record yet. The number is computed today in engine/src/projection/compare.ts (ProjectionSummary.endingEstateToCharity).

HECM draw annual

Tax-free HECM line-of-credit proceeds drawn this year (coordinated draws after down years plus last-resort backstop draws).

Field: HECM draw Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: cash-flow-drilldown (hecmCoordinatedDraw and hecmBackstopDraw source lines (YearCashFlow line identities))

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.hecmDraw).

Income taxable yield annual

Taxable account income recognized in a projection year.

Field: Taxable investment yield Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: chart (taxableYield); csv (taxableYield); scenarios-page (Lifetime income "Taxable yield"); cash-flow-drilldown (taxableAccountYield source line)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.incomes.taxableYield).

Pension election annuity present value

Present value of the lifetime pension annuity to the planning age at the curve-anchored discount rate, compared with the lump-sum offer.

Field: Pension annuity present value Unit: US dollars Basis: today's dollars (real) Computed by: Engine Status: No calculation record yet

Appears in: insights (pension-election-pending card rationale "the annuity's discounted value (~$X)" and the discount rate)

No calculation record yet. The number is computed today in engine/src/decisions/pensionElection.ts (analyzePensionElections (presentValueAtCurveRate, curveRatePct)).

Projection summary ending after tax estate

Ending net worth after estimated income tax on inherited pre-tax accounts.

Field: endingAfterTaxEstate Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: results-headline (ResultsPage / ReportPage KPI "After-tax estate"); report (headline-results block endingAfterTaxEstate); scenarios-page (Headline and estate table "Ending after-tax estate" / "After-tax estate to heirs"); compare-page (After-tax estate row); optimize-page (Objective the tournament ranks on; claim-age exact estates); solver-page (Evidence "Ending after-tax estate" and SWR rule rows); ss-page (Claim-age sweep, refinement, bridge comparison and survivor tables); relocation-page (Ending after-tax estate column (deflated for display)); monte-carlo-page (Historical stress windows "Estate" column); insights (spending-headroom card ending estate (deflated)); mcp (run_projection.summary.endingAfterTaxEstate); mcp (batch_evaluate.results[].objective); mcp (compare_scenarios.a.endingAfterTaxEstate); mcp (compare_scenarios.b.endingAfterTaxEstate)

No calculation record yet. The number is computed today in engine/src/projection/compare.ts (ProjectionSummary.endingAfterTaxEstate).

MCP batch ending traditional objective

Adapter sum of ending balances for traditional accounts in each evaluated candidate.

Field: Batch ending traditional balance objective Unit: US dollars Basis: nominal dollars Computed by: Adapter Status: No calculation record yet

Appears in: mcp (batch_evaluate.results[].objective)

No calculation record yet. The number is computed today outside the engine, in RetireGolden-MCP/src/adapter.ts in the RetireGolden-MCP repository (batchEvaluate).

Inherited distribution forced annual

Sum of executed required amounts and final-sweep amounts across inherited accounts this year (traditional and Roth character); voluntary draws excluded.

Field: Forced inherited-account distribution Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: cash-flow-drilldown (inheritedAccountDistribution source line)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.inheritedDistribution).

QCD annual

Gross qualified charitable distribution physically made in a projection year.

Field: Qualified charitable distribution Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: cash-flow-drilldown (QCD lines); csv (qcd); scenarios-page (Annual "QCD" and lifetime "QCDs")

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.qcd / qcdIncomeOffset).

RMD required annual

Required minimum distribution dollars taken during the projection year.

Field: requiredAmount Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (rmd); report (year ledger RMD); results-table (RMD column); scenarios-page (Annual "RMD" and lifetime "RMDs"); cash-flow-drilldown (requiredMinimumDistribution source line)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.rmd).

Optimizer recommended conversion annual

Per-year Roth conversion dollars the optimizer recommends: the solver schedule, the exact-ledger tournament winner's conversions, and the post-processed (cleaned) executable schedule.

Field: Recommended Roth conversion schedule Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: optimize-page (Conversion schedule chart bars and "N year(s)" schedule summary; post-processing adjustment list); report (modeled-findings winner conversions are summed into requested/executed totals); mcp (run_optimizer.schedule[].amount); mcp (run_optimizer.tournament.winnerConversions[].amount)

No calculation record yet. The number is computed today in engine/src/projection/optimizePlan.ts (ExactLedgerTournament.winnerConversions[].amount / ExactLedgerScheduleAdjustment.requested, executed, cleaned).

Optimizer schedule conversion total

Total dollars in a conversion schedule: the raw solver request, the cleaned executable schedule, or the tournament winner's conversions.

Field: Optimizer conversion schedule total Unit: US dollars Basis: nominal dollars Computed by: UI transformation Status: Relocation pending

Appears in: optimize-page ("$X of conversions across N years", "Raw optimizer request", "Cleaned executable schedule")

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/OptimizePage.tsx (totalScheduleConversions); planner-ui/src/planner/OptimizePage.tsx (OptimizePage).

Projection summary lifetime Roth conversions

Total traditional-account dollars converted to Roth across the projection.

Field: lifetimeRothConversions Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: report (Lifetime Roth conversions); results-headline (KpiBar "Roth converted"); report (headline-results block lifetimeRothConversions); mcp (run_projection.summary.lifetimeRothConversions); mcp (compare_scenarios.a.lifetimeRothConversions); mcp (compare_scenarios.b.lifetimeRothConversions)

No calculation record yet. The number is computed today in engine/src/projection/compare.ts (ProjectionSummary.lifetimeRothConversions).

Roth conversion annual

Traditional-to-Roth dollars actually converted in a projection year.

Field: Roth conversion Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (rothConversion); optimize-page (conversion schedule); report (yearLedger); results-table (Conversion column); scenarios-page (Annual "Roth conversion" and lifetime "Roth conversions"); cash-flow-drilldown (namedRothConversion and aggregateRothConversion transfer lines); mcp (run_projection.years[].rothConversion)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.rothConversion).

Funded ratio result essential spending PV

Present value of essential retirement spending over the funded-ratio horizon.

Field: essentialSpendingPv Unit: US dollars Basis: today's dollars (real) Computed by: Engine Status: Complete chain

Appears in: income-floor (essential spending valued today); insights (income-floor-funded card title and rationale (computeFundedRatio values))

• Funded ratio: present values of essential spending and guaranteed income Composition record, justified by derivation

  Purpose: How much of the essential-spending floor, valued on the TIPS curve, is covered by guaranteed income valued the same way.

  Statement: From the deterministic ledger years with calendar year >= fromYear (default: the start year), each year's expenses.requiredSpending and the sum incomes.socialSecurity + pension + annuity + tipsLadder are deflated to today's dollars by the caller-supplied deflator and discounted as real flows at offset t = year - startYear on the TIPS par curve (ladder-real-present-value; t = 0 is undiscounted). essentialSpendingPv = E, guaranteedIncomePv = G, fundedRatioPct = 100·G/E, unfundedPv = max(0, E - G). Returns null when there are no years or E <= 0. Units: real dollars and percent. Rounding: none.

  Formula: E = sum_t d_t S_t/(1 + y(t)/100)^t; G = sum_t d_t I_t/(1 + y(t)/100)^t; ratio = 100 G/E; unfunded = max(0, E - G)

  • t: Years from the start year to the ledger year (unit: years) (domain: integer t >= 0)
  • d_t: Deflator from nominal year-t dollars to today's dollars (unit: 1) (domain: d_t > 0)
  • S_t: Nominal required-floor spending in year t (unit: usd) (domain: S_t >= 0)
  • I_t: Nominal guaranteed income in year t (Social Security + pension + annuity + TIPS ladder) (unit: usd) (domain: I_t >= 0)
  • y(t): Interpolated par real yield at t years (unit: percent/year) (domain: y(t) > -100)

  Timing: end of year t, annual; the start year is t = 0 and undiscounted

  Rounding: none

  Limits:

  • Par yields are treated as spot rates: a planning convention, not a bootstrapped zero curve
  • Guaranteed income counts Social Security, pensions, annuities and TIPS-ladder flows only; wages and portfolio income are excluded by design
  • Years before fromYear are excluded from both sides; the horizon ends at the last ledger year
  • The deflator is supplied by the caller; the record assumes it maps nominal ledger dollars to the same real basis as the curve
  • Returns null rather than a ratio when the essential present value is not positive

  Provenance: derived by codex, implemented by claude-subagent.

  Independent review: cursor

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: funded-ratio-hand-present-value.md Mutation receipt: funded-ratio-hand-present-value.mutation.md

  Evidence tests: fundedRatio.evidence.test.ts

  Implemented in: fundedRatio.ts

  Is the number of: funded-ratio-result-essential-spending-pv, funded-ratio-result-guaranteed-income-pv, funded-ratio-result-funded-ratio-pct, funded-ratio-result-unfunded-pv

Fed by: Real present value of a cash-flow stream on the TIPS curve (formula record, 6 of 6 gates pass); Par real yield at a maturity: linear interpolation with flat endpoints (formula record, 6 of 6 gates pass); Embedded Treasury par real-yield curve, 2026-06-30 (data record, 6 of 6 gates pass). Open the family for each record's worksheet, receipt, tests and code.

Funded ratio result funded ratio pct

Percentage of essential retirement spending present value covered by guaranteed income.

Field: fundedRatioPct Unit: percent Basis: no dollar basis Computed by: Engine Status: Complete chain

Appears in: income-floor (essential floor funded percentage); insights (income-floor-funded card title and rationale (computeFundedRatio values))

• Funded ratio: present values of essential spending and guaranteed income Composition record, justified by derivation

  Purpose: How much of the essential-spending floor, valued on the TIPS curve, is covered by guaranteed income valued the same way.

  Statement: From the deterministic ledger years with calendar year >= fromYear (default: the start year), each year's expenses.requiredSpending and the sum incomes.socialSecurity + pension + annuity + tipsLadder are deflated to today's dollars by the caller-supplied deflator and discounted as real flows at offset t = year - startYear on the TIPS par curve (ladder-real-present-value; t = 0 is undiscounted). essentialSpendingPv = E, guaranteedIncomePv = G, fundedRatioPct = 100·G/E, unfundedPv = max(0, E - G). Returns null when there are no years or E <= 0. Units: real dollars and percent. Rounding: none.

  Formula: E = sum_t d_t S_t/(1 + y(t)/100)^t; G = sum_t d_t I_t/(1 + y(t)/100)^t; ratio = 100 G/E; unfunded = max(0, E - G)

  • t: Years from the start year to the ledger year (unit: years) (domain: integer t >= 0)
  • d_t: Deflator from nominal year-t dollars to today's dollars (unit: 1) (domain: d_t > 0)
  • S_t: Nominal required-floor spending in year t (unit: usd) (domain: S_t >= 0)
  • I_t: Nominal guaranteed income in year t (Social Security + pension + annuity + TIPS ladder) (unit: usd) (domain: I_t >= 0)
  • y(t): Interpolated par real yield at t years (unit: percent/year) (domain: y(t) > -100)

  Timing: end of year t, annual; the start year is t = 0 and undiscounted

  Rounding: none

  Limits:

  • Par yields are treated as spot rates: a planning convention, not a bootstrapped zero curve
  • Guaranteed income counts Social Security, pensions, annuities and TIPS-ladder flows only; wages and portfolio income are excluded by design
  • Years before fromYear are excluded from both sides; the horizon ends at the last ledger year
  • The deflator is supplied by the caller; the record assumes it maps nominal ledger dollars to the same real basis as the curve
  • Returns null rather than a ratio when the essential present value is not positive

  Provenance: derived by codex, implemented by claude-subagent.

  Independent review: cursor

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: funded-ratio-hand-present-value.md Mutation receipt: funded-ratio-hand-present-value.mutation.md

  Evidence tests: fundedRatio.evidence.test.ts

  Implemented in: fundedRatio.ts

  Is the number of: funded-ratio-result-essential-spending-pv, funded-ratio-result-guaranteed-income-pv, funded-ratio-result-funded-ratio-pct, funded-ratio-result-unfunded-pv

Fed by: Real present value of a cash-flow stream on the TIPS curve (formula record, 6 of 6 gates pass); Par real yield at a maturity: linear interpolation with flat endpoints (formula record, 6 of 6 gates pass); Embedded Treasury par real-yield curve, 2026-06-30 (data record, 6 of 6 gates pass). Open the family for each record's worksheet, receipt, tests and code.

Funded ratio result guaranteed income PV

Present value of guaranteed retirement income over the funded-ratio horizon.

Field: guaranteedIncomePv Unit: US dollars Basis: today's dollars (real) Computed by: Engine Status: Complete chain

Appears in: income-floor (guaranteed income valued today); insights (income-floor-funded card title and rationale (computeFundedRatio values))

• Funded ratio: present values of essential spending and guaranteed income Composition record, justified by derivation

  Purpose: How much of the essential-spending floor, valued on the TIPS curve, is covered by guaranteed income valued the same way.

  Statement: From the deterministic ledger years with calendar year >= fromYear (default: the start year), each year's expenses.requiredSpending and the sum incomes.socialSecurity + pension + annuity + tipsLadder are deflated to today's dollars by the caller-supplied deflator and discounted as real flows at offset t = year - startYear on the TIPS par curve (ladder-real-present-value; t = 0 is undiscounted). essentialSpendingPv = E, guaranteedIncomePv = G, fundedRatioPct = 100·G/E, unfundedPv = max(0, E - G). Returns null when there are no years or E <= 0. Units: real dollars and percent. Rounding: none.

  Formula: E = sum_t d_t S_t/(1 + y(t)/100)^t; G = sum_t d_t I_t/(1 + y(t)/100)^t; ratio = 100 G/E; unfunded = max(0, E - G)

  • t: Years from the start year to the ledger year (unit: years) (domain: integer t >= 0)
  • d_t: Deflator from nominal year-t dollars to today's dollars (unit: 1) (domain: d_t > 0)
  • S_t: Nominal required-floor spending in year t (unit: usd) (domain: S_t >= 0)
  • I_t: Nominal guaranteed income in year t (Social Security + pension + annuity + TIPS ladder) (unit: usd) (domain: I_t >= 0)
  • y(t): Interpolated par real yield at t years (unit: percent/year) (domain: y(t) > -100)

  Timing: end of year t, annual; the start year is t = 0 and undiscounted

  Rounding: none

  Limits:

  • Par yields are treated as spot rates: a planning convention, not a bootstrapped zero curve
  • Guaranteed income counts Social Security, pensions, annuities and TIPS-ladder flows only; wages and portfolio income are excluded by design
  • Years before fromYear are excluded from both sides; the horizon ends at the last ledger year
  • The deflator is supplied by the caller; the record assumes it maps nominal ledger dollars to the same real basis as the curve
  • Returns null rather than a ratio when the essential present value is not positive

  Provenance: derived by codex, implemented by claude-subagent.

  Independent review: cursor

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: funded-ratio-hand-present-value.md Mutation receipt: funded-ratio-hand-present-value.mutation.md

  Evidence tests: fundedRatio.evidence.test.ts

  Implemented in: fundedRatio.ts

  Is the number of: funded-ratio-result-essential-spending-pv, funded-ratio-result-guaranteed-income-pv, funded-ratio-result-funded-ratio-pct, funded-ratio-result-unfunded-pv

Fed by: Real present value of a cash-flow stream on the TIPS curve (formula record, 6 of 6 gates pass); Par real yield at a maturity: linear interpolation with flat endpoints (formula record, 6 of 6 gates pass); Embedded Treasury par real-yield curve, 2026-06-30 (data record, 6 of 6 gates pass). Open the family for each record's worksheet, receipt, tests and code.

Funded ratio result unfunded PV

Essential-spending present value left for the portfolio after guaranteed income.

Field: unfundedPv Unit: US dollars Basis: today's dollars (real) Computed by: Engine Status: Complete chain

Appears in: income-floor (gap riding on the portfolio); insights (income-floor-funded card title and rationale (computeFundedRatio values))

• Funded ratio: present values of essential spending and guaranteed income Composition record, justified by derivation

  Purpose: How much of the essential-spending floor, valued on the TIPS curve, is covered by guaranteed income valued the same way.

  Statement: From the deterministic ledger years with calendar year >= fromYear (default: the start year), each year's expenses.requiredSpending and the sum incomes.socialSecurity + pension + annuity + tipsLadder are deflated to today's dollars by the caller-supplied deflator and discounted as real flows at offset t = year - startYear on the TIPS par curve (ladder-real-present-value; t = 0 is undiscounted). essentialSpendingPv = E, guaranteedIncomePv = G, fundedRatioPct = 100·G/E, unfundedPv = max(0, E - G). Returns null when there are no years or E <= 0. Units: real dollars and percent. Rounding: none.

  Formula: E = sum_t d_t S_t/(1 + y(t)/100)^t; G = sum_t d_t I_t/(1 + y(t)/100)^t; ratio = 100 G/E; unfunded = max(0, E - G)

  • t: Years from the start year to the ledger year (unit: years) (domain: integer t >= 0)
  • d_t: Deflator from nominal year-t dollars to today's dollars (unit: 1) (domain: d_t > 0)
  • S_t: Nominal required-floor spending in year t (unit: usd) (domain: S_t >= 0)
  • I_t: Nominal guaranteed income in year t (Social Security + pension + annuity + TIPS ladder) (unit: usd) (domain: I_t >= 0)
  • y(t): Interpolated par real yield at t years (unit: percent/year) (domain: y(t) > -100)

  Timing: end of year t, annual; the start year is t = 0 and undiscounted

  Rounding: none

  Limits:

  • Par yields are treated as spot rates: a planning convention, not a bootstrapped zero curve
  • Guaranteed income counts Social Security, pensions, annuities and TIPS-ladder flows only; wages and portfolio income are excluded by design
  • Years before fromYear are excluded from both sides; the horizon ends at the last ledger year
  • The deflator is supplied by the caller; the record assumes it maps nominal ledger dollars to the same real basis as the curve
  • Returns null rather than a ratio when the essential present value is not positive

  Provenance: derived by codex, implemented by claude-subagent.

  Independent review: cursor

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: funded-ratio-hand-present-value.md Mutation receipt: funded-ratio-hand-present-value.mutation.md

  Evidence tests: fundedRatio.evidence.test.ts

  Implemented in: fundedRatio.ts

  Is the number of: funded-ratio-result-essential-spending-pv, funded-ratio-result-guaranteed-income-pv, funded-ratio-result-funded-ratio-pct, funded-ratio-result-unfunded-pv

Fed by: Real present value of a cash-flow stream on the TIPS curve (formula record, 6 of 6 gates pass); Par real yield at a maturity: linear interpolation with flat endpoints (formula record, 6 of 6 gates pass); Embedded Treasury par real-yield curve, 2026-06-30 (data record, 6 of 6 gates pass). Open the family for each record's worksheet, receipt, tests and code.

Income floor ladder yield pct

Annual real income generated by the modeled ladder as a percentage of its total purchase cost.

Field: Income-floor ladder yield Unit: percent Basis: no dollar basis Computed by: UI transformation Status: Relocation pending

Appears in: income-floor (annual real income as percent of total cost)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/sections/IncomeFloorSection.tsx (IncomeFloorSection).

Fed by: Par real yield at a maturity: linear interpolation with flat endpoints (formula record, 6 of 6 gates pass); Embedded Treasury par real-yield curve, 2026-06-30 (data record, 6 of 6 gates pass). Open the family for each record's worksheet, receipt, tests and code.

Income TIPS ladder annual

Income paid by the modeled TIPS ladder during the projection year.

Field: tipsLadder Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (tipsLadder); scenarios-page (Lifetime income "TIPS ladder"); chart (Income by source "TIPS ladder" series); cash-flow-drilldown (tipsLadderCash source line)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.incomes.tipsLadder).

Ladder build annual real income by offset

Real annual income delivered by the modeled ladder in each future year.

Field: annualRealIncomeByOffset Unit: US dollars Basis: today's dollars (real) Computed by: Engine Status: Complete chain

Appears in: income-floor (ladder income by year)

• Level-real-income ladder: faces solved back to front Formula record, justified by derivation

  Purpose: The face amount of each rung so that every payout year's maturing principal plus the coupons of the rungs still outstanding equals the target real income.

  Statement: For target real income A, first payout offset p and payout count q (each rounded to an integer and clamped to at least 1), rungs mature at offsets m = p..p+q-1 with coupon rates c_m = max(0.125%, y(m))/100. Faces are solved from the last offset backward: F_m = max(0, (A - sum over later offsets j of F_j c_j)/(1 + c_m)), so that F_m(1 + c_m) plus the coupons of every rung still outstanding equals A in year m. Each rung is then priced on the curve (ladder-annual-coupon-par-pricing); totalCost is the sum of rung costs; annualRealIncomeByOffset lists coupons plus maturing principal for offsets 1..p+q-1 (coupon-only inside a deferral window); targetAnnualRealIncome echoes A. Units: real (today's) dollars. Rounding: none.

  Formula: F_m = max(0, (A - sum_{j>m} F_j c_j) / (1 + c_m)) for m from last to first; income_m = F_m (1 + c_m) + sum_{j>m} F_j c_j = A

  • A: Level real income target per payout year (unit: usd) (domain: A >= 0)
  • m: Maturity offset of a rung (unit: years) (domain: integer, p <= m <= p+q-1, p >= 1)
  • c_m: Coupon rate of the rung maturing at m, as a fraction (unit: 1) (domain: c_m >= 0.00125)
  • F_m: Real face of the rung maturing at m (unit: usd) (domain: F_m >= 0)

  Timing: end of year, annual; the rung maturing in year m pays its last coupon and principal that year

  Rounding: none

  Limits:

  • Faces are floored at zero: a target smaller than the later rungs' coupons yields a zero-face rung and that year then receives more than the target
  • Payout offset and count are rounded and clamped to at least 1 rather than rejected
  • Coupons pay annually and par yields serve as spot rates for pricing (ladderMath.ts header simplifications)
  • No CUSIP-level lot rounding in core mode; faces are continuous

  Provenance: derived by codex, implemented by claude-subagent.

  Independent review: cursor

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: ladder-backward-face-construction.md Mutation receipt: ladder-backward-face-construction.mutation.md

  Evidence tests: ladderMath.evidence.test.ts

  Implemented in: ladderMath.ts

  Is the number of: ladder-rung-face, ladder-build-annual-real-income-by-offset, ladder-build-total-cost, ladder-build-target-annual-real-income

Ladder build target annual real income

Real annual income the ladder is designed to deliver.

Field: targetAnnualRealIncome Unit: US dollars Basis: today's dollars (real) Computed by: Engine Status: Complete chain

Appears in: income-floor (target annual real income)

• Level-real-income ladder: faces solved back to front Formula record, justified by derivation

  Purpose: The face amount of each rung so that every payout year's maturing principal plus the coupons of the rungs still outstanding equals the target real income.

  Statement: For target real income A, first payout offset p and payout count q (each rounded to an integer and clamped to at least 1), rungs mature at offsets m = p..p+q-1 with coupon rates c_m = max(0.125%, y(m))/100. Faces are solved from the last offset backward: F_m = max(0, (A - sum over later offsets j of F_j c_j)/(1 + c_m)), so that F_m(1 + c_m) plus the coupons of every rung still outstanding equals A in year m. Each rung is then priced on the curve (ladder-annual-coupon-par-pricing); totalCost is the sum of rung costs; annualRealIncomeByOffset lists coupons plus maturing principal for offsets 1..p+q-1 (coupon-only inside a deferral window); targetAnnualRealIncome echoes A. Units: real (today's) dollars. Rounding: none.

  Formula: F_m = max(0, (A - sum_{j>m} F_j c_j) / (1 + c_m)) for m from last to first; income_m = F_m (1 + c_m) + sum_{j>m} F_j c_j = A

  • A: Level real income target per payout year (unit: usd) (domain: A >= 0)
  • m: Maturity offset of a rung (unit: years) (domain: integer, p <= m <= p+q-1, p >= 1)
  • c_m: Coupon rate of the rung maturing at m, as a fraction (unit: 1) (domain: c_m >= 0.00125)
  • F_m: Real face of the rung maturing at m (unit: usd) (domain: F_m >= 0)

  Timing: end of year, annual; the rung maturing in year m pays its last coupon and principal that year

  Rounding: none

  Limits:

  • Faces are floored at zero: a target smaller than the later rungs' coupons yields a zero-face rung and that year then receives more than the target
  • Payout offset and count are rounded and clamped to at least 1 rather than rejected
  • Coupons pay annually and par yields serve as spot rates for pricing (ladderMath.ts header simplifications)
  • No CUSIP-level lot rounding in core mode; faces are continuous

  Provenance: derived by codex, implemented by claude-subagent.

  Independent review: cursor

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: ladder-backward-face-construction.md Mutation receipt: ladder-backward-face-construction.mutation.md

  Evidence tests: ladderMath.evidence.test.ts

  Implemented in: ladderMath.ts

  Is the number of: ladder-rung-face, ladder-build-annual-real-income-by-offset, ladder-build-total-cost, ladder-build-target-annual-real-income

Ladder build total cost

Purchase cost of all rungs in the modeled income-floor ladder.

Field: totalCost Unit: US dollars Basis: today's dollars (real) Computed by: Engine Status: Complete chain

Appears in: income-floor (ladder total cost)

• Level-real-income ladder: faces solved back to front Formula record, justified by derivation

  Purpose: The face amount of each rung so that every payout year's maturing principal plus the coupons of the rungs still outstanding equals the target real income.

  Statement: For target real income A, first payout offset p and payout count q (each rounded to an integer and clamped to at least 1), rungs mature at offsets m = p..p+q-1 with coupon rates c_m = max(0.125%, y(m))/100. Faces are solved from the last offset backward: F_m = max(0, (A - sum over later offsets j of F_j c_j)/(1 + c_m)), so that F_m(1 + c_m) plus the coupons of every rung still outstanding equals A in year m. Each rung is then priced on the curve (ladder-annual-coupon-par-pricing); totalCost is the sum of rung costs; annualRealIncomeByOffset lists coupons plus maturing principal for offsets 1..p+q-1 (coupon-only inside a deferral window); targetAnnualRealIncome echoes A. Units: real (today's) dollars. Rounding: none.

  Formula: F_m = max(0, (A - sum_{j>m} F_j c_j) / (1 + c_m)) for m from last to first; income_m = F_m (1 + c_m) + sum_{j>m} F_j c_j = A

  • A: Level real income target per payout year (unit: usd) (domain: A >= 0)
  • m: Maturity offset of a rung (unit: years) (domain: integer, p <= m <= p+q-1, p >= 1)
  • c_m: Coupon rate of the rung maturing at m, as a fraction (unit: 1) (domain: c_m >= 0.00125)
  • F_m: Real face of the rung maturing at m (unit: usd) (domain: F_m >= 0)

  Timing: end of year, annual; the rung maturing in year m pays its last coupon and principal that year

  Rounding: none

  Limits:

  • Faces are floored at zero: a target smaller than the later rungs' coupons yields a zero-face rung and that year then receives more than the target
  • Payout offset and count are rounded and clamped to at least 1 rather than rejected
  • Coupons pay annually and par yields serve as spot rates for pricing (ladderMath.ts header simplifications)
  • No CUSIP-level lot rounding in core mode; faces are continuous

  Provenance: derived by codex, implemented by claude-subagent.

  Independent review: cursor

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: ladder-backward-face-construction.md Mutation receipt: ladder-backward-face-construction.mutation.md

  Evidence tests: ladderMath.evidence.test.ts

  Implemented in: ladderMath.ts

  Is the number of: ladder-rung-face, ladder-build-annual-real-income-by-offset, ladder-build-total-cost, ladder-build-target-annual-real-income

Fed by: Synthetic TIPS rung: floored coupon and par-curve price (formula record, 6 of 6 gates pass); Embedded Treasury par real-yield curve, 2026-06-30 (data record, 6 of 6 gates pass). Open the family for each record's worksheet, receipt, tests and code.

Ladder real flows coupons

Inflation-adjusted coupon cash flow paid by ladder holdings in a year.

Field: coupons Unit: US dollars Basis: today's dollars (real) Computed by: Engine Status: Complete chain

Appears in: income-floor (coupon cash flow)

• Ladder cash flows in a year and face outstanding after it Formula record, justified by derivation

  Purpose: The real coupons, maturing principal and outstanding face of a rung set in one year, and the face still outstanding once that year completes.

  Statement: For a rung set and an integer offset k >= 1: coupons = sum over rungs with maturity offset >= k of F·c/100; maturingPrincipal = sum of F over rungs with maturity offset = k; outstandingFace = sum of F over rungs with maturity offset >= k, the maturing rung included so it earns its last coupon and its inflation accretion. ladderRemainingFace(k) = sum of F over rungs with maturity offset > k, the face still outstanding after year k completes. Units: real (today's) dollars. Rounding: none.

  Formula: coupons_k = sum_{m >= k} F_m c_m/100; maturing_k = sum_{m = k} F_m; outstanding_k = sum_{m >= k} F_m; remaining_k = sum_{m > k} F_m

  • k: Year offset from the anchor year (unit: years) (domain: integer k >= 1)
  • F_m: Real face of the rung maturing at offset m (unit: usd) (domain: F_m >= 0)
  • c_m: Annual coupon rate of that rung (unit: percent/year) (domain: c_m >= 0.125)

  Timing: annual; a rung is outstanding through the year it matures and gone the year after

  Rounding: none

  Limits:

  • Values are real (today's) dollars; the ledger multiplies by its own inflation path to index them
  • ladder-value-annual is the ledger's nominal figure: ladderRemainingFace at the year's offset times the purchase scale and the year's inflation factor (projection/internal/tipsLadderAnnualCashFlow.ts); this record pins the remaining-face half of that product
  • Offsets are whole years by construction; a fractional offset matches no maturity

  Provenance: derived by codex, implemented by claude-subagent.

  Independent review: cursor

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: ladder-rung-flows-and-remaining-face.md Mutation receipt: ladder-rung-flows-and-remaining-face.mutation.md

  Evidence tests: ladderMath.evidence.test.ts

  Implemented in: ladderMath.ts

  Is the number of: ladder-real-flows-coupons, ladder-real-flows-maturing-principal

  Feeds: ladder-value-annual

Ladder real flows maturing principal

Inflation-adjusted principal returned by ladder holdings maturing in a year.

Field: maturingPrincipal Unit: US dollars Basis: today's dollars (real) Computed by: Engine Status: Complete chain

Appears in: income-floor (maturing principal cash flow)

• Ladder cash flows in a year and face outstanding after it Formula record, justified by derivation

  Purpose: The real coupons, maturing principal and outstanding face of a rung set in one year, and the face still outstanding once that year completes.

  Statement: For a rung set and an integer offset k >= 1: coupons = sum over rungs with maturity offset >= k of F·c/100; maturingPrincipal = sum of F over rungs with maturity offset = k; outstandingFace = sum of F over rungs with maturity offset >= k, the maturing rung included so it earns its last coupon and its inflation accretion. ladderRemainingFace(k) = sum of F over rungs with maturity offset > k, the face still outstanding after year k completes. Units: real (today's) dollars. Rounding: none.

  Formula: coupons_k = sum_{m >= k} F_m c_m/100; maturing_k = sum_{m = k} F_m; outstanding_k = sum_{m >= k} F_m; remaining_k = sum_{m > k} F_m

  • k: Year offset from the anchor year (unit: years) (domain: integer k >= 1)
  • F_m: Real face of the rung maturing at offset m (unit: usd) (domain: F_m >= 0)
  • c_m: Annual coupon rate of that rung (unit: percent/year) (domain: c_m >= 0.125)

  Timing: annual; a rung is outstanding through the year it matures and gone the year after

  Rounding: none

  Limits:

  • Values are real (today's) dollars; the ledger multiplies by its own inflation path to index them
  • ladder-value-annual is the ledger's nominal figure: ladderRemainingFace at the year's offset times the purchase scale and the year's inflation factor (projection/internal/tipsLadderAnnualCashFlow.ts); this record pins the remaining-face half of that product
  • Offsets are whole years by construction; a fractional offset matches no maturity

  Provenance: derived by codex, implemented by claude-subagent.

  Independent review: cursor

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: ladder-rung-flows-and-remaining-face.md Mutation receipt: ladder-rung-flows-and-remaining-face.mutation.md

  Evidence tests: ladderMath.evidence.test.ts

  Implemented in: ladderMath.ts

  Is the number of: ladder-real-flows-coupons, ladder-real-flows-maturing-principal

  Feeds: ladder-value-annual

Ladder rung cost

Purchase cost of a single modeled ladder rung.

Field: cost Unit: US dollars Basis: today's dollars (real) Computed by: Engine Status: Complete chain

Appears in: income-floor (rung cost)

• Synthetic TIPS rung: floored coupon and par-curve price Formula record, justified by derivation

  Purpose: What one ladder rung costs today: its annual real coupons and principal discounted on the curve, with the coupon set to the yield at maturity floored at 0.125%.

  Statement: For a rung of real face F maturing n whole years out, the coupon rate is c = max(0.125%, y(n)), where y(n) is the interpolated par real yield at n years. The price is the sum over k = 1..n of (F·c/100 + [k = n]·F)/(1 + y(k)/100)^k: each end-of-year cash flow discounted at the interpolated par yield for its own year treated as a spot rate. On a flat curve with a nonbinding floor c = y and the price equals F. Units: real (today's) dollars; percent inputs are divided by 100. Domain: F >= 0, integer n >= 1, y(k) > -100%. Rounding: none.

  Formula: c = max(0.125, y(n)); P = sum_{k=1..n} (F c/100 + [k = n] F) / (1 + y(k)/100)^k

  • F: Real face (principal) of the rung (unit: usd) (domain: F >= 0)
  • n: Maturity offset from the anchor year (unit: years) (domain: integer n >= 1)
  • y(k): Interpolated par real yield at k years (unit: percent/year) (domain: y(k) > -100)
  • c: Annual coupon rate of the synthetic rung (unit: percent/year) (domain: c >= 0.125)
  • P: Real purchase price of the rung (unit: usd) (domain: P >= 0)

  Timing: end of year, annual coupons, principal with the last coupon

  Rounding: none

  Limits:

  • Coupons pay annually; real-world semiannual TIPS timing is ignored (ladderMath.ts header)
  • Par yields are used as spot rates for discounting; no zero curve is bootstrapped (ladderMath.ts header)
  • The 0.125% floor is the regulatory minimum TIPS coupon; a curve yield below it prices the rung above par
  • No CUSIP-level lot rounding in core mode: face is continuous at $1 granularity (ladderMath.ts header)
  • tipsCouponRatePct and priceRung are module-private; the evidence reaches them through buildLadder with a one-rung ladder whose target is F(1 + c), which the back-substitution solves to face F exactly

  Provenance: derived by codex, implemented by claude-subagent.

  Independent review: cursor

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: ladder-annual-coupon-par-pricing.md Mutation receipt: ladder-annual-coupon-par-pricing.mutation.md

  Evidence tests: ladderMath.evidence.test.ts

  Implemented in: ladderMath.ts

  Is the number of: ladder-rung-cost, ladder-rung-coupon-rate-pct

  Feeds: ladder-build-total-cost

Fed by: FedInvest security-price CSV: TIPS rows to reference records (data record, 6 of 6 gates pass); Latest FedInvest price date: previous business day in local time (model record, 6 of 6 gates pass); Nearest FedInvest TIPS for a rung year (formula record, 6 of 6 gates pass); Real present value of a cash-flow stream on the TIPS curve (formula record, 6 of 6 gates pass); Embedded Treasury par real-yield curve, 2026-06-30 (data record, 6 of 6 gates pass). Open the family for each record's worksheet, receipt, tests and code.

Ladder rung coupon rate pct

Annual real coupon rate of a modeled ladder rung.

Field: couponRatePct Unit: percent Basis: no dollar basis Computed by: Engine Status: Complete chain

Appears in: income-floor (coupon rate)

• Synthetic TIPS rung: floored coupon and par-curve price Formula record, justified by derivation

  Purpose: What one ladder rung costs today: its annual real coupons and principal discounted on the curve, with the coupon set to the yield at maturity floored at 0.125%.

  Statement: For a rung of real face F maturing n whole years out, the coupon rate is c = max(0.125%, y(n)), where y(n) is the interpolated par real yield at n years. The price is the sum over k = 1..n of (F·c/100 + [k = n]·F)/(1 + y(k)/100)^k: each end-of-year cash flow discounted at the interpolated par yield for its own year treated as a spot rate. On a flat curve with a nonbinding floor c = y and the price equals F. Units: real (today's) dollars; percent inputs are divided by 100. Domain: F >= 0, integer n >= 1, y(k) > -100%. Rounding: none.

  Formula: c = max(0.125, y(n)); P = sum_{k=1..n} (F c/100 + [k = n] F) / (1 + y(k)/100)^k

  • F: Real face (principal) of the rung (unit: usd) (domain: F >= 0)
  • n: Maturity offset from the anchor year (unit: years) (domain: integer n >= 1)
  • y(k): Interpolated par real yield at k years (unit: percent/year) (domain: y(k) > -100)
  • c: Annual coupon rate of the synthetic rung (unit: percent/year) (domain: c >= 0.125)
  • P: Real purchase price of the rung (unit: usd) (domain: P >= 0)

  Timing: end of year, annual coupons, principal with the last coupon

  Rounding: none

  Limits:

  • Coupons pay annually; real-world semiannual TIPS timing is ignored (ladderMath.ts header)
  • Par yields are used as spot rates for discounting; no zero curve is bootstrapped (ladderMath.ts header)
  • The 0.125% floor is the regulatory minimum TIPS coupon; a curve yield below it prices the rung above par
  • No CUSIP-level lot rounding in core mode: face is continuous at $1 granularity (ladderMath.ts header)
  • tipsCouponRatePct and priceRung are module-private; the evidence reaches them through buildLadder with a one-rung ladder whose target is F(1 + c), which the back-substitution solves to face F exactly

  Provenance: derived by codex, implemented by claude-subagent.

  Independent review: cursor

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: ladder-annual-coupon-par-pricing.md Mutation receipt: ladder-annual-coupon-par-pricing.mutation.md

  Evidence tests: ladderMath.evidence.test.ts

  Implemented in: ladderMath.ts

  Is the number of: ladder-rung-cost, ladder-rung-coupon-rate-pct

  Feeds: ladder-build-total-cost

Fed by: Par real yield at a maturity: linear interpolation with flat endpoints (formula record, 6 of 6 gates pass); Embedded Treasury par real-yield curve, 2026-06-30 (data record, 6 of 6 gates pass). Open the family for each record's worksheet, receipt, tests and code.

Ladder rung face

Face value purchased for a modeled ladder rung.

Field: face Unit: US dollars Basis: today's dollars (real) Computed by: Engine Status: Complete chain

Appears in: income-floor (face value)

• Level-real-income ladder: faces solved back to front Formula record, justified by derivation

  Purpose: The face amount of each rung so that every payout year's maturing principal plus the coupons of the rungs still outstanding equals the target real income.

  Statement: For target real income A, first payout offset p and payout count q (each rounded to an integer and clamped to at least 1), rungs mature at offsets m = p..p+q-1 with coupon rates c_m = max(0.125%, y(m))/100. Faces are solved from the last offset backward: F_m = max(0, (A - sum over later offsets j of F_j c_j)/(1 + c_m)), so that F_m(1 + c_m) plus the coupons of every rung still outstanding equals A in year m. Each rung is then priced on the curve (ladder-annual-coupon-par-pricing); totalCost is the sum of rung costs; annualRealIncomeByOffset lists coupons plus maturing principal for offsets 1..p+q-1 (coupon-only inside a deferral window); targetAnnualRealIncome echoes A. Units: real (today's) dollars. Rounding: none.

  Formula: F_m = max(0, (A - sum_{j>m} F_j c_j) / (1 + c_m)) for m from last to first; income_m = F_m (1 + c_m) + sum_{j>m} F_j c_j = A

  • A: Level real income target per payout year (unit: usd) (domain: A >= 0)
  • m: Maturity offset of a rung (unit: years) (domain: integer, p <= m <= p+q-1, p >= 1)
  • c_m: Coupon rate of the rung maturing at m, as a fraction (unit: 1) (domain: c_m >= 0.00125)
  • F_m: Real face of the rung maturing at m (unit: usd) (domain: F_m >= 0)

  Timing: end of year, annual; the rung maturing in year m pays its last coupon and principal that year

  Rounding: none

  Limits:

  • Faces are floored at zero: a target smaller than the later rungs' coupons yields a zero-face rung and that year then receives more than the target
  • Payout offset and count are rounded and clamped to at least 1 rather than rejected
  • Coupons pay annually and par yields serve as spot rates for pricing (ladderMath.ts header simplifications)
  • No CUSIP-level lot rounding in core mode; faces are continuous

  Provenance: derived by codex, implemented by claude-subagent.

  Independent review: cursor

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: ladder-backward-face-construction.md Mutation receipt: ladder-backward-face-construction.mutation.md

  Evidence tests: ladderMath.evidence.test.ts

  Implemented in: ladderMath.ts

  Is the number of: ladder-rung-face, ladder-build-annual-real-income-by-offset, ladder-build-total-cost, ladder-build-target-annual-real-income

Ladder value annual

Value of the modeled bond/TIPS ladder in a projection year.

Field: Ladder value Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (ladderValue)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.ladderValue).

Fed by: Ladder cash flows in a year and face outstanding after it (formula record, 6 of 6 gates pass). Open the family for each record's worksheet, receipt, tests and code.

Display years before plan end

How many years before the plan horizon the portfolio depletes.

Field: Years depleted before plan end Unit: years Basis: no dollar basis Computed by: UI transformation Status: Relocation pending

Appears in: results-headline (Depletion narrative "depletes N years before the plan ends")

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/ResultsPage.tsx (ResultsPage).

Longevity depletion year

First projection year with any spending shortfall; null when investable assets last through the horizon.

Field: Depletion year Unit: calendar year Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: results-headline (KpiBar "Money lasts ... until YEAR"); results-headline (ResultsPage narrative "This plan runs out of money in YEAR"); results-table (Balances chart "depleted" reference line and "Portfolio depletes in YEAR" callout); report (headline-results block depletionYear); compare-page (Money lasts row); scenarios-page (Headline "Depletion year"); ss-page (Bridge comparison and claim-age tables "until YEAR / never"); survivor-page (Degenerate-timings note "runs out of money in YEAR"); relocation-page (RelocationCandidateRow.depletionYear (carried)); monte-carlo-page (Historical stress windows "Depletes" column); insights (InsightCardView flat-delta note "The base plan runs out of money in YEAR")

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (ProjectionResult.depletionYear).

Longevity survival percentile age

The oldest integer age a person reaches with probability at least pct/100 on the SSA period life table, optionally with a health hazard multiplier and a joint (either-survives) curve for a couple.

Field: Survival-percentile planning age Unit: age in years Basis: no dollar basis Computed by: Engine Status: Complete chain

Appears in: assumptions-card (SurvivalPercentileModal planning-age preview (household section), clamped to 60..120 before it becomes the plan's planning age)

• Joint (either-survives) percentile age on the primary's age clock Formula record, justified by derivation

  Purpose: The couple's planning age: the oldest primary age at which at least one of two independent lives is alive with probability at least pct/100.

  Statement: With from = floor(max(primary.age, 0)), partnerFrom = floor(max(partner.age, 0)) and threshold = min(max(p, 0.1), 100)/100: for t = 0, 1, ... while from + t <= 120, let P(t) = 1 - (1 - S_primary(t))(1 - S_partner(t)), where each S(t) is the product of (1 - q)^h over the t ages from that person's own starting age under that person's hazard (default 1). Record best = from + t while P(t) >= threshold; stop at the first t below the threshold, or once both survivals are 0. Returns best; P(0) = 1, so the result is always >= from and never below the primary's single-life answer. Units: integer primary age. Rounding: none.

  Formula: age* = max{ from + t : 1 - (1 - S_primary(t))(1 - S_partner(t)) >= p/100 }

  • from, partnerFrom: Floored current ages of primary and partner (unit: years) (domain: integer >= 0)
  • t: Years elapsed on the primary's clock (unit: years) (domain: integer >= 0, from + t <= 120)
  • S_primary(t), S_partner(t): Each life's survival over t more years (survival-probability-product) (unit: 1) (domain: [0, 1])
  • p: Percent chance that at least one is alive, clamped to [0.1, 100] (unit: percent) (domain: 0.1 <= p <= 100)

  Timing: annual; both curves advance one year per step on the primary's clock

  Rounding: none

  Limits:

  • Independent lifetimes; the either-alive probability is the complement of both being dead, 1 - (1 - S_a)(1 - S_b)
  • The partner's clock is offset by the age difference and advances with the primary's; the answer is a primary age, not a partner age
  • The percentage is clamped to [0.1, 100] before use, a bound the signature comment does not state
  • Each person's hazard power applies to that person's own curve; a missing hazard is 1

  Provenance: derived by codex, implemented by claude-subagent.

  Independent review: cursor

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: joint-survival-percentile-age.md Mutation receipt: joint-survival-percentile-age.mutation.md

  Evidence tests: survival.evidence.test.ts

  Implemented in: survival.ts

  Is the number of: longevity-survival-percentile-age

• Survival-percentile planning age: oldest age reached with probability at least pct/100 Formula record, justified by derivation

  Purpose: The single-life planning age the assumptions card previews: the age a person has a pct% chance of reaching.

  Statement: For current age c, sex, percentage p and hazard power h (default 1): threshold = min(max(p, 0.1), 100)/100. Starting at from = floor(max(c, 0)) with S = 1 and best = from, for x = from..119 multiply S by (1 - q(x))^h; while S >= threshold record best = x + 1, and stop at the first x whose S falls below the threshold. Returns best: the oldest integer age whose conditional survival from c is at least the threshold, always >= from. Units: integer age. Rounding: none.

  Formula: age* = max{ g >= from : S(from -> g) >= p/100 }, with S(from -> from) = 1

  • from: Floored current age (unit: years) (domain: integer >= 0)
  • p: Percent chance of reaching the age, clamped to [0.1, 100] (unit: percent) (domain: 0.1 <= p <= 100)
  • S(from -> g): Conditional survival to g (survival-probability-product) (unit: 1) (domain: [0, 1], nonincreasing in g)
  • age*: Survival-percentile planning age (unit: years) (domain: from <= age* <= 119)

  Timing: annual survival steps over integer ages

  Rounding: none

  Limits:

  • The percentage is clamped to [0.1, 100] before use, a bound the signature comment does not state; a value passed as a probability (0.97) is read as 0.97%
  • Survival is nonincreasing, so the qualifying ages form an initial interval and the loop may stop at the first failure
  • The signature comment bounds the result by MAX_AGE + 1 (120); since q(119) = 1 the survival to 120 is 0 and 119 is the largest value actually returned
  • The planner-ui SurvivalPercentileModal clamps the result to 60..120 before it becomes the plan's planning age; that clamp is presentation and is not part of this record

  Provenance: derived by codex, implemented by claude-subagent.

  Independent review: cursor

  Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

  Worksheet: survival-percentile-age.md Mutation receipt: survival-percentile-age.mutation.md

  Evidence tests: survival.evidence.test.ts

  Implemented in: survival.ts

  Is the number of: longevity-survival-percentile-age

Fed by: One-year death probability from SSA remaining life expectancy (formula record, 6 of 6 gates pass); Hazard power for a remaining-years multiplier, solved by bisection (model record, 6 of 6 gates pass); Conditional survival to a target age: product of hazard-adjusted one-year survivals (formula record, 6 of 6 gates pass). Open the family for each record's worksheet, receipt, tests and code.

Annuitization payout rate pct

Annual annuity payout as a percent of premium at the payment start age, from the embedded default quote table or the user quote.

Field: SPIA payout rate Unit: percent Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Annuitization paragraph "payout rate X% at age Y"); insights (annuitizationHeadroom card illustrative monthly income (spiaPayoutRate))

No calculation record yet. The number is computed today in engine/src/decisions/annuitization.ts (AnnuitizationSweep.payoutRatePct).

Annuitization sweep annual income

Annual life-annuity income the premium buys at the quoted payout rate.

Field: Annuitization sweep annual income Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Annuitization frontier table "Income/yr" column)

No calculation record yet. The number is computed today in engine/src/decisions/annuitization.ts (AnnuitizationSweepPoint.annualIncome).

Annuitization sweep effective allocation pct

Premium divided by total investable assets, in percent; lower than the requested grid percent when the funding account caps the purchase.

Field: Annuitization sweep effective allocation Unit: percent Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Annuitization frontier chart x-axis and table "Annuitized" column)

No calculation record yet. The number is computed today in engine/src/decisions/annuitization.ts (AnnuitizationSweepPoint.effectiveAllocationPct).

Annuitization sweep premium

SPIA premium traded away at each grid point: the requested share of investable assets, capped by the largest liquid funding account.

Field: Annuitization sweep premium Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Annuitization frontier table "Premium" column)

No calculation record yet. The number is computed today in engine/src/decisions/annuitization.ts (AnnuitizationSweepPoint.premium).

Display fan band widths

Heights of the stacked p10-p90 and p25-p75 bands drawn on the Range of outcomes chart.

Field: Fan chart band widths Unit: US dollars Basis: nominal dollars Computed by: UI transformation Status: Relocation pending

Appears in: monte-carlo-page (Range of outcomes stacked Area dataKeys d.p90 - d.p10 and d.p75 - d.p25)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/MonteCarloPage.tsx (MonteCarloPage).

Display histogram bin label

The dollar label printed under each ending-balance histogram bar.

Field: Histogram bin center label Unit: US dollars Basis: nominal dollars Computed by: UI transformation Status: Relocation pending

Appears in: monte-carlo-page (Ending balances histogram x-axis labels (histRows))

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/MonteCarloPage.tsx (MonteCarloPage).

Historical stress window total shortfall

Sum of unfunded spending over a deterministic replay of one rolling or reversed historical market window.

Field: Historical window total shortfall Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Historical stress windows table "Shortfall" column)

No calculation record yet. The number is computed today in engine/src/montecarlo/historicalSuites.ts (HistoricalStressWindow.totalShortfall).

Monte carlo average longest cut spell years

Among paths that cut at least once, the average length in years of the longest consecutive run of cut years.

Field: Average longest cut spell Unit: count Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Adjustment tile "Longest cut spell (average)")

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.adjustments.averageLongestCutSpellYears).

Monte carlo average total shortfall

Mean across all paths of total unfunded spending.

Field: Average total shortfall Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: scenarios-page (Risk table "Average total shortfall")

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.spendingShortfall.averageTotalShortfallDollars).

Monte carlo average years below target

Mean across paths of the number of years with a target-lifestyle shortfall above SHORTFALL_EPSILON.

Field: Average years below target Unit: count Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Layered success tile "Years below target (average)")

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.averageYearsBelowTarget).

Monte carlo cut years

Among paths that cut at least once, the average and 90th-percentile number of cut years.

Field: Cut years, average and p90 Unit: count Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Adjustment tile "Years cut, typical / worst-case")

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.adjustments.averageCutYears / p90CutYears).

Monte carlo depletion probability by year

Per depletion year, the share of all paths first depleting that year and the cumulative share depleted by that year.

Field: Depletion probability by year Unit: probability Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page ("Depletion probability by year" chart: "First depletion" bars and cumulative line, aria-label cumulative percent); scenarios-page (Risk 'Cumulative depletion probability by year' table (ScenarioRiskComparison.depletionProbabilityByYear[].cumulativeProbability, read at each year from MonteCarloSummary.depletionProbabilityByYear))

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.depletionProbabilityByYear[].probability / cumulativeProbability).

Monte carlo depletion year histogram

Number of paths whose investable assets first deplete in each calendar year (successes excluded).

Field: First-depletion year counts Unit: count Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page ("When depleting plans run out" bar chart and its aria-label total of depleting paths); monte-carlo-page (WhySuccessPanel depletion sentence)

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.depletionYearCounts[].count).

Monte carlo ending after tax estate percentiles

Percentiles (p10, p25, p50, p75, p90) of ending after-tax estate across paths.

Field: Ending after-tax estate percentiles Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Verdict paragraph "Median ending estate / worst 10% / best 10%" (p50, p10, p90)); monte-carlo-page ("Worst-case estate" tile (p10)); monte-carlo-page (Ending-balance histogram aria-label median (p50)); monte-carlo-page (Annuitization table "Median estate" column and frontier point medians (AnnuitizationPointMetrics / StochasticFrontierPoint medianEndingAfterTaxEstate, p10EndingAfterTaxEstate)); scenarios-page (Risk table "After-tax estate p10 / p50 / p90")

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.endingAfterTaxEstate.percentiles).

Monte carlo ending investable histogram

Counts of paths per equal-width bin of ending investable balance (30 bins from min to max).

Field: Ending investable balance histogram Unit: count Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page ("Ending balances" bar chart (counts per bin; bin label from min and binWidth))

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.endingInvestable.histogram (Histogram.min, binWidth, counts)).

Fed by: One-year death probability from SSA remaining life expectancy (formula record, 6 of 6 gates pass); Sampled death age: inverse-Bernoulli walk over annual death probabilities (model record, 6 of 6 gates pass). Open the family for each record's worksheet, receipt, tests and code.

Monte carlo excess funding rate

Across all path-years, excess spending funded divided by excess spending intended.

Field: Excess-layer funding rate Unit: probability Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Layered success tile "Ideal / excess funded" (second percent))

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.excessFundingRate).

Monte carlo expected shortfall on failing paths

Average total unfunded spending across only the paths that depleted.

Field: Expected shortfall on failing paths Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Downside tile "Typical shortfall when the plan falls short"); scenarios-page (Risk table "Expected shortfall on failing paths"); monte-carlo-page (Frontier and annuitization point metrics (expectedShortfallDollars; carried but not charted))

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.downsideRisk.expectedShortfallDollars).

Monte carlo failing path count

Number of paths that depleted.

Field: Failing path count Unit: count Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (WhySuccessPanel "lasted ... in N of M simulated markets" (pathCount - failingPathCount))

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.downsideRisk.failingPathCount).

Monte carlo failure rate

Share of paths that deplete (1 - success rate, computed directly as failingPathCount / pathCount).

Field: Failure probability Unit: probability Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Downside tile "Chance of running short" percent)

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.downsideRisk.failureRate).

Monte carlo flexible goal outcome counts

Total counts of flexible one-time goals funded, partially funded, deferred and skipped, summed over all path-years.

Field: Flexible goal outcomes across paths Unit: count Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Layered success tile "Flexible goals" counts)

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.flexibleGoals.funded / partiallyFunded / deferred / skipped).

Monte carlo guardrail action counts

Total number of guardrail cut and raise actions summed over all path-years.

Field: Guardrail actions across path-years Unit: count Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Layered success tile "{cut} cuts · {raise} raises")

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.guardrailActionCounts.cut / raise).

Monte carlo ideal funding rate

Across all path-years, ideal spending funded divided by ideal spending intended.

Field: Ideal-layer funding rate Unit: probability Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Layered success tile "Ideal / excess funded" (first percent))

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.idealFundingRate).

Monte carlo investable fan percentiles

Per projection year, the 10th, 25th, 50th, 75th and 90th percentiles of end-of-year investable balance across paths (linear-interpolated order statistics).

Field: Investable-balance fan percentiles Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page ("Range of outcomes" fan chart: p10-p90 and p25-p75 bands, median line, and the aria-label figures for the last year); monte-carlo-page (WhySuccessPanel decade-out p10 versus p50 sentence); mcp (run_monte_carlo.percentiles.p10); mcp (run_monte_carlo.percentiles.p25); mcp (run_monte_carlo.percentiles.p50); mcp (run_monte_carlo.percentiles.p75); mcp (run_monte_carlo.percentiles.p90)

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.fan (YearPercentiles)).

Monte carlo max cut depth percentiles

Among paths that cut at least once, the median and 90th-percentile deepest cut as a fraction of the discretionary layer.

Field: Deepest cut, median and p90 Unit: percent Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Adjustment tile "Typical / worst-case cut depth")

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.adjustments.medianMaxCutDepth / p90MaxCutDepth).

Monte carlo P90 average annual target shortfall

90th percentile across paths of the path-average annual target-lifestyle shortfall.

Field: p90 average annual target shortfall Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Layered success tile "Worst 10% average annual target miss")

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.p90AverageAnnualTargetShortfall).

Monte carlo P90 total shortfall

90th percentile across all paths of the total unfunded spending over the whole retirement.

Field: p90 cumulative shortfall Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Downside tile "Worst 10% cumulative shortfall")

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.spendingShortfall.p90TotalShortfallDollars (= downsideRisk.p90TotalShortfallDollars)).

Monte carlo paths with cut share

Share of paths with at least one guardrail cut year.

Field: Probability of a spending cut Unit: probability Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Adjustment tile "Chance of a spending cut"); scenarios-page (Risk table "Probability of a spending cut")

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.adjustments.pathsWithCut).

Monte carlo paths with raise share

Share of paths with at least one guardrail raise action.

Field: Probability of a spending raise Unit: probability Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Adjustment tile "Chance of a raise")

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.adjustments.pathsWithRaise).

Monte carlo prob ending above bequest target

Share of paths whose ending after-tax estate is at least the bequest target inflated along that path's realized inflation series; null without a target.

Field: Probability of clearing the bequest target Unit: probability Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Adjustment tile "Chance of meeting the bequest target")

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.adjustments.probEndingAboveBequestTarget).

Monte carlo prob ending surplus

Share of paths whose ending after-tax estate is positive.

Field: Probability of ending with a surplus Unit: probability Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Adjustment tile "Chance of ending with money left")

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.adjustments.probEndingSurplus).

Monte carlo required floor success rate

Share of paths that funded the required spending floor in every year (a shortfall below SHORTFALL_EPSILON is ignored).

Field: Required-floor success probability Unit: probability Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Layered success tile "Required floor met"); scenarios-page (Risk table "Required-floor success rate"); mcp (run_monte_carlo.requiredFloorSuccessRate)

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.requiredFloorSuccessRate).

Monte carlo success rate

Share of simulated market paths on which investable assets never deplete before the plan horizon.

Field: Success probability Unit: probability Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (SuccessGauge percent and verdict heading); monte-carlo-page (Layered success tile "Any spending shortfall" (successRate)); monte-carlo-page (WhySuccessPanel "What it counts" percent); monte-carlo-page (Spending vs. success and Retirement age vs. success frontier charts (StochasticFrontierPoint.successRate)); monte-carlo-page (Annuitization frontier chart success line and glidepath-only dashed line (AnnuitizationPointMetrics.successRate)); results-headline (KpiBar "Market success" percent (useMcSuccessRateState headline run)); optimize-page ("Monte Carlo success rate with this claim change" and the success stat); scenarios-page (Risk table "Portfolio success rate"); relocation-page (Success column when Monte Carlo is enabled); ss-page (Bridge comparison and claim-age table success columns); insights (InsightCardView base and patched 250-path runs behind the Monte Carlo delta line); mcp (run_monte_carlo.successRate)

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.successRate).

Fed by: One-year death probability from SSA remaining life expectancy (formula record, 6 of 6 gates pass); Sampled death age: inverse-Bernoulli walk over annual death probabilities (model record, 6 of 6 gates pass). Open the family for each record's worksheet, receipt, tests and code.

Monte carlo target attainment median

Median across paths of the share of target-lifestyle spending funded over the path (1 = every target dollar funded).

Field: Median target attainment Unit: probability Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Layered success tile "Median target attainment"); scenarios-page (Risk table "Median target attainment")

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.targetAttainmentPct.p50).

Monte carlo target lifestyle success rate

Share of paths that funded full target-lifestyle spending in every year.

Field: Target-lifestyle success probability Unit: probability Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Layered success tile "Target lifestyle funded"); scenarios-page (Risk table "Target-lifestyle success rate")

No calculation record yet. The number is computed today in engine/src/montecarlo/run.ts (MonteCarloSummary.targetLifestyleSuccessRate).

Stochastic frontier variant axis

The spending level or retirement age each frontier variant was built with (grid multipliers 0.85..1.15 of spending; -2..+2 years of retirement age).

Field: Frontier variant value Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: monte-carlo-page (Frontier charts x-axis (spending dollars; retirement age))

No calculation record yet. The number is computed today in engine/src/montecarlo/frontiers.ts (StochasticFrontierPoint.x).

Claim age co optimization combinations evaluated

Number of household Social Security claim-age combinations evaluated by optimization.

Field: combinationsEvaluated Unit: count Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: optimize-page (claim combinations evaluated); report (modeled-findings claim-age "SS claim combinations optimized")

No calculation record yet. The number is computed today in engine/src/projection/optimizePlan.ts (ClaimAgeCoOptimization.combinationsEvaluated).

Claim age co optimization current claim exact estate

After-tax estate produced by exact validation of the current claim ages.

Field: currentClaimExactEstate Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: optimize-page (current claim exact estate); report (modeled-findings claim-age evidence)

No calculation record yet. The number is computed today in engine/src/projection/optimizePlan.ts (ClaimAgeCoOptimization.currentClaimExactEstate).

Claim age co optimization joint exact estate

After-tax estate produced by exact validation of the jointly optimized claim ages.

Field: jointExactEstate Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: optimize-page (co-optimized claim estate); report (modeled-findings claim-age evidence)

No calculation record yet. The number is computed today in engine/src/projection/optimizePlan.ts (ClaimAgeCoOptimization.jointExactEstate).

Compare plan deltas

Differences between two plans in last funded year, depletion age and deterministic success (100 or 0 by depletion), with bounded labels when only one plan depletes.

Field: Plan B minus Plan A: money lasts, ages and deterministic success Unit: years Basis: no dollar basis Computed by: UI-native Status: Relocation pending

Appears in: compare-page (Money lasts, Depletion age and Deterministic success rows (delta column))

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/compareDeltas.ts (compareDeltas); planner-ui/src/planner/compareDeltas.ts (moneyLastsDelta); planner-ui/src/planner/compareDeltas.ts (deterministicSuccessPct); planner-ui/src/planner/ComparePlansPage.tsx (primaryAgeIn).

Compare plan money deltas

Differences between two plans in ending net worth, ending investable, ending after-tax estate and lifetime tax plus penalties.

Field: Plan B minus Plan A money deltas Unit: US dollars Basis: nominal dollars Computed by: UI-native Status: Relocation pending

Appears in: compare-page (Delta column of the four money rows)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/ComparePlansPage.tsx (ComparePlansPage).

Exact ledger tournament margin over MILP dollars

After-tax-estate margin by which the exact-ledger winner beats the solver schedule.

Field: marginOverMilpDollars Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: optimize-page (winner margin over solver schedule); monte-carlo-page (WhySuccessPanel (explainPanels) "beat the solver's own schedule by $X")

No calculation record yet. The number is computed today in engine/src/projection/optimizePlan.ts (ExactLedgerTournament.marginOverMilpDollars).

Exact ledger validation ending net worth delta

Change in ending net worth between the candidate recommendation and baseline plan.

Field: endingNetWorthDelta Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: report (validation ending net-worth delta)

No calculation record yet. The number is computed today in engine/src/projection/optimizePlan.ts (ExactLedgerValidation.endingNetWorthDelta).

Exact ledger validation executed conversion ratio

Share of requested Roth-conversion dollars actually executed by the projection ledger.

Field: executedConversionRatio Unit: percent Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: optimize-page (executed conversion percentage); report (modeled-findings validation executed percent)

No calculation record yet. The number is computed today in engine/src/projection/optimizePlan.ts (ExactLedgerValidation.executedConversionRatio).

Exact ledger validation first materially unexecuted year

First year in which a requested Roth conversion is materially not executed.

Field: firstMateriallyUnexecutedYear Unit: calendar year Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: optimize-page (first materially unexecuted year); report (modeled-findings validation "First material execution shortfall")

No calculation record yet. The number is computed today in engine/src/projection/optimizePlan.ts (ExactLedgerValidation.firstMateriallyUnexecutedYear).

Exact ledger validation requested conversion total

Total Roth-conversion dollars requested by the candidate schedule.

Field: requestedConversionTotal Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: report (requested conversion total); report (modeled-findings validation "Requested conversions")

No calculation record yet. The number is computed today in engine/src/projection/optimizePlan.ts (ExactLedgerValidation.requestedConversionTotal).

Exact ledger validation traditional depletion year

First year traditional-account assets are depleted under the validated schedule.

Field: traditionalDepletionYear Unit: calendar year Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: report (traditional depletion year)

No calculation record yet. The number is computed today in engine/src/projection/optimizePlan.ts (ExactLedgerValidation.traditionalDepletionYear).

Optimization baseline after tax estate

Baseline plan after-tax estate used to validate an optimization recommendation.

Field: baselineAfterTaxEstate Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: report (validation baseline after-tax estate); report (modeled-findings validation "Baseline after-tax estate")

No calculation record yet. The number is computed today in engine/src/projection/optimizePlan.ts (ExactLedgerValidation.baseline.endingAfterTaxEstate).

Optimization candidate after tax estate

Candidate plan after-tax estate shown in optimization validation evidence.

Field: candidateAfterTaxEstate Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: report (validation candidate after-tax estate); report (modeled-findings validation "Candidate after-tax estate")

No calculation record yet. The number is computed today in engine/src/projection/optimizePlan.ts (ExactLedgerValidation.candidate.endingAfterTaxEstate).

Relocation tax comparison

Lifetime tax-plus-penalties delta of each candidate versus the baseline, and the candidate ending estate deflated to the display basis.

Field: Relocation candidate deltas and display basis Unit: US dollars Basis: nominal dollars Computed by: UI-native Status: Relocation pending

Appears in: relocation-page (Candidate table "vs. baseline" delta column and deflated ending after-tax estate)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/RelocationComparePage.tsx (RelocationComparePage).

Simple candidate evaluation after tax estate delta

Candidate change in after-tax estate relative to the current plan.

Field: afterTaxEstateDelta Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: optimize-page (after-tax estate improvement); report (modeled-findings validation "After-tax estate delta" and candidate rows)

No calculation record yet. The number is computed today in engine/src/projection/optimizePlan.ts (SimpleCandidateEvaluation.afterTaxEstateDelta).

Simple candidate evaluation executed conversion total

Roth-conversion dollars actually executed for the evaluated candidate.

Field: executedConversionTotal Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: optimize-page (executed conversions); report (modeled-findings validation "Executed conversions")

No calculation record yet. The number is computed today in engine/src/projection/optimizePlan.ts (SimpleCandidateEvaluation.executedConversionTotal).

Simple candidate evaluation incomplete computation years

Projection years with incomplete calculations in the evaluated candidate.

Field: incompleteComputationYears Unit: calendar year Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: optimize-page (incomplete computation years)

No calculation record yet. The number is computed today in engine/src/projection/optimizePlan.ts (SimpleCandidateEvaluation.incompleteComputationYears).

Simple candidate evaluation lifetime tax delta

Candidate change in lifetime taxes and penalties relative to the current plan.

Field: lifetimeTaxDelta Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: optimize-page (lifetime tax change); report (modeled-findings validation "Lifetime tax delta" and candidate rows)

No calculation record yet. The number is computed today in engine/src/projection/optimizePlan.ts (SimpleCandidateEvaluation.lifetimeTaxDelta).

Simple candidate evaluation money lasts years delta

Change in the number of funded plan years for the candidate versus baseline.

Field: moneyLastsYearsDelta Unit: years Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: report (money-lasts years change); report (modeled-findings validation "Money-lasts delta" and candidate rows)

No calculation record yet. The number is computed today in engine/src/projection/optimizePlan.ts (SimpleCandidateEvaluation.moneyLastsYearsDelta).

SWR rule result depletion year

First year a displayed safe-withdrawal rule runs out of investable assets.

Field: depletionYear Unit: calendar year Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: solver-page (withdrawal rule depletion year)

No calculation record yet. The number is computed today in engine/src/decisions/swrComparator.ts (SwrRuleResult.depletionYear).

SWR rule result end year

Final planning year used to evaluate a displayed safe-withdrawal rule.

Field: endYear Unit: calendar year Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: solver-page (withdrawal rule plan end year)

No calculation record yet. The number is computed today in engine/src/decisions/swrComparator.ts (SwrRuleResult.endYear).

SWR rule result ending after tax estate

After-tax estate left by a displayed safe-withdrawal rule at the end of the plan.

Field: endingAfterTaxEstate Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: solver-page (withdrawal rule ending after-tax estate); solver-page (SWR rule rows ending after-tax estate (deflated for display))

No calculation record yet. The number is computed today in engine/src/decisions/swrComparator.ts (SwrRuleResult.endingAfterTaxEstate).

SWR rule result initial annual spend

First-year spending supported by a displayed safe-withdrawal rule.

Field: initialAnnualSpend Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: solver-page (withdrawal rule initial annual spend)

No calculation record yet. The number is computed today in engine/src/decisions/swrComparator.ts (SwrRuleResult.initialAnnualSpend).

SWR rule result initial rate pct

Initial portfolio withdrawal rate used by a displayed safe-withdrawal rule.

Field: initialRatePct Unit: percent Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: solver-page (withdrawal rule initial rate)

No calculation record yet. The number is computed today in engine/src/decisions/swrComparator.ts (SwrRuleResult.initialRatePct).

SWR rule result lifetime taxes and penalties

Total taxes and penalties paid under a displayed safe-withdrawal rule.

Field: lifetimeTaxesAndPenalties Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: solver-page (withdrawal rule lifetime tax and penalties)

No calculation record yet. The number is computed today in engine/src/decisions/swrComparator.ts (SwrRuleResult.lifetimeTaxesAndPenalties).

MCP compare ending after tax estate delta

Adapter-computed Plan B minus Plan A ending after-tax estate.

Field: MCP scenario ending-estate delta Unit: US dollars Basis: nominal dollars Computed by: Adapter Status: No calculation record yet

Appears in: mcp (compare_scenarios.deltaEndingAfterTaxEstate)

No calculation record yet. The number is computed today outside the engine, in RetireGolden-MCP/src/adapter.ts in the RetireGolden-MCP repository (compareScenarios).

Scenario comparison cell

For each compared scenario metric, the baseline plan's value, the proposal plan's value and the change (proposal minus baseline, null when either side has no comparable value); the metric's own family says what the value is.

Field: Scenario comparison cell (baseline, proposal, change) Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: scenarios-page (Baseline, Proposal and Change columns of every MetricTable (formatMetricValue, formatScenarioDelta) and of the annual ledger comparison)

No calculation record yet. The number is computed today in engine/src/scenarios/comparison.ts (ScalarComparison / NullableScalarComparison (scalar, nullableScalar)).

Bucket lens allocation

Investable assets assigned to near-, middle-, and long-horizon spending buckets.

Field: buckets Unit: US dollars Basis: nominal dollars Computed by: UI-native Status: Relocation pending

Appears in: results-table (bucket lens allocation)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/bucketLens.ts (bucketLens).

Cash flow line amount

Dollar amount carried by a source-to-use line in the selected year cash-flow drilldown.

Field: Cash-flow line amount Unit: US dollars Basis: as displayed Computed by: UI transformation Status: Relocation pending

Appears in: cash-flow-drilldown (Sankey link and node amount labels)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/yearCashFlow/buildYearCashFlow.ts (buildYearCashFlowSankey); planner-ui/src/planner/yearCashFlow/YearCashFlowSankey.tsx (YearCashFlowSankey).

Cash flow reconciliation totals

Per year, the total of funded sources, the total of funded uses, the unfunded (shortfall) uses, and the paired transfer debit and credit totals that the identity-bearing cash-flow ledger reconciles.

Field: Cash-flow reconciliation totals Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: cash-flow-drilldown (YearCashFlowDialog summary tiles "Sources", "Funded uses", "Shortfall" and Sankey props); cash-flow-drilldown (YearCashFlowSankey aria-label: 'Cash flow for YEAR. Source total $X. Funded uses $Y. Shortfall $Z.' and, on the transfers view, 'Transfers for YEAR. Debits $X. Credits $Y.')

No calculation record yet. The number is computed today in engine/src/projection/internal/types/cashFlow.ts (YearCashFlowCashIdentityTotals.sourceTotalPlanDollars / YearCashFlowUseIdentityTotals.fundedUsesPlanDollars, unfundedUsesPlanDollars / YearCashFlowTransferIdentityTotals.debitsPlanDollars, creditsPlanDollars).

Display dollar basis conversion

Conversion of a nominal year amount to today's dollars, or back to nominal dollars for a chart.

Field: Today's-dollar display conversion Unit: US dollars Basis: nominal or real, as displayed Computed by: UI transformation Status: Relocation pending

Appears in: results-table (today dollars toggle); results-headline (KpiBar and ResultsPage "in today's dollars" ending net worth); solver-page (Evidence ending after-tax estate today's dollars (deflator) and SWR rows); relocation-page (deflateEnd on ending after-tax estate); cash-flow-drilldown (displayAmount applied to every line, node and reconciliation total); insights (DetectorProjection.deflate handed to detectors for today's-dollar figures); chart (Every Results chart series through the DollarAdjuster)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/projection.ts (inflationView).

Display FI target annual

Financial-independence portfolio target plotted in the same year and dollar basis as account balances.

Field: Displayed FI target Unit: US dollars Basis: as displayed Computed by: UI transformation Status: Relocation pending

Appears in: chart (fiTarget)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/resultsRows.ts (buildResultsRows).

Flexible goal funded amount annual

Dollars delivered to flexible goals during the projection year.

Field: flexibleGoalFundedAmount Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (flexibleGoalFundedAmount)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.flexibleGoals.fundedAmount).

Flexible goal unfunded amount annual

Dollars requested by flexible goals but not delivered during the projection year.

Field: flexibleGoalUnfundedAmount Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (flexibleGoalUnfundedAmount)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.flexibleGoals.unfundedAmount).

Flexible goals deferred count annual

Number of flexible goals postponed to a later year in this projection year.

Field: flexibleGoalsDeferred Unit: count Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: csv (flexibleGoalsDeferred); results-table (Guardrails column goal-outcome aria-label)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.flexibleGoals.deferred).

Flexible goals funded count annual

Number of flexible goals fully funded in this projection year.

Field: flexibleGoalsFunded Unit: count Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: csv (flexibleGoalsFunded); results-table (Guardrails column goal-outcome aria-label)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.flexibleGoals.funded).

Flexible goals partially funded count annual

Number of flexible goals partly funded in this projection year.

Field: flexibleGoalsPartiallyFunded Unit: count Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: csv (flexibleGoalsPartiallyFunded); results-table (Guardrails column goal-outcome aria-label)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.flexibleGoals.partiallyFunded).

Flexible goals skipped count annual

Number of flexible goals skipped in this projection year.

Field: flexibleGoalsSkipped Unit: count Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: csv (flexibleGoalsSkipped); results-table (Guardrails column goal-outcome aria-label)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.flexibleGoals.skipped).

Income annuity annual

Annuity payments received in a projection year.

Field: Annuity income Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: chart (annuity); csv (annuity); scenarios-page (Lifetime income "Annuity"); cash-flow-drilldown (annuityPayment source line)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.incomes.annuity).

Fed by: Joint last-survivor life expectancy of two independent lives (formula record, 6 of 6 gates pass). Open the family for each record's worksheet, receipt, tests and code.

Income one time annual

One-time income recognized in a projection year.

Field: One-time income Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: chart (oneTime); csv (oneTimeIncome); scenarios-page (Lifetime income "One-time income"); cash-flow-drilldown (oneTimeIncome source line)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.incomes.oneTime).

Income ordinary dividends annual

Ordinary dividend income recognized during the projection year.

Field: ordinaryDividends Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (ordinaryDividends)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.incomes.ordinaryDividends).

Income pension annual

Pension income paid in a projection year.

Field: Pension income Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: chart (pension); csv (pension); scenarios-page (Lifetime income "Pension"); cash-flow-drilldown (pension source line)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.incomes.pension).

Income qualified dividends annual

Qualified dividend income recognized during the projection year.

Field: qualifiedDividends Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (qualifiedDividends)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.incomes.qualifiedDividends).

Income recurring annual

Recurring non-wage income in a projection year.

Field: Recurring income Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: chart (recurring); csv (recurring); scenarios-page (Lifetime income "Recurring income"); cash-flow-drilldown (recurringIncome source line)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.incomes.recurring).

Income taxable interest annual

Taxable interest credited to the household during the projection year.

Field: taxableInterest Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (taxableInterest)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.incomes.taxableInterest).

Income total annual

All modeled income received in a projection year before expenses and taxes.

Field: Total income Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: chart (income); csv (totalIncome); report (yearLedger); results-table (income total); results-table (Income column); report (year-ledger block income and ReportPage year table); scenarios-page (Annual "Gross income" and lifetime "Total gross income"); results-headline (Depletion narrative "Income doesn't stop: about $X" (deflated))

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.incomes.total).

Income wages annual

Employment wages modeled for a projection year.

Field: Wages Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: chart (wages); csv (wages); scenarios-page (Lifetime income "Wages"); cash-flow-drilldown (wages source line)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.incomes.wages).

Inherited account final deadline year

Final calendar year by which an inherited account must be emptied.

Field: finalDeadlineYear Unit: calendar year Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: report (inherited account final deadline); results-table (Inherited schedule deadline sentence); report (inherited-schedules block finalDeadlineYear)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/accountActivity.ts (InheritedAccountYearEvidence.finalDeadlineYear).

Inherited distribution required annual

Required inherited-account distribution dollars due for the account and year.

Field: inheritedRequiredAmount Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (inheritedRequiredAmount); results-table (Inherited schedules Required column); report (inherited-schedules block requiredAmount)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.inheritedAccounts[].requiredAmount).

Inherited distribution required executed annual

Required inherited-account distribution dollars actually executed for the account and year.

Field: inheritedExecutedRequiredAmount Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (inheritedExecutedRequiredAmount); report (inherited required amount executed); results-table (Inherited schedules Executed column); report (inherited-schedules block executedRequiredAmount and ReportPage inherited table)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.inheritedAccounts[].executedRequiredAmount).

Inherited distribution voluntary annual

Inherited-account distribution dollars taken voluntarily beyond the required amount for the account and year.

Field: inheritedVoluntaryAmount Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (inheritedVoluntaryAmount); report (inherited voluntary distribution); results-table (Inherited schedules Voluntary column)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.inheritedAccounts[].voluntaryAmount).

Insurance cash value annual

Cash surrender value of modeled insurance at the end of the projection year.

Field: insuranceCashValue Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (insuranceCashValue)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.insuranceCashValue).

Insurance death benefit annual

Insurance death benefit included in the projection year estate value.

Field: deathBenefit Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (deathBenefit); cash-flow-drilldown (lifeInsuranceDeathBenefit source line)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.deathBenefit).

Long term care benefit annual

Long-term-care insurance benefit received during the projection year.

Field: ltcBenefit Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (ltcBenefit)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.expenses.ltcBenefit).

Projection result ending investable

Investable assets remaining at the end of the projection.

Field: endingInvestable Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: compare-page (ending investable assets); report (headline-results block endingInvestable); scenarios-page (Headline "Ending investable assets")

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (ProjectionResult.endingInvestable).

Projection result ending net worth

Total net worth remaining at the end of the projection.

Field: endingNetWorth Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: compare-page (ending net worth); results-headline (KpiBar "Ending net worth" and ResultsPage narrative); report (headline-results block endingNetWorth and ReportPage KPI); scenarios-page (Headline "Ending net worth" and estate "Gross net worth")

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (ProjectionResult.endingNetWorth).

Projection summary average pre retirement savings rate pct

Average share of pre-retirement earnings saved across working years.

Field: averagePreRetirementSavingsRatePct Unit: percent Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: results-headline (pre-retirement savings rate); report (headline-results block average-pre-retirement-savings-rate-pct and ReportPage KPI); mcp (run_projection.summary.averagePreRetirementSavingsRatePct); mcp (compare_scenarios.a.averagePreRetirementSavingsRatePct); mcp (compare_scenarios.b.averagePreRetirementSavingsRatePct)

No calculation record yet. The number is computed today in engine/src/projection/compare.ts (ProjectionSummary.averagePreRetirementSavingsRatePct).

Projection summary coast fire number

Current invested amount needed to reach the FI target without further contributions.

Field: coastFireNumber Unit: US dollars Basis: today's dollars (real) Computed by: Engine Status: No calculation record yet

Appears in: results-headline (Coast FI number); report (headline-results block coast-fire-number and ReportPage KPI); mcp (run_projection.summary.coastFireNumber); mcp (compare_scenarios.a.coastFireNumber); mcp (compare_scenarios.b.coastFireNumber)

No calculation record yet. The number is computed today in engine/src/projection/compare.ts (ProjectionSummary.coastFireNumber).

Projection summary ending investable

Investable assets remaining at the end of the scenario projection.

Field: endingInvestable Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: scenarios-page (ending investable assets); compare-page (Ending investable row); mcp (run_projection.summary.endingInvestable); mcp (compare_scenarios.a.endingInvestable); mcp (compare_scenarios.b.endingInvestable)

No calculation record yet. The number is computed today in engine/src/projection/compare.ts (ProjectionSummary.endingInvestable).

Projection summary ending net worth

Total net worth remaining at the end of the scenario projection.

Field: endingNetWorth Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: results-headline (ending net worth); scenarios-page (Headline "Ending net worth" (summary copy)); mcp (run_projection.summary.endingNetWorth); mcp (compare_scenarios.a.endingNetWorth); mcp (compare_scenarios.b.endingNetWorth); scenarios-page (Estate table 'Gross net worth' (ScenarioEstateComparison.grossNetWorth reads the summary copy))

No calculation record yet. The number is computed today in engine/src/projection/compare.ts (ProjectionSummary.endingNetWorth).

Projection summary FI age

Age at which modeled investable assets first reach the financial-independence target.

Field: fiAge Unit: age in years Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: results-headline (financial independence age); results-headline (FI section "(Age N)"); report (headline-results block fiAge); mcp (run_projection.summary.fiAge); mcp (compare_scenarios.a.fiAge); mcp (compare_scenarios.b.fiAge)

No calculation record yet. The number is computed today in engine/src/projection/compare.ts (ProjectionSummary.fiAge).

Projection summary FI number

Today-dollar portfolio target used to identify financial independence.

Field: fiNumber Unit: US dollars Basis: today's dollars (real) Computed by: Engine Status: No calculation record yet

Appears in: results-headline (financial independence number); report (headline-results block fi-number and ReportPage KPI); chart (Path to FI chart target line via display-fi-target-annual); mcp (run_projection.summary.fiNumber); mcp (compare_scenarios.a.fiNumber); mcp (compare_scenarios.b.fiNumber)

No calculation record yet. The number is computed today in engine/src/projection/compare.ts (ProjectionSummary.fiNumber).

Projection summary FI year

Calendar year in which modeled assets first reach the financial-independence target.

Field: fiYear Unit: calendar year Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: report (financial independence year); results-headline (FI section "you reach FI in YEAR (age N)"); report (headline-results block fiYear); mcp (run_projection.summary.fiYear); mcp (compare_scenarios.a.fiYear); mcp (compare_scenarios.b.fiYear)

No calculation record yet. The number is computed today in engine/src/projection/compare.ts (ProjectionSummary.fiYear).

Spending care cost gross annual

Gross long-term-care cost incurred during the projection year before insurance benefits.

Field: careCost Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (careCost)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.expenses.careCost).

Spending debt service annual

Principal and interest paid on modeled debts during the projection year.

Field: debtService Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (debtService); chart (Spending by category "Debt payments"); cash-flow-drilldown (debtService use line)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.expenses.debtService).

Spending excess requested annual

Optional spending above the ideal lifestyle amount attempted during the projection year.

Field: excessSpending Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (excessSpending)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.expenses.excessSpending).

Spending excess shortfall annual

Unfunded optional spending above the ideal lifestyle amount in the projection year.

Field: excessShortfall Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (excessShortfall)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.excessShortfall).

Spending guardrail factor annual

Multiplier applied to flexible spending after the projection year guardrail decision.

Field: guardrailFactor Unit: factor Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: csv (guardrailFactor)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.expenses.guardrailFactor).

Spending ideal requested annual

Ideal lifestyle spending requested for the projection year.

Field: idealSpending Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (idealSpending)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.expenses.idealSpending).

Spending ideal shortfall annual

Unfunded ideal lifestyle spending in the projection year.

Field: idealShortfall Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (idealShortfall)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.idealShortfall).

Spending insurance premiums annual

Insurance premiums charged as expenses during the projection year.

Field: insurancePremiums Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (insurancePremiums); chart (Spending by category "Insurance premiums"); cash-flow-drilldown (insurancePremium use line)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.expenses.insurancePremiums).

Spending intended annual

Total spending the plan intended to fund before available cash constrained it.

Field: intendedSpending Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (intendedSpending); scenarios-page (Annual "Intended spending" and lifetime "Intended spending")

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.expenses.intendedSpending).

Spending one time goals annual

One-time goal spending paid during the projection year.

Field: goals Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (goals); chart (Spending by category "One-time goals"); cash-flow-drilldown (oneTimeGoal use line)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.expenses.oneTimeGoals).

Spending property costs annual

Property taxes, maintenance, and other modeled property costs paid during the projection year.

Field: propertyCosts Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (propertyCosts); chart (Spending by category "Property tax + insurance"); cash-flow-drilldown (propertyCosts use line)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.expenses.propertyCosts).

Spending required requested annual

Essential spending floor requested for the projection year.

Field: requiredSpending Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (requiredSpending); results-table (Required column (layered spending))

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.expenses.requiredSpending).

Spending required shortfall annual

Unfunded essential spending in the projection year.

Field: requiredShortfall Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (requiredShortfall); results-table (Layer miss "Req"); scenarios-page (Annual "Required shortfall" and lifetime "Required-floor shortfall")

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.requiredShortfall).

Spending target requested annual

Target lifestyle spending requested for the projection year.

Field: targetSpending Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (targetSpending); results-table (Target column (layered spending))

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.expenses.targetSpending).

Spending target shortfall annual

Unfunded target lifestyle spending in the projection year.

Field: targetShortfall Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (targetShortfall); results-table (Layer miss "Target"); scenarios-page (Annual "Target shortfall" and lifetime "Target-lifestyle shortfall")

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.targetShortfall).

Surplus invested annual

Surplus cash flow invested this year into cash, else taxable, else unassigned.

Field: Surplus invested Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: cash-flow-drilldown (Summary "Surplus" figure and surplusInvestment use/transfer lines)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.surplusInvested).

Sustainable spending result max base annual

Highest annual base spending that satisfies the solver constraints.

Field: maxBaseAnnual Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: solver-page (maximum base annual spending); insights (spending-headroom card after Preview "sustains about $X/yr"); scenarios-page (Spending capacity "Solved annual base spending"); mcp (solve_max_spending.maxBaseAnnual)

No calculation record yet. The number is computed today in engine/src/decisions/spendingSolver.ts (SustainableSpendingResult.maxBaseAnnual).

Sustainable spending result simulation count

Number of deterministic projections evaluated by the spending solver.

Field: simulationCount Unit: count Basis: no dollar basis Computed by: Engine Status: No calculation record yet

Appears in: solver-page (simulations run); scenarios-page (Spending capacity simulation count column); mcp (solve_max_spending.simulationCount)

No calculation record yet. The number is computed today in engine/src/decisions/spendingSolver.ts (SustainableSpendingResult.simulationCount).

Sustainable spending result spending slack dollars

Remaining dollar margin between solved spending and the feasibility boundary.

Field: spendingSlackDollars Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: solver-page (spending feasibility slack); insights (spending-headroom card after Preview "$Y/yr above your current level"); scenarios-page (Spending capacity "Slack vs. current base spending"); mcp (solve_max_spending.spendingSlackDollars)

No calculation record yet. The number is computed today in engine/src/decisions/spendingSolver.ts (SustainableSpendingResult.spendingSlackDollars).

Year result contributions

Employee and household dollars contributed to investment accounts during the projection year.

Field: contributions Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (contributions); results-table (Contrib. column); report (year-ledger block contributions and ReportPage year table); cash-flow-drilldown (contribution use and employeeContribution transfer lines)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.contributions).

Year result employer match

Employer matching contributions credited during the projection year.

Field: employerMatch Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (employerMatch); results-table (Match column); report (ReportPage year table Match column); cash-flow-drilldown (employerMatch transfer line)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.employerMatch).

Year result LTCG zero headroom

Additional long-term capital gains available before leaving the zero-percent bracket.

Field: ltcgZeroHeadroom Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: results-table (0% capital-gains headroom)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.ltcgZeroHeadroom).

Year result tax exempt interest

Tax-exempt interest income received during the projection year.

Field: taxExemptInterest Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: csv (taxExemptInterest); chart (Income by source "Tax-exempt interest" series); scenarios-page (Annual "Tax-exempt interest" and lifetime "Tax-exempt interest"); cash-flow-drilldown (taxExemptInterest source line)

No calculation record yet. The number is computed today in engine/src/projection/internal/types/result.ts (YearResult.taxExemptInterest).

Cash flow line plan dollars

The nominal plan-dollar amount of one identity-bearing cash-flow line in a projection year: a source line's amount, a use line's requested, funded and unfunded amounts, and a transfer line's paired debit and credit.

Field: Cash-flow line amounts (nominal plan dollars) Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: cash-flow-drilldown (YearCashFlowDialog DetailTable columns Amount, Requested, Funded, Unfunded, Debit and Credit (through display-dollar-basis-conversion)); cash-flow-drilldown (Sankey links and per-node totals (the UI mapping is cash-flow-line-amount)); cash-flow-drilldown (detailCsv.ts columns nominalAmount, requested, funded, unfunded, debit, credit (unrounded nominal plan dollars))

No calculation record yet. The number is computed today in engine/src/projection/internal/types/cashFlow.ts (YearCashFlowCashSourceLine.amountPlanDollars / YearCashFlowPostSolveDepositLine.amountPlanDollars / YearCashFlowUseLine.requestedPlanDollars, fundedPlanDollars, unfundedPlanDollars / YearCashFlowTransferLine.debitPlanDollars, creditPlanDollars).

Insight annuitization headroom illustrative SPIA

Illustrative single-premium annuity: premium = min(25% of the largest liquid account, $250,000); monthly income = premium × spiaPayoutRate(startAge) / 12.

Field: Illustrative SPIA premium and income Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: insights (annuitization-headroom card rationale "Trading $X ... (~$Y/mo)")

No calculation record yet. The number is computed today in engine/src/insights/detectors/annuitizationHeadroom.ts (annuitizationHeadroom.screen (premium, monthly)).

Insight asset location swappable exposure

Dollars of bond or stock exposure the preferred asset-location swap would relocate between account wrappers while holding the household mix constant.

Field: Swappable class exposure Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: insights (asset-location card impact "Up to $X of class exposure could be relocated")

No calculation record yet. The number is computed today in engine/src/insights/detectors/assetLocation.ts (assetLocation.screen (swapped from assetLocationGenerator metadata)).

Insight HECM buffer illustrative credit line

Initial HECM line of credit = principal limit factor (published table for the youngest borrower age) × home value; the card also sums cash, taxable, equity comp, traditional, Roth and HSA balances as the investable portfolio it compares against.

Field: Illustrative HECM credit line Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: insights (hecm-buffer-candidate card rationale "would start near $X (P% of value)" and the portfolio total)

No calculation record yet. The number is computed today in engine/src/insights/detectors/hecmBufferCandidate.ts (hecmBufferCandidate.screen (lineSize, investable)).

Insight impact ending after tax estate delta

Estimated change in ending after-tax estate from an insight action.

Field: endingAfterTaxEstateDelta Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: insights (InsightCardView "Ending estate delta" after Preview impact; rough "≈ ... estate delta" when no qualitative text)

No calculation record yet. The number is computed today in engine/src/insights/types.ts (InsightImpact.endingAfterTaxEstateDelta).

Insight impact lifetime tax delta

Estimated change in lifetime taxes from an insight action.

Field: lifetimeTaxDelta Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: insights (InsightCardView "Lifetime tax delta" after Preview impact)

No calculation record yet. The number is computed today in engine/src/insights/types.ts (InsightImpact.lifetimeTaxDelta).

Insight IRMAA tier edge premium cliff

Extra annual Medicare premiums (Part B plus Part D surcharge, all Medicare-age people) that a MAGI just over an IRMAA threshold triggers two years later, versus MAGI one dollar under the threshold.

Field: IRMAA tier-edge premium cliff Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: insights (irmaa-tier-edge card impact text "save roughly $X of Medicare premiums" and the rough estate delta)

No calculation record yet. The number is computed today in engine/src/insights/detectors/irmaaTierEdge.ts (irmaaTierEdge.screen (annualPremiumCliff)).

Insight monte carlo success delta

Change in Monte Carlo success rate, in percentage points, between the patched plan and the base plan on 250 shared-seed paths.

Field: Insight Monte Carlo success delta Unit: percent Basis: no dollar basis Computed by: UI-native Status: Relocation pending

Appears in: insights (InsightCardView "Monte Carlo success" line after Preview)

Relocation pending. This number is currently computed in the app's UI and is scheduled to move into the engine, where a calculation record can be written for it. UI sources: planner-ui/src/planner/insights/InsightCardView.tsx (InsightCardView).

Insight spending guardrails illustrative floor

Required spending floor the guardrail preview uses: the plan's requiredAnnual when set, otherwise 80% of base spending generated by probabilityBandSpendingGuardrailGenerator.

Field: Illustrative guardrail spending floor Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: insights (spending-guardrails card rationale "with a $X required floor")

No calculation record yet. The number is computed today in engine/src/insights/detectors/spendingGuardrails.ts (spendingGuardrails.screen (requiredAnnual from guardrailPatchFromGenerator)).

Insight spending headroom rough annual

Ending after-tax estate deflated to today, minus the bequest target, divided by the years remaining in the projection.

Field: Rough annual spending headroom Unit: US dollars Basis: today's dollars (real) Computed by: Engine Status: No calculation record yet

Appears in: insights (spending-headroom card rationale "end with roughly $X" and impact "≈ $Y/yr of rough headroom")

No calculation record yet. The number is computed today in engine/src/insights/detectors/spendingHeadroom.ts (spendingHeadroom.screen (roughHeadroomPerYear, endingEstateToday)).

Insight SS bridge gap total

Sum over delaying claimants of the bridge ladder cost and of the annual real bridge income sized by sizeBridge, for claimants whose gap years are not already covered by a plan ladder.

Field: Social Security bridge total cost and income Unit: US dollars Basis: nominal dollars Computed by: Engine Status: No calculation record yet

Appears in: insights (ss-bridge-gap card rationale "A TIPS bridge ladder (≈$X today) pays you ... (~$Y/yr)")

No calculation record yet. The number is computed today in engine/src/insights/detectors/ssBridgeGap.ts (ssBridgeGap.screen (totalCost, annualTotal)).

Insight state relocation lifetime state tax savings

Sum over projection years of deflated (best zero-tax candidate state tax minus baseline state tax), floored at zero, for the best of FL, TX and WA.

Field: Lifetime state tax saved by relocating Unit: US dollars Basis: today's dollars (real) Computed by: Engine Status: No calculation record yet

Appears in: insights (state-relocation card impact after Preview "staying in ST costs about $X of lifetime state+local income tax")

No calculation record yet. The number is computed today in engine/src/insights/detectors/stateRelocation.ts (stateRelocation.evaluate (savings)).

Insight widows penalty bracket jump

Federal tax on the first single-filed survivor year's MAGI computed as Single minus the same income computed as married filing jointly, deflated to today's dollars.

Field: Survivor bracket jump Unit: US dollars Basis: today's dollars (real) Computed by: Engine Status: No calculation record yet

Appears in: insights (widows-penalty-roth card rationale "cost about $X more (today's $)")

No calculation record yet. The number is computed today in engine/src/insights/detectors/widowsPenalty.ts (widowsPenalty.screen (bracketJumpToday)).