@retiregolden/engine 0.1.0

package/dist/insights/types.d.ts

@@ -0,0 +1,70 @@
+import type { Plan } from '../model/plan.js';
+import type { ProjectionResult } from '../projection/types.js';
+import type { ProjectionSummary } from '../projection/compare.js';
+import type { ParameterPack } from '../params/types.js';
+export type InsightCategory = 'tax-brackets' | 'accounts-contributions' | 'withdrawals-charitable' | 'sequence-risk' | 'social-security' | 'longevity-insurance-geography';
+export type InsightActionKind = 'advisory' | 'preview-scenario' | 'apply-toggle';
+export interface InsightImpact {
+    /** Rough (screen) or exact (evaluate) change in ending after-tax estate, today's $. */
+    endingAfterTaxEstateDelta?: number;
+    /** Change in lifetime taxes & penalties, today's $ (negative = savings). */
+    lifetimeTaxDelta?: number;
+    /** Change in Monte Carlo success rate, percentage points. */
+    successRateDeltaPct?: number;
+    /** Free-form for advisory levers that can't produce a clean delta yet. */
+    qualitative?: string;
+}
+export interface InsightCard {
+    id: string;
+    category: InsightCategory;
+    title: string;
+    rationale: string;
+    impact: InsightImpact;
+    exact: boolean;
+    confidence: 'high' | 'medium' | 'low';
+    learnSlug?: string;
+    plannerRoute?: string;
+    action: InsightAction;
+}
+export type InsightAction = {
+    kind: 'advisory';
+} | {
+    kind: 'preview-scenario';
+    scenarioName: string;
+    patch: Record<string, unknown>;
+} | {
+    kind: 'apply-toggle';
+    patch: Record<string, unknown>;
+};
+export interface DetectorProjection {
+    result: ProjectionResult;
+    summary: ProjectionSummary;
+    startYear: number;
+    deflate: (year: number, amount: number) => number;
+}
+export interface DetectorContext {
+    plan: Plan;
+    projection: DetectorProjection;
+    params: ParameterPack;
+}
+export interface Detector {
+    id: string;
+    category: InsightCategory;
+    /**
+     * Cheap, synchronous, pure. Reads the baseline projection only — NO new
+     * simulate() calls. Returns null when the lever doesn't apply to this plan,
+     * or a card with a ROUGH impact estimate (exact:false). Must be fast enough
+     * to run all detectors on every committed edit.
+     */
+    screen(ctx: DetectorContext): InsightCard | null;
+    /**
+     * On-demand exact evaluation (only when a card is expanded or previewed).
+     * For preview-scenario detectors this builds the patch and the caller runs
+     * compareScenarios; this returns the patch + scenario name. Advisory
+     * detectors may omit evaluate() entirely.
+     */
+    evaluate?(ctx: DetectorContext): {
+        action: InsightAction;
+        impact?: InsightImpact;
+    };
+}

