@retiregolden/engine 0.1.0

package/dist/montecarlo/mortality.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Mortality sampling for stochastic-longevity Monte Carlo (roadmap V6).
+ *
+ * Annual death probability q(x) is derived from the SSA 2022 period life
+ * expectancy table already in the repo, via the standard identity
+ *   E(x) = e(x) − 0.5 = p(x)·(1 + E(x+1))   ⇒   q(x) = 1 − (e(x)−0.5)/(e(x+1)+0.5)
+ * where E is the curtate expectation and p = 1−q is one-year survival. This
+ * grounds the model in the same cited SSA data the deterministic life-
+ * expectancy estimate uses — no separate q(x) dataset to maintain.
+ *
+ * @see ../../longevity/ssaPeriod2022 (SSA Table 4C6, 2022)
+ */
+import type { Rng } from './rng.js';
+export type Sex = 'male' | 'female' | 'average';
+/** Oldest integer age in the table; everyone is forced to die by here. */
+export declare const MAX_AGE: number;
+/** One-year probability of death at integer age `age` for the given sex. */
+export declare function annualMortality(age: number, sex: Sex): number;
+/**
+ * Sample the age (last full year alive) at death for someone currently `currentAge`,
+ * walking the survival curve year by year with the path RNG. Returns an age that
+ * plays the same role as `planningAge` (alive through it, dead the next year).
+ * Deterministic given the RNG stream, so paths stay reproducible.
+ */
+export declare function sampleDeathAge(rng: Rng, currentAge: number, sex: Sex): number;
+/**
+ * Joint last-survivor life expectancy at the two ages — the years until *both*
+ * are dead, assuming independent lifetimes: e = 0.5 + Σ_t [1 − (1−tp_a)(1−tp_b)].
+ * Used for stochastic-longevity analysis; IRS RMD Table II lives in the RMD module.
+ */
+export declare function jointLastSurvivorExpectancy(ageA: number, sexA: Sex, ageB: number, sexB: Sex): number;

package/dist/montecarlo/mortality.js

@@ -0,0 +1,61 @@
+/**
+ * Mortality sampling for stochastic-longevity Monte Carlo (roadmap V6).
+ *
+ * Annual death probability q(x) is derived from the SSA 2022 period life
+ * expectancy table already in the repo, via the standard identity
+ *   E(x) = e(x) − 0.5 = p(x)·(1 + E(x+1))   ⇒   q(x) = 1 − (e(x)−0.5)/(e(x+1)+0.5)
+ * where E is the curtate expectation and p = 1−q is one-year survival. This
+ * grounds the model in the same cited SSA data the deterministic life-
+ * expectancy estimate uses — no separate q(x) dataset to maintain.
+ *
+ * @see ../../longevity/ssaPeriod2022 (SSA Table 4C6, 2022)
+ */
+import { FEMALE, MALE } from '../longevity/ssaPeriod2022.js';
+const AVERAGE = MALE.map((m, i) => (m + (FEMALE[i] ?? m)) / 2);
+/** Oldest integer age in the table; everyone is forced to die by here. */
+export const MAX_AGE = MALE.length - 1;
+function expectancyTable(sex) {
+    return sex === 'male' ? MALE : sex === 'female' ? FEMALE : AVERAGE;
+}
+/** One-year probability of death at integer age `age` for the given sex. */
+export function annualMortality(age, sex) {
+    const t = expectancyTable(sex);
+    const x = Math.floor(age);
+    if (x < 0)
+        return 0;
+    if (x >= t.length - 1)
+        return 1;
+    const survival = (t[x] - 0.5) / (t[x + 1] + 0.5);
+    return Math.min(1, Math.max(0, 1 - survival));
+}
+/**
+ * Sample the age (last full year alive) at death for someone currently `currentAge`,
+ * walking the survival curve year by year with the path RNG. Returns an age that
+ * plays the same role as `planningAge` (alive through it, dead the next year).
+ * Deterministic given the RNG stream, so paths stay reproducible.
+ */
+export function sampleDeathAge(rng, currentAge, sex) {
+    let age = Math.floor(Math.max(currentAge, 0));
+    while (age < MAX_AGE) {
+        if (rng.next() < annualMortality(age, sex))
+            return age;
+        age++;
+    }
+    return MAX_AGE;
+}
+/**
+ * Joint last-survivor life expectancy at the two ages — the years until *both*
+ * are dead, assuming independent lifetimes: e = 0.5 + Σ_t [1 − (1−tp_a)(1−tp_b)].
+ * Used for stochastic-longevity analysis; IRS RMD Table II lives in the RMD module.
+ */
+export function jointLastSurvivorExpectancy(ageA, sexA, ageB, sexB) {
+    let expectancy = 0.5;
+    let survivalA = 1;
+    let survivalB = 1;
+    for (let t = 1; t <= MAX_AGE + 1; t++) {
+        survivalA *= 1 - annualMortality(ageA + t - 1, sexA);
+        survivalB *= 1 - annualMortality(ageB + t - 1, sexB);
+        expectancy += 1 - (1 - survivalA) * (1 - survivalB);
+    }
+    return expectancy;
+}

