@retiregolden/engine 0.1.0

package/dist/montecarlo/run.js

@@ -0,0 +1,353 @@
+/**
+ * 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 { summarizeProjection } from '../projection/compare.js';
+import { simulatePlan } from '../projection/simulate.js';
+import { sampleCareEvents } from './ltcShock.js';
+import { MAX_AGE, sampleDeathAge } from './mortality.js';
+import { createRng, derivePathSeed } from './rng.js';
+/** Dollar threshold below which a shortfall is treated as rounding, not a miss. */
+const SHORTFALL_EPSILON = 0.5;
+export function runMonteCarloPaths(plan, opts) {
+    const first = opts.firstPathIndex ?? 0;
+    const paths = [];
+    let startYear = opts.startYear;
+    let endYear = opts.startYear;
+    // In stochastic-longevity mode, run every path to a fixed wide horizon (the
+    // youngest person reaching the table's max age) so the year grids align even
+    // though sampled death ages differ; otherwise the horizon is plan-determined.
+    const horizonEndYear = opts.stochasticLongevity
+        ? Math.max(...plan.household.people.map((p) => Number(p.dob.slice(0, 4)) + MAX_AGE))
+        : undefined;
+    for (let i = 0; i < opts.pathCount; i++) {
+        const rng = createRng(derivePathSeed(opts.seed, first + i));
+        // 120 years comfortably covers any plan horizon; simulate clamps reads.
+        const market = opts.model.generatePath(rng, 120);
+        let pathPlan = plan;
+        let deathAgeByPersonId;
+        if (opts.stochasticLongevity) {
+            deathAgeByPersonId = {};
+            for (const p of plan.household.people) {
+                deathAgeByPersonId[p.id] = sampleDeathAge(rng, opts.startYear - Number(p.dob.slice(0, 4)), p.sex);
+            }
+        }
+        if (opts.ltcShock) {
+            const sampled = sampleCareEvents(rng, plan.household.people, opts.startYear, opts.ltcShock);
+            if (sampled.length > 0)
+                pathPlan = { ...plan, careEvents: [...plan.careEvents, ...sampled] };
+        }
+        const result = simulatePlan(pathPlan, {
+            startYear: opts.startYear,
+            taxCalculator: opts.taxCalculator,
+            market,
+            deathAgeByPersonId,
+            horizonEndYear,
+        });
+        const projectionSummary = summarizeProjection(pathPlan, result);
+        startYear = result.startYear;
+        endYear = result.endYear;
+        const investableByYear = new Float64Array(result.years.length);
+        let requiredFloorMet = true;
+        let targetLifestyleMet = true;
+        let totalShortfall = 0;
+        let totalRequiredShortfall = 0;
+        let totalTargetShortfall = 0;
+        let targetIntended = 0;
+        let targetFunded = 0;
+        let targetShortfallTotal = 0;
+        let yearsBelowTarget = 0;
+        let idealIntended = 0;
+        let idealFunded = 0;
+        let excessIntended = 0;
+        let excessFunded = 0;
+        const flexibleGoals = { funded: 0, partiallyFunded: 0, deferred: 0, skipped: 0, fundedAmount: 0, unfundedAmount: 0 };
+        const guardrailActionCounts = { cut: 0, raise: 0, hold: 0 };
+        let guardrailCutYears = 0;
+        let longestGuardrailCutSpellYears = 0;
+        let currentCutSpellYears = 0;
+        let maxGuardrailCutDepth = 0;
+        for (let y = 0; y < result.years.length; y++) {
+            const yr = result.years[y];
+            investableByYear[y] = yr.investableTotal;
+            const guardrailFactor = yr.expenses.guardrailFactor;
+            if (guardrailFactor < 1 - 1e-9) {
+                guardrailCutYears++;
+                currentCutSpellYears++;
+                if (currentCutSpellYears > longestGuardrailCutSpellYears)
+                    longestGuardrailCutSpellYears = currentCutSpellYears;
+                if (1 - guardrailFactor > maxGuardrailCutDepth)
+                    maxGuardrailCutDepth = 1 - guardrailFactor;
+            }
+            else {
+                currentCutSpellYears = 0;
+            }
+            totalShortfall += yr.shortfall;
+            totalRequiredShortfall += yr.requiredShortfall;
+            totalTargetShortfall += yr.targetShortfall;
+            if (yr.requiredShortfall > SHORTFALL_EPSILON)
+                requiredFloorMet = false;
+            if (yr.targetShortfall > SHORTFALL_EPSILON)
+                targetLifestyleMet = false;
+            targetIntended += yr.expenses.targetSpending;
+            targetFunded += Math.max(0, yr.expenses.targetSpending - yr.targetShortfall);
+            targetShortfallTotal += yr.targetShortfall;
+            if (yr.targetShortfall > SHORTFALL_EPSILON)
+                yearsBelowTarget++;
+            idealIntended += yr.expenses.idealSpending;
+            idealFunded += Math.max(0, yr.expenses.idealSpending - yr.idealShortfall);
+            excessIntended += yr.expenses.excessSpending;
+            excessFunded += Math.max(0, yr.expenses.excessSpending - yr.excessShortfall);
+            flexibleGoals.funded += yr.flexibleGoals.funded;
+            flexibleGoals.partiallyFunded += yr.flexibleGoals.partiallyFunded;
+            flexibleGoals.deferred += yr.flexibleGoals.deferred;
+            flexibleGoals.skipped += yr.flexibleGoals.skipped;
+            flexibleGoals.fundedAmount += yr.flexibleGoals.fundedAmount;
+            flexibleGoals.unfundedAmount += yr.flexibleGoals.unfundedAmount;
+            guardrailActionCounts[yr.guardrailAction]++;
+        }
+        // Bequest target is entered in today's dollars; the ending estate is
+        // nominal at path end, so the target is inflated across the path horizon
+        // using this path's *realized* inflation series (mirroring the ledger's
+        // cumulative factor, with the plan assumption as the past-series fallback).
+        const bequestTarget = pathPlan.expenses.bequestTargetDollars ?? 0;
+        let pathInflationFactor = 1;
+        if (bequestTarget > 0) {
+            const series = market.inflationPct;
+            for (let y = 0; y < result.endYear - result.startYear; y++) {
+                const pct = series && series.length > 0
+                    ? (series[Math.min(y, series.length - 1)] ?? pathPlan.assumptions.inflationPct)
+                    : pathPlan.assumptions.inflationPct;
+                pathInflationFactor *= 1 + pct / 100;
+            }
+        }
+        const endingAboveBequestTarget = bequestTarget > 0 ? projectionSummary.endingAfterTaxEstate >= bequestTarget * pathInflationFactor : null;
+        paths.push({
+            investableByYear,
+            endingInvestable: result.endingInvestable,
+            endingNetWorth: result.endingNetWorth,
+            endingAfterTaxEstate: projectionSummary.endingAfterTaxEstate,
+            depletionYear: result.depletionYear,
+            totalShortfall,
+            totalRequiredShortfall,
+            totalTargetShortfall,
+            requiredFloorMet,
+            targetLifestyleMet,
+            targetAttainmentPct: targetIntended > 0 ? Math.min(1, targetFunded / targetIntended) : 1,
+            averageAnnualTargetShortfall: result.years.length > 0 ? targetShortfallTotal / result.years.length : 0,
+            yearsBelowTarget,
+            idealIntended,
+            idealFunded,
+            excessIntended,
+            excessFunded,
+            flexibleGoals,
+            guardrailActionCounts,
+            guardrailCutYears,
+            longestGuardrailCutSpellYears,
+            maxGuardrailCutDepth,
+            endingAboveBequestTarget,
+        });
+        opts.onPathDone?.(i + 1);
+    }
+    return { startYear, endYear, paths };
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = (p / 100) * (sorted.length - 1);
+    const lo = Math.floor(idx);
+    const hi = Math.ceil(idx);
+    const frac = idx - lo;
+    return sorted[lo] * (1 - frac) + sorted[hi] * frac;
+}
+function percentileSet(sorted) {
+    return {
+        p10: percentile(sorted, 10),
+        p25: percentile(sorted, 25),
+        p50: percentile(sorted, 50),
+        p75: percentile(sorted, 75),
+        p90: percentile(sorted, 90),
+    };
+}
+function histogramFor(sorted, histogramBins) {
+    const min = sorted[0] ?? 0;
+    const max = sorted[sorted.length - 1] ?? 0;
+    const binWidth = max > min ? (max - min) / histogramBins : 1;
+    const counts = new Array(histogramBins).fill(0);
+    for (const v of sorted) {
+        counts[Math.min(histogramBins - 1, Math.floor((v - min) / binWidth))]++;
+    }
+    return { min, binWidth, counts };
+}
+export function aggregateMonteCarlo(result, histogramBins = 30) {
+    const { paths, startYear } = result;
+    const yearCount = paths[0]?.investableByYear.length ?? 0;
+    const fan = [];
+    const column = new Array(paths.length);
+    for (let y = 0; y < yearCount; y++) {
+        for (let i = 0; i < paths.length; i++)
+            column[i] = paths[i].investableByYear[y];
+        column.sort((a, b) => a - b);
+        fan.push({ year: startYear + y, ...percentileSet(column) });
+    }
+    const endings = paths.map((p) => p.endingInvestable).sort((a, b) => a - b);
+    const endingNetWorths = paths.map((p) => p.endingNetWorth).sort((a, b) => a - b);
+    const endingAfterTaxEstates = paths.map((p) => p.endingAfterTaxEstate).sort((a, b) => a - b);
+    const depletionMap = new Map();
+    let successes = 0;
+    let requiredFloorSuccesses = 0;
+    let targetLifestyleSuccesses = 0;
+    let averageAnnualTargetShortfallTotal = 0;
+    let yearsBelowTargetTotal = 0;
+    let idealIntendedTotal = 0;
+    let idealFundedTotal = 0;
+    let excessIntendedTotal = 0;
+    let excessFundedTotal = 0;
+    let totalShortfallTotal = 0;
+    let totalRequiredShortfallTotal = 0;
+    let totalTargetShortfallTotal = 0;
+    let failingPathShortfallTotal = 0;
+    let failingPathRequiredShortfallTotal = 0;
+    let failingPathTargetShortfallTotal = 0;
+    let failingPathCount = 0;
+    const totalShortfalls = [];
+    const targetAttainments = [];
+    const averageTargetShortfalls = [];
+    const flexibleGoals = { funded: 0, partiallyFunded: 0, deferred: 0, skipped: 0, fundedAmount: 0, unfundedAmount: 0 };
+    const guardrailActionCounts = { cut: 0, raise: 0, hold: 0 };
+    const cutDepths = [];
+    const cutYearCounts = [];
+    let cutSpellTotal = 0;
+    let pathsWithCut = 0;
+    let pathsWithRaise = 0;
+    let surplusPaths = 0;
+    let bequestTargetPaths = 0;
+    let aboveBequestTargetPaths = 0;
+    for (const p of paths) {
+        if (p.depletionYear === null)
+            successes++;
+        else {
+            depletionMap.set(p.depletionYear, (depletionMap.get(p.depletionYear) ?? 0) + 1);
+            failingPathCount++;
+            failingPathShortfallTotal += p.totalShortfall;
+            failingPathRequiredShortfallTotal += p.totalRequiredShortfall;
+            failingPathTargetShortfallTotal += p.totalTargetShortfall;
+        }
+        totalShortfalls.push(p.totalShortfall);
+        totalShortfallTotal += p.totalShortfall;
+        totalRequiredShortfallTotal += p.totalRequiredShortfall;
+        totalTargetShortfallTotal += p.totalTargetShortfall;
+        if (p.requiredFloorMet)
+            requiredFloorSuccesses++;
+        if (p.targetLifestyleMet)
+            targetLifestyleSuccesses++;
+        targetAttainments.push(p.targetAttainmentPct);
+        averageTargetShortfalls.push(p.averageAnnualTargetShortfall);
+        averageAnnualTargetShortfallTotal += p.averageAnnualTargetShortfall;
+        yearsBelowTargetTotal += p.yearsBelowTarget;
+        idealIntendedTotal += p.idealIntended;
+        idealFundedTotal += p.idealFunded;
+        excessIntendedTotal += p.excessIntended;
+        excessFundedTotal += p.excessFunded;
+        flexibleGoals.funded += p.flexibleGoals.funded;
+        flexibleGoals.partiallyFunded += p.flexibleGoals.partiallyFunded;
+        flexibleGoals.deferred += p.flexibleGoals.deferred;
+        flexibleGoals.skipped += p.flexibleGoals.skipped;
+        flexibleGoals.fundedAmount += p.flexibleGoals.fundedAmount;
+        flexibleGoals.unfundedAmount += p.flexibleGoals.unfundedAmount;
+        guardrailActionCounts.cut += p.guardrailActionCounts.cut;
+        guardrailActionCounts.raise += p.guardrailActionCounts.raise;
+        guardrailActionCounts.hold += p.guardrailActionCounts.hold;
+        if (p.guardrailCutYears > 0) {
+            pathsWithCut++;
+            cutDepths.push(p.maxGuardrailCutDepth);
+            cutYearCounts.push(p.guardrailCutYears);
+            cutSpellTotal += p.longestGuardrailCutSpellYears;
+        }
+        if (p.guardrailActionCounts.raise > 0)
+            pathsWithRaise++;
+        if (p.endingAfterTaxEstate > 0)
+            surplusPaths++;
+        if (p.endingAboveBequestTarget !== null) {
+            bequestTargetPaths++;
+            if (p.endingAboveBequestTarget)
+                aboveBequestTargetPaths++;
+        }
+    }
+    const depletionYearCounts = [...depletionMap.entries()]
+        .map(([year, count]) => ({ year, count }))
+        .sort((a, b) => a.year - b.year);
+    const share = (n) => (paths.length === 0 ? 0 : n / paths.length);
+    let cumulative = 0;
+    const depletionProbabilityByYear = depletionYearCounts.map(({ year, count }) => {
+        const probability = share(count);
+        cumulative += probability;
+        return { year, count, probability, cumulativeProbability: cumulative };
+    });
+    targetAttainments.sort((a, b) => a - b);
+    averageTargetShortfalls.sort((a, b) => a - b);
+    totalShortfalls.sort((a, b) => a - b);
+    cutDepths.sort((a, b) => a - b);
+    cutYearCounts.sort((a, b) => a - b);
+    const adjustments = {
+        pathsWithCut: share(pathsWithCut),
+        pathsWithRaise: share(pathsWithRaise),
+        medianMaxCutDepth: percentile(cutDepths, 50),
+        p90MaxCutDepth: percentile(cutDepths, 90),
+        averageCutYears: pathsWithCut === 0 ? 0 : cutYearCounts.reduce((a, b) => a + b, 0) / pathsWithCut,
+        p90CutYears: percentile(cutYearCounts, 90),
+        averageLongestCutSpellYears: pathsWithCut === 0 ? 0 : cutSpellTotal / pathsWithCut,
+        probEndingSurplus: share(surplusPaths),
+        probEndingAboveBequestTarget: bequestTargetPaths === 0 ? null : aboveBequestTargetPaths / bequestTargetPaths,
+    };
+    return {
+        pathCount: paths.length,
+        successRate: share(successes),
+        requiredFloorSuccessRate: share(requiredFloorSuccesses),
+        targetLifestyleSuccessRate: share(targetLifestyleSuccesses),
+        targetAttainmentPct: percentileSet(targetAttainments),
+        averageAnnualTargetShortfall: paths.length === 0 ? 0 : averageAnnualTargetShortfallTotal / paths.length,
+        p90AverageAnnualTargetShortfall: percentile(averageTargetShortfalls, 90),
+        averageYearsBelowTarget: paths.length === 0 ? 0 : yearsBelowTargetTotal / paths.length,
+        idealFundingRate: idealIntendedTotal > 0 ? idealFundedTotal / idealIntendedTotal : 1,
+        excessFundingRate: excessIntendedTotal > 0 ? excessFundedTotal / excessIntendedTotal : 1,
+        flexibleGoals,
+        guardrailActionCounts,
+        adjustments,
+        downsideRisk: {
+            failureRate: share(failingPathCount),
+            failingPathCount,
+            expectedShortfallDollars: failingPathCount === 0 ? 0 : failingPathShortfallTotal / failingPathCount,
+            expectedRequiredShortfallDollars: failingPathCount === 0 ? 0 : failingPathRequiredShortfallTotal / failingPathCount,
+            expectedTargetShortfallDollars: failingPathCount === 0 ? 0 : failingPathTargetShortfallTotal / failingPathCount,
+            p90TotalShortfallDollars: percentile(totalShortfalls, 90),
+        },
+        spendingShortfall: {
+            averageTotalShortfallDollars: paths.length === 0 ? 0 : totalShortfallTotal / paths.length,
+            averageRequiredShortfallDollars: paths.length === 0 ? 0 : totalRequiredShortfallTotal / paths.length,
+            averageTargetShortfallDollars: paths.length === 0 ? 0 : totalTargetShortfallTotal / paths.length,
+            p90TotalShortfallDollars: percentile(totalShortfalls, 90),
+        },
+        fan,
+        endingInvestable: { percentiles: percentileSet(endings), histogram: histogramFor(endings, histogramBins) },
+        endingNetWorth: { percentiles: percentileSet(endingNetWorths), histogram: histogramFor(endingNetWorths, histogramBins) },
+        endingAfterTaxEstate: {
+            percentiles: percentileSet(endingAfterTaxEstates),
+            histogram: histogramFor(endingAfterTaxEstates, histogramBins),
+        },
+        depletionYearCounts,
+        depletionProbabilityByYear,
+    };
+}
+/** Merge per-worker partial results (path order does not affect aggregation). */
+export function mergePathResults(parts) {
+    const nonEmpty = parts.filter((p) => p.paths.length > 0);
+    const first = nonEmpty[0] ?? parts[0] ?? { startYear: 0, endYear: 0, paths: [] };
+    return { startYear: first.startYear, endYear: first.endYear, paths: nonEmpty.flatMap((p) => p.paths) };
+}