package/dist/insights/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ladder/bridge.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Social Security bridge sizing (social-security-bridge-and-tips-ladder,
+ * step 3). The canonical fix for the early-claiming problem (Bipartisan
+ * Policy Center, July 2025): instead of claiming at 62, pay yourself the
+ * forgone age-62 benefit from a dedicated bridge account until the chosen
+ * (usually later, often 70) claim age — buying the delayed benefit's
+ * longevity insurance without a lifestyle gap.
+ *
+ * Pure sizing math: the plan artifact itself is a TIPS ladder
+ * (plan.incomeFloor) covering the bridge window; the ledger prices its cash
+ * flows and taxes like any other ladder.
+ */
+import type { RealYieldCurve } from '../params/types.js';
+import { type ClaimAge } from '../socialSecurity/claimFactor.js';
+/**
+ * Minimum share of the quoted ladder cost the funding account must hold
+ * before a bridge is proposed. One threshold shared by the `ss-bridge-gap`
+ * Insights detector and `bridgeLadderGenerator`, so a household never gets a
+ * decision candidate without the matching Insights card (or vice versa) —
+ * the "can you fund this?" story stays consistent across surfaces.
+ */
+export declare const BRIDGE_FUNDING_MIN_FRACTION = 0.5;
+export interface BridgeSizingInput {
+    /** Worker's PIA, monthly, today's dollars. */
+    piaMonthly: number;
+    dob: {
+        year: number;
+        month: number;
+        day: number;
+    };
+    /** The chosen (or optimized) claim age the bridge funds the wait for. */
+    claimAge: ClaimAge;
+    /** Calendar year the projection starts ("today"). */
+    currentYear: number;
+    /**
+     * Calendar year retirement-phase spending begins (wages stop). The bridge
+     * never starts before age 62 — before that there is no forgone benefit to
+     * replace — nor before next year (this year's income is already set).
+     */
+    retirementYear: number;
+    curve: RealYieldCurve;
+}
+export interface BridgeSizing {
+    /** Forgone age-62 benefit: monthly, today's dollars. */
+    monthlyAge62Benefit: number;
+    /** The bridge's level real payout — the annualized age-62 benefit. */
+    annualRealAmount: number;
+    /** First calendar year the bridge pays. */
+    startYear: number;
+    /**
+     * Last calendar year the bridge pays: the year before the claim starts, or
+     * the claim year itself for a mid-year claim (months > 0) — the ledger pays
+     * only the post-claim months of SS that year, so ending the bridge a year
+     * earlier would leave the pre-claim months unfunded. Bridging the whole
+     * claim year is the conservative planning-grade resolution (the bridge and
+     * the new benefit overlap for the post-claim months).
+     */
+    endYear: number;
+    years: number;
+    /**
+     * Quoted TIPS-ladder cost (today's $) on the curve, anchored to a purchase
+     * THIS year — matching how the SS Optimizer panel, the detector, and the
+     * generator all buy the ladder (purchase.year = current year), which is the
+     * ledger's anchor for the same rungs.
+     */
+    ladderCost: number;
+}
+/**
+ * Size the bridge for one claimant, or null when there is no gap to fund
+ * (claiming at/before 62, or the claim starts before any bridge year could).
+ */
+export declare function sizeBridge(input: BridgeSizingInput): BridgeSizing | null;

package/dist/ladder/bridge.js

@@ -0,0 +1,59 @@
+/**
+ * Social Security bridge sizing (social-security-bridge-and-tips-ladder,
+ * step 3). The canonical fix for the early-claiming problem (Bipartisan
+ * Policy Center, July 2025): instead of claiming at 62, pay yourself the
+ * forgone age-62 benefit from a dedicated bridge account until the chosen
+ * (usually later, often 70) claim age — buying the delayed benefit's
+ * longevity insurance without a lifestyle gap.
+ *
+ * Pure sizing math: the plan artifact itself is a TIPS ladder
+ * (plan.incomeFloor) covering the bridge window; the ledger prices its cash
+ * flows and taxes like any other ladder.
+ */
+import { claimFactor } from '../socialSecurity/claimFactor.js';
+import { buildLadder } from './ladderMath.js';
+/**
+ * Minimum share of the quoted ladder cost the funding account must hold
+ * before a bridge is proposed. One threshold shared by the `ss-bridge-gap`
+ * Insights detector and `bridgeLadderGenerator`, so a household never gets a
+ * decision candidate without the matching Insights card (or vice versa) —
+ * the "can you fund this?" story stays consistent across surfaces.
+ */
+export const BRIDGE_FUNDING_MIN_FRACTION = 0.5;
+/**
+ * Size the bridge for one claimant, or null when there is no gap to fund
+ * (claiming at/before 62, or the claim starts before any bridge year could).
+ */
+export function sizeBridge(input) {
+    const { piaMonthly, dob, claimAge, currentYear, curve } = input;
+    if (piaMonthly <= 0)
+        return null;
+    const claimYears = claimAge.years + claimAge.months / 12;
+    if (claimYears <= 62)
+        return null;
+    const age62Year = dob.year + 62;
+    const claimYear = dob.year + Math.floor(claimYears);
+    const startYear = Math.max(input.retirementYear, age62Year, currentYear + 1);
+    // A mid-year claim (months > 0) pays SS only from the claim month on, so the
+    // claim year itself is bridged too (see BridgeSizing.endYear).
+    const endYear = claimAge.months > 0 ? claimYear : claimYear - 1;
+    if (endYear < startYear)
+        return null;
+    const monthlyAge62Benefit = piaMonthly * claimFactor(dob.year, dob.month, dob.day, { years: 62, months: 0 });
+    const annualRealAmount = monthlyAge62Benefit * 12;
+    const years = endYear - startYear + 1;
+    const build = buildLadder({
+        annualRealIncome: annualRealAmount,
+        firstPayoutOffset: startYear - currentYear,
+        payoutYears: years,
+        curve,
+    });
+    return {
+        monthlyAge62Benefit,
+        annualRealAmount,
+        startYear,
+        endYear,
+        years,
+        ladderCost: build.totalCost,
+    };
+}