package/dist/montecarlo/riskBasedGuardrails.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Risk-based guardrail threshold solver (risk-based-guardrails plan, step 2).
+ *
+ * Translates a target probability-of-success band into dollar-denominated
+ * portfolio thresholds: "if the portfolio falls below $X, cut spending; above
+ * $Z, raise it." For a candidate balance level the solver re-evaluates the
+ * plan's Monte Carlo success probability with every investable balance scaled
+ * to that level — always on the same seeded market paths, so each probe sees
+ * identical market histories and the search is deterministic. Bisection over
+ * the balance scale finds where success crosses each band edge; a second
+ * bisection over the spending level sizes the adjustment that would bring
+ * success back to the middle of the band.
+ *
+ * The evaluated variant is the plan's *fixed-target* spending (any guardrail
+ * policy stripped): the question each threshold answers is "what is the chance
+ * the current spending plan succeeds with no future adjustments" — the public
+ * risk-based guardrail methodology (Kitces 2025; Guyton–Klinger critiques by
+ * Pfau/Jeske motivate the balance-based trigger). Nested full re-simulation
+ * per probe is the budgeted cost; callers keep pathCount modest and run this
+ * in a worker.
+ */
+import type { Plan } from '../model/plan.js';
+import type { TaxCalculator } from '../projection/types.js';
+import type { LtcShockParams } from './ltcShock.js';
+import type { MarketModelConfig } from './marketModels.js';
+export declare const DEFAULT_TARGET_SUCCESS_LOWER_PCT = 70;
+export declare const DEFAULT_TARGET_SUCCESS_UPPER_PCT = 95;
+export interface RiskBasedGuardrailSolveOptions {
+    startYear: number;
+    taxCalculator: TaxCalculator;
+    model: MarketModelConfig;
+    pathCount: number;
+    seed: number;
+    stochasticLongevity?: boolean;
+    ltcShock?: LtcShockParams | null;
+    /** Success-band edges as percents; default to the policy on the plan, then 70/95. */
+    lowerBandPct?: number;
+    upperBandPct?: number;
+    /** Called after each completed Monte Carlo probe (drives progress UI). */
+    onProbeDone?: (completed: number, total: number) => void;
+}
+export interface RiskBasedThreshold {
+    /** Balance level as a fraction of today's investable portfolio. */
+    balanceFrac: number;
+    /** The same level in dollars (today's dollars). */
+    balanceDollars: number;
+    /** Success probability re-evaluated at the threshold (0..1). */
+    successAtThreshold: number;
+}
+/**
+ * Why a band edge has no threshold. 'always-above-band': success stays at or
+ * above the edge even at the bottom of the search bracket — the plan is safe
+ * at any realistic balance and needs no trigger. 'never-reaches-band': success
+ * stays below the edge even at the top of the bracket — the plan is underfunded
+ * for this band at any realistic balance, which is the opposite of safe.
+ */
+export type RiskBasedThresholdOutcome = 'solved' | 'always-above-band' | 'never-reaches-band';
+export interface RiskBasedAdjustment {
+    /** Spending multiplier that restores success to the recovery target at the threshold. */
+    spendingMultiplier: number;
+    /** Adjustment size in today's dollars per year (positive for both cut and raise). */
+    annualDollars: number;
+    /** The same per month. */
+    monthlyDollars: number;
+    /** Success probability after the adjustment, evaluated at the threshold balance (0..1). */
+    successAfter: number;
+}
+export interface RiskBasedGuardrailSolution {
+    /** Sum of investable balances today — the base the fractions apply to. */
+    startingInvestable: number;
+    /** Success probability of the fixed-target plan at today's balances (0..1). */
+    successAtCurrent: number;
+    lowerBandPct: number;
+    upperBandPct: number;
+    /**
+     * Balance below which success falls under the lower band edge. Null when no
+     * crossing exists inside the search bracket; `lowerOutcome` says which way —
+     * always safe vs underfunded (the two must not be conflated).
+     */
+    lower: RiskBasedThreshold | null;
+    lowerOutcome: RiskBasedThresholdOutcome;
+    /** Balance above which success clears the upper band edge; null when no crossing exists. */
+    upper: RiskBasedThreshold | null;
+    upperOutcome: RiskBasedThresholdOutcome;
+    /** Spending cut at the lower threshold that restores success to the band midpoint. */
+    suggestedCut: RiskBasedAdjustment | null;
+    /** Spending raise at the upper threshold that brings success back down to the band midpoint. */
+    suggestedRaise: RiskBasedAdjustment | null;
+    pathCount: number;
+    seed: number;
+}
+export declare function startingInvestableOf(plan: Plan): number;
+export declare function solveRiskBasedGuardrails(plan: Plan, opts: RiskBasedGuardrailSolveOptions): RiskBasedGuardrailSolution;

