@retiregolden/engine 0.1.0

package/dist/socialSecurity/maritalBenefits.js

@@ -0,0 +1,87 @@
+/**
+ * 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 { claimFactor, spousalBenefitFactor } from './claimFactor.js';
+import { effectiveBirthYear, fraForBirthYear, fraTotalMonths, survivorFraForBirthYear } from './nra.js';
+import { survivorBenefitMonthly } from './survivorBenefit.js';
+export const DIVORCED_MIN_MARRIAGE_YEARS = 10;
+export const SURVIVOR_MIN_MARRIAGE_YEARS = 0.75; // 9 months
+export const SURVIVOR_MIN_AGE = 60;
+export const DIVORCED_EX_MIN_AGE = 62;
+export const REMARRIAGE_SURVIVOR_PRESERVE_AGE = 60;
+function birthYear(dob) {
+    return Number(dob.slice(0, 4));
+}
+/** Eligibility + monthly amount for one former-spouse record; null if not eligible this year. */
+export function maritalBenefitFor(record, ctx) {
+    // A benefit on someone else's record only starts once the claimant has claimed.
+    if (ctx.claimantAge < ctx.claimantClaimAge.years)
+        return null;
+    if (record.relationship === 'divorced') {
+        if (!ctx.claimantIsSingle)
+            return null;
+        if (record.marriageYears < DIVORCED_MIN_MARRIAGE_YEARS)
+            return null;
+        if (ctx.year - birthYear(record.dob) < DIVORCED_EX_MIN_AGE)
+            return null;
+        const factor = spousalBenefitFactor(ctx.claimantDob.year, ctx.claimantDob.month, ctx.claimantDob.day, ctx.claimantClaimAge);
+        return { kind: 'divorcedSpousal', monthly: 0.5 * record.piaMonthly * factor };
+    }
+    // Deceased former spouse → survivor.
+    if (record.marriageYears < SURVIVOR_MIN_MARRIAGE_YEARS)
+        return null;
+    if (ctx.claimantAge < SURVIVOR_MIN_AGE)
+        return null;
+    if (record.remarriedAtAge !== null && record.remarriedAtAge < REMARRIAGE_SURVIVOR_PRESERVE_AGE)
+        return null;
+    // Survivor base = the deceased ex's actual (claim-age-adjusted) benefit, with
+    // the RIB-LIM widow's-limit cap and the early-claim widow(er) reduction — both
+    // computed by the shared helper (cited in domain rules §4). The deceased's
+    // claim age defaults to "claimed at FRA" (factor 1, actual = PIA) when omitted.
+    const exDobYear = birthYear(record.dob);
+    const exDobMonth = Number(record.dob.slice(5, 7));
+    const exDobDay = Number(record.dob.slice(8, 10));
+    const exEffYear = effectiveBirthYear(exDobYear, exDobMonth, exDobDay);
+    const exFra = fraForBirthYear(exEffYear);
+    const exClaimAge = record.deceasedClaimAge ?? { years: exFra.years, months: exFra.extraMonths };
+    const deceasedActualMonthly = record.piaMonthly * claimFactor(exDobYear, exDobMonth, exDobDay, exClaimAge);
+    const claimantEffYear = effectiveBirthYear(ctx.claimantDob.year, ctx.claimantDob.month, ctx.claimantDob.day);
+    const survivorFraMonths = fraTotalMonths(survivorFraForBirthYear(claimantEffYear));
+    const monthly = survivorBenefitMonthly({
+        deceasedPiaMonthly: record.piaMonthly,
+        deceasedActualMonthly,
+        survivorClaimAge: ctx.claimantSurvivorClaimAge ?? ctx.claimantClaimAge,
+        survivorFraMonths,
+    });
+    return { kind: 'survivor', monthly };
+}
+/** Largest eligible monthly marital benefit across all former spouses; null if none. */
+export function bestMaritalBenefit(records, ctx) {
+    let best = null;
+    for (const record of records ?? []) {
+        const candidate = maritalBenefitFor(record, ctx);
+        if (candidate && (best === null || candidate.monthly > best.monthly))
+            best = candidate;
+    }
+    return best;
+}