package/dist/ladder/fedInvest.d.ts

@@ -0,0 +1,55 @@
+/**
+ * FedInvest TIPS price data — the pure half (CSV parsing, price-date math,
+ * rung matching). See social-security-bridge-and-tips-ladder, step 5.
+ *
+ * The engine performs no IO: the actual fetch against the FedInvest service
+ * and the per-day localStorage cache live in the consuming app (the web
+ * app's `src/data/fedInvestClient.ts`), which hands CSV text to
+ * {@link parseFedInvestCsv} and assembles {@link FedInvestSnapshot} values.
+ * The embedded real-yield curve always remains the planning source of truth
+ * — FedInvest prices are an opt-in, user-triggered reference only.
+ *
+ * Data: FedInvest publishes end-of-day prices per $100 face for every
+ * marketable Treasury, including TIPS, keyed by CUSIP (CSV columns: cusip,
+ * security type, rate as a decimal fraction, maturity date, call date, buy,
+ * sell, end-of-day). We surface the TIPS rows as a reference against the
+ * embedded-curve quote. (Planning note: TIPS trade with a separate inflation
+ * index ratio FedInvest does not include, so these prices sanity-check the
+ * quote rather than replace it.)
+ */
+export interface FedInvestTips {
+    cusip: string;
+    /** Coupon rate, percent. */
+    ratePct: number;
+    /** Maturity date, ISO YYYY-MM-DD. */
+    maturityIso: string;
+    /** End-of-day price per $100 face. */
+    endOfDayPrice: number;
+}
+export interface FedInvestSnapshot {
+    /**
+     * Price date the quotes are for (ISO). null for imported files: the
+     * FedInvest CSV does not carry its own date, so we never guess one — the
+     * prices are "as of whenever the user downloaded the file".
+     */
+    priceDateIso: string | null;
+    /** When the fetch/import happened (ISO timestamp). */
+    fetchedAtIso: string;
+    /** 'fetch' = direct FedInvest request; 'import' = user-supplied CSV file. */
+    source: 'fetch' | 'import';
+    tips: FedInvestTips[];
+}
+export declare const FEDINVEST_PAGE_URL = "https://www.treasurydirect.gov/GA-FI/FedInvest/selectSecurityPriceDate";
+export declare const FEDINVEST_CSV_URL = "https://www.treasurydirect.gov/GA-FI/FedInvest/securityPriceDetail";
+/** Most recent likely-published business day (prices publish evenings, US). */
+export declare function latestPriceDate(now?: Date): Date;
+/** Same as {@link latestPriceDate}, as the ISO string used by snapshots and staleness checks. */
+export declare function latestPriceDateIso(now?: Date): string;
+/**
+ * Parse the FedInvest `securityprice.csv` payload: one row per security,
+ * `cusip,type,rate,maturity(MM/DD/YYYY),call,buy,sell,endOfDay`, no header.
+ * Rates arrive as decimal fractions (0.00125 = 0.125%).
+ */
+export declare function parseFedInvestCsv(text: string): FedInvestTips[];
+/** The TIPS whose maturity falls nearest a target calendar year (for rung reference rows). */
+export declare function nearestTipsForYear(tips: FedInvestTips[], year: number): FedInvestTips | null;

