@retiregolden/engine 0.1.0

package/dist/montecarlo/frontiers.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Bounded stochastic frontier sweeps.
+ *
+ * The helpers build ordinary plan variants and evaluate them through the
+ * shared-path primitive. They do not search; callers provide small fixed grids.
+ */
+import type { Plan } from '../model/plan.js';
+import { type SharedPathComparisonOptions } from './sharedPaths.js';
+export declare const MAX_FRONTIER_POINTS = 15;
+export interface StochasticFrontierPoint {
+    id: string;
+    label: string;
+    x: number;
+    successRate: number;
+    requiredFloorSuccessRate: number;
+    targetLifestyleSuccessRate: number;
+    p10EndingAfterTaxEstate: number;
+    medianEndingAfterTaxEstate: number;
+    expectedShortfallDollars: number;
+}
+export declare function buildSpendingSuccessFrontier(plan: Plan, opts: SharedPathComparisonOptions, multipliers?: readonly number[]): StochasticFrontierPoint[];
+export declare function buildRetirementAgeSuccessFrontier(plan: Plan, opts: SharedPathComparisonOptions, deltas?: readonly number[]): StochasticFrontierPoint[];

package/dist/montecarlo/frontiers.js

@@ -0,0 +1,61 @@
+/**
+ * Bounded stochastic frontier sweeps.
+ *
+ * The helpers build ordinary plan variants and evaluate them through the
+ * shared-path primitive. They do not search; callers provide small fixed grids.
+ */
+import { comparePlansOnSharedMarketPaths, } from './sharedPaths.js';
+export const MAX_FRONTIER_POINTS = 15;
+function assertBounded(pointCount) {
+    if (pointCount > MAX_FRONTIER_POINTS) {
+        throw new Error(`Frontier sweeps are capped at ${MAX_FRONTIER_POINTS} points; received ${pointCount}.`);
+    }
+}
+function pointFromRow(id, label, x, row) {
+    return {
+        id,
+        label,
+        x,
+        successRate: row.summary.successRate,
+        requiredFloorSuccessRate: row.summary.requiredFloorSuccessRate,
+        targetLifestyleSuccessRate: row.summary.targetLifestyleSuccessRate,
+        p10EndingAfterTaxEstate: row.summary.endingAfterTaxEstate.percentiles.p10,
+        medianEndingAfterTaxEstate: row.summary.endingAfterTaxEstate.percentiles.p50,
+        expectedShortfallDollars: row.summary.downsideRisk.expectedShortfallDollars,
+    };
+}
+export function buildSpendingSuccessFrontier(plan, opts, multipliers = [0.85, 0.9, 0.95, 1, 1.05, 1.1, 1.15]) {
+    assertBounded(multipliers.length);
+    const variants = multipliers.map((multiplier) => {
+        const baseAnnual = Math.max(0, Math.round(plan.expenses.baseAnnual * multiplier));
+        const pct = Math.round(multiplier * 100);
+        return {
+            id: `spending-${pct}`,
+            label: `${pct}% spending`,
+            plan: { ...plan, expenses: { ...plan.expenses, baseAnnual } },
+        };
+    });
+    const comparison = comparePlansOnSharedMarketPaths(variants, opts);
+    return comparison.rows.map((row, index) => pointFromRow(row.id, row.label, variants[index].plan.expenses.baseAnnual, row));
+}
+export function buildRetirementAgeSuccessFrontier(plan, opts, deltas = [-2, -1, 0, 1, 2]) {
+    assertBounded(deltas.length);
+    const variants = deltas.map((delta) => {
+        const people = plan.household.people.map((person) => ({
+            ...person,
+            retirementAge: person.retirementAge === null ? null : Math.min(80, Math.max(30, person.retirementAge + delta)),
+        }));
+        const changedAges = people
+            .map((person) => person.retirementAge)
+            .filter((age) => age !== null);
+        const x = changedAges.length > 0 ? Math.min(...changedAges) : 0;
+        return {
+            id: `retirement-${delta >= 0 ? 'plus' : 'minus'}-${Math.abs(delta)}`,
+            label: delta === 0 ? 'Current retirement age' : `${Math.abs(delta)}y ${delta < 0 ? 'earlier' : 'later'}`,
+            plan: { ...plan, household: { ...plan.household, people } },
+            x,
+        };
+    });
+    const comparison = comparePlansOnSharedMarketPaths(variants, opts);
+    return comparison.rows.map((row, index) => pointFromRow(row.id, row.label, variants[index].x ?? 0, row));
+}

