@retiregolden/engine 0.1.0

package/dist/rmd/rmd.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Required minimum distributions (SECURE 2.0).
+ *
+ * Uses the Uniform Lifetime Table, except when the sole-beneficiary spouse is
+ * more than 10 years younger — then the Joint Life & Last Survivor expectancy
+ * applies (a larger divisor → smaller RMD), from IRS Pub 590-B Table II.
+ * Inherited-account 10-year rules and the first-year April 1 deferral are later
+ * phases (the RMD is taken in the age-attained year).
+ * Roth IRAs and Roth 401(k)s (since 2024) have no lifetime RMDs.
+ *
+ * @see DOCS/domain/domain-rules-reference.md §6
+ */
+import type { Sex } from '../montecarlo/mortality.js';
+import type { ParameterPack } from '../params/types.js';
+export interface RmdSpouse {
+    ageAttained: number;
+    sex: Sex;
+}
+export interface RmdOptions {
+    /** Kept for API compatibility; IRS Table II is not sex-specific. */
+    ownerSex?: Sex;
+    /** Sole-beneficiary spouse, if any; triggers the Joint Life table when >10 yrs younger. */
+    spouse?: RmdSpouse;
+}
+/**
+ * RMD for one traditional account-year.
+ * `priorYearEndBalance` is the Dec 31 balance of the previous year.
+ */
+export declare function requiredMinimumDistribution(pack: ParameterPack, birthYear: number, ageAttained: number, priorYearEndBalance: number, opts?: RmdOptions): number;

package/dist/rmd/rmd.js

@@ -0,0 +1,34 @@
+/**
+ * Required minimum distributions (SECURE 2.0).
+ *
+ * Uses the Uniform Lifetime Table, except when the sole-beneficiary spouse is
+ * more than 10 years younger — then the Joint Life & Last Survivor expectancy
+ * applies (a larger divisor → smaller RMD), from IRS Pub 590-B Table II.
+ * Inherited-account 10-year rules and the first-year April 1 deferral are later
+ * phases (the RMD is taken in the age-attained year).
+ * Roth IRAs and Roth 401(k)s (since 2024) have no lifetime RMDs.
+ *
+ * @see DOCS/domain/domain-rules-reference.md §6
+ */
+import { rmdStartAgeForBirthYear, uniformLifetimeDivisor } from '../params/index.js';
+import { jointLifeTableDivisor } from './jointLifeTable.js';
+/**
+ * RMD for one traditional account-year.
+ * `priorYearEndBalance` is the Dec 31 balance of the previous year.
+ */
+export function requiredMinimumDistribution(pack, birthYear, ageAttained, priorYearEndBalance, opts = {}) {
+    if (priorYearEndBalance <= 0)
+        return 0;
+    if (ageAttained < rmdStartAgeForBirthYear(birthYear))
+        return 0;
+    let divisor = uniformLifetimeDivisor(pack, ageAttained);
+    if (divisor === undefined || divisor <= 0)
+        return 0;
+    // Joint Life & Last Survivor table when the spouse beneficiary is >10 yrs younger.
+    if (opts.spouse && ageAttained - opts.spouse.ageAttained > 10) {
+        const joint = jointLifeTableDivisor(ageAttained, opts.spouse.ageAttained);
+        if (joint !== undefined)
+            divisor = Math.max(divisor, joint);
+    }
+    return priorYearEndBalance / divisor;
+}

