@robotixai/calculator-engine 0.1.0

package/dist/backtest.d.ts

@@ -0,0 +1,28 @@
+import type { Scenario, Metrics } from './types';
+export interface BacktestPeriod {
+    startYear: number;
+    endYear: number;
+    terminalReal: number;
+    survived: boolean;
+}
+export interface BacktestResult {
+    periods: BacktestPeriod[];
+    successRate: number;
+}
+/**
+ * Runs the scenario against historical Shiller data using rolling N-year windows.
+ *
+ * N = end_age - current_age (the full projection span).
+ * For each starting year where N years of data are available, the projection
+ * is run using historical real stock returns, and the terminal balance and
+ * survival status are recorded.
+ *
+ * @param scenario   The base scenario (retirement_age, current_age, etc.)
+ * @param projectionFn  A projection function that accepts a Scenario plus an
+ *                      array of annual real returns and produces Metrics.
+ * @returns  Array of BacktestPeriod results and the overall success rate (0-100).
+ */
+export declare function runHistoricalBacktest(scenario: Scenario, projectionFn: (s: Scenario, returns: number[]) => {
+    metrics: Metrics;
+}): BacktestResult;
+//# sourceMappingURL=backtest.d.ts.map

package/dist/backtest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backtest.d.ts","sourceRoot":"","sources":["../src/backtest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AA6KjD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,GACrE,cAAc,CAoEhB"}

package/dist/backtest.js