package/dist/montecarlo/historicalReturns.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Annual US market history for the bootstrap return models (roadmap V4).
+ *
+ * Values are approximate (≈0.1–0.5pp), transcribed from the public Damodaran
+ * (NYU Stern) "Historical Returns on Stocks, Bonds and Bills" dataset, which
+ * itself derives from Shiller's annual series: S&P 500 total return, 10-year
+ * Treasury total return, and calendar-year CPI inflation. Bootstrap sampling
+ * cares about the joint distribution and sequencing of these series, not
+ * basis-point precision. Refresh alongside the annual parameter-pack
+ * workstream (see DOCS/maintenance-schedule.md, standing workstreams).
+ *
+ * Source: https://pages.stern.nyu.edu/~adamodar/New_Home_Page/datafile/histretSP.html
+ */
+export interface HistoricalYear {
+    year: number;
+    /** S&P 500 total return, percent. */
+    stocksPct: number;
+    /** 10-year US Treasury total return, percent. */
+    bondsPct: number;
+    /** CPI-U calendar-year inflation, percent. */
+    inflationPct: number;
+}
+export declare const HISTORICAL_YEARS: readonly HistoricalYear[];
+/** Blended nominal portfolio return for one historical year. */
+export declare function portfolioReturnPct(year: HistoricalYear, equityWeightPct: number): number;
+/** Mean blended return across the dataset (centers bootstrap shocks at zero). */
+export declare function meanPortfolioReturnPct(equityWeightPct: number): number;

package/dist/montecarlo/historicalReturns.js