package/dist/montecarlo/sharedPaths.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared-path stochastic comparisons.
+ *
+ * Every plan variant is evaluated with the same seed, path count, and market
+ * model config, so path index N means the same market history for every row.
+ * This is the reusable primitive for scenario/candidate stochastic deltas.
+ */
+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';
+import { type MonteCarloSummary } from './run.js';
+export interface SharedPathPlan {
+    id: string;
+    label: string;
+    plan: Plan;
+    /**
+     * Per-entry tax stack, when variants need different calculators (e.g. the
+     * relocation compare's per-candidate local rates). Falls back to the shared
+     * `opts.taxCalculator`.
+     */
+    taxCalculator?: TaxCalculator;
+}
+export interface SharedPathComparisonOptions {
+    startYear: number;
+    taxCalculator: TaxCalculator;
+    model: MarketModelConfig;
+    pathCount: number;
+    seed: number;
+    stochasticLongevity?: boolean;
+    ltcShock?: LtcShockParams | null;
+}
+export interface SharedPathComparisonRow {
+    id: string;
+    label: string;
+    summary: MonteCarloSummary;
+}
+export interface SharedPathComparison {
+    seed: number;
+    pathCount: number;
+    rows: SharedPathComparisonRow[];
+}
+export declare function comparePlansOnSharedMarketPaths(plans: SharedPathPlan[], opts: SharedPathComparisonOptions): SharedPathComparison;