@@ -0,0 +1,235 @@
+// ---------------------------------------------------------------------------
+// Historical Backtest — Shiller Data (real total stock returns, 1871-2024)
+// ---------------------------------------------------------------------------
+/**
+ * Embedded Shiller real total stock return data (inflation-adjusted).
+ * Source: Robert Shiller's dataset — real total return on S&P composite index.
+ * Values represent annual real (after-inflation) total returns including
+ * dividends, expressed as decimals (e.g., 0.1478 = 14.78%).
+ */
+const SHILLER_DATA = [
+    { year: 1871, realStockReturn: 0.1478 },
+    { year: 1872, realStockReturn: 0.1076 },
+    { year: 1873, realStockReturn: -0.0415 },
+    { year: 1874, realStockReturn: 0.1249 },
+    { year: 1875, realStockReturn: 0.0555 },
+    { year: 1876, realStockReturn: -0.0290 },
+    { year: 1877, realStockReturn: 0.0187 },
+    { year: 1878, realStockReturn: 0.1797 },
+    { year: 1879, realStockReturn: 0.2102 },
+    { year: 1880, realStockReturn: 0.2361 },
+    { year: 1881, realStockReturn: 0.0118 },
+    { year: 1882, realStockReturn: 0.0043 },
+    { year: 1883, realStockReturn: -0.0041 },
+    { year: 1884, realStockReturn: -0.0785 },
+    { year: 1885, realStockReturn: 0.3034 },
+    { year: 1886, realStockReturn: 0.1350 },
+    { year: 1887, realStockReturn: -0.0122 },
+    { year: 1888, realStockReturn: 0.0447 },
+    { year: 1889, realStockReturn: 0.0511 },
+    { year: 1890, realStockReturn: -0.0678 },
+    { year: 1891, realStockReturn: 0.1920 },
+    { year: 1892, realStockReturn: 0.0486 },
+    { year: 1893, realStockReturn: -0.1716 },
+    { year: 1894, realStockReturn: 0.0311 },
+    { year: 1895, realStockReturn: 0.0520 },
+    { year: 1896, realStockReturn: -0.0146 },
+    { year: 1897, realStockReturn: 0.1768 },
+    { year: 1898, realStockReturn: 0.2315 },
+    { year: 1899, realStockReturn: 0.0178 },
+    { year: 1900, realStockReturn: 0.1422 },
+    { year: 1901, realStockReturn: 0.2007 },
+    { year: 1902, realStockReturn: 0.0694 },
+    { year: 1903, realStockReturn: -0.1724 },
+    { year: 1904, realStockReturn: 0.3269 },
+    { year: 1905, realStockReturn: 0.2206 },
+    { year: 1906, realStockReturn: -0.0123 },
+    { year: 1907, realStockReturn: -0.3274 },
+    { year: 1908, realStockReturn: 0.4576 },
+    { year: 1909, realStockReturn: 0.1805 },
+    { year: 1910, realStockReturn: -0.0254 },
+    { year: 1911, realStockReturn: 0.0399 },
+    { year: 1912, realStockReturn: 0.0196 },
+    { year: 1913, realStockReturn: -0.1087 },
+    { year: 1914, realStockReturn: -0.0641 },
+    { year: 1915, realStockReturn: 0.3197 },
+    { year: 1916, realStockReturn: -0.0159 },
+    { year: 1917, realStockReturn: -0.3180 },
+    { year: 1918, realStockReturn: 0.1073 },
+    { year: 1919, realStockReturn: 0.0759 },
+    { year: 1920, realStockReturn: -0.1702 },
+    { year: 1921, realStockReturn: 0.2315 },
+    { year: 1922, realStockReturn: 0.2934 },
+    { year: 1923, realStockReturn: 0.0540 },
+    { year: 1924, realStockReturn: 0.2772 },
+    { year: 1925, realStockReturn: 0.2808 },
+    { year: 1926, realStockReturn: 0.1124 },
+    { year: 1927, realStockReturn: 0.3727 },
+    { year: 1928, realStockReturn: 0.4362 },
+    { year: 1929, realStockReturn: -0.0885 },
+    { year: 1930, realStockReturn: -0.2512 },
+    { year: 1931, realStockReturn: -0.3887 },
+    { year: 1932, realStockReturn: -0.0157 },
+    { year: 1933, realStockReturn: 0.5701 },
+    { year: 1934, realStockReturn: 0.0225 },
+    { year: 1935, realStockReturn: 0.4577 },
+    { year: 1936, realStockReturn: 0.3274 },
+    { year: 1937, realStockReturn: -0.3788 },
+    { year: 1938, realStockReturn: 0.2862 },
+    { year: 1939, realStockReturn: 0.0230 },
+    { year: 1940, realStockReturn: -0.0935 },
+    { year: 1941, realStockReturn: -0.1792 },
+    { year: 1942, realStockReturn: 0.1218 },
+    { year: 1943, realStockReturn: 0.2275 },
+    { year: 1944, realStockReturn: 0.1741 },
+    { year: 1945, realStockReturn: 0.3413 },
+    { year: 1946, realStockReturn: -0.2449 },
+    { year: 1947, realStockReturn: -0.0434 },
+    { year: 1948, realStockReturn: 0.0233 },
+    { year: 1949, realStockReturn: 0.2115 },
+    { year: 1950, realStockReturn: 0.2493 },
+    { year: 1951, realStockReturn: 0.1458 },
+    { year: 1952, realStockReturn: 0.1470 },
+    { year: 1953, realStockReturn: -0.0124 },
+    { year: 1954, realStockReturn: 0.5266 },
+    { year: 1955, realStockReturn: 0.3139 },
+    { year: 1956, realStockReturn: 0.0389 },
+    { year: 1957, realStockReturn: -0.1401 },
+    { year: 1958, realStockReturn: 0.4292 },
+    { year: 1959, realStockReturn: 0.1055 },
+    { year: 1960, realStockReturn: -0.0012 },
+    { year: 1961, realStockReturn: 0.2638 },
+    { year: 1962, realStockReturn: -0.1001 },
+    { year: 1963, realStockReturn: 0.2055 },
+    { year: 1964, realStockReturn: 0.1555 },
+    { year: 1965, realStockReturn: 0.1040 },
+    { year: 1966, realStockReturn: -0.1369 },
+    { year: 1967, realStockReturn: 0.2084 },
+    { year: 1968, realStockReturn: 0.0658 },
+    { year: 1969, realStockReturn: -0.1464 },
+    { year: 1970, realStockReturn: -0.0203 },
+    { year: 1971, realStockReturn: 0.1068 },
+    { year: 1972, realStockReturn: 0.1520 },
+    { year: 1973, realStockReturn: -0.2343 },
+    { year: 1974, realStockReturn: -0.3728 },
+    { year: 1975, realStockReturn: 0.2896 },
+    { year: 1976, realStockReturn: 0.1924 },
+    { year: 1977, realStockReturn: -0.1248 },
+    { year: 1978, realStockReturn: -0.0186 },
+    { year: 1979, realStockReturn: 0.0574 },
+    { year: 1980, realStockReturn: 0.1934 },
+    { year: 1981, realStockReturn: -0.1269 },
+    { year: 1982, realStockReturn: 0.1703 },
+    { year: 1983, realStockReturn: 0.1871 },
+    { year: 1984, realStockReturn: 0.0122 },
+    { year: 1985, realStockReturn: 0.2810 },
+    { year: 1986, realStockReturn: 0.1683 },
+    { year: 1987, realStockReturn: 0.0192 },
+    { year: 1988, realStockReturn: 0.1201 },
+    { year: 1989, realStockReturn: 0.2662 },
+    { year: 1990, realStockReturn: -0.0917 },
+    { year: 1991, realStockReturn: 0.2654 },
+    { year: 1992, realStockReturn: 0.0441 },
+    { year: 1993, realStockReturn: 0.0720 },
+    { year: 1994, realStockReturn: -0.0138 },
+    { year: 1995, realStockReturn: 0.3452 },
+    { year: 1996, realStockReturn: 0.1920 },
+    { year: 1997, realStockReturn: 0.3128 },
+    { year: 1998, realStockReturn: 0.2709 },
+    { year: 1999, realStockReturn: 0.1826 },
+    { year: 2000, realStockReturn: -0.1249 },
+    { year: 2001, realStockReturn: -0.1347 },
+    { year: 2002, realStockReturn: -0.2388 },
+    { year: 2003, realStockReturn: 0.2637 },
+    { year: 2004, realStockReturn: 0.0769 },
+    { year: 2005, realStockReturn: 0.0146 },
+    { year: 2006, realStockReturn: 0.1338 },
+    { year: 2007, realStockReturn: 0.0111 },
+    { year: 2008, realStockReturn: -0.3685 },
+    { year: 2009, realStockReturn: 0.2646 },
+    { year: 2010, realStockReturn: 0.1306 },
+    { year: 2011, realStockReturn: -0.0183 },
+    { year: 2012, realStockReturn: 0.1396 },
+    { year: 2013, realStockReturn: 0.3069 },
+    { year: 2014, realStockReturn: 0.1156 },
+    { year: 2015, realStockReturn: 0.0065 },
+    { year: 2016, realStockReturn: 0.0977 },
+    { year: 2017, realStockReturn: 0.1930 },
+    { year: 2018, realStockReturn: -0.0624 },
+    { year: 2019, realStockReturn: 0.2880 },
+    { year: 2020, realStockReturn: 0.1640 },
+    { year: 2021, realStockReturn: 0.2168 },
+    { year: 2022, realStockReturn: -0.2455 },
+    { year: 2023, realStockReturn: 0.2214 },
+    { year: 2024, realStockReturn: 0.2315 },
+];
+/**
+ * Runs the scenario against historical Shiller data using rolling N-year windows.
+ *
+ * N = end_age - current_age (the full projection span).
+ * For each starting year where N years of data are available, the projection
+ * is run using historical real stock returns, and the terminal balance and
+ * survival status are recorded.
+ *
+ * @param scenario   The base scenario (retirement_age, current_age, etc.)
+ * @param projectionFn  A projection function that accepts a Scenario plus an
+ *                      array of annual real returns and produces Metrics.
+ * @returns  Array of BacktestPeriod results and the overall success rate (0-100).
+ */
+export function runHistoricalBacktest(scenario, projectionFn) {
+    const span = scenario.end_age - scenario.current_age;
+    // Guard: span must be at least 1
+    if (span < 1) {
+        return { periods: [], successRate: 0 };
+    }
+    const periods = [];
+    const firstYear = SHILLER_DATA[0].year;
+    const lastYear = SHILLER_DATA[SHILLER_DATA.length - 1].year;
+    const dataLength = lastYear - firstYear + 1;
+    // Number of rolling windows we can create
+    const windowCount = dataLength - span + 1;
+    if (windowCount < 1) {
+        // Projection span exceeds available data — return empty with a note
+        // (CONTRACT-005: "fewer periods returned; minimum 1 period required" —
+        //  but if we truly can't make even 1 window, return empty.)
+        return { periods: [], successRate: 0 };
+    }
+    // Build a lookup map for O(1) access by year
+    const returnsByYear = new Map();
+    for (const entry of SHILLER_DATA) {
+        returnsByYear.set(entry.year, entry.realStockReturn);
+    }
+    let survivedCount = 0;
+    for (let i = 0; i < windowCount; i++) {
+        const startYear = firstYear + i;
+        const endYear = startYear + span - 1;
+        // Extract returns for this window
+        const returns = [];
+        for (let y = startYear; y <= endYear; y++) {
+            const r = returnsByYear.get(y);
+            if (r === undefined)
+                break;
+            returns.push(r);
+        }
+        // If we didn't get enough years (shouldn't happen given windowCount calc), skip
+        if (returns.length < span)
+            continue;
+        // Run projection with historical returns
+        const result = projectionFn(scenario, returns);
+        // Balance floor at 0 (CONTRACT-005 invariant)
+        const terminalReal = Math.max(0, result.metrics.terminal_real);
+        const survived = result.metrics.first_shortfall_age === null;
+        periods.push({
+            startYear,
+            endYear,
+            terminalReal,
+            survived,
+        });
+        if (survived)
+            survivedCount++;
+    }
+    const successRate = periods.length > 0
+        ? (survivedCount / periods.length) * 100
+        : 0;
+    return { periods, successRate };
+}