package/dist/scenarios/scenarios.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Named scenarios: patch application, diffing, and side-by-side comparison
+ * (roadmap V4, feature catalog §12).
+ *
+ * A scenario is a partial deep-override of the plan ("retire at 62", "17% SS
+ * cut from 2034", "no Roth conversions"). Patches are stored loosely typed on
+ * the plan (plan.scenarios[].patch); applying one deep-merges it over the
+ * base plan and re-parses through the Zod schema, so an invalid override
+ * fails loudly instead of simulating garbage.
+ *
+ * Merge rule: plain objects merge recursively; arrays, primitives, and null
+ * replace wholesale. Replacing arrays keeps patches predictable (overriding
+ * "accounts[1].balance" positionally would silently break when the user
+ * reorders accounts).
+ */
+import type { Plan, Scenario } from '../model/plan.js';
+import { type ParsePlanResult } from '../model/plan.js';
+import type { MarketModelConfig } from '../montecarlo/marketModels.js';
+import { type ProjectionSummary } from '../projection/compare.js';
+import { type SimulateOptions } from '../projection/simulate.js';
+import type { TaxCalculator } from '../projection/types.js';
+/**
+ * Deep-merge a scenario patch over the plan and validate the result. The
+ * merged plan keeps the base plan's id/name/scenarios; the patch cannot
+ * change the schema version.
+ */
+export declare function applyScenarioPatch(plan: Plan, patch: Record<string, unknown>): ParsePlanResult;
+export interface ScenarioDiffEntry {
+    /** Dotted path of the overridden leaf (e.g. "assumptions.ssHaircut.cutPct"). */
+    path: string;
+    baseValue: unknown;
+    scenarioValue: unknown;
+}
+/** Leaf-level diff of what a patch changes, for the comparison UI's "changed assumptions" panel. */
+export declare function diffScenarioPatch(plan: Plan, patch: Record<string, unknown>): ScenarioDiffEntry[];
+export interface ScenarioMonteCarloOptions {
+    model: MarketModelConfig;
+    pathCount: number;
+    seed: number;
+}
+export interface CompareScenariosOptions extends SimulateOptions {
+    /** When present, each scenario also gets a Monte Carlo success rate (same seed ⇒ same market paths). */
+    monteCarlo?: ScenarioMonteCarloOptions;
+    /**
+     * Build the tax stack from each row's own (patched) plan instead of pricing
+     * every row with `taxCalculator`. Needed when a patch changes tax
+     * assumptions (flat state-rate override, local rate) — e.g. relocation
+     * scenarios — so the scenario reproduces the surface that created it.
+     */
+    taxCalculatorForPlan?: (plan: Plan) => TaxCalculator;
+}
+export interface ScenarioComparisonRow {
+    /** null for the base plan row. */
+    scenarioId: string | null;
+    name: string;
+    summary: ProjectionSummary;
+    /** Patch-application or validation problems; when set, summary metrics are absent. */
+    error: string | null;
+    diff: ScenarioDiffEntry[];
+    successRate: number | null;
+}
+export interface ScenarioComparison {
+    rows: ScenarioComparisonRow[];
+}
+/**
+ * Run the base plan plus the given scenarios (default: all of plan.scenarios)
+ * and produce one comparison row each. Scenario rows that fail validation get
+ * an error string instead of metrics, so one bad patch never sinks the table.
+ */
+export declare function compareScenarios(plan: Plan, opts: CompareScenariosOptions, scenarios?: Scenario[]): ScenarioComparison;

package/dist/scenarios/scenarios.js

@@ -0,0 +1,130 @@
+/**
+ * Named scenarios: patch application, diffing, and side-by-side comparison
+ * (roadmap V4, feature catalog §12).
+ *
+ * A scenario is a partial deep-override of the plan ("retire at 62", "17% SS
+ * cut from 2034", "no Roth conversions"). Patches are stored loosely typed on
+ * the plan (plan.scenarios[].patch); applying one deep-merges it over the
+ * base plan and re-parses through the Zod schema, so an invalid override
+ * fails loudly instead of simulating garbage.
+ *
+ * Merge rule: plain objects merge recursively; arrays, primitives, and null
+ * replace wholesale. Replacing arrays keeps patches predictable (overriding
+ * "accounts[1].balance" positionally would silently break when the user
+ * reorders accounts).
+ */
+import { parsePlan } from '../model/plan.js';
+import { createMarketModel } from '../montecarlo/marketModels.js';
+import { aggregateMonteCarlo, runMonteCarloPaths } from '../montecarlo/run.js';
+import { summarizeProjection } from '../projection/compare.js';
+import { simulatePlan } from '../projection/simulate.js';
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function deepMerge(base, patch) {
+    if (!isPlainObject(base) || !isPlainObject(patch))
+        return patch;
+    const out = { ...base };
+    for (const [key, value] of Object.entries(patch)) {
+        out[key] = key in out ? deepMerge(out[key], value) : value;
+    }
+    return out;
+}
+/**
+ * Deep-merge a scenario patch over the plan and validate the result. The
+ * merged plan keeps the base plan's id/name/scenarios; the patch cannot
+ * change the schema version.
+ */
+export function applyScenarioPatch(plan, patch) {
+    const merged = deepMerge(plan, patch);
+    merged.schemaVersion = plan.schemaVersion;
+    merged.id = plan.id;
+    merged.scenarios = plan.scenarios;
+    return parsePlan(merged);
+}
+/** Leaf-level diff of what a patch changes, for the comparison UI's "changed assumptions" panel. */
+export function diffScenarioPatch(plan, patch) {
+    const entries = [];
+    const walk = (base, node, path) => {
+        if (isPlainObject(node) && isPlainObject(base)) {
+            for (const [key, value] of Object.entries(node)) {
+                walk(base[key], value, path ? `${path}.${key}` : key);
+            }
+            return;
+        }
+        if (JSON.stringify(base) !== JSON.stringify(node)) {
+            entries.push({ path, baseValue: base, scenarioValue: node });
+        }
+    };
+    walk(plan, patch, '');
+    return entries;
+}
+function runOne(plan, opts) {
+    const taxCalculator = opts.taxCalculatorForPlan ? opts.taxCalculatorForPlan(plan) : opts.taxCalculator;
+    const summary = summarizeProjection(plan, simulatePlan(plan, { startYear: opts.startYear, taxCalculator }));
+    let successRate = null;
+    if (opts.monteCarlo) {
+        const result = runMonteCarloPaths(plan, {
+            startYear: opts.startYear,
+            taxCalculator,
+            model: createMarketModel(opts.monteCarlo.model),
+            seed: opts.monteCarlo.seed,
+            pathCount: opts.monteCarlo.pathCount,
+        });
+        successRate = aggregateMonteCarlo(result).successRate;
+    }
+    return { summary, successRate };
+}
+const EMPTY_SUMMARY = {
+    lifetimeTaxesAndPenalties: 0,
+    lifetimeRothConversions: 0,
+    endingInvestable: 0,
+    endingNetWorth: 0,
+    endingAfterTaxEstate: 0,
+    endingEstateHeirTax: 0,
+    endingEstateToCharity: 0,
+    estateBreakdown: [],
+    endingByCategory: { cash: 0, taxable: 0, traditional: 0, roth: 0, hsa: 0 },
+    depletionYear: null,
+    warnings: [],
+    savingsRates: [],
+    averagePreRetirementSavingsRatePct: 0,
+    fiNumber: 0,
+    fiYear: null,
+    fiAge: null,
+    coastFireNumber: 0,
+};
+/**
+ * Run the base plan plus the given scenarios (default: all of plan.scenarios)
+ * and produce one comparison row each. Scenario rows that fail validation get
+ * an error string instead of metrics, so one bad patch never sinks the table.
+ */
+export function compareScenarios(plan, opts, scenarios) {
+    const rows = [];
+    const base = runOne(plan, opts);
+    rows.push({ scenarioId: null, name: 'Base plan', summary: base.summary, error: null, diff: [], successRate: base.successRate });
+    for (const scenario of scenarios ?? plan.scenarios) {
+        const applied = applyScenarioPatch(plan, scenario.patch);
+        if (!applied.ok) {
+            rows.push({
+                scenarioId: scenario.id,
+                name: scenario.name,
+                summary: EMPTY_SUMMARY,
+                error: `Scenario overrides are invalid: ${applied.issues.join('; ')}`,
+                diff: diffScenarioPatch(plan, scenario.patch),
+                successRate: null,
+            });
+            continue;
+        }
+        const run = runOne(applied.plan, opts);
+        rows.push({
+            scenarioId: scenario.id,
+            name: scenario.name,
+            summary: run.summary,
+            error: null,
+            diff: diffScenarioPatch(plan, scenario.patch),
+            successRate: run.successRate,
+        });
+    }
+    return { rows };
+}

package/dist/socialSecurity/benefitFactor.d.ts

@@ -0,0 +1,13 @@
+import type { FraComponents } from './nra.js';
+/**
+ * Retirement benefit as a fraction of PIA for claiming at **completed** age
+ * `claimAgeYears` (62–70), vs FRA. Uses SSA monthly reduction / delayed credit rules
+ * (same formula for all NRAs once expressed in months early / late).
+ *
+ * @see https://www.ssa.gov/benefits/retirement/planner/agereduction.html
+ */
+/** Months before FRA: first 36 at 5/9% per month, beyond 36 at 5/12% per month. */
+export declare function earlyRetirementFactor(monthsBeforeFra: number): number;
+/** DRC: 2/3% of PIA per month after FRA, up to age 70 (no further increase). */
+export declare function delayedRetirementFactor(monthsAfterFra: number, maxMonthsAfterFraToAge70: number): number;
+export declare function retirementBenefitPiaFactor(claimAgeYears: number, fra: FraComponents): number;

package/dist/socialSecurity/benefitFactor.js

@@ -0,0 +1,40 @@
+import { fraTotalMonths, ageToTotalMonths } from './nra.js';
+/**
+ * Retirement benefit as a fraction of PIA for claiming at **completed** age
+ * `claimAgeYears` (62–70), vs FRA. Uses SSA monthly reduction / delayed credit rules
+ * (same formula for all NRAs once expressed in months early / late).
+ *
+ * @see https://www.ssa.gov/benefits/retirement/planner/agereduction.html
+ */
+/** Months before FRA: first 36 at 5/9% per month, beyond 36 at 5/12% per month. */
+export function earlyRetirementFactor(monthsBeforeFra) {
+    if (monthsBeforeFra <= 0)
+        return 1;
+    const m = monthsBeforeFra;
+    const first = Math.min(36, m);
+    const second = Math.max(0, m - 36);
+    const reductionPct = first * (5 / 9) + second * (5 / 12);
+    return 1 - reductionPct / 100;
+}
+/** DRC: 2/3% of PIA per month after FRA, up to age 70 (no further increase). */
+export function delayedRetirementFactor(monthsAfterFra, maxMonthsAfterFraToAge70) {
+    if (monthsAfterFra <= 0)
+        return 1;
+    const d = Math.min(monthsAfterFra, Math.max(0, maxMonthsAfterFraToAge70));
+    return 1 + (d * (2 / 3)) / 100;
+}
+export function retirementBenefitPiaFactor(claimAgeYears, fra) {
+    if (claimAgeYears < 62 || claimAgeYears > 70) {
+        throw new RangeError('claimAgeYears must be between 62 and 70 inclusive');
+    }
+    const claimM = ageToTotalMonths(claimAgeYears);
+    const fraM = fraTotalMonths(fra);
+    const maxDrcMonths = Math.max(0, ageToTotalMonths(70) - fraM);
+    if (claimM < fraM) {
+        return earlyRetirementFactor(fraM - claimM);
+    }
+    if (claimM > fraM) {
+        return delayedRetirementFactor(claimM - fraM, maxDrcMonths);
+    }
+    return 1;
+}

package/dist/socialSecurity/claimFactor.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Monthly-granularity claiming factor for the v2 engine.
+ *
+ * Reuses the FRA schedule and reduction/credit math in this directory, which
+ * already works in months — v1 only ever called it with whole-year claim
+ * ages. The projection engine (engine/projection/simulate.ts) imports this
+ * module directly; it must stay pure (no UI, storage, or DOM access).
+ */
+export interface ClaimAge {
+    years: number;
+    months: number;
+}
+/**
+ * Retirement benefit as a fraction of PIA for claiming at `claimAge`
+ * (62y0m–70y0m), for a person born on the given date.
+ */
+export declare function claimFactor(dobYear: number, dobMonth: number, dobDay: number, claimAge: ClaimAge): number;
+/**
+ * Spousal benefit as a fraction of the worker's PIA (so the spousal benefit is
+ * this × 0.5 × workerPIA at FRA, before the reduction below).
+ *
+ * Key differences from the retirement factor: the spousal benefit earns **no
+ * delayed retirement credits** (it tops out at FRA), and the early-claim
+ * reduction schedule is steeper — 25/36 of 1% per month for the first 36
+ * months early, then 5/12 of 1% per month beyond that.
+ *
+ * Simplifications (deemed-filing era, born 1954+): assumes the worker has
+ * already filed so the spouse is eligible, and ignores the spouse's own
+ * earnings-test interaction. Returns the fraction to apply to 0.5 × workerPIA.
+ *
+ * @see https://www.ssa.gov/benefits/retirement/planner/applying7.html
+ */
+export declare function spousalBenefitFactor(dobYear: number, dobMonth: number, dobDay: number, claimAge: ClaimAge): number;

package/dist/socialSecurity/claimFactor.js

@@ -0,0 +1,58 @@
+/**
+ * Monthly-granularity claiming factor for the v2 engine.
+ *
+ * Reuses the FRA schedule and reduction/credit math in this directory, which
+ * already works in months — v1 only ever called it with whole-year claim
+ * ages. The projection engine (engine/projection/simulate.ts) imports this
+ * module directly; it must stay pure (no UI, storage, or DOM access).
+ */
+import { delayedRetirementFactor, earlyRetirementFactor } from './benefitFactor.js';
+import { effectiveBirthYear, fraForBirthYear, fraTotalMonths } from './nra.js';
+/**
+ * Retirement benefit as a fraction of PIA for claiming at `claimAge`
+ * (62y0m–70y0m), for a person born on the given date.
+ */
+export function claimFactor(dobYear, dobMonth, dobDay, claimAge) {
+    const claimM = claimAge.years * 12 + claimAge.months;
+    if (claimM < 62 * 12 || claimM > 70 * 12) {
+        throw new RangeError('claim age must be between 62y0m and 70y0m');
+    }
+    const effY = effectiveBirthYear(dobYear, dobMonth, dobDay);
+    const fraM = fraTotalMonths(fraForBirthYear(effY));
+    const maxDrcMonths = Math.max(0, 70 * 12 - fraM);
+    if (claimM < fraM)
+        return earlyRetirementFactor(fraM - claimM);
+    if (claimM > fraM)
+        return delayedRetirementFactor(claimM - fraM, maxDrcMonths);
+    return 1;
+}
+/**
+ * Spousal benefit as a fraction of the worker's PIA (so the spousal benefit is
+ * this × 0.5 × workerPIA at FRA, before the reduction below).
+ *
+ * Key differences from the retirement factor: the spousal benefit earns **no
+ * delayed retirement credits** (it tops out at FRA), and the early-claim
+ * reduction schedule is steeper — 25/36 of 1% per month for the first 36
+ * months early, then 5/12 of 1% per month beyond that.
+ *
+ * Simplifications (deemed-filing era, born 1954+): assumes the worker has
+ * already filed so the spouse is eligible, and ignores the spouse's own
+ * earnings-test interaction. Returns the fraction to apply to 0.5 × workerPIA.
+ *
+ * @see https://www.ssa.gov/benefits/retirement/planner/applying7.html
+ */
+export function spousalBenefitFactor(dobYear, dobMonth, dobDay, claimAge) {
+    const claimM = claimAge.years * 12 + claimAge.months;
+    if (claimM < 62 * 12 || claimM > 70 * 12) {
+        throw new RangeError('claim age must be between 62y0m and 70y0m');
+    }
+    const effY = effectiveBirthYear(dobYear, dobMonth, dobDay);
+    const fraM = fraTotalMonths(fraForBirthYear(effY));
+    if (claimM >= fraM)
+        return 1; // no delayed credits on spousal benefits
+    const monthsEarly = fraM - claimM;
+    const first = Math.min(36, monthsEarly);
+    const beyond = Math.max(0, monthsEarly - 36);
+    const reductionPct = first * (25 / 36) + beyond * (5 / 12);
+    return Math.max(0, 1 - reductionPct / 100);
+}

package/dist/socialSecurity/disability.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Social Security disability (SSDI) — the pure helper behind the `disability`
+ * input on a Social Security stream. Cited in DOCS/domain/domain-rules-reference.md
+ * §4 (SSDI); illustrative, not a filing tool.
+ *
+ * The defining rule: **SSDI pays the worker's full PIA with no early-retirement
+ * reduction** (unlike early *retirement* claiming), starting at a disability-onset
+ * age. At FRA it **converts to the retirement benefit at the same dollar amount**
+ * (the PIA — continuous, no jump), so the PIA persists from onset through life and
+ * the recipient earns no delayed-retirement credits (the benefit is already being
+ * paid). Pre-FRA, earnings above **Substantial Gainful Activity (SGA)** suspend
+ * SSDI (SSA replaces the retirement earnings test with SGA for disabled workers).
+ *
+ * Documented simplifications (out of scope for the first build): the disability
+ * freeze (excludes disability months from the AIME average), the trial-work
+ * period / extended Medicare / expedited reinstatement, and auxiliary/family
+ * benefits on SSDI. The planner uses the PIA the user entered or derived from
+ * earnings (the freeze is not recomputed).
+ */
+/** SSDI monthly benefit = the worker's full PIA (no early-retirement reduction). */
+export declare function ssdiMonthlyBenefit(piaMonthly: number): number;
+/** Annual-approximation months used to convert the monthly SGA limit to a year. */
+export declare const SGA_ANNUAL_MONTHS = 12;
+/**
+ * SGA gate (annual approximation): wages above SGA × 12 suspend SSDI for the
+ * year. The monthly SGA limit comes from the parameter pack
+ * (`socialSecurity.sgaMonthlyNonBlind`); `annualSgaLimit` is that value scaled
+ * to a year (×12 × inflation growth, supplied by the caller).
+ */
+export declare function ssdiSuspendedBySga(annualWages: number, annualSgaLimit: number): boolean;
+/**
+ * Whether a person is in the SSDI window (onset ≤ age < FRA). Pre-FRA, SSDI
+ * applies and SGA (not the retirement earnings test) gates it. At/after FRA the
+ * benefit has converted to retirement (still the PIA) and no earnings test applies.
+ */
+export declare function inSsdiWindow(ageAttained: number, onsetAge: number, fraYears: number): boolean;

package/dist/socialSecurity/disability.js

@@ -0,0 +1,42 @@
+/**
+ * Social Security disability (SSDI) — the pure helper behind the `disability`
+ * input on a Social Security stream. Cited in DOCS/domain/domain-rules-reference.md
+ * §4 (SSDI); illustrative, not a filing tool.
+ *
+ * The defining rule: **SSDI pays the worker's full PIA with no early-retirement
+ * reduction** (unlike early *retirement* claiming), starting at a disability-onset
+ * age. At FRA it **converts to the retirement benefit at the same dollar amount**
+ * (the PIA — continuous, no jump), so the PIA persists from onset through life and
+ * the recipient earns no delayed-retirement credits (the benefit is already being
+ * paid). Pre-FRA, earnings above **Substantial Gainful Activity (SGA)** suspend
+ * SSDI (SSA replaces the retirement earnings test with SGA for disabled workers).
+ *
+ * Documented simplifications (out of scope for the first build): the disability
+ * freeze (excludes disability months from the AIME average), the trial-work
+ * period / extended Medicare / expedited reinstatement, and auxiliary/family
+ * benefits on SSDI. The planner uses the PIA the user entered or derived from
+ * earnings (the freeze is not recomputed).
+ */
+/** SSDI monthly benefit = the worker's full PIA (no early-retirement reduction). */
+export function ssdiMonthlyBenefit(piaMonthly) {
+    return Math.max(0, piaMonthly);
+}
+/** Annual-approximation months used to convert the monthly SGA limit to a year. */
+export const SGA_ANNUAL_MONTHS = 12;
+/**
+ * SGA gate (annual approximation): wages above SGA × 12 suspend SSDI for the
+ * year. The monthly SGA limit comes from the parameter pack
+ * (`socialSecurity.sgaMonthlyNonBlind`); `annualSgaLimit` is that value scaled
+ * to a year (×12 × inflation growth, supplied by the caller).
+ */
+export function ssdiSuspendedBySga(annualWages, annualSgaLimit) {
+    return annualWages > annualSgaLimit;
+}
+/**
+ * Whether a person is in the SSDI window (onset ≤ age < FRA). Pre-FRA, SSDI
+ * applies and SGA (not the retirement earnings test) gates it. At/after FRA the
+ * benefit has converted to retirement (still the PIA) and no earnings test applies.
+ */
+export function inSsdiWindow(ageAttained, onsetAge, fraYears) {
+    return ageAttained >= onsetAge && ageAttained < fraYears;
+}

package/dist/socialSecurity/familyMaximum.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Retirement/survivor family maximum (MFB), using SSA's PIA-based formula.
+ *
+ * The worker's own benefit is never reduced by the family maximum; auxiliary
+ * benefits payable on that worker's record share the remaining room. RetireGolden
+ * currently models only the current-spouse auxiliary on a worker record (no child
+ * dependents), so the capping helper applies that single auxiliary conservatively.
+ *
+ * @see https://www.ssa.gov/oact/cola/familymax.html
+ */
+import type { ClaimAge } from './claimFactor.js';
+/** Year of eligibility for the retirement/survivor family maximum. */
+export declare function familyMaximumEligibilityYearFromDobParts(year: number, month: number, day: number): number;
+/**
+ * Monthly family maximum for a retirement/survivor worker record, before COLA
+ * and trust-fund haircut.
+ */
+export declare function familyMaximumMonthlyFromPia(piaMonthly: number, eligibilityYear: number): number;
+export interface AuxiliaryFamilyMaximumInput {
+    /** Worker PIA on whose record the auxiliary is paid, today's dollars. */
+    workerPiaMonthly: number;
+    /** Worker payable monthly benefit on that record, before COLA/haircut. */
+    workerActualMonthly: number;
+    /** Worker date of birth, used to pick the eligibility-year bend points. */
+    workerDob: {
+        year: number;
+        month: number;
+        day: number;
+    };
+    /** Proposed auxiliary benefit on the worker record, before COLA/haircut. */
+    auxiliaryMonthly: number;
+}
+/**
+ * Cap a single auxiliary benefit to the available room under the worker's MFB.
+ * With no child benefits modeled, this is the full current-spouse allocation.
+ */
+export declare function capAuxiliaryForFamilyMaximum(input: AuxiliaryFamilyMaximumInput): number;
+export declare function claimAgeTotalMonths(claimAge: ClaimAge): number;

package/dist/socialSecurity/familyMaximum.js

@@ -0,0 +1,48 @@
+/**
+ * Retirement/survivor family maximum (MFB), using SSA's PIA-based formula.
+ *
+ * The worker's own benefit is never reduced by the family maximum; auxiliary
+ * benefits payable on that worker's record share the remaining room. RetireGolden
+ * currently models only the current-spouse auxiliary on a worker record (no child
+ * dependents), so the capping helper applies that single auxiliary conservatively.
+ *
+ * @see https://www.ssa.gov/oact/cola/familymax.html
+ */
+import { effectiveBirthYear } from './nra.js';
+import { familyMaximumBendPointsForEligibilityYearOrLatest } from './ssaWageData.js';
+function floorToDime(value) {
+    return Math.floor(value * 10 + 1e-9) / 10;
+}
+/** Year of eligibility for the retirement/survivor family maximum. */
+export function familyMaximumEligibilityYearFromDobParts(year, month, day) {
+    return effectiveBirthYear(year, month, day) + 62;
+}
+/**
+ * Monthly family maximum for a retirement/survivor worker record, before COLA
+ * and trust-fund haircut.
+ */
+export function familyMaximumMonthlyFromPia(piaMonthly, eligibilityYear) {
+    if (piaMonthly <= 0)
+        return 0;
+    const bp = familyMaximumBendPointsForEligibilityYearOrLatest(eligibilityYear);
+    const first = Math.min(piaMonthly, bp.first);
+    const second = Math.max(0, Math.min(piaMonthly, bp.second) - bp.first);
+    const third = Math.max(0, Math.min(piaMonthly, bp.third) - bp.second);
+    const above = Math.max(0, piaMonthly - bp.third);
+    return floorToDime(first * 1.5 + second * 2.72 + third * 1.34 + above * 1.75);
+}
+/**
+ * Cap a single auxiliary benefit to the available room under the worker's MFB.
+ * With no child benefits modeled, this is the full current-spouse allocation.
+ */
+export function capAuxiliaryForFamilyMaximum(input) {
+    if (input.auxiliaryMonthly <= 0 || input.workerPiaMonthly <= 0)
+        return 0;
+    const eligibilityYear = familyMaximumEligibilityYearFromDobParts(input.workerDob.year, input.workerDob.month, input.workerDob.day);
+    const familyMaximum = familyMaximumMonthlyFromPia(input.workerPiaMonthly, eligibilityYear);
+    const roomForAuxiliaries = Math.max(0, familyMaximum - Math.max(0, input.workerActualMonthly));
+    return Math.min(input.auxiliaryMonthly, roomForAuxiliaries);
+}
+export function claimAgeTotalMonths(claimAge) {
+    return claimAge.years * 12 + claimAge.months;
+}

package/dist/socialSecurity/maritalBenefits.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Marital-history benefit menu (V7 phase 3): the divorced-spousal and survivor
+ * benefits a person can claim on a *former* spouse's record, separate from the
+ * current-spouse spousal top-up the engine already models for couples.
+ *
+ * Eligibility rules (from the gap analysis):
+ *  - Divorced-spousal: marriage lasted ≥10 years, the claimant is currently
+ *    unmarried, and the ex is eligible (≥62) — the ex need not have filed. Worth
+ *    up to 50% of the ex's PIA, reduced for the claimant's own (early) claim age,
+ *    with no delayed credits (same factor as current-spousal).
+ *  - Survivor: marriage lasted ≥9 months, the claimant is ≥60, and remarriage
+ *    rules are satisfied (remarrying before 60 forfeits it; at/after 60 preserves
+ *    it). Survivor benefit is based on the deceased's actual benefit, with the
+ *    early-claim widow(er) reduction and the RIB-LIM widow's-limit cap applied by
+ *    the shared `survivorBenefitMonthly` helper (cited in domain rules §4).
+ *
+ * Simplifications (spec §6): survivor is modeled at the claimant's own claim age
+ * (the ledger doesn't model separate survivor-vs-own claim ages here — that
+ * sequencing lives in the actuarial `survivorSwitching` view); the
+ * 2-years-since-divorce "independently entitled" rule for divorced-spousal on a
+ * living ex is ignored (rarely binds in planning). Here a person receives the
+ * larger of own vs the best marital benefit at their single claim age.
+ */
+import type { FormerSpouse } from '../model/plan.js';
+import { type ClaimAge } from './claimFactor.js';
+export declare const DIVORCED_MIN_MARRIAGE_YEARS = 10;
+export declare const SURVIVOR_MIN_MARRIAGE_YEARS = 0.75;
+export declare const SURVIVOR_MIN_AGE = 60;
+export declare const DIVORCED_EX_MIN_AGE = 62;
+export declare const REMARRIAGE_SURVIVOR_PRESERVE_AGE = 60;
+export type MaritalBenefitKind = 'divorcedSpousal' | 'survivor';
+export interface MaritalBenefitContext {
+    claimantDob: {
+        year: number;
+        month: number;
+        day: number;
+    };
+    /** Claim age for retirement/divorced-spousal factors, including any ARF credit the caller applies. */
+    claimantClaimAge: ClaimAge;
+    /** Claim age for survivor factors; defaults to claimantClaimAge for direct helper callers. */
+    claimantSurvivorClaimAge?: ClaimAge;
+    /** Whole age the claimant has attained in the year being evaluated. */
+    claimantAge: number;
+    /** Calendar year being evaluated (to derive the ex-spouse's current age). */
+    year: number;
+    /** True when the claimant has no current spouse (single household). */
+    claimantIsSingle: boolean;
+}
+export interface MaritalBenefitCandidate {
+    kind: MaritalBenefitKind;
+    /** Monthly benefit at the claimant's claim age, today's dollars, before COLA/haircut. */
+    monthly: number;
+}
+/** Eligibility + monthly amount for one former-spouse record; null if not eligible this year. */
+export declare function maritalBenefitFor(record: FormerSpouse, ctx: MaritalBenefitContext): MaritalBenefitCandidate | null;
+/** Largest eligible monthly marital benefit across all former spouses; null if none. */
+export declare function bestMaritalBenefit(records: FormerSpouse[] | undefined, ctx: MaritalBenefitContext): MaritalBenefitCandidate | null;