package/dist/socialSecurity/nra.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Full retirement age (FRA) in years + months after age 65, by **year of birth**
+ * (SSA “normal retirement age” schedule). Jan 1 DOB uses prior calendar year.
+ *
+ * @see https://www.ssa.gov/benefits/retirement/planner/agereduction.html
+ */
+export declare function effectiveBirthYear(year: number, month: number, day: number): number;
+/** FRA as completed years + extra months (0, 2, …, 10) beyond those full years. */
+export interface FraComponents {
+    years: number;
+    extraMonths: number;
+}
+/**
+ * SSA NRA schedule (simplified to birth **year**; month-of-year refinements omitted).
+ * Years before 1938: treated as 65 + 0 (legacy). Years after 2025: 67 + 0 (current law; may change).
+ */
+export declare function fraForBirthYear(birthYearEffective: number): FraComponents;
+/** Total “month slots” from birth to reach FRA / claim age (approximation: 12y + extra). */
+export declare function ageToTotalMonths(ageYears: number, extraMonths?: number): number;
+export declare function fraTotalMonths(fra: FraComponents): number;
+/**
+ * Survivor (widow(er)) full retirement age — a separate, **earlier** schedule
+ * than the worker retirement FRA above: 65y0m for born ≤1945, ramping to 66y0m
+ * for 1951–56, then 66y2m→66y8m for 1957–60, topping out at **66y8m** for born
+ * 1960+ (it never reaches 67). The widow(er) early-claim reduction (up to 28.5%
+ * at 60) is measured against this FRA, not the worker FRA.
+ *
+ * @see https://www.ssa.gov/oact/ProgData/nra.html (Full Retirement Age for Survivors)
+ */
+export declare function survivorFraForBirthYear(birthYearEffective: number): FraComponents;

package/dist/socialSecurity/nra.js

@@ -0,0 +1,83 @@
+/**
+ * Full retirement age (FRA) in years + months after age 65, by **year of birth**
+ * (SSA “normal retirement age” schedule). Jan 1 DOB uses prior calendar year.
+ *
+ * @see https://www.ssa.gov/benefits/retirement/planner/agereduction.html
+ */
+export function effectiveBirthYear(year, month, day) {
+    if (month === 1 && day === 1)
+        return year - 1;
+    return year;
+}
+/**
+ * SSA NRA schedule (simplified to birth **year**; month-of-year refinements omitted).
+ * Years before 1938: treated as 65 + 0 (legacy). Years after 2025: 67 + 0 (current law; may change).
+ */
+export function fraForBirthYear(birthYearEffective) {
+    const y = birthYearEffective;
+    if (y <= 1937)
+        return { years: 65, extraMonths: 0 };
+    if (y === 1938)
+        return { years: 65, extraMonths: 2 };
+    if (y === 1939)
+        return { years: 65, extraMonths: 4 };
+    if (y === 1940)
+        return { years: 65, extraMonths: 6 };
+    if (y === 1941)
+        return { years: 65, extraMonths: 8 };
+    if (y === 1942)
+        return { years: 65, extraMonths: 10 };
+    if (y >= 1943 && y <= 1954)
+        return { years: 66, extraMonths: 0 };
+    if (y === 1955)
+        return { years: 66, extraMonths: 2 };
+    if (y === 1956)
+        return { years: 66, extraMonths: 4 };
+    if (y === 1957)
+        return { years: 66, extraMonths: 6 };
+    if (y === 1958)
+        return { years: 66, extraMonths: 8 };
+    if (y === 1959)
+        return { years: 66, extraMonths: 10 };
+    return { years: 67, extraMonths: 0 };
+}
+/** Total “month slots” from birth to reach FRA / claim age (approximation: 12y + extra). */
+export function ageToTotalMonths(ageYears, extraMonths = 0) {
+    return ageYears * 12 + extraMonths;
+}
+export function fraTotalMonths(fra) {
+    return fra.years * 12 + fra.extraMonths;
+}
+/**
+ * Survivor (widow(er)) full retirement age — a separate, **earlier** schedule
+ * than the worker retirement FRA above: 65y0m for born ≤1945, ramping to 66y0m
+ * for 1951–56, then 66y2m→66y8m for 1957–60, topping out at **66y8m** for born
+ * 1960+ (it never reaches 67). The widow(er) early-claim reduction (up to 28.5%
+ * at 60) is measured against this FRA, not the worker FRA.
+ *
+ * @see https://www.ssa.gov/oact/ProgData/nra.html (Full Retirement Age for Survivors)
+ */
+export function survivorFraForBirthYear(birthYearEffective) {
+    const y = birthYearEffective;
+    if (y <= 1945)
+        return { years: 65, extraMonths: 0 };
+    if (y === 1946)
+        return { years: 65, extraMonths: 2 };
+    if (y === 1947)
+        return { years: 65, extraMonths: 4 };
+    if (y === 1948)
+        return { years: 65, extraMonths: 6 };
+    if (y === 1949)
+        return { years: 65, extraMonths: 8 };
+    if (y === 1950)
+        return { years: 65, extraMonths: 10 };
+    if (y >= 1951 && y <= 1956)
+        return { years: 66, extraMonths: 0 };
+    if (y === 1957)
+        return { years: 66, extraMonths: 2 };
+    if (y === 1958)
+        return { years: 66, extraMonths: 4 };
+    if (y === 1959)
+        return { years: 66, extraMonths: 6 };
+    return { years: 66, extraMonths: 8 }; // born 1960+
+}