package/dist/montecarlo/sharedPaths.js

@@ -0,0 +1,28 @@
+/**
+ * Shared-path stochastic comparisons.
+ *
+ * Every plan variant is evaluated with the same seed, path count, and market
+ * model config, so path index N means the same market history for every row.
+ * This is the reusable primitive for scenario/candidate stochastic deltas.
+ */
+import { createMarketModel } from './marketModels.js';
+import { aggregateMonteCarlo, runMonteCarloPaths } from './run.js';
+export function comparePlansOnSharedMarketPaths(plans, opts) {
+    return {
+        seed: opts.seed,
+        pathCount: opts.pathCount,
+        rows: plans.map((entry) => ({
+            id: entry.id,
+            label: entry.label,
+            summary: aggregateMonteCarlo(runMonteCarloPaths(entry.plan, {
+                startYear: opts.startYear,
+                taxCalculator: entry.taxCalculator ?? opts.taxCalculator,
+                model: createMarketModel(opts.model),
+                seed: opts.seed,
+                pathCount: opts.pathCount,
+                stochasticLongevity: opts.stochasticLongevity,
+                ltcShock: opts.ltcShock,
+            })),
+        })),
+    };
+}

package/dist/montecarlo/survival.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Survival-percentile planning ages (spending-paths & SWR-lenses plan, Goal 4).
+ *
+ * "Plan to the age you have a 25% (or 10%) chance of reaching" is standard
+ * longevity-risk advice — the refreshed Actuaries Longevity Illustrator is the
+ * canonical tool that operationalizes it. These helpers compute that age from
+ * the same SSA 2022 q(x) derivation the stochastic-longevity Monte Carlo uses
+ * (mortality.ts), so every surface quotes one mortality table.
+ *
+ * The optional health adjustment is a proportional-hazards transform: annual
+ * survival p(x) is raised to a hazard power h (q' = 1 − (1−q)^h; h > 1 = worse
+ * health). `hazardForExpectancyMultiplier` converts the longevity wizard's
+ * remaining-years multiplier (its sourced smoking/health/activity factors,
+ * see ../../longevity/factors.ts) into that hazard power, so the percentile
+ * picker can reuse the questionnaire instead of a second unsourced factor set.
+ */
+import { type Sex } from './mortality.js';
+/**
+ * Probability someone `currentAge` today is still alive at `targetAge`
+ * (product of one-year survivals over integer ages). 1 for targetAge ≤ current.
+ */
+export declare function survivalProbabilityTo(currentAge: number, sex: Sex, targetAge: number, hazard?: number): number;
+/**
+ * The oldest integer age this person still reaches with probability ≥ pct/100 —
+ * "the age I have a `pct`% chance of reaching". Monotone: smaller pct ⇒ older
+ * age. Always ≥ the current age (you have already reached it) and ≤ MAX_AGE + 1
+ * (the table forces death by then).
+ */
+export declare function survivalPercentileAge(currentAge: number, sex: Sex, pct: number, hazard?: number): number;
+export interface SurvivalPerson {
+    age: number;
+    sex: Sex;
+    hazard?: number;
+}
+/**
+ * Joint ("either of us") percentile age on the primary person's age clock: the
+ * oldest primary age A such that P(at least one member alive when the primary
+ * would be A) ≥ pct/100, assuming independent lifetimes —
+ * P = 1 − (1 − S_primary)(1 − S_partner). Always ≥ the single-life answer.
+ */
+export declare function jointSurvivalPercentileAge(primary: SurvivalPerson, partner: SurvivalPerson, pct: number): number;
+/**
+ * Convert a remaining-years multiplier `m` (the longevity questionnaire's
+ * applied multiplier: m < 1 = shorter expectancy) into the proportional-hazards
+ * power whose adjusted expectancy at this age is m × the SSA baseline, solved
+ * by bisection. m = 1 returns ~1 (identity); results are clamped to a sane
+ * hazard range so extreme questionnaire answers cannot degenerate the curve.
+ */
+export declare function hazardForExpectancyMultiplier(age: number, sex: Sex, m: number): number;