@@ -0,0 +1,124 @@
+/**
+ * Annual US market history for the bootstrap return models (roadmap V4).
+ *
+ * Values are approximate (≈0.1–0.5pp), transcribed from the public Damodaran
+ * (NYU Stern) "Historical Returns on Stocks, Bonds and Bills" dataset, which
+ * itself derives from Shiller's annual series: S&P 500 total return, 10-year
+ * Treasury total return, and calendar-year CPI inflation. Bootstrap sampling
+ * cares about the joint distribution and sequencing of these series, not
+ * basis-point precision. Refresh alongside the annual parameter-pack
+ * workstream (see DOCS/maintenance-schedule.md, standing workstreams).
+ *
+ * Source: https://pages.stern.nyu.edu/~adamodar/New_Home_Page/datafile/histretSP.html
+ */
+// prettier-ignore
+export const HISTORICAL_YEARS = [
+    { year: 1928, stocksPct: 43.8, bondsPct: 0.8, inflationPct: -1.2 },
+    { year: 1929, stocksPct: -8.3, bondsPct: 4.2, inflationPct: 0.6 },
+    { year: 1930, stocksPct: -25.1, bondsPct: 4.5, inflationPct: -6.4 },
+    { year: 1931, stocksPct: -43.8, bondsPct: -2.6, inflationPct: -9.3 },
+    { year: 1932, stocksPct: -8.6, bondsPct: 8.8, inflationPct: -10.3 },
+    { year: 1933, stocksPct: 50.0, bondsPct: 1.9, inflationPct: 0.8 },
+    { year: 1934, stocksPct: -1.2, bondsPct: 8.0, inflationPct: 1.5 },
+    { year: 1935, stocksPct: 46.7, bondsPct: 4.5, inflationPct: 3.0 },
+    { year: 1936, stocksPct: 31.9, bondsPct: 5.0, inflationPct: 1.4 },
+    { year: 1937, stocksPct: -35.3, bondsPct: 1.4, inflationPct: 2.9 },
+    { year: 1938, stocksPct: 29.3, bondsPct: 4.2, inflationPct: -2.8 },
+    { year: 1939, stocksPct: -1.1, bondsPct: 4.4, inflationPct: 0.0 },
+    { year: 1940, stocksPct: -10.7, bondsPct: 5.4, inflationPct: 0.7 },
+    { year: 1941, stocksPct: -12.8, bondsPct: -2.0, inflationPct: 9.9 },
+    { year: 1942, stocksPct: 19.2, bondsPct: 2.3, inflationPct: 9.0 },
+    { year: 1943, stocksPct: 25.1, bondsPct: 2.5, inflationPct: 3.0 },
+    { year: 1944, stocksPct: 19.0, bondsPct: 2.6, inflationPct: 2.3 },
+    { year: 1945, stocksPct: 35.8, bondsPct: 3.8, inflationPct: 2.2 },
+    { year: 1946, stocksPct: -8.4, bondsPct: 3.1, inflationPct: 18.1 },
+    { year: 1947, stocksPct: 5.2, bondsPct: 0.9, inflationPct: 8.8 },
+    { year: 1948, stocksPct: 5.7, bondsPct: 2.0, inflationPct: 3.0 },
+    { year: 1949, stocksPct: 18.3, bondsPct: 4.7, inflationPct: -2.1 },
+    { year: 1950, stocksPct: 30.8, bondsPct: 0.4, inflationPct: 5.9 },
+    { year: 1951, stocksPct: 23.7, bondsPct: -0.3, inflationPct: 6.0 },
+    { year: 1952, stocksPct: 18.2, bondsPct: 2.3, inflationPct: 0.8 },
+    { year: 1953, stocksPct: -1.2, bondsPct: 4.1, inflationPct: 0.7 },
+    { year: 1954, stocksPct: 52.6, bondsPct: 3.3, inflationPct: -0.7 },
+    { year: 1955, stocksPct: 32.6, bondsPct: -1.3, inflationPct: 0.4 },
+    { year: 1956, stocksPct: 7.4, bondsPct: -2.3, inflationPct: 3.0 },
+    { year: 1957, stocksPct: -10.5, bondsPct: 6.8, inflationPct: 2.9 },
+    { year: 1958, stocksPct: 43.7, bondsPct: -2.1, inflationPct: 1.8 },
+    { year: 1959, stocksPct: 12.1, bondsPct: -2.6, inflationPct: 1.7 },
+    { year: 1960, stocksPct: 0.3, bondsPct: 11.6, inflationPct: 1.4 },
+    { year: 1961, stocksPct: 26.6, bondsPct: 2.1, inflationPct: 0.7 },
+    { year: 1962, stocksPct: -8.8, bondsPct: 5.7, inflationPct: 1.3 },
+    { year: 1963, stocksPct: 22.6, bondsPct: 1.7, inflationPct: 1.6 },
+    { year: 1964, stocksPct: 16.4, bondsPct: 3.7, inflationPct: 1.0 },
+    { year: 1965, stocksPct: 12.4, bondsPct: 0.7, inflationPct: 1.9 },
+    { year: 1966, stocksPct: -10.0, bondsPct: 2.9, inflationPct: 3.5 },
+    { year: 1967, stocksPct: 23.8, bondsPct: -1.6, inflationPct: 3.0 },
+    { year: 1968, stocksPct: 10.8, bondsPct: 3.3, inflationPct: 4.7 },
+    { year: 1969, stocksPct: -8.2, bondsPct: -5.0, inflationPct: 6.2 },
+    { year: 1970, stocksPct: 3.6, bondsPct: 16.8, inflationPct: 5.6 },
+    { year: 1971, stocksPct: 14.2, bondsPct: 9.8, inflationPct: 3.3 },
+    { year: 1972, stocksPct: 18.8, bondsPct: 2.8, inflationPct: 3.4 },
+    { year: 1973, stocksPct: -14.3, bondsPct: 3.7, inflationPct: 8.7 },
+    { year: 1974, stocksPct: -25.9, bondsPct: 2.0, inflationPct: 12.3 },
+    { year: 1975, stocksPct: 37.0, bondsPct: 3.6, inflationPct: 6.9 },
+    { year: 1976, stocksPct: 23.8, bondsPct: 16.0, inflationPct: 4.9 },
+    { year: 1977, stocksPct: -7.0, bondsPct: 1.3, inflationPct: 6.7 },
+    { year: 1978, stocksPct: 6.5, bondsPct: -0.8, inflationPct: 9.0 },
+    { year: 1979, stocksPct: 18.5, bondsPct: 0.7, inflationPct: 13.3 },
+    { year: 1980, stocksPct: 31.7, bondsPct: -3.0, inflationPct: 12.5 },
+    { year: 1981, stocksPct: -4.7, bondsPct: 8.2, inflationPct: 8.9 },
+    { year: 1982, stocksPct: 20.4, bondsPct: 32.8, inflationPct: 3.8 },
+    { year: 1983, stocksPct: 22.3, bondsPct: 3.2, inflationPct: 3.8 },
+    { year: 1984, stocksPct: 6.1, bondsPct: 13.7, inflationPct: 3.9 },
+    { year: 1985, stocksPct: 31.2, bondsPct: 25.7, inflationPct: 3.8 },
+    { year: 1986, stocksPct: 18.5, bondsPct: 24.3, inflationPct: 1.1 },
+    { year: 1987, stocksPct: 5.8, bondsPct: -5.0, inflationPct: 4.4 },
+    { year: 1988, stocksPct: 16.5, bondsPct: 8.2, inflationPct: 4.4 },
+    { year: 1989, stocksPct: 31.5, bondsPct: 17.7, inflationPct: 4.6 },
+    { year: 1990, stocksPct: -3.1, bondsPct: 6.2, inflationPct: 6.1 },
+    { year: 1991, stocksPct: 30.2, bondsPct: 15.0, inflationPct: 3.1 },
+    { year: 1992, stocksPct: 7.5, bondsPct: 9.4, inflationPct: 2.9 },
+    { year: 1993, stocksPct: 10.0, bondsPct: 14.2, inflationPct: 2.7 },
+    { year: 1994, stocksPct: 1.3, bondsPct: -8.0, inflationPct: 2.7 },
+    { year: 1995, stocksPct: 37.2, bondsPct: 23.5, inflationPct: 2.5 },
+    { year: 1996, stocksPct: 22.7, bondsPct: 1.4, inflationPct: 3.3 },
+    { year: 1997, stocksPct: 33.1, bondsPct: 9.9, inflationPct: 1.7 },
+    { year: 1998, stocksPct: 28.3, bondsPct: 14.9, inflationPct: 1.6 },
+    { year: 1999, stocksPct: 20.9, bondsPct: -8.3, inflationPct: 2.7 },
+    { year: 2000, stocksPct: -9.0, bondsPct: 16.7, inflationPct: 3.4 },
+    { year: 2001, stocksPct: -11.9, bondsPct: 5.6, inflationPct: 1.6 },
+    { year: 2002, stocksPct: -22.0, bondsPct: 15.1, inflationPct: 2.4 },
+    { year: 2003, stocksPct: 28.4, bondsPct: 0.4, inflationPct: 1.9 },
+    { year: 2004, stocksPct: 10.7, bondsPct: 4.5, inflationPct: 3.3 },
+    { year: 2005, stocksPct: 4.8, bondsPct: 2.9, inflationPct: 3.4 },
+    { year: 2006, stocksPct: 15.6, bondsPct: 2.0, inflationPct: 2.5 },
+    { year: 2007, stocksPct: 5.5, bondsPct: 10.2, inflationPct: 4.1 },
+    { year: 2008, stocksPct: -36.6, bondsPct: 20.1, inflationPct: 0.1 },
+    { year: 2009, stocksPct: 25.9, bondsPct: -11.1, inflationPct: 2.7 },
+    { year: 2010, stocksPct: 14.8, bondsPct: 8.5, inflationPct: 1.5 },
+    { year: 2011, stocksPct: 2.1, bondsPct: 16.0, inflationPct: 3.0 },
+    { year: 2012, stocksPct: 15.9, bondsPct: 3.0, inflationPct: 1.7 },
+    { year: 2013, stocksPct: 32.2, bondsPct: -9.1, inflationPct: 1.5 },
+    { year: 2014, stocksPct: 13.5, bondsPct: 10.7, inflationPct: 0.8 },
+    { year: 2015, stocksPct: 1.4, bondsPct: 1.3, inflationPct: 0.7 },
+    { year: 2016, stocksPct: 11.8, bondsPct: 0.7, inflationPct: 2.1 },
+    { year: 2017, stocksPct: 21.6, bondsPct: 2.8, inflationPct: 2.1 },
+    { year: 2018, stocksPct: -4.2, bondsPct: 0.0, inflationPct: 1.9 },
+    { year: 2019, stocksPct: 31.2, bondsPct: 9.6, inflationPct: 2.3 },
+    { year: 2020, stocksPct: 18.0, bondsPct: 11.3, inflationPct: 1.4 },
+    { year: 2021, stocksPct: 28.5, bondsPct: -4.4, inflationPct: 7.0 },
+    { year: 2022, stocksPct: -18.0, bondsPct: -17.8, inflationPct: 6.5 },
+    { year: 2023, stocksPct: 26.1, bondsPct: 3.9, inflationPct: 3.4 },
+];
+/** Blended nominal portfolio return for one historical year. */
+export function portfolioReturnPct(year, equityWeightPct) {
+    const w = equityWeightPct / 100;
+    return year.stocksPct * w + year.bondsPct * (1 - w);
+}
+/** Mean blended return across the dataset (centers bootstrap shocks at zero). */
+export function meanPortfolioReturnPct(equityWeightPct) {
+    let sum = 0;
+    for (const y of HISTORICAL_YEARS)
+        sum += portfolioReturnPct(y, equityWeightPct);
+    return sum / HISTORICAL_YEARS.length;
+}