package/dist/defaults.d.ts

@@ -0,0 +1,4 @@
+import type { Cadence, Scenario } from './types';
+export declare const CadenceMultiplier: Record<Cadence, number>;
+export declare const DEFAULT_SCENARIO: Scenario;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAMjD,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAKrD,CAAC;AAMF,eAAO,MAAM,gBAAgB,EAAE,QAqF9B,CAAC"}

package/dist/defaults.js

@@ -0,0 +1,84 @@
+// ---------------------------------------------------------------------------
+// Engine Defaults — standalone default values (no Zod dependency)
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Cadence Multiplier
+// ---------------------------------------------------------------------------
+export const CadenceMultiplier = {
+    Annual: 1,
+    Monthly: 12,
+    'Bi-Weekly': 26,
+    Weekly: 52,
+};
+// ---------------------------------------------------------------------------
+// Default Scenario
+// ---------------------------------------------------------------------------
+export const DEFAULT_SCENARIO = {
+    name: 'Scenario A',
+    // Timeline
+    current_age: 30,
+    retirement_age: 65,
+    end_age: 100,
+    // Portfolio
+    current_balance: 100000,
+    contrib_amount: 500,
+    contrib_cadence: 'Monthly',
+    contrib_increase_pct: 0,
+    // Returns
+    nominal_return_pct: 8,
+    return_stdev_pct: 15,
+    return_distribution: 'log-normal',
+    inflation_pct: 3,
+    inflation_enabled: true,
+    fee_pct: 0.5,
+    perf_fee_pct: 0,
+    // Withdrawal
+    withdrawal_method: 'Fixed % of prior-year end balance',
+    withdrawal_pct: 4,
+    withdrawal_real_amount: 50000,
+    withdrawal_frequency: 'Annual',
+    withdrawal_strategy: 'Standard',
+    // Guyton-Klinger
+    gk_ceiling_pct: 20,
+    gk_floor_pct: 20,
+    gk_prosperity_threshold: 20,
+    gk_capital_preservation_threshold: 20,
+    // Spending phases
+    spending_phases: [],
+    // Monte Carlo
+    enable_mc: true,
+    mc_runs: 1000,
+    // Tax
+    enable_taxes: false,
+    effective_tax_rate_pct: 0,
+    tax_jurisdiction: 'Custom',
+    tax_config: null,
+    tax_deferred_pct: 85,
+    // Planning
+    planning_mode: 'Individual',
+    partner_name: '',
+    partner_current_age: null,
+    partner_retirement_age: null,
+    partner_income_sources: [],
+    // Assets
+    assets: [],
+    liquid_pct: 100,
+    // Advanced
+    detail_mode: 'basic',
+    financial_items: [],
+    // Income
+    income_sources: [],
+    // Liquidity events
+    liquidity_events: [],
+    // Estate
+    desired_estate: 0,
+    // Black swan
+    black_swan_enabled: false,
+    black_swan_age: 70,
+    black_swan_loss_pct: 50,
+    // Currency
+    currency_code: 'USD',
+    currency_symbol: '$',
+    // Withdrawal order
+    withdrawal_order: 'Tax-Efficient',
+};