package/dist/montecarlo/survival.js

@@ -0,0 +1,126 @@
+/**
+ * Survival-percentile planning ages (spending-paths & SWR-lenses plan, Goal 4).
+ *
+ * "Plan to the age you have a 25% (or 10%) chance of reaching" is standard
+ * longevity-risk advice — the refreshed Actuaries Longevity Illustrator is the
+ * canonical tool that operationalizes it. These helpers compute that age from
+ * the same SSA 2022 q(x) derivation the stochastic-longevity Monte Carlo uses
+ * (mortality.ts), so every surface quotes one mortality table.
+ *
+ * The optional health adjustment is a proportional-hazards transform: annual
+ * survival p(x) is raised to a hazard power h (q' = 1 − (1−q)^h; h > 1 = worse
+ * health). `hazardForExpectancyMultiplier` converts the longevity wizard's
+ * remaining-years multiplier (its sourced smoking/health/activity factors,
+ * see ../../longevity/factors.ts) into that hazard power, so the percentile
+ * picker can reuse the questionnaire instead of a second unsourced factor set.
+ */
+import { baselineRemainingYears } from '../longevity/ssaPeriod2022.js';
+import { annualMortality, MAX_AGE } from './mortality.js';
+/** One-year survival probability at integer age, under a hazard power. */
+function annualSurvival(age, sex, hazard) {
+    const q = annualMortality(age, sex);
+    if (q >= 1)
+        return 0;
+    return Math.pow(1 - q, hazard);
+}
+/**
+ * Probability someone `currentAge` today is still alive at `targetAge`
+ * (product of one-year survivals over integer ages). 1 for targetAge ≤ current.
+ */
+export function survivalProbabilityTo(currentAge, sex, targetAge, hazard = 1) {
+    const from = Math.floor(Math.max(currentAge, 0));
+    const to = Math.floor(targetAge);
+    let s = 1;
+    for (let age = from; age < to; age++) {
+        s *= annualSurvival(age, sex, hazard);
+        if (s <= 0)
+            return 0;
+    }
+    return s;
+}
+/**
+ * The oldest integer age this person still reaches with probability ≥ pct/100 —
+ * "the age I have a `pct`% chance of reaching". Monotone: smaller pct ⇒ older
+ * age. Always ≥ the current age (you have already reached it) and ≤ MAX_AGE + 1
+ * (the table forces death by then).
+ */
+export function survivalPercentileAge(currentAge, sex, pct, hazard = 1) {
+    const threshold = Math.min(Math.max(pct, 0.1), 100) / 100;
+    const from = Math.floor(Math.max(currentAge, 0));
+    let s = 1;
+    let best = from;
+    for (let age = from; age <= MAX_AGE; age++) {
+        s *= annualSurvival(age, sex, hazard);
+        if (s >= threshold)
+            best = age + 1;
+        else
+            break;
+    }
+    return best;
+}
+/**
+ * Joint ("either of us") percentile age on the primary person's age clock: the
+ * oldest primary age A such that P(at least one member alive when the primary
+ * would be A) ≥ pct/100, assuming independent lifetimes —
+ * P = 1 − (1 − S_primary)(1 − S_partner). Always ≥ the single-life answer.
+ */
+export function jointSurvivalPercentileAge(primary, partner, pct) {
+    const threshold = Math.min(Math.max(pct, 0.1), 100) / 100;
+    const from = Math.floor(Math.max(primary.age, 0));
+    const partnerFrom = Math.floor(Math.max(partner.age, 0));
+    let sPrimary = 1;
+    let sPartner = 1;
+    let best = from;
+    // Walk both survival curves on the primary's clock; the partner's own clock
+    // is offset by the age difference.
+    for (let t = 0; from + t <= MAX_AGE + 1; t++) {
+        const eitherAlive = 1 - (1 - sPrimary) * (1 - sPartner);
+        if (eitherAlive >= threshold)
+            best = from + t;
+        else
+            break;
+        sPrimary *= annualSurvival(from + t, primary.sex, primary.hazard ?? 1);
+        sPartner *= annualSurvival(partnerFrom + t, partner.sex, partner.hazard ?? 1);
+        if (sPrimary <= 0 && sPartner <= 0)
+            break;
+    }
+    return best;
+}
+/** Curtate-style remaining life expectancy under a hazard power: 0.5 + Σ S(t). */
+function expectancyUnderHazard(age, sex, hazard) {
+    const from = Math.floor(Math.max(age, 0));
+    let s = 1;
+    let e = 0.5;
+    for (let a = from; a <= MAX_AGE; a++) {
+        s *= annualSurvival(a, sex, hazard);
+        e += s;
+        if (s <= 1e-12)
+            break;
+    }
+    return e;
+}
+/**
+ * Convert a remaining-years multiplier `m` (the longevity questionnaire's
+ * applied multiplier: m < 1 = shorter expectancy) into the proportional-hazards
+ * power whose adjusted expectancy at this age is m × the SSA baseline, solved
+ * by bisection. m = 1 returns ~1 (identity); results are clamped to a sane
+ * hazard range so extreme questionnaire answers cannot degenerate the curve.
+ */
+export function hazardForExpectancyMultiplier(age, sex, m) {
+    const target = Math.max(0.1, m) * baselineRemainingYears(age, sex);
+    let lo = 0.2; // far healthier than the table
+    let hi = 8; // far sicker than the table
+    // Expectancy is strictly decreasing in the hazard power.
+    if (expectancyUnderHazard(age, sex, lo) <= target)
+        return lo;
+    if (expectancyUnderHazard(age, sex, hi) >= target)
+        return hi;
+    for (let i = 0; i < 40; i++) {
+        const mid = (lo + hi) / 2;
+        if (expectancyUnderHazard(age, sex, mid) > target)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return (lo + hi) / 2;
+}

package/dist/params/data/realYieldCurve2026.d.ts

@@ -0,0 +1,17 @@
+import type { RealYieldCurve } from '../types.js';
+/**
+ * Embedded TIPS real-yield curve snapshot (par real yields, percent per year).
+ *
+ * Source: U.S. Treasury "Daily Treasury Par Real Yield Curve Rates"
+ * (https://home.treasury.gov/resource-center/data-chart-center/interest-rates),
+ * end-of-June 2026 readings rounded to 5bp. The Treasury publishes 5-, 7-, 10-,
+ * 20-, and 30-year par real yields; the ladder engine interpolates between
+ * points and holds the endpoints flat outside them.
+ *
+ * This snapshot is the app's offline posture: every ladder quote and funded
+ * ratio works without a network call. Refresh cadence: annually with the
+ * parameter packs (see DOCS/maintenance-schedule.md), or opt-in per-session
+ * via the FedInvest live-price fetch (engine/ladder/fedInvest.ts), which
+ * never replaces this embedded default.
+ */
+export declare const REAL_YIELD_CURVE_2026: RealYieldCurve;

package/dist/params/data/realYieldCurve2026.js

@@ -0,0 +1,26 @@
+/**
+ * Embedded TIPS real-yield curve snapshot (par real yields, percent per year).
+ *
+ * Source: U.S. Treasury "Daily Treasury Par Real Yield Curve Rates"
+ * (https://home.treasury.gov/resource-center/data-chart-center/interest-rates),
+ * end-of-June 2026 readings rounded to 5bp. The Treasury publishes 5-, 7-, 10-,
+ * 20-, and 30-year par real yields; the ladder engine interpolates between
+ * points and holds the endpoints flat outside them.
+ *
+ * This snapshot is the app's offline posture: every ladder quote and funded
+ * ratio works without a network call. Refresh cadence: annually with the
+ * parameter packs (see DOCS/maintenance-schedule.md), or opt-in per-session
+ * via the FedInvest live-price fetch (engine/ladder/fedInvest.ts), which
+ * never replaces this embedded default.
+ */
+export const REAL_YIELD_CURVE_2026 = {
+    asOfIso: '2026-06-30',
+    source: 'U.S. Treasury Daily Par Real Yield Curve Rates',
+    points: [
+        { maturityYears: 5, realYieldPct: 1.85 },
+        { maturityYears: 7, realYieldPct: 2.05 },
+        { maturityYears: 10, realYieldPct: 2.25 },
+        { maturityYears: 20, realYieldPct: 2.55 },
+        { maturityYears: 30, realYieldPct: 2.7 },
+    ],
+};

package/dist/params/data/year2026.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Tax year 2026 parameter pack (post-OBBBA current law).
+ *
+ * Sources (verified June 2026) — see DOCS/domain/domain-rules-reference.md:
+ * - Brackets/deductions/AMT: IRS inflation adjustments; Tax Foundation 2026 tables
+ * - Capital gains/NIIT: IRS; Kiplinger 2026 LTCG thresholds
+ * - Limits: IRS IR news release (401(k) $24,500; IRA $7,500)
+ * - RMD: IRS Pub 590-B Uniform Lifetime Table (2022+); QCD $111,000 (2026)
+ * - Medicare: CMS 2026 ($202.90 standard Part B); IRMAA tiers per statute
+ * - Social Security: SSA 2026 COLA fact sheet
+ * - FPL: HHS 2025 guidelines (apply to 2026 ACA coverage year)
+ */
+import type { ParameterPack } from '../types.js';
+export declare const year2026: ParameterPack;