package/dist/ladder/fedInvest.js

@@ -0,0 +1,77 @@
+/**
+ * FedInvest TIPS price data — the pure half (CSV parsing, price-date math,
+ * rung matching). See social-security-bridge-and-tips-ladder, step 5.
+ *
+ * The engine performs no IO: the actual fetch against the FedInvest service
+ * and the per-day localStorage cache live in the consuming app (the web
+ * app's `src/data/fedInvestClient.ts`), which hands CSV text to
+ * {@link parseFedInvestCsv} and assembles {@link FedInvestSnapshot} values.
+ * The embedded real-yield curve always remains the planning source of truth
+ * — FedInvest prices are an opt-in, user-triggered reference only.
+ *
+ * Data: FedInvest publishes end-of-day prices per $100 face for every
+ * marketable Treasury, including TIPS, keyed by CUSIP (CSV columns: cusip,
+ * security type, rate as a decimal fraction, maturity date, call date, buy,
+ * sell, end-of-day). We surface the TIPS rows as a reference against the
+ * embedded-curve quote. (Planning note: TIPS trade with a separate inflation
+ * index ratio FedInvest does not include, so these prices sanity-check the
+ * quote rather than replace it.)
+ */
+export const FEDINVEST_PAGE_URL = 'https://www.treasurydirect.gov/GA-FI/FedInvest/selectSecurityPriceDate';
+export const FEDINVEST_CSV_URL = 'https://www.treasurydirect.gov/GA-FI/FedInvest/securityPriceDetail';
+/** Most recent likely-published business day (prices publish evenings, US). */
+export function latestPriceDate(now = new Date()) {
+    const d = new Date(now);
+    d.setDate(d.getDate() - 1); // yesterday: today's prices aren't out yet
+    while (d.getDay() === 0 || d.getDay() === 6)
+        d.setDate(d.getDate() - 1);
+    return d;
+}
+/**
+ * Local calendar date as YYYY-MM-DD. The business-day walk and the FedInvest
+ * form body both use LOCAL date components, so the snapshot/cache key must
+ * too — `toISOString()` is UTC and disagrees near timezone boundaries.
+ */
+function localIsoDate(d) {
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+/** Same as {@link latestPriceDate}, as the ISO string used by snapshots and staleness checks. */
+export function latestPriceDateIso(now = new Date()) {
+    return localIsoDate(latestPriceDate(now));
+}
+/**
+ * Parse the FedInvest `securityprice.csv` payload: one row per security,
+ * `cusip,type,rate,maturity(MM/DD/YYYY),call,buy,sell,endOfDay`, no header.
+ * Rates arrive as decimal fractions (0.00125 = 0.125%).
+ */
+export function parseFedInvestCsv(text) {
+    const tips = [];
+    for (const line of text.split(/\r?\n/)) {
+        const cells = line.split(',').map((c) => c.trim().replace(/^"|"$/g, ''));
+        if (cells.length < 8)
+            continue;
+        const [cusip, type, rate, maturity, , , , endOfDay] = cells;
+        if (!cusip || type !== 'TIPS')
+            continue;
+        const rateFraction = Number(rate);
+        const endOfDayPrice = Number(endOfDay);
+        const m = /^(\d{2})\/(\d{2})\/(\d{4})$/.exec(maturity ?? '');
+        if (!m || !Number.isFinite(rateFraction) || !Number.isFinite(endOfDayPrice) || endOfDayPrice <= 0)
+            continue;
+        tips.push({ cusip, ratePct: rateFraction * 100, maturityIso: `${m[3]}-${m[1]}-${m[2]}`, endOfDayPrice });
+    }
+    return tips.sort((a, b) => a.maturityIso.localeCompare(b.maturityIso));
+}
+/** The TIPS whose maturity falls nearest a target calendar year (for rung reference rows). */
+export function nearestTipsForYear(tips, year) {
+    let best = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const t of tips) {
+        const distance = Math.abs(Number(t.maturityIso.slice(0, 4)) - year);
+        if (distance < bestDistance) {
+            best = t;
+            bestDistance = distance;
+        }
+    }
+    return best && bestDistance <= 1 ? best : null;
+}

