@retiregolden/engine 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# @retiregolden/engine
+
+Pure-TypeScript retirement-planning engine — the calculation core of
+[RetireGolden](https://retiregolden.app/). It projects a household's finances
+year by year and models federal + state taxes, Social Security (claiming,
+spousal/survivor, PIA from earnings), RMDs, Roth conversions, withdrawal
+strategies, insurance, Monte Carlo, and an LP-based optimizer.
+
+Source of truth: [github.com/RetireGolden/RetireGolden](https://github.com/RetireGolden/RetireGolden)
+(`packages/engine`). Engineering docs live in the repo's `DOCS/`.
+
+## Runtime contract
+
+- **ESM, Node ≥ 20** (also bundles cleanly for browsers). No CommonJS build.
+- **No browser globals, no ambient network, no persistence.** The engine never
+  touches `fetch`, `localStorage`, `indexedDB`, or the DOM — enforced by lint.
+  IO always crosses an injection seam owned by the consumer:
+  - anything stochastic takes an injected seedable RNG (`montecarlo/rng`);
+  - the optimizer loads the HiGHS wasm via an optional `locateFile` option
+    (`strategies/optimizer`);
+  - FedInvest TIPS prices: the engine only parses CSV text
+    (`ladder/fedInvest`); fetching and caching are the consumer's job.
+- **Deterministic.** Same plan + same options ⇒ bit-identical results.
+- Parameters (tax brackets, limits, SSA tables, Medicare/FPL) are versioned
+  data packs under `params/`, with provenance.
+
+## Usage
+
+Deep subpath imports are the primary API; the root export covers the core
+validate-and-project loop:
+
+```ts
+import { planSchema, simulatePlan } from '@retiregolden/engine'
+
+const plan = planSchema.parse(JSON.parse(planJson))
+const result = simulatePlan(plan, { startYear: 2026 })
+```
+
+```ts
+import { runMonteCarlo } from '@retiregolden/engine/montecarlo/run'
+import { packForYear } from '@retiregolden/engine/params'
+```
+
+Test fixtures used by the RetireGolden apps' own suites ship under
+`@retiregolden/engine/testing/*` — framework-free (no vitest or other
+test-runner dependency), but not part of the supported runtime API.
+
+## Layout
+
+| Subpath | Contents |
+|---------|----------|
+| `model/` | Plan schema (Zod), types, migrations |
+| `params/` | Annual parameter packs (tax brackets, limits, RMD, Medicare, SS, state) + typed accessors |
+| `tax/` | Federal + state tax engine, ACA credit, Medicare/IRMAA |
+| `rmd/` | Required minimum distributions (SECURE 2.0) |
+| `socialSecurity/` | Claiming factors, NRA/FRA, PIA from earnings, spousal/survivor/family-maximum, disability |
+| `longevity/` | SSA 2022 period life table + shared types |
+| `strategies/` | Roth-conversion sizing (fill-to-target), withdrawal ordering, SEPP, inherited-IRA, the optimizer |
+| `projection/` | Deterministic annual ledger + summaries/comparison |
+| `montecarlo/` | Seedable RNG, market models (lognormal, historical bootstrap), path runner + aggregation, mortality/survival |
+| `scenarios/` | Scenario patch apply/diff + side-by-side comparison |
+| `decisions/`, `insights/` | Candidate evaluation, recommendation detectors |
+| `ladder/` | TIPS ladder math, Social Security bridge, FedInvest CSV parsing |
+| `allocation/`, `spending/` | Asset classes, spending shape presets |
+| `testing/` | Plan fixtures and money matchers for consumer test suites |
+
+## License
+
+**AGPL-3.0-only** (see [LICENSE](LICENSE)). The engine is free and un-gutted —
+the full math ships in the free web app.
+
+RetireGolden, LLC also ships a commercial desktop edition built from this same
+engine under a separate commercial license, which funds the free one. That
+dual-license arrangement is why contributions to the
+[upstream repo](https://github.com/RetireGolden/RetireGolden) require a
+one-time [Contributor License Agreement](https://github.com/RetireGolden/RetireGolden/blob/main/CLA.md)
+— you keep your copyright; the CLA lets the LLC also ship your contribution in
+the commercial edition. See
+[CONTRIBUTING.md](https://github.com/RetireGolden/RetireGolden/blob/main/CONTRIBUTING.md).

package/dist/allocation/assetClasses.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Asset classes, sourced default parameters, and allocation/glidepath math
+ * (asset-allocation-and-return-model-v2, steps 1–3).
+ *
+ * Pure helpers shared by the deterministic ledger, Monte Carlo class shocks,
+ * the decision engine's asset-location generator, and the UI. The schema for
+ * per-account allocation policies lives in `engine/model/plan.ts`; this module
+ * owns the numbers and the math.
+ *
+ * Allocation is opt-in per account: an account without an `allocation` keeps
+ * the single expected-return model unchanged (feature-off is byte-identical).
+ *
+ * @see DOCS/domain/domain-rules-reference.md §14 (class defaults + sources)
+ */
+import type { AssetAllocationPolicy, AssetClassId, AssetClassParamOverrides, Assumptions, AllocationWeights, Account, Plan } from '../model/plan.js';
+export interface AssetClassParams {
+    label: string;
+    /** Long-run expected annual nominal total return, percent. */
+    returnPct: number;
+    /** Annual return volatility, percentage points (drives Monte Carlo class shocks). */
+    volatilityPct: number;
+    /** Portion of the total return distributed as taxable interest, percent of balance. */
+    interestYieldPct: number;
+    /** Portion of the total return distributed as dividends, percent of balance. */
+    dividendYieldPct: number;
+    /** Share of dividends taxed as qualified dividends, percent. */
+    qualifiedRatioPct: number;
+}
+/**
+ * Sourced planning defaults, editable in Assumptions. Expected returns follow
+ * the app's long-run nominal conventions (the in-app return estimator uses
+ * stocks ≈ 7%, bonds ≈ 4%, cash ≈ 2.5%); volatilities and correlations are
+ * long-horizon historical values from the Damodaran (NYU Stern) annual
+ * dataset — the same source as the embedded Monte Carlo history — with
+ * international equity proxied by MSCI EAFE history. Yields are current-era
+ * index-fund figures. Sources + review cadence:
+ * DOCS/domain/domain-rules-reference.md §14.
+ */
+export declare const DEFAULT_ASSET_CLASS_PARAMS: Record<AssetClassId, AssetClassParams>;
+/**
+ * Default long-horizon correlation matrix over ASSET_CLASS_IDS order
+ * (usStocks, intlStocks, bonds, cash). Documented + sourced in domain rules
+ * §14; editable defaults can ship later without changing this seam.
+ */
+export declare const DEFAULT_CLASS_CORRELATIONS: readonly (readonly number[])[];
+/** Assumption overrides merged over the sourced defaults (absent = default). */
+export declare function resolveAssetClassParams(overrides: AssetClassParamOverrides | undefined): Record<AssetClassId, AssetClassParams>;
+/** Weights record → normalized fraction vector in ASSET_CLASS_IDS order. */
+export declare function weightsToVector(weights: AllocationWeights): number[];
+/**
+ * Compile a glidepath policy to this year's target weights (normalized
+ * fractions in ASSET_CLASS_IDS order). Linear interpolates between its
+ * endpoints and clamps outside them; staged is a step function holding each
+ * stage from its fromYear; custom interpolates between year targets and
+ * clamps outside the first/last target.
+ */
+export declare function targetWeightsAt(policy: AssetAllocationPolicy, year: number): number[];
+/** Blended expected nominal return for a weight vector, percent. */
+export declare function blendedReturnPct(weights: number[], params: Record<AssetClassId, AssetClassParams>): number;
+export interface BlendedTaxableYield {
+    interestYieldPct: number;
+    dividendYieldPct: number;
+    /** Dividend-weighted qualified share, 0–1 (0.85 fallback when no dividends). */
+    qualifiedRatio: number;
+}
+/** Class yields blended by weight — feeds the shipped taxable-drag fields. */
+export declare function blendedTaxableYield(weights: number[], params: Record<AssetClassId, AssetClassParams>): BlendedTaxableYield;
+/**
+ * Weights after one year in which class i returned ratesPct[i] percent (no
+ * rebalance). Total-return drift: distributions are treated as reinvested
+ * pro-rata for weight purposes, a planning-grade simplification.
+ */
+export declare function driftWeights(weights: number[], ratesPct: number[]): number[];
+/** Fraction of the account sold to move current → target (Σ overweight). */
+export declare function rebalanceTurnoverFraction(current: number[], target: number[]): number;
+/** Non-cash share of a weight vector (the market-shocked portion under the single-factor model). */
+export declare function nonCashWeight(weights: number[]): number;
+/** The account's allocation policy, when its type supports one and it is set. */
+export declare function accountAllocation(account: Account): AssetAllocationPolicy | undefined;
+/** Whether any account opts into class-level allocation (gates MC class shocks). */
+export declare function planUsesAssetAllocation(plan: Plan): boolean;
+/**
+ * Expected nominal return for an account this year: the allocation blend when
+ * the account opts in (its explicit annualReturnPct is superseded), else the
+ * account's own return, else the plan default.
+ */
+export declare function expectedAccountReturnPct(account: Account, assumptions: Assumptions, year: number): number;
+/**
+ * Cholesky factor L (lower-triangular, LLᵀ = matrix) for correlated class
+ * draws. For non-positive-definite input the diagonal term is clamped to a
+ * small epsilon (1e-12) rather than failing, so the factorization always
+ * returns (defensive: the shipped default matrix is PD).
+ */
+export declare function choleskyDecompose(matrix: readonly (readonly number[])[]): number[][];

package/dist/allocation/assetClasses.js

@@ -0,0 +1,215 @@
+/**
+ * Asset classes, sourced default parameters, and allocation/glidepath math
+ * (asset-allocation-and-return-model-v2, steps 1–3).
+ *
+ * Pure helpers shared by the deterministic ledger, Monte Carlo class shocks,
+ * the decision engine's asset-location generator, and the UI. The schema for
+ * per-account allocation policies lives in `engine/model/plan.ts`; this module
+ * owns the numbers and the math.
+ *
+ * Allocation is opt-in per account: an account without an `allocation` keeps
+ * the single expected-return model unchanged (feature-off is byte-identical).
+ *
+ * @see DOCS/domain/domain-rules-reference.md §14 (class defaults + sources)
+ */
+import { ASSET_CLASS_IDS } from '../model/plan.js';
+/**
+ * Sourced planning defaults, editable in Assumptions. Expected returns follow
+ * the app's long-run nominal conventions (the in-app return estimator uses
+ * stocks ≈ 7%, bonds ≈ 4%, cash ≈ 2.5%); volatilities and correlations are
+ * long-horizon historical values from the Damodaran (NYU Stern) annual
+ * dataset — the same source as the embedded Monte Carlo history — with
+ * international equity proxied by MSCI EAFE history. Yields are current-era
+ * index-fund figures. Sources + review cadence:
+ * DOCS/domain/domain-rules-reference.md §14.
+ */
+export const DEFAULT_ASSET_CLASS_PARAMS = {
+    usStocks: { label: 'US stocks', returnPct: 7.0, volatilityPct: 19.6, interestYieldPct: 0, dividendYieldPct: 1.5, qualifiedRatioPct: 95 },
+    intlStocks: { label: 'International stocks', returnPct: 7.0, volatilityPct: 21.0, interestYieldPct: 0, dividendYieldPct: 3.0, qualifiedRatioPct: 70 },
+    bonds: { label: 'Bonds', returnPct: 4.0, volatilityPct: 7.7, interestYieldPct: 4.0, dividendYieldPct: 0, qualifiedRatioPct: 0 },
+    cash: { label: 'Cash', returnPct: 2.5, volatilityPct: 0.5, interestYieldPct: 2.5, dividendYieldPct: 0, qualifiedRatioPct: 0 },
+};
+/**
+ * Default long-horizon correlation matrix over ASSET_CLASS_IDS order
+ * (usStocks, intlStocks, bonds, cash). Documented + sourced in domain rules
+ * §14; editable defaults can ship later without changing this seam.
+ */
+export const DEFAULT_CLASS_CORRELATIONS = [
+    [1.0, 0.75, 0.1, 0.0],
+    [0.75, 1.0, 0.1, 0.0],
+    [0.1, 0.1, 1.0, 0.2],
+    [0.0, 0.0, 0.2, 1.0],
+];
+/** Assumption overrides merged over the sourced defaults (absent = default). */
+export function resolveAssetClassParams(overrides) {
+    const resolved = {};
+    for (const id of ASSET_CLASS_IDS) {
+        const d = DEFAULT_ASSET_CLASS_PARAMS[id];
+        const o = overrides?.[id];
+        resolved[id] = {
+            label: d.label,
+            returnPct: o?.returnPct ?? d.returnPct,
+            volatilityPct: o?.volatilityPct ?? d.volatilityPct,
+            interestYieldPct: o?.interestYieldPct ?? d.interestYieldPct,
+            dividendYieldPct: o?.dividendYieldPct ?? d.dividendYieldPct,
+            qualifiedRatioPct: o?.qualifiedRatioPct ?? d.qualifiedRatioPct,
+        };
+    }
+    return resolved;
+}
+/** Weights record → normalized fraction vector in ASSET_CLASS_IDS order. */
+export function weightsToVector(weights) {
+    const raw = ASSET_CLASS_IDS.map((id) => Math.max(0, weights[id]));
+    const total = raw.reduce((a, b) => a + b, 0);
+    if (total <= 0)
+        return ASSET_CLASS_IDS.map((id) => (id === 'cash' ? 1 : 0));
+    return raw.map((w) => w / total);
+}
+function lerpVectors(a, b, t) {
+    const mixed = a.map((v, i) => v + (b[i] - v) * t);
+    const total = mixed.reduce((x, y) => x + y, 0);
+    return total > 0 ? mixed.map((v) => v / total) : mixed;
+}
+/**
+ * Compile a glidepath policy to this year's target weights (normalized
+ * fractions in ASSET_CLASS_IDS order). Linear interpolates between its
+ * endpoints and clamps outside them; staged is a step function holding each
+ * stage from its fromYear; custom interpolates between year targets and
+ * clamps outside the first/last target.
+ */
+export function targetWeightsAt(policy, year) {
+    switch (policy.mode) {
+        case 'static':
+            return weightsToVector(policy.weights);
+        case 'linear': {
+            const from = weightsToVector(policy.from);
+            const to = weightsToVector(policy.to);
+            if (year <= policy.startYear || policy.endYear <= policy.startYear)
+                return from;
+            if (year >= policy.endYear)
+                return to;
+            return lerpVectors(from, to, (year - policy.startYear) / (policy.endYear - policy.startYear));
+        }
+        case 'staged': {
+            const stages = [...policy.stages].sort((a, b) => a.fromYear - b.fromYear);
+            let current = stages[0];
+            for (const stage of stages) {
+                if (stage.fromYear <= year)
+                    current = stage;
+            }
+            return weightsToVector(current.weights);
+        }
+        case 'custom': {
+            const targets = [...policy.targets].sort((a, b) => a.year - b.year);
+            if (year <= targets[0].year)
+                return weightsToVector(targets[0].weights);
+            const last = targets[targets.length - 1];
+            if (year >= last.year)
+                return weightsToVector(last.weights);
+            for (let i = 0; i < targets.length - 1; i++) {
+                const lo = targets[i];
+                const hi = targets[i + 1];
+                if (year >= lo.year && year <= hi.year) {
+                    const t = (year - lo.year) / (hi.year - lo.year);
+                    return lerpVectors(weightsToVector(lo.weights), weightsToVector(hi.weights), t);
+                }
+            }
+            return weightsToVector(last.weights);
+        }
+    }
+}
+/** Blended expected nominal return for a weight vector, percent. */
+export function blendedReturnPct(weights, params) {
+    return ASSET_CLASS_IDS.reduce((sum, id, i) => sum + (weights[i] ?? 0) * params[id].returnPct, 0);
+}
+/** Class yields blended by weight — feeds the shipped taxable-drag fields. */
+export function blendedTaxableYield(weights, params) {
+    let interest = 0;
+    let dividends = 0;
+    let qualified = 0;
+    ASSET_CLASS_IDS.forEach((id, i) => {
+        const w = weights[i] ?? 0;
+        interest += w * params[id].interestYieldPct;
+        dividends += w * params[id].dividendYieldPct;
+        qualified += w * params[id].dividendYieldPct * (params[id].qualifiedRatioPct / 100);
+    });
+    return {
+        interestYieldPct: interest,
+        dividendYieldPct: dividends,
+        qualifiedRatio: dividends > 0 ? qualified / dividends : 0.85,
+    };
+}
+/**
+ * Weights after one year in which class i returned ratesPct[i] percent (no
+ * rebalance). Total-return drift: distributions are treated as reinvested
+ * pro-rata for weight purposes, a planning-grade simplification.
+ */
+export function driftWeights(weights, ratesPct) {
+    const grown = weights.map((w, i) => w * Math.max(0, 1 + (ratesPct[i] ?? 0) / 100));
+    const total = grown.reduce((a, b) => a + b, 0);
+    return total > 0 ? grown.map((v) => v / total) : weights;
+}
+/** Fraction of the account sold to move current → target (Σ overweight). */
+export function rebalanceTurnoverFraction(current, target) {
+    let turnover = 0;
+    for (let i = 0; i < current.length; i++) {
+        turnover += Math.max(0, (current[i] ?? 0) - (target[i] ?? 0));
+    }
+    return turnover;
+}
+/** Non-cash share of a weight vector (the market-shocked portion under the single-factor model). */
+export function nonCashWeight(weights) {
+    const cashIndex = ASSET_CLASS_IDS.indexOf('cash');
+    return Math.max(0, 1 - (weights[cashIndex] ?? 0));
+}
+/** The account's allocation policy, when its type supports one and it is set. */
+export function accountAllocation(account) {
+    if (account.type === 'taxable' ||
+        account.type === 'traditional' ||
+        account.type === 'roth' ||
+        account.type === 'hsa') {
+        return account.allocation;
+    }
+    return undefined;
+}
+/** Whether any account opts into class-level allocation (gates MC class shocks). */
+export function planUsesAssetAllocation(plan) {
+    return plan.accounts.some((a) => accountAllocation(a) !== undefined);
+}
+/**
+ * Expected nominal return for an account this year: the allocation blend when
+ * the account opts in (its explicit annualReturnPct is superseded), else the
+ * account's own return, else the plan default.
+ */
+export function expectedAccountReturnPct(account, assumptions, year) {
+    const policy = accountAllocation(account);
+    if (policy) {
+        return blendedReturnPct(targetWeightsAt(policy, year), resolveAssetClassParams(assumptions.assetClassParams));
+    }
+    const own = 'annualReturnPct' in account ? account.annualReturnPct : null;
+    return own ?? assumptions.defaultReturnPct;
+}
+/**
+ * Cholesky factor L (lower-triangular, LLᵀ = matrix) for correlated class
+ * draws. For non-positive-definite input the diagonal term is clamped to a
+ * small epsilon (1e-12) rather than failing, so the factorization always
+ * returns (defensive: the shipped default matrix is PD).
+ */
+export function choleskyDecompose(matrix) {
+    const n = matrix.length;
+    const L = Array.from({ length: n }, () => new Array(n).fill(0));
+    for (let i = 0; i < n; i++) {
+        for (let j = 0; j <= i; j++) {
+            let sum = 0;
+            for (let k = 0; k < j; k++)
+                sum += L[i][k] * L[j][k];
+            if (i === j) {
+                L[i][j] = Math.sqrt(Math.max(1e-12, matrix[i][i] - sum));
+            }
+            else {
+                L[i][j] = (matrix[i][j] - sum) / L[j][j];
+            }
+        }
+    }
+    return L;
+}

package/dist/decisions/annuitization.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Annuitization sweep solver (annuity-pension-and-home-equity decisions,
+ * step 2): how much of the portfolio to trade for a SPIA?
+ *
+ * Sweeps a bounded grid of allocation percentages through the shared-path
+ * Monte Carlo primitive: each point adds a life-only SPIA purchase (funded
+ * from the largest liquid account, priced at the sourced default payout rate
+ * or a user-entered quote) and reports success-rate / estate metrics against
+ * the 0% point — a success-vs-legacy frontier on identical market paths.
+ *
+ * Kitces attribution: much of a SPIA's measured benefit is the implicit
+ * rising-equity glidepath — the bond-like premium leaves the portfolio, so
+ * the remaining dollars run at a higher equity share. To isolate it, each
+ * point (when the funding account carries a static allocation with enough
+ * bonds) also evaluates a control variant that shifts the same premium from
+ * bonds to US stocks WITHOUT buying the annuity: control − baseline is the
+ * glidepath share of the benefit, point − control is what annuitization adds
+ * beyond it (mortality credits and payout floor, net of lost liquidity).
+ * Everything is priced on the exact ledger inside the Monte Carlo runner —
+ * the sweep never decides, it measures.
+ */
+import type { Plan } from '../model/plan.js';
+import { type SharedPathComparisonOptions } from '../montecarlo/sharedPaths.js';
+export interface AnnuitizationPointMetrics {
+    successRate: number;
+    requiredFloorSuccessRate: number;
+    targetLifestyleSuccessRate: number;
+    p10EndingAfterTaxEstate: number;
+    medianEndingAfterTaxEstate: number;
+    expectedShortfallDollars: number;
+}
+export interface AnnuitizationSweepPoint {
+    /** Requested grid percent of total investable assets (unique point key). */
+    allocationPct: number;
+    /**
+     * Share of total investable assets the premium actually represents
+     * (premium ÷ investable). Lower than `allocationPct` when the funding
+     * account caps the purchase — retirement-heavy plans can request 30% but
+     * only fund what the largest liquid account holds. Charts plot this.
+     */
+    effectiveAllocationPct: number;
+    /** SPIA premium this point trades away (nominal, at the start year). */
+    premium: number;
+    /** Annual annuity income the premium buys at the quoted rate. */
+    annualIncome: number;
+    metrics: AnnuitizationPointMetrics;
+    /** Allocation-matched control (glidepath without the annuity); absent when not constructible. */
+    glidepathControl?: AnnuitizationPointMetrics;
+}
+export interface AnnuitizationSweep {
+    points: AnnuitizationSweepPoint[];
+    /** Age payments start (max(current age, 65)) and the payout rate used. */
+    startAge: number;
+    payoutRatePct: number;
+    /** 'default-table' or 'user-quote' — where the payout rate came from. */
+    rateSource: 'default-table' | 'user-quote';
+    /**
+     * True when the glidepath controls could be built (static-allocation funding
+     * account with bond weight to shift); the Kitces attribution columns are
+     * only meaningful then.
+     */
+    attributionAvailable: boolean;
+    /** Why the sweep is empty or attribution is missing, for the UI. */
+    notes: string[];
+}
+export interface AnnuitizationSweepConfig {
+    /** Allocation grid (percent of investable). Bounded by MAX_FRONTIER_POINTS budget. */
+    allocationPcts?: readonly number[];
+    /** User-entered annual payout rate (percent of premium) overriding the default table. */
+    quotedPayoutRatePct?: number;
+}
+export declare function buildAnnuitizationSweep(plan: Plan, opts: SharedPathComparisonOptions, config?: AnnuitizationSweepConfig): AnnuitizationSweep;

package/dist/decisions/annuitization.js

@@ -0,0 +1,184 @@
+/**
+ * Annuitization sweep solver (annuity-pension-and-home-equity decisions,
+ * step 2): how much of the portfolio to trade for a SPIA?
+ *
+ * Sweeps a bounded grid of allocation percentages through the shared-path
+ * Monte Carlo primitive: each point adds a life-only SPIA purchase (funded
+ * from the largest liquid account, priced at the sourced default payout rate
+ * or a user-entered quote) and reports success-rate / estate metrics against
+ * the 0% point — a success-vs-legacy frontier on identical market paths.
+ *
+ * Kitces attribution: much of a SPIA's measured benefit is the implicit
+ * rising-equity glidepath — the bond-like premium leaves the portfolio, so
+ * the remaining dollars run at a higher equity share. To isolate it, each
+ * point (when the funding account carries a static allocation with enough
+ * bonds) also evaluates a control variant that shifts the same premium from
+ * bonds to US stocks WITHOUT buying the annuity: control − baseline is the
+ * glidepath share of the benefit, point − control is what annuitization adds
+ * beyond it (mortality credits and payout floor, net of lost liquidity).
+ * Everything is priced on the exact ledger inside the Monte Carlo runner —
+ * the sweep never decides, it measures.
+ */
+import { comparePlansOnSharedMarketPaths } from '../montecarlo/sharedPaths.js';
+import { MAX_FRONTIER_POINTS } from '../montecarlo/frontiers.js';
+import { spiaPayoutRate } from './spiaQuotes.js';
+const DEFAULT_GRID = [0, 5, 10, 15, 20, 25, 30];
+function dobYear(dob) {
+    return Number(dob.slice(0, 4));
+}
+function accountBalance(account) {
+    return 'balance' in account ? account.balance : 0;
+}
+function metricsFromRow(row) {
+    return {
+        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,
+    };
+}
+/** Sum of liquid + retirement balances the sweep sizes premiums against. */
+function investableTotal(plan) {
+    let total = 0;
+    for (const account of plan.accounts) {
+        if (account.type === 'cash' ||
+            account.type === 'taxable' ||
+            account.type === 'equityComp' ||
+            account.type === 'traditional' ||
+            account.type === 'roth' ||
+            account.type === 'hsa') {
+            total += accountBalance(account);
+        }
+    }
+    return total;
+}
+export function buildAnnuitizationSweep(plan, opts, config = {}) {
+    const notes = [];
+    const grid = [...(config.allocationPcts ?? DEFAULT_GRID)].sort((a, b) => a - b);
+    const primary = plan.household.people[0];
+    const funding = plan.accounts
+        .filter((a) => a.type === 'cash' || a.type === 'taxable')
+        .sort((a, b) => accountBalance(b) - accountBalance(a))[0];
+    const total = investableTotal(plan);
+    if (!primary || !funding || total <= 0) {
+        return {
+            points: [],
+            startAge: 65,
+            payoutRatePct: 0,
+            rateSource: 'default-table',
+            attributionAvailable: false,
+            notes: ['The sweep needs a household member and a cash or taxable account to fund purchases from.'],
+        };
+    }
+    const currentAge = opts.startYear - dobYear(primary.dob);
+    const startAge = Math.min(95, Math.max(currentAge, 65));
+    const rateSource = config.quotedPayoutRatePct !== undefined ? 'user-quote' : 'default-table';
+    const payoutRate = config.quotedPayoutRatePct !== undefined ? config.quotedPayoutRatePct / 100 : spiaPayoutRate(startAge);
+    // Premiums cap at what the funding account can actually pay (leaving 5% so
+    // the purchase never zeroes the household's most liquid account).
+    const fundingCap = accountBalance(funding) * 0.95;
+    const nonZeroPcts = grid.filter((pct) => pct > 0);
+    // Attribution controls need a static allocation on the funding account so
+    // "sell bonds for the SPIA" has a concrete meaning.
+    const fundingAllocation = 'allocation' in funding ? funding.allocation : undefined;
+    const staticWeights = fundingAllocation?.mode === 'static' ? fundingAllocation.weights : undefined;
+    if (!staticWeights) {
+        notes.push('Glidepath attribution needs a static asset allocation on the funding account (so shifting the premium out of bonds is well-defined); controls were skipped.');
+    }
+    // Budget: 1 baseline + a SPIA variant and (when constructible) a control per
+    // non-zero point, inside the shared-path frontier cap.
+    const budgetPerPoint = staticWeights ? 2 : 1;
+    const maxPoints = Math.floor((MAX_FRONTIER_POINTS - 1) / budgetPerPoint);
+    const pcts = nonZeroPcts.slice(0, maxPoints);
+    if (pcts.length < nonZeroPcts.length) {
+        notes.push(`The allocation grid was truncated to ${pcts.length} points to stay inside the bounded sweep budget.`);
+    }
+    const variants = [{ id: 'annuitize-0', label: '0% (no annuity)', plan }];
+    const pointMeta = [];
+    for (const pct of pcts) {
+        const premium = Math.min((pct / 100) * total, fundingCap);
+        if (premium < 5_000)
+            continue;
+        const annualIncome = premium * payoutRate;
+        const spia = {
+            id: `annuitize-sweep-${opts.startYear}-${funding.id}-${pct}`,
+            type: 'annuity',
+            name: `SPIA sweep ${pct}%`,
+            ownerPersonId: primary.id,
+            annualReturnPct: null,
+            startAge,
+            monthlyAmount: annualIncome / 12,
+            colaPct: 0,
+            taxablePct: 100,
+            purchase: { year: opts.startYear, premium, fundingAccountId: funding.id, taxQualification: 'nonQualified' },
+        };
+        variants.push({
+            id: `annuitize-${pct}`,
+            label: `${pct}% annuitized`,
+            plan: { ...plan, accounts: [...plan.accounts, spia] },
+        });
+        let controlId;
+        if (staticWeights) {
+            // Shift the premium's dollars from bonds to US stocks inside the funding
+            // account — the rising-equity glidepath a bond-funded SPIA buyer gets,
+            // without the annuity. Clamped to the bonds actually there.
+            const balance = accountBalance(funding);
+            const shiftPct = balance > 0 ? Math.min((premium / balance) * 100, staticWeights.bonds) : 0;
+            if (shiftPct > 0.5) {
+                controlId = `glidepath-${pct}`;
+                const shiftedFunding = {
+                    ...funding,
+                    allocation: {
+                        ...fundingAllocation,
+                        weights: {
+                            ...staticWeights,
+                            bonds: staticWeights.bonds - shiftPct,
+                            usStocks: Math.min(100, staticWeights.usStocks + shiftPct),
+                        },
+                    },
+                };
+                variants.push({
+                    id: controlId,
+                    label: `${pct}% glidepath control`,
+                    plan: { ...plan, accounts: plan.accounts.map((a) => (a.id === funding.id ? shiftedFunding : a)) },
+                });
+            }
+        }
+        pointMeta.push({ pct, premium, annualIncome, controlId });
+    }
+    const comparison = comparePlansOnSharedMarketPaths(variants, opts);
+    const rowById = new Map(comparison.rows.map((row) => [row.id, row]));
+    const baselineRow = rowById.get('annuitize-0');
+    if (!baselineRow)
+        return { points: [], startAge, payoutRatePct: payoutRate * 100, rateSource, attributionAvailable: false, notes };
+    const points = [
+        { allocationPct: 0, effectiveAllocationPct: 0, premium: 0, annualIncome: 0, metrics: metricsFromRow(baselineRow) },
+    ];
+    let anyControl = false;
+    let anyCapped = false;
+    for (const meta of pointMeta) {
+        const row = rowById.get(`annuitize-${meta.pct}`);
+        if (!row)
+            continue;
+        const controlRow = meta.controlId ? rowById.get(meta.controlId) : undefined;
+        if (controlRow)
+            anyControl = true;
+        const effectiveAllocationPct = total > 0 ? (meta.premium / total) * 100 : 0;
+        if (effectiveAllocationPct < meta.pct - 0.05)
+            anyCapped = true;
+        points.push({
+            allocationPct: meta.pct,
+            effectiveAllocationPct,
+            premium: meta.premium,
+            annualIncome: meta.annualIncome,
+            metrics: metricsFromRow(row),
+            glidepathControl: controlRow ? metricsFromRow(controlRow) : undefined,
+        });
+    }
+    if (anyCapped) {
+        notes.push('Some grid points were capped by the funding account (the largest cash/taxable balance): the reported share is the premium actually funded ÷ investable assets, not the requested grid value.');
+    }
+    return { points, startAge, payoutRatePct: payoutRate * 100, rateSource, attributionAvailable: anyControl, notes };
+}