package/dist/montecarlo/riskBasedGuardrails.js

@@ -0,0 +1,200 @@
+/**
+ * Risk-based guardrail threshold solver (risk-based-guardrails plan, step 2).
+ *
+ * Translates a target probability-of-success band into dollar-denominated
+ * portfolio thresholds: "if the portfolio falls below $X, cut spending; above
+ * $Z, raise it." For a candidate balance level the solver re-evaluates the
+ * plan's Monte Carlo success probability with every investable balance scaled
+ * to that level — always on the same seeded market paths, so each probe sees
+ * identical market histories and the search is deterministic. Bisection over
+ * the balance scale finds where success crosses each band edge; a second
+ * bisection over the spending level sizes the adjustment that would bring
+ * success back to the middle of the band.
+ *
+ * The evaluated variant is the plan's *fixed-target* spending (any guardrail
+ * policy stripped): the question each threshold answers is "what is the chance
+ * the current spending plan succeeds with no future adjustments" — the public
+ * risk-based guardrail methodology (Kitces 2025; Guyton–Klinger critiques by
+ * Pfau/Jeske motivate the balance-based trigger). Nested full re-simulation
+ * per probe is the budgeted cost; callers keep pathCount modest and run this
+ * in a worker.
+ */
+import { createMarketModel } from './marketModels.js';
+import { runMonteCarloPaths } from './run.js';
+export const DEFAULT_TARGET_SUCCESS_LOWER_PCT = 70;
+export const DEFAULT_TARGET_SUCCESS_UPPER_PCT = 95;
+/** Balance-scale search bracket: 2% to 400% of today's portfolio. */
+const MIN_BALANCE_FRAC = 0.02;
+const MAX_BALANCE_FRAC = 4;
+/** Bisection iterations: balance resolution ~0.4% of the bracket, spending ~0.3%. */
+const BALANCE_BISECTION_ITERATIONS = 10;
+const SPENDING_BISECTION_ITERATIONS = 8;
+const INVESTABLE_ACCOUNT_TYPES = new Set(['taxable', 'equityComp', 'traditional', 'roth', 'hsa', 'cash']);
+function isInvestable(account) {
+    return INVESTABLE_ACCOUNT_TYPES.has(account.type);
+}
+export function startingInvestableOf(plan) {
+    let total = 0;
+    for (const account of plan.accounts) {
+        if (isInvestable(account) && 'balance' in account)
+            total += account.balance;
+    }
+    return total;
+}
+/**
+ * Scale every investable balance (and its basis fields proportionally, so the
+ * tax character of the portfolio is unchanged) to `frac` of today's level.
+ */
+function scaleInvestableBalances(plan, frac) {
+    return {
+        ...plan,
+        accounts: plan.accounts.map((account) => {
+            if (!isInvestable(account) || !('balance' in account))
+                return account;
+            const scaled = { ...account, balance: account.balance * frac };
+            if ('costBasis' in scaled)
+                scaled.costBasis = scaled.costBasis * frac;
+            if ('contributionBasis' in scaled && scaled.contributionBasis !== undefined) {
+                scaled.contributionBasis = scaled.contributionBasis * frac;
+            }
+            if ('nondeductibleBasis' in scaled && scaled.nondeductibleBasis !== undefined) {
+                scaled.nondeductibleBasis = scaled.nondeductibleBasis * frac;
+            }
+            return scaled;
+        }),
+    };
+}
+function scaleTargetSpending(plan, multiplier) {
+    return {
+        ...plan,
+        expenses: { ...plan.expenses, baseAnnual: Math.max(0, plan.expenses.baseAnnual * multiplier) },
+    };
+}
+export function solveRiskBasedGuardrails(plan, opts) {
+    const policy = plan.expenses.spendingPolicy;
+    const lowerBandPct = opts.lowerBandPct ?? policy?.targetSuccessLowerPct ?? DEFAULT_TARGET_SUCCESS_LOWER_PCT;
+    const upperBandPct = opts.upperBandPct ?? policy?.targetSuccessUpperPct ?? DEFAULT_TARGET_SUCCESS_UPPER_PCT;
+    if (!(lowerBandPct < upperBandPct)) {
+        throw new Error(`The success band is inverted (${lowerBandPct}–${upperBandPct}%): the cut edge must be below the raise edge.`);
+    }
+    const recoveryTarget = (lowerBandPct + upperBandPct) / 2 / 100;
+    // The evaluated variant keeps spending fixed: thresholds describe the chance
+    // the *current* plan succeeds without future adjustments.
+    const fixedTargetPlan = { ...plan, expenses: { ...plan.expenses, spendingPolicy: undefined } };
+    const startingInvestable = startingInvestableOf(plan);
+    const totalProbes = 1 + 2 * BALANCE_BISECTION_ITERATIONS + 2 + 2 * (SPENDING_BISECTION_ITERATIONS + 1);
+    let completedProbes = 0;
+    const successOf = (variant) => {
+        const result = runMonteCarloPaths(variant, {
+            startYear: opts.startYear,
+            taxCalculator: opts.taxCalculator,
+            model: createMarketModel(opts.model),
+            seed: opts.seed,
+            pathCount: opts.pathCount,
+            stochasticLongevity: opts.stochasticLongevity,
+            ltcShock: opts.ltcShock,
+        });
+        completedProbes++;
+        opts.onProbeDone?.(completedProbes, totalProbes);
+        if (result.paths.length === 0)
+            return 0;
+        let successes = 0;
+        for (const p of result.paths)
+            if (p.depletionYear === null)
+                successes++;
+        return successes / result.paths.length;
+    };
+    const successByFrac = new Map();
+    const successAtFrac = (frac) => {
+        const key = Math.round(frac * 1e6);
+        const cached = successByFrac.get(key);
+        if (cached !== undefined)
+            return cached;
+        const success = successOf(scaleInvestableBalances(fixedTargetPlan, frac));
+        successByFrac.set(key, success);
+        return success;
+    };
+    const successAtCurrent = successAtFrac(1);
+    // Success is monotone nondecreasing in the balance scale on shared paths, so
+    // each band edge is a single crossing findable by bisection. The solved frac
+    // is the *lowest* balance still inside the band for the lower edge, and the
+    // lowest balance above the band for the upper edge. A missing crossing keeps
+    // its reason: staying above the edge everywhere (safe) is the opposite of
+    // never reaching it (underfunded), and callers must not conflate them.
+    const solveCrossing = (targetPct) => {
+        const target = targetPct / 100;
+        if (successAtFrac(MIN_BALANCE_FRAC) >= target)
+            return { threshold: null, outcome: 'always-above-band' };
+        if (successAtFrac(MAX_BALANCE_FRAC) < target)
+            return { threshold: null, outcome: 'never-reaches-band' };
+        let lo = MIN_BALANCE_FRAC;
+        let hi = MAX_BALANCE_FRAC;
+        for (let i = 0; i < BALANCE_BISECTION_ITERATIONS; i++) {
+            const mid = (lo + hi) / 2;
+            if (successAtFrac(mid) >= target)
+                hi = mid;
+            else
+                lo = mid;
+        }
+        return {
+            threshold: { balanceFrac: hi, balanceDollars: hi * startingInvestable, successAtThreshold: successAtFrac(hi) },
+            outcome: 'solved',
+        };
+    };
+    const lowerCrossing = solveCrossing(lowerBandPct);
+    const upperCrossing = solveCrossing(upperBandPct);
+    const lower = lowerCrossing.threshold;
+    const upper = upperCrossing.threshold;
+    // Size the adjustment: at the threshold balance, bisect the target-spending
+    // multiplier until success returns to the middle of the band. The floor of
+    // the cut search respects the plan's required spending floor.
+    const solveAdjustment = (threshold, direction) => {
+        if (!threshold || plan.expenses.baseAnnual <= 0)
+            return null;
+        const atThreshold = scaleInvestableBalances(fixedTargetPlan, threshold.balanceFrac);
+        const requiredFloorMultiplier = Math.min(1, (plan.expenses.requiredAnnual ?? 0) / plan.expenses.baseAnnual);
+        const minMultiplier = direction === 'cut' ? Math.max(0.3, requiredFloorMultiplier) : 1;
+        const maxMultiplier = direction === 'cut' ? 1 : 2;
+        const successAtSpend = (m) => successOf(scaleTargetSpending(atThreshold, m));
+        // Success falls as spending rises: check the target is reachable inside the bracket.
+        const bestCase = successAtSpend(direction === 'cut' ? minMultiplier : maxMultiplier);
+        if (direction === 'cut' && bestCase < recoveryTarget)
+            return null;
+        if (direction === 'raise' && bestCase > recoveryTarget) {
+            // Even a 2× raise keeps success above the midpoint; report the bracket max.
+            const annual = plan.expenses.baseAnnual * (maxMultiplier - 1);
+            return { spendingMultiplier: maxMultiplier, annualDollars: annual, monthlyDollars: annual / 12, successAfter: bestCase };
+        }
+        let lo = minMultiplier;
+        let hi = maxMultiplier;
+        for (let i = 0; i < SPENDING_BISECTION_ITERATIONS; i++) {
+            const mid = (lo + hi) / 2;
+            if (successAtSpend(mid) >= recoveryTarget)
+                lo = mid;
+            else
+                hi = mid;
+        }
+        const multiplier = lo;
+        const annual = Math.abs(1 - multiplier) * plan.expenses.baseAnnual;
+        return {
+            spendingMultiplier: multiplier,
+            annualDollars: annual,
+            monthlyDollars: annual / 12,
+            successAfter: successAtSpend(multiplier),
+        };
+    };
+    return {
+        startingInvestable,
+        successAtCurrent,
+        lowerBandPct,
+        upperBandPct,
+        lower,
+        lowerOutcome: lowerCrossing.outcome,
+        upper,
+        upperOutcome: upperCrossing.outcome,
+        suggestedCut: solveAdjustment(lower, 'cut'),
+        suggestedRaise: solveAdjustment(upper, 'raise'),
+        pathCount: opts.pathCount,
+        seed: opts.seed,
+    };
+}