package/dist/heatmap.d.ts

@@ -0,0 +1,38 @@
+import type { Scenario, Metrics } from './types';
+export interface HeatmapCell {
+    retirementAge: number;
+    annualSpending: number;
+    viable: boolean;
+    terminalReal: number;
+}
+export interface HeatmapOptions {
+    /** [min, max] retirement age range. Defaults to [current_age+1, end_age-1]. */
+    retirementAgeRange?: [number, number];
+    /** [min, max] annual spending range. Defaults to [10_000, 120_000]. */
+    spendingRange?: [number, number];
+    /** Number of steps on each axis. Defaults to 10. */
+    steps?: number;
+}
+/**
+ * Generates a 2D grid of retirement_age x annual_spending cells.
+ *
+ * For each combination, the scenario is adjusted and a deterministic projection
+ * is run.  Each cell records whether the scenario is viable (no shortfall and
+ * terminal_real >= desired_estate) along with the terminal_real value.
+ *
+ * The spending adjustment modifies:
+ *   - withdrawal_pct (when using "Fixed % of prior-year end balance")
+ *   - withdrawal_real_amount (when using "Fixed real-dollar amount")
+ *
+ * For percentage-based withdrawal, the spending value is treated as a dollar
+ * amount and the withdrawal_real_amount is set (method switched to fixed-dollar)
+ * so the heatmap consistently represents dollar-denominated spending levels.
+ *
+ * @param scenario      Base scenario
+ * @param projectionFn  Deterministic projection function
+ * @param options       Optional axis ranges and step count
+ */
+export declare function generateHeatmap(scenario: Scenario, projectionFn: (s: Scenario) => {
+    metrics: Metrics;
+}, options?: HeatmapOptions): HeatmapCell[];
+//# sourceMappingURL=heatmap.d.ts.map