package/dist/ladder/fundedRatio.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Funded ratio (social-security-bridge-and-tips-ladder, step 4) — Pfau's
+ * "pension accounting for households" lens: the present value of essential
+ * (required-floor) spending discounted on the TIPS curve, against the present
+ * value of the guaranteed real income dedicated to it (Social Security,
+ * pensions, annuities, TIPS-ladder flows).
+ *
+ * Both sides are read from the SAME deterministic ledger years and deflated to
+ * today's dollars, so the ratio is consistent with the projection by
+ * construction: every tax, COLA, survivor, and haircut effect the ledger
+ * models is already inside the cash flows being discounted.
+ */
+import type { RealYieldCurve } from '../params/types.js';
+import type { YearResult } from '../projection/types.js';
+export interface FundedRatioInput {
+    years: YearResult[];
+    startYear: number;
+    /** Deflator from the projection (nominal in `year` → today's $). */
+    deflate: (year: number, amount: number) => number;
+    curve: RealYieldCurve;
+    /**
+     * Count essential spending only from this year on (typically the retirement
+     * year): pre-retirement spending is funded by wages, not the floor.
+     */
+    fromYear?: number;
+}
+export interface FundedRatioResult {
+    /** PV (today's $) of required-floor spending over the horizon, on the TIPS curve. */
+    essentialSpendingPv: number;
+    /** PV (today's $) of guaranteed income: SS + pensions + annuities + ladder flows. */
+    guaranteedIncomePv: number;
+    /** guaranteedIncomePv / essentialSpendingPv × 100. */
+    fundedRatioPct: number;
+    /** PV of the floor left for the portfolio to cover: max(0, essential − guaranteed). */
+    unfundedPv: number;
+    /** First and last calendar years counted. */
+    fromYear: number;
+    toYear: number;
+}
+/** Null when there is nothing to measure (no years, or no essential spending in the window). */
+export declare function computeFundedRatio(input: FundedRatioInput): FundedRatioResult | null;

package/dist/ladder/fundedRatio.js

@@ -0,0 +1,46 @@
+/**
+ * Funded ratio (social-security-bridge-and-tips-ladder, step 4) — Pfau's
+ * "pension accounting for households" lens: the present value of essential
+ * (required-floor) spending discounted on the TIPS curve, against the present
+ * value of the guaranteed real income dedicated to it (Social Security,
+ * pensions, annuities, TIPS-ladder flows).
+ *
+ * Both sides are read from the SAME deterministic ledger years and deflated to
+ * today's dollars, so the ratio is consistent with the projection by
+ * construction: every tax, COLA, survivor, and haircut effect the ledger
+ * models is already inside the cash flows being discounted.
+ */
+import { realPresentValue } from './ladderMath.js';
+/** Null when there is nothing to measure (no years, or no essential spending in the window). */
+export function computeFundedRatio(input) {
+    const { years, startYear, deflate, curve } = input;
+    if (years.length === 0)
+        return null;
+    const fromYear = input.fromYear ?? startYear;
+    const essentialFlows = [];
+    const guaranteedFlows = [];
+    let toYear = fromYear;
+    for (const y of years) {
+        if (y.year < fromYear)
+            continue;
+        toYear = y.year;
+        const yearsFromNow = y.year - startYear;
+        essentialFlows.push({ yearsFromNow, realAmount: deflate(y.year, y.expenses.requiredSpending) });
+        guaranteedFlows.push({
+            yearsFromNow,
+            realAmount: deflate(y.year, y.incomes.socialSecurity + y.incomes.pension + y.incomes.annuity + y.incomes.tipsLadder),
+        });
+    }
+    const essentialSpendingPv = realPresentValue(essentialFlows, curve);
+    if (essentialSpendingPv <= 0)
+        return null;
+    const guaranteedIncomePv = realPresentValue(guaranteedFlows, curve);
+    return {
+        essentialSpendingPv,
+        guaranteedIncomePv,
+        fundedRatioPct: (guaranteedIncomePv / essentialSpendingPv) * 100,
+        unfundedPv: Math.max(0, essentialSpendingPv - guaranteedIncomePv),
+        fromYear,
+        toYear,
+    };
+}