package/dist/montecarlo/rng.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Seedable RNG for Monte Carlo (roadmap V4). Engine purity requires injected
+ * randomness; mulberry32 is fast, tiny, and good enough for simulation
+ * sampling (not cryptography). Per-path seeds are derived from (seed, index)
+ * so results are reproducible regardless of how paths are split across
+ * workers.
+ */
+export interface Rng {
+    /** Uniform in [0, 1). */
+    next(): number;
+    /** Standard normal (Box–Muller). */
+    nextNormal(): number;
+    /** Uniform integer in [0, n). */
+    nextInt(n: number): number;
+}
+export declare function createRng(seed: number): Rng;
+/** SplitMix32-style hash so path i's stream is independent of path i−1's length. */
+export declare function derivePathSeed(seed: number, pathIndex: number): number;

package/dist/montecarlo/rng.js

@@ -0,0 +1,44 @@
+/**
+ * Seedable RNG for Monte Carlo (roadmap V4). Engine purity requires injected
+ * randomness; mulberry32 is fast, tiny, and good enough for simulation
+ * sampling (not cryptography). Per-path seeds are derived from (seed, index)
+ * so results are reproducible regardless of how paths are split across
+ * workers.
+ */
+export function createRng(seed) {
+    let a = seed >>> 0;
+    const next = () => {
+        a = (a + 0x6d2b79f5) | 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+    let spareNormal = null;
+    return {
+        next,
+        nextNormal() {
+            if (spareNormal !== null) {
+                const v = spareNormal;
+                spareNormal = null;
+                return v;
+            }
+            // Box–Muller; u clamped away from 0 so log() stays finite.
+            const u = Math.max(next(), 1e-12);
+            const v = next();
+            const r = Math.sqrt(-2 * Math.log(u));
+            spareNormal = r * Math.sin(2 * Math.PI * v);
+            return r * Math.cos(2 * Math.PI * v);
+        },
+        nextInt(n) {
+            return Math.min(n - 1, Math.floor(next() * n));
+        },
+    };
+}
+/** SplitMix32-style hash so path i's stream is independent of path i−1's length. */
+export function derivePathSeed(seed, pathIndex) {
+    let h = (seed ^ Math.imul(pathIndex + 1, 0x9e3779b9)) >>> 0;
+    h = Math.imul(h ^ (h >>> 16), 0x21f0aaad);
+    h = Math.imul(h ^ (h >>> 15), 0x735a2d97);
+    return (h ^ (h >>> 15)) >>> 0;
+}

package/dist/montecarlo/run.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Monte Carlo path runner + aggregation (roadmap V4, feature catalog §11).
+ *
+ * Each path is the same deterministic annual ledger (engine/projection)
+ * driven by one stochastic MarketSeries — never a separate model. Per-path
+ * seeds derive from (seed, pathIndex), so a run is reproducible regardless
+ * of how paths are partitioned across workers. Aggregation produces the
+ * headline outputs: success probability, the per-year percentile fan,
+ * the ending-balance distribution, and the depletion-age histogram.
+ */
+import type { Plan } from '../model/plan.js';
+import type { TaxCalculator } from '../projection/types.js';
+import type { LtcShockParams } from './ltcShock.js';
+import type { MarketModel } from './marketModels.js';
+export interface MonteCarloPathOptions {
+    startYear: number;
+    taxCalculator: TaxCalculator;
+    model: MarketModel;
+    seed: number;
+    /** Number of paths this call runs. */
+    pathCount: number;
+    /** Global index of the first path (worker partitioning); default 0. */
+    firstPathIndex?: number;
+    /** Sample each person's lifespan from the mortality table per path (roadmap V6). */
+    stochasticLongevity?: boolean;
+    /** Inject a probabilistic LTC care episode per path (roadmap V6); null = off. */
+    ltcShock?: LtcShockParams | null;
+    /** Called after each completed path (drives progress UI). */
+    onPathDone?: (completed: number) => void;
+}
+/** One path, reduced to what aggregation needs (full ledgers stay worker-local). */
+export interface MonteCarloPath {
+    /** End-of-year investable balance per projection year. */
+    investableByYear: Float64Array;
+    endingInvestable: number;
+    endingNetWorth: number;
+    endingAfterTaxEstate: number;
+    depletionYear: number | null;
+    /** Sum of unfunded spending across the path. */
+    totalShortfall: number;
+    /** Sum of unfunded required-floor dollars across the path. */
+    totalRequiredShortfall: number;
+    /** Sum of missed target-lifestyle dollars across the path. */
+    totalTargetShortfall: number;
+    /**
+     * No year left the required spending floor unfunded (planning-depth roadmap
+     * §4). Distinct from `depletionYear`: a guardrail plan can deliberately cut
+     * discretionary spending yet still fund every essential.
+     */
+    requiredFloorMet: boolean;
+    /** No year missed target-lifestyle spending (a superset failure of the floor). */
+    targetLifestyleMet: boolean;
+    /** Share of target spending funded across the path. */
+    targetAttainmentPct: number;
+    /** Average annual target shortfall across the path. */
+    averageAnnualTargetShortfall: number;
+    /** Number of years with any target shortfall. */
+    yearsBelowTarget: number;
+    idealIntended: number;
+    idealFunded: number;
+    excessIntended: number;
+    excessFunded: number;
+    flexibleGoals: {
+        funded: number;
+        partiallyFunded: number;
+        deferred: number;
+        skipped: number;
+        fundedAmount: number;
+        unfundedAmount: number;
+    };
+    guardrailActionCounts: {
+        cut: number;
+        raise: number;
+        hold: number;
+    };
+    /** Years this path spent with the discretionary layer cut below full (guardrail plans only). */
+    guardrailCutYears: number;
+    /** Longest consecutive run of cut years on this path. */
+    longestGuardrailCutSpellYears: number;
+    /** Deepest cut reached on this path, as a fraction of the discretionary layer (0..1). */
+    maxGuardrailCutDepth: number;
+    /** Ending after-tax estate cleared the plan's bequest target (today's $, inflated to path end); null = no target set. */
+    endingAboveBequestTarget: boolean | null;
+}
+export interface MonteCarloPathsResult {
+    startYear: number;
+    endYear: number;
+    paths: MonteCarloPath[];
+}
+export declare function runMonteCarloPaths(plan: Plan, opts: MonteCarloPathOptions): MonteCarloPathsResult;
+export interface YearPercentiles {
+    year: number;
+    p10: number;
+    p25: number;
+    p50: number;
+    p75: number;
+    p90: number;
+}
+export interface Histogram {
+    min: number;
+    binWidth: number;
+    /** counts[i] covers [min + i·binWidth, min + (i+1)·binWidth). */
+    counts: number[];
+}
+export interface MonteCarloSummary {
+    pathCount: number;
+    /** Share of paths whose investable assets never deplete. */
+    successRate: number;
+    /**
+     * Share of paths that funded the required spending floor every year
+     * (planning-depth roadmap §4). Equals `successRate` unless a guardrail policy
+     * or required-floor layer is in play; then it is the more meaningful "never
+     * ran short on essentials" number.
+     */
+    requiredFloorSuccessRate: number;
+    /** Share of paths that funded full target-lifestyle spending every year. */
+    targetLifestyleSuccessRate: number;
+    /** Path-level target-attainment distribution (1 = every target dollar funded). */
+    targetAttainmentPct: Omit<YearPercentiles, 'year'>;
+    averageAnnualTargetShortfall: number;
+    p90AverageAnnualTargetShortfall: number;
+    averageYearsBelowTarget: number;
+    idealFundingRate: number;
+    excessFundingRate: number;
+    flexibleGoals: {
+        funded: number;
+        partiallyFunded: number;
+        deferred: number;
+        skipped: number;
+        fundedAmount: number;
+        unfundedAmount: number;
+    };
+    guardrailActionCounts: {
+        cut: number;
+        raise: number;
+        hold: number;
+    };
+    /**
+     * Probability-and-magnitude-of-adjustment reporting (risk-based guardrails
+     * plan, Kitces 2025 framing): instead of a bare success %, report how likely
+     * a mid-course spending adjustment is, how big it tends to be, how long it
+     * lasts, and how likely the plan ends with a surplus. Cut metrics are
+     * conditional on paths that cut at least once; they are all zero for plans
+     * without a guardrail policy.
+     */
+    adjustments: {
+        /** Share of paths with at least one cut year. */
+        pathsWithCut: number;
+        /** Share of paths with at least one raise action. */
+        pathsWithRaise: number;
+        /** Among cut paths: median deepest cut as a fraction of the discretionary layer. */
+        medianMaxCutDepth: number;
+        /** Among cut paths: 90th-percentile deepest cut. */
+        p90MaxCutDepth: number;
+        /** Among cut paths: average number of cut years. */
+        averageCutYears: number;
+        /** Among cut paths: 90th-percentile number of cut years. */
+        p90CutYears: number;
+        /** Among cut paths: average longest consecutive cut spell, in years. */
+        averageLongestCutSpellYears: number;
+        /** Share of paths ending with any after-tax estate left. */
+        probEndingSurplus: number;
+        /** Share of paths whose ending estate clears the bequest target; null = no target set. */
+        probEndingAboveBequestTarget: number | null;
+    };
+    downsideRisk: {
+        failureRate: number;
+        failingPathCount: number;
+        /** Average total unfunded spending across failing paths. */
+        expectedShortfallDollars: number;
+        expectedRequiredShortfallDollars: number;
+        expectedTargetShortfallDollars: number;
+        p90TotalShortfallDollars: number;
+    };
+    spendingShortfall: {
+        averageTotalShortfallDollars: number;
+        averageRequiredShortfallDollars: number;
+        averageTargetShortfallDollars: number;
+        p90TotalShortfallDollars: number;
+    };
+    /** Per-year investable-balance fan (10/25/50/75/90). */
+    fan: YearPercentiles[];
+    endingInvestable: {
+        percentiles: Omit<YearPercentiles, 'year'>;
+        histogram: Histogram;
+    };
+    endingNetWorth: {
+        percentiles: Omit<YearPercentiles, 'year'>;
+        histogram: Histogram;
+    };
+    endingAfterTaxEstate: {
+        percentiles: Omit<YearPercentiles, 'year'>;
+        histogram: Histogram;
+    };
+    /** Depletion year → number of paths first depleting that year (successes excluded). */
+    depletionYearCounts: {
+        year: number;
+        count: number;
+    }[];
+    /** Cumulative probability that assets have depleted by each depletion year. */
+    depletionProbabilityByYear: {
+        year: number;
+        count: number;
+        probability: number;
+        cumulativeProbability: number;
+    }[];
+}
+export declare function aggregateMonteCarlo(result: MonteCarloPathsResult, histogramBins?: number): MonteCarloSummary;
+/** Merge per-worker partial results (path order does not affect aggregation). */
+export declare function mergePathResults(parts: MonteCarloPathsResult[]): MonteCarloPathsResult;