package/dist/montecarlo/historicalSuites.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Deterministic historical stress suites.
+ *
+ * These are not random Monte Carlo runs. They replay every rolling historical
+ * window, plus optional reversed windows, through the same projection ledger.
+ */
+import { type Plan } from '../model/plan.js';
+import { type ProjectionSummary } from '../projection/compare.js';
+import { type SimulateOptions } from '../projection/simulate.js';
+import type { ProjectionResult } from '../projection/types.js';
+export type HistoricalStressSuiteKind = 'rolling' | 'reversed';
+export interface HistoricalStressWindow {
+    suite: HistoricalStressSuiteKind;
+    label: string;
+    startHistoricalYear: number;
+    endHistoricalYear: number;
+    reversed: boolean;
+    marketYears: number[];
+    projection: ProjectionResult;
+    summary: ProjectionSummary;
+    success: boolean;
+    totalShortfall: number;
+    totalRequiredShortfall: number;
+    totalTargetShortfall: number;
+}
+export interface HistoricalStressSuite {
+    kind: HistoricalStressSuiteKind;
+    name: string;
+    windowLengthYears: number;
+    windows: HistoricalStressWindow[];
+    worstByEndingAfterTaxEstate: HistoricalStressWindow[];
+    worstByTotalShortfall: HistoricalStressWindow[];
+}
+export interface HistoricalStressSuiteResult {
+    windowLengthYears: number;
+    suites: HistoricalStressSuite[];
+}
+export interface HistoricalStressSuiteOptions extends SimulateOptions {
+    equityWeightPct?: number;
+    windowLengthYears?: number;
+    suites?: readonly HistoricalStressSuiteKind[];
+    classShocks?: boolean;
+    worstWindowCount?: number;
+}
+export declare function runHistoricalStressSuites(plan: Plan, opts: HistoricalStressSuiteOptions): HistoricalStressSuiteResult;