package/dist/socialSecurity/piaFromEarnings.d.ts

@@ -0,0 +1,100 @@
+/**
+ * PIA from covered earnings (retirement), using SSA wage indexing and bend points.
+ * @see https://www.ssa.gov/oact/COLA/Benefits.html
+ * @see DOCS/features/social-security.md
+ */
+export type PiaFromEarningsErrorCode = 'eligibility_before_1979' | 'missing_awi' | 'missing_bend_points' | 'no_computation_years' | 'last_earnings_year_out_of_range';
+export interface PiaFromEarningsError {
+    code: PiaFromEarningsErrorCode;
+    message: string;
+}
+export interface YearEarning {
+    year: number;
+    /** Taxed Social Security earnings for that calendar year (before wage-base cap). */
+    amount: number;
+}
+/**
+ * Optional projection of future covered earnings. Without it, every base year
+ * after `lastEarningsYear` is treated as zero — which understates the PIA for
+ * someone who is still working but will retire a few years out. With it, those
+ * years are filled at an assumed wage up to a retirement age.
+ */
+export interface EarningsProjection {
+    /** Covered earnings to assume for each projected year; null = reuse the last reported year's amount. */
+    assumedAnnualEarnings: number | null;
+    /** Project covered earnings through the worker's last full working year before this age. */
+    throughAge: number;
+}
+export interface PiaFromEarningsInput {
+    dobYear: number;
+    dobMonth: number;
+    dobDay: number;
+    /** Calendar years and covered earnings; years outside the base window are ignored. */
+    earnings: YearEarning[];
+    /** Last calendar year with covered earnings; later base years are treated as zero (unless projected). */
+    lastEarningsYear: number;
+    /** Optional: fill base years after `lastEarningsYear` with assumed earnings instead of zero. */
+    projection?: EarningsProjection | null;
+}
+export interface IndexedYearDetail {
+    year: number;
+    rawEarnings: number;
+    cappedEarnings: number;
+    indexedAnnual: number;
+    wageIndexed: boolean;
+    /** True when this year's earnings were filled in by the future-earnings projection (not reported). */
+    projected: boolean;
+}
+export interface PiaFromEarningsResult {
+    eligibilityYear: number;
+    firstBaseYear: number;
+    lastBaseYear: number;
+    indexingYearAwi: number;
+    indexedYears: IndexedYearDetail[];
+    /** After dropout / top-35 selection, in eligibility-year dollars (indexed or nominal per rules). */
+    yearsUsedInAime: number[];
+    computationYearCount: number;
+    /** How many base years were filled by the future-earnings projection. */
+    projectedYearCount: number;
+    aime: number;
+    /** Monthly PIA at full retirement age before COLA (rounded down to next lower $0.10). */
+    piaMonthly: number;
+    /**
+     * True when eligibility or some indexed earnings year is beyond published SSA tables in this app;
+     * latest bend points and/or AWI are used as a rough stand-in (SSA will apply official values later).
+     */
+    usesStandInForFutureTables: boolean;
+}
+/** Year of eligibility for retirement: calendar year worker attains age 62 (Jan 1 rule via effective birth year). */
+export declare function eligibilityYearFromDobParts(y: number, m: number, d: number): number;
+/**
+ * PIA from AIME using eligibility-year bend points (monthly formula).
+ * @see https://www.ssa.gov/oact/COLA/piaformula.html
+ */
+export declare function piaMonthlyFromAime(aime: number, eligibilityYear: number): number;
+/**
+ * Full earnings-history → AIME → PIA path for a retirement benefit illustration.
+ */
+export declare function computePiaFromEarnings(input: PiaFromEarningsInput): PiaFromEarningsResult | PiaFromEarningsError;
+export declare function isPiaFromEarningsError(x: PiaFromEarningsResult | PiaFromEarningsError): x is PiaFromEarningsError;
+/**
+ * Assemble a {@link PiaFromEarningsInput} from a person's date of birth and an
+ * earnings history, clamping `lastEarningsYear` into the AIME base window. Shared
+ * by the projection engine and the planner UI so the windowing logic lives in
+ * one place. Assumes `earnings` is non-empty (callers guard).
+ */
+export declare function piaInputFromEarnings(dobYear: number, dobMonth: number, dobDay: number, earnings: YearEarning[], projection?: EarningsProjection | null): PiaFromEarningsInput;
+/**
+ * Resolve the plan's stored earnings-projection settings into an engine
+ * {@link EarningsProjection}, defaulting `throughAge` to the person's retirement
+ * age. Returns null when no projection is configured or no age is available.
+ */
+export declare function resolveEarningsProjection(stored: {
+    assumedAnnualEarnings: number | null;
+    throughAge: number | null;
+} | null | undefined, retirementAge: number | null): EarningsProjection | null;
+/** Parse "YYYY amount" lines (whitespace-separated). */
+export declare function parseEarningsLines(text: string): {
+    rows: YearEarning[];
+    errors: string[];
+};