package/dist/heatmap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heatmap.d.ts","sourceRoot":"","sources":["../src/heatmap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAMjD,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,uEAAuE;IACvE,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AASD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,CAAC,CAAC,EAAE,QAAQ,KAAK;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,EACnD,OAAO,CAAC,EAAE,cAAc,GACvB,WAAW,EAAE,CAoDf"}

package/dist/heatmap.js

@@ -0,0 +1,63 @@
+/**
+ * Deep-clone a scenario.
+ */
+function cloneScenario(s) {
+    return JSON.parse(JSON.stringify(s));
+}
+/**
+ * Generates a 2D grid of retirement_age x annual_spending cells.
+ *
+ * For each combination, the scenario is adjusted and a deterministic projection
+ * is run.  Each cell records whether the scenario is viable (no shortfall and
+ * terminal_real >= desired_estate) along with the terminal_real value.
+ *
+ * The spending adjustment modifies:
+ *   - withdrawal_pct (when using "Fixed % of prior-year end balance")
+ *   - withdrawal_real_amount (when using "Fixed real-dollar amount")
+ *
+ * For percentage-based withdrawal, the spending value is treated as a dollar
+ * amount and the withdrawal_real_amount is set (method switched to fixed-dollar)
+ * so the heatmap consistently represents dollar-denominated spending levels.
+ *
+ * @param scenario      Base scenario
+ * @param projectionFn  Deterministic projection function
+ * @param options       Optional axis ranges and step count
+ */
+export function generateHeatmap(scenario, projectionFn, options) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    const steps = (_a = options === null || options === void 0 ? void 0 : options.steps) !== null && _a !== void 0 ? _a : 10;
+    const ageMin = (_c = (_b = options === null || options === void 0 ? void 0 : options.retirementAgeRange) === null || _b === void 0 ? void 0 : _b[0]) !== null && _c !== void 0 ? _c : scenario.current_age + 1;
+    const ageMax = (_e = (_d = options === null || options === void 0 ? void 0 : options.retirementAgeRange) === null || _d === void 0 ? void 0 : _d[1]) !== null && _e !== void 0 ? _e : scenario.end_age - 1;
+    const spendMin = (_g = (_f = options === null || options === void 0 ? void 0 : options.spendingRange) === null || _f === void 0 ? void 0 : _f[0]) !== null && _g !== void 0 ? _g : 10000;
+    const spendMax = (_j = (_h = options === null || options === void 0 ? void 0 : options.spendingRange) === null || _h === void 0 ? void 0 : _h[1]) !== null && _j !== void 0 ? _j : 120000;
+    // Ensure at least 2 steps to avoid division by zero
+    const effectiveSteps = Math.max(steps, 2);
+    const ageStep = (ageMax - ageMin) / (effectiveSteps - 1);
+    const spendStep = (spendMax - spendMin) / (effectiveSteps - 1);
+    const cells = [];
+    const desiredEstate = (_k = scenario.desired_estate) !== null && _k !== void 0 ? _k : 0;
+    for (let ai = 0; ai < effectiveSteps; ai++) {
+        const retirementAge = Math.round(ageMin + ai * ageStep);
+        // Clamp retirement age to valid range
+        const clampedAge = Math.max(scenario.current_age + 1, Math.min(scenario.end_age - 1, retirementAge));
+        for (let si = 0; si < effectiveSteps; si++) {
+            const annualSpending = Math.round(spendMin + si * spendStep);
+            const s = cloneScenario(scenario);
+            s.retirement_age = clampedAge;
+            // Set spending as a fixed real-dollar amount for consistent comparison
+            s.withdrawal_method = 'Fixed real-dollar amount';
+            s.withdrawal_real_amount = Math.max(0, annualSpending);
+            const result = projectionFn(s);
+            const terminalReal = result.metrics.terminal_real;
+            const survived = result.metrics.first_shortfall_age === null;
+            const viable = survived && terminalReal >= desiredEstate;
+            cells.push({
+                retirementAge: clampedAge,
+                annualSpending,
+                viable,
+                terminalReal,
+            });
+        }
+    }
+    return cells;
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export type { Cadence, CurrencyCode, ContribStep, ProfitStep, RaiseStep, YieldStep, IncomeStep, LoanDraw, LumpRepayment, SpendingPhase, TaxConfig, IncomeSource, Asset, LiquidityEvent, FinancialItemCategory, FinancialItem, Scenario, TimelineRow, FanChartRow, Metrics, } from './types';
+export { CadenceMultiplier, DEFAULT_SCENARIO } from './defaults';
+export { runProjection } from './projection';
+export { runAdvancedProjection } from './advanced';
+export { runMonteCarloSimulation, type MCOptions, type MCResult, type ProjectionFn, } from './monte-carlo';
+export { runSensitivityAnalysis, type SensitivityFactor, } from './sensitivity';
+export { runHistoricalBacktest, type BacktestPeriod, type BacktestResult, } from './backtest';
+export { findEarliestRetirementAge, type OptimizerResult, type OptimizerOutput, type OptimizerOptions, } from './optimizer';
+export { generateHeatmap, type HeatmapCell, type HeatmapOptions, } from './heatmap';
+export { blendPortfolio, calculateEstateValue, type BlendedPortfolio, } from './portfolio';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,YAAY,EACV,OAAO,EACP,YAAY,EACZ,WAAW,EACX,UAAU,EACV,SAAS,EACT,SAAS,EACT,UAAU,EACV,QAAQ,EACR,aAAa,EACb,aAAa,EACb,SAAS,EACT,YAAY,EACZ,KAAK,EACL,cAAc,EACd,qBAAqB,EACrB,aAAa,EACb,QAAQ,EACR,WAAW,EACX,WAAW,EACX,OAAO,GACR,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGjE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGnD,OAAO,EACL,uBAAuB,EACvB,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,sBAAsB,EACtB,KAAK,iBAAiB,GACvB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,qBAAqB,EACrB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,yBAAyB,EACzB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,cAAc,GACpB,MAAM,WAAW,CAAC;AAGnB,OAAO,EACL,cAAc,EACd,oBAAoB,EACpB,KAAK,gBAAgB,GACtB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+// ---------------------------------------------------------------------------
+// Engine — barrel export
+// ---------------------------------------------------------------------------
+export { CadenceMultiplier, DEFAULT_SCENARIO } from './defaults';
+// Deterministic projection (basic & advanced)
+export { runProjection } from './projection';
+export { runAdvancedProjection } from './advanced';
+// Monte Carlo simulation
+export { runMonteCarloSimulation, } from './monte-carlo';
+// Sensitivity (Tornado chart)
+export { runSensitivityAnalysis, } from './sensitivity';
+// Historical backtest (Shiller data)
+export { runHistoricalBacktest, } from './backtest';
+// Retirement age optimizer
+export { findEarliestRetirementAge, } from './optimizer';
+// Retirement age x spending heatmap
+export { generateHeatmap, } from './heatmap';
+// Portfolio blending & estate value
+export { blendPortfolio, calculateEstateValue, } from './portfolio';