package/dist/montecarlo/historicalSuites.js

@@ -0,0 +1,102 @@
+/**
+ * Deterministic historical stress suites.
+ *
+ * These are not random Monte Carlo runs. They replay every rolling historical
+ * window, plus optional reversed windows, through the same projection ledger.
+ */
+import { ASSET_CLASS_IDS } from '../model/plan.js';
+import { summarizeProjection } from '../projection/compare.js';
+import { simulatePlan } from '../projection/simulate.js';
+import { HISTORICAL_YEARS, meanPortfolioReturnPct, portfolioReturnPct } from './historicalReturns.js';
+function historicalReplaySeries(args) {
+    const mean = meanPortfolioReturnPct(args.equityWeightPct);
+    const meanStocks = meanPortfolioReturnPct(100);
+    const meanBonds = meanPortfolioReturnPct(0);
+    const returnShockPct = new Array(args.projectionYears);
+    const inflationPct = new Array(args.projectionYears);
+    const classSeries = args.classShocks
+        ? Object.fromEntries(ASSET_CLASS_IDS.map((id) => [id, new Array(args.projectionYears)]))
+        : null;
+    const marketYears = [];
+    for (let i = 0; i < args.projectionYears; i++) {
+        const offset = i % args.windowLength;
+        const historicalIndex = args.reversed
+            ? args.startIndex + args.windowLength - 1 - offset
+            : args.startIndex + offset;
+        const sample = HISTORICAL_YEARS[historicalIndex];
+        marketYears.push(sample.year);
+        returnShockPct[i] = portfolioReturnPct(sample, args.equityWeightPct) - mean;
+        inflationPct[i] = sample.inflationPct;
+        if (classSeries) {
+            const stockShock = sample.stocksPct - meanStocks;
+            classSeries.usStocks[i] = stockShock;
+            classSeries.intlStocks[i] = stockShock;
+            classSeries.bonds[i] = sample.bondsPct - meanBonds;
+            classSeries.cash[i] = 0;
+        }
+    }
+    return {
+        market: classSeries ? { returnShockPct, inflationPct, classReturnShockPct: classSeries } : { returnShockPct, inflationPct },
+        marketYears,
+    };
+}
+function total(result, pick) {
+    return result.years.reduce((sum, year) => sum + pick(year), 0);
+}
+function suiteName(kind, windowLength) {
+    return kind === 'rolling' ? `Rolling ${windowLength}-year historical windows` : `Reversed ${windowLength}-year historical windows`;
+}
+export function runHistoricalStressSuites(plan, opts) {
+    const baseline = simulatePlan(plan, { startYear: opts.startYear, taxCalculator: opts.taxCalculator });
+    const projectionYears = baseline.years.length;
+    const windowLength = Math.max(1, Math.min(opts.windowLengthYears ?? projectionYears, HISTORICAL_YEARS.length));
+    const kinds = opts.suites ?? ['rolling', 'reversed'];
+    const lastStart = HISTORICAL_YEARS.length - windowLength;
+    const worstWindowCount = Math.max(1, opts.worstWindowCount ?? 5);
+    const suites = [];
+    for (const kind of kinds) {
+        const reversed = kind === 'reversed';
+        const windows = [];
+        for (let startIndex = 0; startIndex <= lastStart; startIndex++) {
+            const first = HISTORICAL_YEARS[startIndex];
+            const last = HISTORICAL_YEARS[startIndex + windowLength - 1];
+            const { market, marketYears } = historicalReplaySeries({
+                startIndex,
+                windowLength,
+                projectionYears,
+                equityWeightPct: opts.equityWeightPct ?? 60,
+                reversed,
+                classShocks: opts.classShocks ?? false,
+            });
+            const projection = simulatePlan(plan, { startYear: opts.startYear, taxCalculator: opts.taxCalculator, market });
+            const summary = summarizeProjection(plan, projection);
+            windows.push({
+                suite: kind,
+                label: reversed ? `${first.year}-${last.year} reversed` : `${first.year}-${last.year}`,
+                startHistoricalYear: first.year,
+                endHistoricalYear: last.year,
+                reversed,
+                marketYears,
+                projection,
+                summary,
+                success: projection.depletionYear === null,
+                totalShortfall: total(projection, (year) => year.shortfall),
+                totalRequiredShortfall: total(projection, (year) => year.requiredShortfall),
+                totalTargetShortfall: total(projection, (year) => year.targetShortfall),
+            });
+        }
+        suites.push({
+            kind,
+            name: suiteName(kind, windowLength),
+            windowLengthYears: windowLength,
+            windows,
+            worstByEndingAfterTaxEstate: [...windows]
+                .sort((a, b) => a.summary.endingAfterTaxEstate - b.summary.endingAfterTaxEstate)
+                .slice(0, worstWindowCount),
+            worstByTotalShortfall: [...windows]
+                .sort((a, b) => b.totalShortfall - a.totalShortfall || a.summary.endingAfterTaxEstate - b.summary.endingAfterTaxEstate)
+                .slice(0, worstWindowCount),
+        });
+    }
+    return { windowLengthYears: windowLength, suites };
+}