package/dist/socialSecurity/piaFromEarnings.js

@@ -0,0 +1,202 @@
+/**
+ * PIA from covered earnings (retirement), using SSA wage indexing and bend points.
+ * @see https://www.ssa.gov/oact/COLA/Benefits.html
+ * @see DOCS/features/social-security.md
+ */
+import { effectiveBirthYear } from './nra.js';
+import { awiForYear, awiForYearOrLatest, bendPointsForEligibilityYearOrLatest, LATEST_PIA_BEND_POINT_ELIGIBILITY_YEAR, wageBaseForYearOrLatest, } from './ssaWageData.js';
+function floorToDime(x) {
+    return Math.floor(x * 10 + 1e-9) / 10;
+}
+/** Year of eligibility for retirement: calendar year worker attains age 62 (Jan 1 rule via effective birth year). */
+export function eligibilityYearFromDobParts(y, m, d) {
+    return effectiveBirthYear(y, m, d) + 62;
+}
+/**
+ * PIA from AIME using eligibility-year bend points (monthly formula).
+ * @see https://www.ssa.gov/oact/COLA/piaformula.html
+ */
+export function piaMonthlyFromAime(aime, eligibilityYear) {
+    const bp = bendPointsForEligibilityYearOrLatest(eligibilityYear);
+    const b1 = bp.first;
+    const b2 = bp.second;
+    let pia = 0.9 * Math.min(aime, b1) +
+        0.32 * Math.max(0, Math.min(aime, b2) - b1) +
+        0.15 * Math.max(0, aime - b2);
+    pia = floorToDime(pia);
+    return pia;
+}
+function capEarnings(year, amount) {
+    // Cap at the year's taxable maximum, falling back to the latest published wage
+    // base for projected/future years SSA has not set yet (otherwise high earners'
+    // projected years would inflate AIME past the Social Security taxable maximum).
+    return Math.max(0, Math.min(amount, wageBaseForYearOrLatest(year)));
+}
+/**
+ * Full earnings-history → AIME → PIA path for a retirement benefit illustration.
+ */
+export function computePiaFromEarnings(input) {
+    const { dobYear, dobMonth, dobDay, earnings, lastEarningsYear, projection } = input;
+    const eligibilityYear = eligibilityYearFromDobParts(dobYear, dobMonth, dobDay);
+    if (eligibilityYear < 1979) {
+        return {
+            code: 'eligibility_before_1979',
+            message: 'This tool uses the modern PIA formula (1979+). For birth dates implying eligibility before 1979, enter PIA manually in quick mode.',
+        };
+    }
+    const effBirth = effectiveBirthYear(dobYear, dobMonth, dobDay);
+    const firstBaseYear = effBirth + 22;
+    const lastBaseYear = eligibilityYear - 1;
+    if (lastEarningsYear < firstBaseYear || lastEarningsYear > lastBaseYear) {
+        return {
+            code: 'last_earnings_year_out_of_range',
+            message: `Last earnings year must be between ${firstBaseYear} and ${lastBaseYear} for this date of birth.`,
+        };
+    }
+    const awiNumYear = eligibilityYear - 2;
+    let usesStandInForFutureTables = eligibilityYear > LATEST_PIA_BEND_POINT_ELIGIBILITY_YEAR;
+    if (awiForYear(awiNumYear) === undefined)
+        usesStandInForFutureTables = true;
+    if (!usesStandInForFutureTables) {
+        for (let y = firstBaseYear; y <= lastBaseYear && y <= eligibilityYear - 2; y++) {
+            if (awiForYear(y) === undefined) {
+                usesStandInForFutureTables = true;
+                break;
+            }
+        }
+    }
+    const indexingAwi = awiForYearOrLatest(awiNumYear);
+    const byYear = new Map();
+    for (const row of earnings) {
+        if (!Number.isFinite(row.year) || !Number.isFinite(row.amount))
+            continue;
+        const y = Math.trunc(row.year);
+        const prev = byYear.get(y) ?? 0;
+        byYear.set(y, prev + Math.max(0, row.amount));
+    }
+    // Future-earnings projection: fill base years after the last reported year up
+    // to the worker's last full working year before `throughAge` (effBirth + age).
+    const projectionThroughYear = projection ? effBirth + projection.throughAge - 1 : lastEarningsYear;
+    const projectedAmount = projection
+        ? (projection.assumedAnnualEarnings ?? byYear.get(lastEarningsYear) ?? 0)
+        : 0;
+    const indexedDetails = [];
+    const annualIndexedList = [];
+    let projectedYearCount = 0;
+    for (let year = firstBaseYear; year <= lastBaseYear; year++) {
+        let raw;
+        let projected = false;
+        if (year <= lastEarningsYear) {
+            raw = byYear.get(year) ?? 0;
+        }
+        else if (projection && year <= projectionThroughYear) {
+            raw = projectedAmount;
+            projected = true;
+            projectedYearCount++;
+        }
+        else {
+            raw = 0;
+        }
+        const capped = capEarnings(year, raw);
+        const wageIndexed = year <= eligibilityYear - 2;
+        let indexedAnnual = capped;
+        if (wageIndexed) {
+            const awiY = awiForYearOrLatest(year);
+            indexedAnnual = Math.floor((capped * indexingAwi) / awiY);
+        }
+        indexedDetails.push({
+            year,
+            rawEarnings: raw,
+            cappedEarnings: capped,
+            indexedAnnual,
+            wageIndexed,
+            projected,
+        });
+        annualIndexedList.push(indexedAnnual);
+    }
+    annualIndexedList.sort((a, b) => a - b);
+    const afterDropout = annualIndexedList.slice(5);
+    if (afterDropout.length === 0) {
+        return {
+            code: 'no_computation_years',
+            message: 'Not enough covered earnings years in the base period after dropout (need at least one year).',
+        };
+    }
+    afterDropout.sort((a, b) => b - a);
+    const top = afterDropout.slice(0, 35);
+    const computationYearCount = Math.min(35, afterDropout.length);
+    const sumTop = top.reduce((s, v) => s + v, 0);
+    const divisorMonths = 12 * computationYearCount;
+    const aime = Math.floor(sumTop / divisorMonths);
+    const pia = piaMonthlyFromAime(aime, eligibilityYear);
+    return {
+        eligibilityYear,
+        firstBaseYear,
+        lastBaseYear,
+        indexingYearAwi: indexingAwi,
+        indexedYears: indexedDetails,
+        yearsUsedInAime: top,
+        computationYearCount,
+        projectedYearCount,
+        aime,
+        piaMonthly: pia,
+        usesStandInForFutureTables,
+    };
+}
+export function isPiaFromEarningsError(x) {
+    return 'code' in x;
+}
+/**
+ * Assemble a {@link PiaFromEarningsInput} from a person's date of birth and an
+ * earnings history, clamping `lastEarningsYear` into the AIME base window. Shared
+ * by the projection engine and the planner UI so the windowing logic lives in
+ * one place. Assumes `earnings` is non-empty (callers guard).
+ */
+export function piaInputFromEarnings(dobYear, dobMonth, dobDay, earnings, projection) {
+    const effBirth = effectiveBirthYear(dobYear, dobMonth, dobDay);
+    const firstBaseYear = effBirth + 22;
+    const lastBaseYear = effBirth + 61;
+    const lastEarningsYear = Math.min(Math.max(...earnings.map((e) => e.year), firstBaseYear), lastBaseYear);
+    return { dobYear, dobMonth, dobDay, earnings, lastEarningsYear, projection: projection ?? null };
+}
+/**
+ * Resolve the plan's stored earnings-projection settings into an engine
+ * {@link EarningsProjection}, defaulting `throughAge` to the person's retirement
+ * age. Returns null when no projection is configured or no age is available.
+ */
+export function resolveEarningsProjection(stored, retirementAge) {
+    if (!stored)
+        return null;
+    const throughAge = stored.throughAge ?? retirementAge;
+    if (throughAge === null)
+        return null;
+    return { assumedAnnualEarnings: stored.assumedAnnualEarnings, throughAge };
+}
+/** Parse "YYYY amount" lines (whitespace-separated). */
+export function parseEarningsLines(text) {
+    const rows = [];
+    const errors = [];
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const parts = line.split(/[\s,]+/).filter(Boolean);
+        if (parts.length < 2) {
+            errors.push(`Line ${i + 1}: need year and amount (e.g. "1995 42000").`);
+            continue;
+        }
+        const y = Number.parseInt(parts[0], 10);
+        const amt = Number.parseFloat(parts[1]);
+        if (!Number.isFinite(y) || y < 1951 || y > 2100) {
+            errors.push(`Line ${i + 1}: invalid year.`);
+            continue;
+        }
+        if (!Number.isFinite(amt) || amt < 0) {
+            errors.push(`Line ${i + 1}: invalid amount.`);
+            continue;
+        }
+        rows.push({ year: y, amount: amt });
+    }
+    return { rows, errors };
+}

