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

Appears in: monte-carlo-page ("When depleting plans run out" bar chart); monte-carlo-page (WhySuccessPanel "Which years drive it": "Failing paths first run out between EARLIEST and LATEST" (the first and last rows))

Calculation records

• Depletion-year histogram across paths Formula record, justified by derivation

  Purpose: How many paths first ran out of investable assets in each year, with the paths that never depleted left out.

  Statement: Every path with a non-null depletionYear adds 1 to that year's bucket; a path whose depletionYear is null never depleted and contributes nothing at all. The buckets are published as { year, count } rows in ascending year order, one row per year that occurs. For the worksheet's five paths (null, 2031, 2031, 2033, null) the rows are [{ year: 2031, count: 2 }, { year: 2033, count: 1 }]. Units: paths per calendar year. Rounding: none; integer counts and years, compared exactly.

  Formula: count(y) = |{ p : p.depletionYear = y }| for each y that occurs, rows sorted by ascending y

  • p.depletionYear: Year a path first depleted; null when it never did (unit: calendar year or null) (domain: worksheet null, 2031, 2031, 2033, null)
  • count(y): Paths first depleting in year y (unit: paths) (domain: integer >= 1 for a year that appears)

  Timing: once per aggregation, over the completed path set

  Rounding: none; integer counts

  Limits:

  • Successful paths are absent entirely: there is no null bucket, and no zero row for a year in which nothing depleted
  • The rows are grouped, not one row per failing path; the two 2031 failures are one row of count 2
  • depletionProbabilityByYear divides these counts by a base this record does not publish; monte-carlo-depletion-probability-by-year states that rule
  • The evidence supplies depletionYear only; every other MonteCarloPath field is at the test’s neutral (zero balances and shortfalls, floor and target met, attainment 1, no goal or guardrail activity, 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-depletion-distribution.md Mutation receipt: monte-carlo-depletion-distribution.mutation.md

  Evidence tests: run.evidence.test.ts

  Implemented in: run.ts

  Is the number of: monte-carlo-depletion-year-histogram

Engine source: engine/src/montecarlo/run.ts (MonteCarloSummary.depletionYearCounts[].count)