package/dist/montecarlo/ltcShock.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Probabilistic long-term-care shock for Monte Carlo (roadmap V6 §4).
+ *
+ * Each path may draw a paid-care episode per person — incidence, onset age, and
+ * duration — so an LTC policy's risk reduction shows up in the success-rate and
+ * ending-balance distribution, not just the single deterministic "LTC stress"
+ * what-if. The sampled episode is injected as a plan careEvent, so the existing
+ * engine offset (monthly cap × inflation rider, elimination period, benefit
+ * period) applies unchanged.
+ *
+ * Default distribution (planning precision, editable in the UI):
+ *  - incidence: ~50% of people 65+ need a significant period of *paid* LTSS
+ *    (HHS/ASPE, "Long-Term Services and Supports for Older Americans").
+ *  - duration: right-skewed — most need <2 years, a meaningful tail needs 5+.
+ *  - annual cost: ~$75k, near the national median for assisted living / a year
+ *    of substantial home care (Genworth Cost of Care survey range).
+ */
+import type { CareEvent } from '../model/plan.js';
+import type { Rng } from './rng.js';
+export interface LtcShockParams {
+    /** Probability a person experiences a paid-care episode in late life. */
+    incidence: number;
+    /** Onset age sampled uniformly in [minOnsetAge, maxOnsetAge]. */
+    minOnsetAge: number;
+    maxOnsetAge: number;
+    /** Discrete duration distribution (years → relative weight). */
+    durations: ReadonlyArray<{
+        years: number;
+        weight: number;
+    }>;
+    /** Annual care cost, today's dollars. */
+    annualCost: number;
+}
+export declare const DEFAULT_LTC_SHOCK: LtcShockParams;
+/**
+ * Sample zero or one care episode per person for one path. Onset is clamped to
+ * be no earlier than the person's current age so the spike lands in the future.
+ */
+export declare function sampleCareEvents(rng: Rng, people: ReadonlyArray<{
+    id: string;
+    dob: string;
+}>, startYear: number, params: LtcShockParams): CareEvent[];