package/dist/ladder/ladderMath.d.ts

@@ -0,0 +1,88 @@
+/**
+ * TIPS ladder math (social-security-bridge-and-tips-ladder, step 1).
+ *
+ * Pure functions: a target real income + payout window + real-yield curve
+ * produce a rung schedule (face amounts, coupons, cost) and per-year cash
+ * flows. Everything here is in REAL (today's) dollars — the ledger multiplies
+ * by its own inflation path, which is exactly the TIPS inflation adjustment
+ * (principal and coupons both index to CPI).
+ *
+ * Planning-grade model (documented simplifications):
+ *  - Each rung is a par TIPS: coupon rate = the interpolated par real yield at
+ *    its maturity (floored at the 0.125% statutory minimum TIPS coupon), so a
+ *    rung on a flat curve prices exactly at face.
+ *  - Rungs are priced by discounting their real cash flows on the same par
+ *    curve (par-yields-as-spot approximation, fine at planning grade).
+ *  - Coupons pay annually; real-world semiannual timing is ignored.
+ *  - No CUSIP-level lot rounding in core mode ($1 granularity); the opt-in
+ *    FedInvest mode (step 5) exists for users who want real security prices.
+ */
+import type { RealYieldCurve } from '../params/types.js';
+/** Statutory minimum TIPS coupon rate (percent). */
+export declare const MIN_TIPS_COUPON_PCT = 0.125;
+/** Interpolated par real yield (percent) at a maturity; endpoints held flat. */
+export declare function realYieldAt(curve: RealYieldCurve, maturityYears: number): number;
+export interface LadderRung {
+    /** Years from the anchor (purchase) year to maturity; >= 1. */
+    maturityOffset: number;
+    /** Real principal (today's $) returned at maturity. */
+    face: number;
+    /** Annual coupon rate (percent of inflation-adjusted principal). */
+    couponRatePct: number;
+    /** Real (today's $) purchase price of the rung. */
+    cost: number;
+}
+export interface LadderBuildInput {
+    /** Level real income (today's $) the ladder should pay each payout year. */
+    annualRealIncome: number;
+    /** Years from the anchor year to the first payout; >= 1 (1 = next year). */
+    firstPayoutOffset: number;
+    /** Number of consecutive payout years; >= 1. */
+    payoutYears: number;
+    curve: RealYieldCurve;
+}
+export interface LadderBuild {
+    rungs: LadderRung[];
+    /** Total real (today's $) purchase cost of all rungs. */
+    totalCost: number;
+    /** The input target, echoed for display. */
+    targetAnnualRealIncome: number;
+    /**
+     * Real income received in each year offset 1..lastMaturityOffset: coupons
+     * from outstanding rungs plus any maturing principal. During a deferral
+     * window (offsets before firstPayoutOffset) this is coupon income only.
+     */
+    annualRealIncomeByOffset: number[];
+}
+/**
+ * Construct a level-real-income ladder: one rung per payout year, faces solved
+ * back-to-front so that each payout year's maturing principal plus the coupons
+ * of all still-outstanding rungs equals the target income (the standard
+ * DIY/tipsladder.com construction).
+ */
+export declare function buildLadder(input: LadderBuildInput): LadderBuild;
+export interface LadderRealFlows {
+    /** Coupon income (real $) from all rungs outstanding during this year. */
+    coupons: number;
+    /** Principal (real $) of the rung maturing this year (0 in non-payout years). */
+    maturingPrincipal: number;
+    /**
+     * Total face (real $) outstanding during this year — the maturing rung
+     * included. Inflation accretion (taxable phantom income) applies to this.
+     */
+    outstandingFace: number;
+}
+/** Real cash flows of a rung set in the year at `offset` (>= 1) from the anchor. */
+export declare function ladderRealFlowsAtOffset(rungs: LadderRung[], offset: number): LadderRealFlows;
+/** Total face (real $) still outstanding AFTER the year at `offset` completes. */
+export declare function ladderRemainingFace(rungs: LadderRung[], offset: number): number;
+/**
+ * Present value (real, today's $) of a stream of real cash flows discounted on
+ * the TIPS curve — the "pension accounting" discounting behind the funded
+ * ratio: what it would cost today to defease each future real dollar with a
+ * Treasury of matching maturity.
+ */
+export declare function realPresentValue(flows: Array<{
+    yearsFromNow: number;
+    realAmount: number;
+}>, curve: RealYieldCurve): number;

