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: Complete chain

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

Calculation records

• Historical stress window total shortfall Composition record, justified by derivation

  Purpose: How many dollars of spending one replayed history left unfunded across the whole projection.

  Statement: montecarlo/historicalSuites.ts#HistoricalStressWindow.totalShortfall is the sum, over EVERY projection year of that window's replayed run, of the year's YearResult.shortfall: the funding shortfall left after every withdrawal and any HECM backstop draw. Every year is counted, including years after the portfolio first empties, and each year's shortfall is that year's own unfunded spending rather than a cumulative miss. The annual shortfalls remain outputs of the full shared ledger: returns, inflation, taxes, income, withdrawals and HECM draws are priced by simulatePlan on the window's market series, not by a side model. Units: nominal dollars. Rounding: none.

  Formula: totalShortfall = sum over projection years of shortfall_y

  • shortfall_y: Year y's funding shortfall after every withdrawal and any HECM backstop draw (unit: usd) (domain: shortfall_y >= 0)
  • window: One rolling (or reversed) historical return/inflation series replayed through the ledger (unit: years) (domain: windowLengthYears from HISTORICAL_YEARS)

  Timing: once per window, over every published projection year

  Rounding: none

  Limits:

  • Beyond the worksheet's inputs the evidence plan fixes a plan the replay cannot move on either axis: one CASH account, which annualPostSolveAccountGrowth exempts from the market return shock, so the replayed returns really are the worksheet's 0, 0, 0; and the $60,000 a year delivered as the scheduled payment of an interest-free note, because debt service is NOMINAL while base spending and one-time goals are both inflated to the year (the 2000-2002 window's own 3.4% and 1.6% CPI prints rescale a goal-based test to a 2027 shortfall of $22,040). Beside that: a 58-year-old single filer (no Medicare month, no traditional account to penalize), no income, no tax, no HECM, and a three-year horizon from the planning age
  • Because that plan is replay-invariant, every rolling window in the suite reports the same total; the evidence reads the 2000-2002 window by label, and the identity it pins is the sum, not a property of those particular historical years
  • Suites are run with suites: ['rolling'] and windowLengthYears 3 to keep the test to one pass over the rolling windows
  • An explicit windowLengthYears must be a whole number of years from 1 to 96; anything else is refused with a message before any window is simulated, rather than clamped
  • The sum does not distinguish a discretionary miss from a floor miss: totalRequiredShortfall and totalTargetShortfall are separate fields over the same years

  Provenance: derived by codex, implemented by claude.

  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: historical-stress-window-total-shortfall.md Mutation receipt: historical-stress-window-total-shortfall.mutation.md

  Evidence tests: historicalSuites.evidence.test.ts

  Implemented in: historicalSuites.ts

  Is the number of: historical-stress-window-total-shortfall

Engine source: engine/src/montecarlo/historicalSuites.ts (HistoricalStressWindow.totalShortfall)