package/dist/montecarlo/ltcShock.js

@@ -0,0 +1,62 @@
+/**
+ * Probabilistic long-term-care shock for Monte Carlo (roadmap V6 §4).
+ *
+ * Each path may draw a paid-care episode per person — incidence, onset age, and
+ * duration — so an LTC policy's risk reduction shows up in the success-rate and
+ * ending-balance distribution, not just the single deterministic "LTC stress"
+ * what-if. The sampled episode is injected as a plan careEvent, so the existing
+ * engine offset (monthly cap × inflation rider, elimination period, benefit
+ * period) applies unchanged.
+ *
+ * Default distribution (planning precision, editable in the UI):
+ *  - incidence: ~50% of people 65+ need a significant period of *paid* LTSS
+ *    (HHS/ASPE, "Long-Term Services and Supports for Older Americans").
+ *  - duration: right-skewed — most need <2 years, a meaningful tail needs 5+.
+ *  - annual cost: ~$75k, near the national median for assisted living / a year
+ *    of substantial home care (Genworth Cost of Care survey range).
+ */
+export const DEFAULT_LTC_SHOCK = {
+    incidence: 0.5,
+    minOnsetAge: 80,
+    maxOnsetAge: 90,
+    durations: [
+        { years: 1, weight: 0.3 },
+        { years: 2, weight: 0.3 },
+        { years: 3, weight: 0.2 },
+        { years: 5, weight: 0.15 },
+        { years: 8, weight: 0.05 },
+    ],
+    annualCost: 75_000,
+};
+function pickDuration(rng, durations) {
+    const total = durations.reduce((sum, d) => sum + d.weight, 0);
+    let r = rng.next() * total;
+    for (const d of durations) {
+        r -= d.weight;
+        if (r <= 0)
+            return d.years;
+    }
+    return durations[durations.length - 1]?.years ?? 1;
+}
+/**
+ * Sample zero or one care episode per person for one path. Onset is clamped to
+ * be no earlier than the person's current age so the spike lands in the future.
+ */
+export function sampleCareEvents(rng, people, startYear, params) {
+    const events = [];
+    for (const p of people) {
+        if (rng.next() >= params.incidence)
+            continue;
+        const span = Math.max(0, params.maxOnsetAge - params.minOnsetAge);
+        const currentAge = startYear - Number(p.dob.slice(0, 4));
+        const startAge = Math.max(currentAge, params.minOnsetAge + rng.nextInt(span + 1));
+        events.push({
+            id: `ltc-shock-${p.id}`,
+            personId: p.id,
+            startAge,
+            durationYears: pickDuration(rng, params.durations),
+            annualCost: params.annualCost,
+        });
+    }
+    return events;
+}