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

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))

Calculation records

• Shortfall averages, p90s, and expected shortfall on failing paths Formula record, justified by derivation

  Purpose: How much spending went unfunded across the run, and how much worse it was on the paths that actually ran out.

  Statement: spendingShortfall.averageTotalShortfallDollars and averageYearsBelowTarget are means over all paths; spendingShortfall.p90TotalShortfallDollars and p90AverageAnnualTargetShortfall are interpolated 90th percentiles of the all-path samples; targetAttainmentPct.p50 is the interpolated median of the per-path attainment. downsideRisk.expectedShortfallDollars is the mean total shortfall over the failing paths alone, a failing path being one whose depletionYear is non-null. For the worksheet's five paths these are $36, $80, 3 years, $32, 0.8 and $35. Units: usd, years, and attainment as a fraction of target spending. Rounding: none; absolute 1e-9.

  Formula: mean = (1/N) sum_p x_p; p90 by interpolation at 0.9(N-1); expectedShortfall = (1/F) sum_{p : depletionYear_p != null} totalShortfall_p

  • N: All paths (unit: paths) (domain: worksheet 5)
  • F: Failing paths (non-null depletionYear) (unit: paths) (domain: worksheet 2)
  • totalShortfall_p: One path's unfunded spending (unit: usd) (domain: worksheet 0, 10, 20, 50, 100)
  • targetAttainmentPct_p: One path's share of target spending funded (unit: 1) (domain: worksheet 1.00, 0.90, 0.80, 0.60, 0.20)

  Timing: once per aggregation, over the completed path set

  Rounding: none

  Limits:

  • Expected shortfall conditions on depletion, not on a positive shortfall: path E's $100 shortfall without depletion stays outside it, and averaging all five would give $36 rather than $35
  • The p90 figures are interpolated, so they need not be an observed value: nearest rank would give $100 and $40
  • The requested attainment figure is the median of the percentile set, not the mean, which is 0.70 on these paths
  • The worksheet allows absolute $0.005 on a dollar average whose division is inexact; these five inputs divide exactly, so the test holds every figure to 1e-9
  • downsideRisk.expectedShortfallDollars and the required and target variants beside it are zero, not undefined, when no path fails
  • The evidence supplies depletionYear, totalShortfall, yearsBelowTarget, averageAnnualTargetShortfall and targetAttainmentPct only; every other MonteCarloPath field is at the test’s neutral (floor and target met, no goal or guardrail activity, zero balances, no bequest target)

  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: monte-carlo-shortfall-statistics.md Mutation receipt: monte-carlo-shortfall-statistics.mutation.md

  Evidence tests: run.evidence.test.ts

  Implemented in: run.ts

  Is the number of: monte-carlo-average-total-shortfall, monte-carlo-p90-total-shortfall, monte-carlo-expected-shortfall-on-failing-paths, monte-carlo-average-years-below-target, monte-carlo-p90-average-annual-target-shortfall, monte-carlo-target-attainment-median

Engine source: engine/src/montecarlo/run.ts (MonteCarloSummary.downsideRisk.expectedShortfallDollars)