package/dist/socialSecurity/ssaWageData.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Official SSA series for wage indexing, bend points, family maximum bend
+ * points, and taxable maximum.
+ * @see https://www.ssa.gov/oact/COLA/awiseries.html
+ * @see https://www.ssa.gov/oact/COLA/bendpoints.html
+ * @see https://www.ssa.gov/oact/COLA/cbb.html
+ */
+/** National average wage index (AWI), dollars. */
+export declare const AWI_BY_YEAR: Readonly<Record<number, number>>;
+/** PIA formula bend points by year of eligibility (attain age 62 / disability / death). */
+export declare const PIA_BEND_POINTS: Readonly<Record<number, {
+    first: number;
+    second: number;
+}>>;
+/** Retirement/survivor family-maximum formula bend points by year of eligibility. */
+export declare const FAMILY_MAXIMUM_BEND_POINTS: Readonly<Record<number, {
+    first: number;
+    second: number;
+    third: number;
+}>>;
+/** OASDI contribution & benefit base (taxable maximum), dollars. */
+export declare const WAGE_BASE_BY_YEAR: Readonly<Record<number, number>>;
+/** Latest calendar year for which `AWI_BY_YEAR` has an official value. */
+export declare const LATEST_PUBLISHED_AWI_YEAR: number;
+/** Latest eligibility year for which `PIA_BEND_POINTS` has an official pair. */
+export declare const LATEST_PIA_BEND_POINT_ELIGIBILITY_YEAR: number;
+/** Latest eligibility year for which `FAMILY_MAXIMUM_BEND_POINTS` has an official triplet. */
+export declare const LATEST_FAMILY_MAXIMUM_BEND_POINT_ELIGIBILITY_YEAR: number;
+/** Latest calendar year for which `WAGE_BASE_BY_YEAR` has an official taxable maximum. */
+export declare const LATEST_PUBLISHED_WAGE_BASE_YEAR: number;
+export declare function awiForYear(year: number): number | undefined;
+/**
+ * Published AWI, or the latest on file when the year is not yet released (illustrative only).
+ */
+export declare function awiForYearOrLatest(year: number): number;
+export declare function bendPointsForEligibilityYear(year: number): {
+    first: number;
+    second: number;
+} | undefined;
+/**
+ * Official bend points for that eligibility year, or the latest on file when SSA has not yet
+ * published figures (illustrative only).
+ */
+export declare function bendPointsForEligibilityYearOrLatest(eligibilityYear: number): {
+    first: number;
+    second: number;
+};
+export declare function familyMaximumBendPointsForEligibilityYear(year: number): {
+    first: number;
+    second: number;
+    third: number;
+} | undefined;
+/**
+ * Official family-maximum bend points for that eligibility year, or the latest
+ * on file when SSA has not yet published figures (illustrative only).
+ */
+export declare function familyMaximumBendPointsForEligibilityYearOrLatest(eligibilityYear: number): {
+    first: number;
+    second: number;
+    third: number;
+};
+export declare function wageBaseForYear(year: number): number | undefined;
+/**
+ * Social Security taxable maximum (wage base) for a year, or the latest on file
+ * when SSA has not yet published it (illustrative only). Used to cap projected
+ * future earnings so they cannot exceed the taxable maximum.
+ */
+export declare function wageBaseForYearOrLatest(year: number): number;