package/dist/monte-carlo.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Monte Carlo Simulation Engine
+ *
+ * Deterministic, seeded PRNG-based Monte Carlo runner for retirement projections.
+ * Generates randomized annual returns and delegates year-by-year calculation to
+ * a caller-provided projection function, keeping MC fully decoupled from the
+ * projection engine.
+ */
+import type { Scenario, TimelineRow, Metrics, FanChartRow } from './types';
+export type ProjectionFn = (scenario: Scenario, overrideReturns?: number[]) => {
+    timeline: TimelineRow[];
+    metrics: Metrics;
+};
+export interface MCOptions {
+    /** Number of simulation runs. Default 1000, validated 100-10000. */
+    runs?: number;
+    /** PRNG seed for reproducibility. Default 42. */
+    seed?: number;
+    /** Wall-clock budget in ms before aborting. Default 50000. */
+    budgetMs?: number;
+}
+export interface MCResult {
+    probability_no_shortfall: number;
+    median_terminal: number;
+    p10_terminal: number;
+    p90_terminal: number;
+    fan_chart: FanChartRow[];
+    terminal_distribution: number[];
+    runs_completed: number;
+    truncated: boolean;
+}
+export declare class SeededRNG {
+    private state;
+    constructor(seed?: number);
+    /** Returns a uniform random number in [0, 1). Mulberry32 algorithm. */
+    next(): number;
+    /** Returns a standard normal random variate via Box-Muller transform. */
+    gaussian(): number;
+}
+export declare function generateReturn(rng: SeededRNG, mean: number, stdev: number, distribution: 'log-normal' | 'normal'): number;
+export declare function extractPercentile(sortedArray: number[], p: number): number;
+export declare function runMonteCarloSimulation(scenario: Scenario, projectionFn: ProjectionFn, options?: MCOptions): MCResult;
+//# sourceMappingURL=monte-carlo.d.ts.map

package/dist/monte-carlo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monte-carlo.d.ts","sourceRoot":"","sources":["../src/monte-carlo.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAM3E,MAAM,MAAM,YAAY,GAAG,CACzB,QAAQ,EAAE,QAAQ,EAClB,eAAe,CAAC,EAAE,MAAM,EAAE,KACvB;IAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAEnD,MAAM,WAAW,SAAS;IACxB,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,QAAQ;IACvB,wBAAwB,EAAE,MAAM,CAAC;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,WAAW,EAAE,CAAC;IACzB,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;CACpB;AAMD,qBAAa,SAAS;IACpB,OAAO,CAAC,KAAK,CAAS;gBAEV,IAAI,GAAE,MAAW;IAI7B,uEAAuE;IACvE,IAAI,IAAI,MAAM;IAQd,yEAAyE;IACzE,QAAQ,IAAI,MAAM;CAUnB;AAMD,wBAAgB,cAAc,CAC5B,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,YAAY,GAAG,QAAQ,GACpC,MAAM,CAuBR;AAMD,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAK1E;AAMD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,QAAQ,EAClB,YAAY,EAAE,YAAY,EAC1B,OAAO,GAAE,SAAc,GACtB,QAAQ,CAoIV"}