package/dist/ladder/ladderMath.js

@@ -0,0 +1,140 @@
+/**
+ * TIPS ladder math (social-security-bridge-and-tips-ladder, step 1).
+ *
+ * Pure functions: a target real income + payout window + real-yield curve
+ * produce a rung schedule (face amounts, coupons, cost) and per-year cash
+ * flows. Everything here is in REAL (today's) dollars — the ledger multiplies
+ * by its own inflation path, which is exactly the TIPS inflation adjustment
+ * (principal and coupons both index to CPI).
+ *
+ * Planning-grade model (documented simplifications):
+ *  - Each rung is a par TIPS: coupon rate = the interpolated par real yield at
+ *    its maturity (floored at the 0.125% statutory minimum TIPS coupon), so a
+ *    rung on a flat curve prices exactly at face.
+ *  - Rungs are priced by discounting their real cash flows on the same par
+ *    curve (par-yields-as-spot approximation, fine at planning grade).
+ *  - Coupons pay annually; real-world semiannual timing is ignored.
+ *  - No CUSIP-level lot rounding in core mode ($1 granularity); the opt-in
+ *    FedInvest mode (step 5) exists for users who want real security prices.
+ */
+/** Statutory minimum TIPS coupon rate (percent). */
+export const MIN_TIPS_COUPON_PCT = 0.125;
+/** Interpolated par real yield (percent) at a maturity; endpoints held flat. */
+export function realYieldAt(curve, maturityYears) {
+    const points = curve.points;
+    if (points.length === 0)
+        return 0;
+    const first = points[0];
+    const last = points[points.length - 1];
+    if (maturityYears <= first.maturityYears)
+        return first.realYieldPct;
+    if (maturityYears >= last.maturityYears)
+        return last.realYieldPct;
+    for (let i = 1; i < points.length; i++) {
+        const lo = points[i - 1];
+        const hi = points[i];
+        if (maturityYears <= hi.maturityYears) {
+            const t = (maturityYears - lo.maturityYears) / (hi.maturityYears - lo.maturityYears);
+            return lo.realYieldPct + t * (hi.realYieldPct - lo.realYieldPct);
+        }
+    }
+    return last.realYieldPct;
+}
+/** Real price of one rung: its coupons + principal discounted on the curve. */
+function priceRung(face, couponRatePct, maturityOffset, curve) {
+    let price = 0;
+    for (let k = 1; k <= maturityOffset; k++) {
+        const y = realYieldAt(curve, k) / 100;
+        const coupon = face * (couponRatePct / 100);
+        const principal = k === maturityOffset ? face : 0;
+        price += (coupon + principal) / Math.pow(1 + y, k);
+    }
+    return price;
+}
+/**
+ * Construct a level-real-income ladder: one rung per payout year, faces solved
+ * back-to-front so that each payout year's maturing principal plus the coupons
+ * of all still-outstanding rungs equals the target income (the standard
+ * DIY/tipsladder.com construction).
+ */
+export function buildLadder(input) {
+    const { annualRealIncome, curve } = input;
+    const firstPayoutOffset = Math.max(1, Math.round(input.firstPayoutOffset));
+    const payoutYears = Math.max(1, Math.round(input.payoutYears));
+    const lastOffset = firstPayoutOffset + payoutYears - 1;
+    const offsets = [];
+    for (let m = firstPayoutOffset; m <= lastOffset; m++)
+        offsets.push(m);
+    const couponRate = (m) => Math.max(MIN_TIPS_COUPON_PCT, realYieldAt(curve, m)) / 100;
+    // Back-substitution: the last rung funds its year alone; earlier rungs fund
+    // the target net of the coupons every later (still-outstanding) rung pays.
+    const faces = new Map();
+    for (let i = offsets.length - 1; i >= 0; i--) {
+        const m = offsets[i];
+        let laterCoupons = 0;
+        for (let j = i + 1; j < offsets.length; j++) {
+            const later = offsets[j];
+            laterCoupons += (faces.get(later) ?? 0) * couponRate(later);
+        }
+        faces.set(m, Math.max(0, (annualRealIncome - laterCoupons) / (1 + couponRate(m))));
+    }
+    const rungs = offsets.map((m) => {
+        const face = faces.get(m) ?? 0;
+        const couponRatePct = Math.max(MIN_TIPS_COUPON_PCT, realYieldAt(curve, m));
+        return { maturityOffset: m, face, couponRatePct, cost: priceRung(face, couponRatePct, m, curve) };
+    });
+    const annualRealIncomeByOffset = [];
+    for (let offset = 1; offset <= lastOffset; offset++) {
+        const flow = ladderRealFlowsAtOffset(rungs, offset);
+        annualRealIncomeByOffset.push(flow.coupons + flow.maturingPrincipal);
+    }
+    return {
+        rungs,
+        totalCost: rungs.reduce((sum, r) => sum + r.cost, 0),
+        targetAnnualRealIncome: annualRealIncome,
+        annualRealIncomeByOffset,
+    };
+}
+/** Real cash flows of a rung set in the year at `offset` (>= 1) from the anchor. */
+export function ladderRealFlowsAtOffset(rungs, offset) {
+    let coupons = 0;
+    let maturingPrincipal = 0;
+    let outstandingFace = 0;
+    for (const rung of rungs) {
+        if (rung.maturityOffset < offset)
+            continue;
+        outstandingFace += rung.face;
+        coupons += rung.face * (rung.couponRatePct / 100);
+        if (rung.maturityOffset === offset)
+            maturingPrincipal += rung.face;
+    }
+    return { coupons, maturingPrincipal, outstandingFace };
+}
+/** Total face (real $) still outstanding AFTER the year at `offset` completes. */
+export function ladderRemainingFace(rungs, offset) {
+    let face = 0;
+    for (const rung of rungs)
+        if (rung.maturityOffset > offset)
+            face += rung.face;
+    return face;
+}
+/**
+ * Present value (real, today's $) of a stream of real cash flows discounted on
+ * the TIPS curve — the "pension accounting" discounting behind the funded
+ * ratio: what it would cost today to defease each future real dollar with a
+ * Treasury of matching maturity.
+ */
+export function realPresentValue(flows, curve) {
+    let pv = 0;
+    for (const flow of flows) {
+        if (flow.yearsFromNow < 0 || flow.realAmount === 0)
+            continue;
+        if (flow.yearsFromNow === 0) {
+            pv += flow.realAmount;
+            continue;
+        }
+        const y = realYieldAt(curve, flow.yearsFromNow) / 100;
+        pv += flow.realAmount / Math.pow(1 + y, flow.yearsFromNow);
+    }
+    return pv;
+}

package/dist/longevity/ssaPeriod2022.d.ts

@@ -0,0 +1,10 @@
+import type { Sex } from './types.js';
+/**
+ * Period life expectancy e(x) — **remaining years** at exact integer age x.
+ * Source: SSA Table 4C6, 2022 (2025 TR), male/female columns.
+ * @see https://www.ssa.gov/oact/STATS/table4c6.html
+ */
+export declare const MALE: readonly number[];
+export declare const FEMALE: readonly number[];
+/** SSA baseline: remaining years at integer age (linear between ages if fractional). */
+export declare function baselineRemainingYears(age: number, sex: Sex): number;