@retiregolden/engine 0.1.0

package/dist/strategies/accountEligibility.js

@@ -0,0 +1,98 @@
+/**
+ * Account eligibility service (account/HSA/fixed-asset depth plan, step 1).
+ *
+ * One pure module answering, per account (and where relevant, per year/owner):
+ * can it accept contributions? can it be converted to Roth? does it follow the
+ * owner's own RMDs? is its balance spendable this year? and what early-
+ * withdrawal penalty rate applies? The ledger (`projection/simulate.ts`), the
+ * optimizer input builder (`projection/optimizePlan.ts`), and the decision
+ * engine (`decisions/*`) all consume these helpers, so every recommended
+ * account movement is explainable by a rule that exists in exactly one place —
+ * the roadmap §7 acceptance criterion.
+ *
+ * Rules encoded here (each documented in DOCS/domain/domain-rules-reference.md):
+ * - Inherited traditional accounts (SECURE Act 10-year rule) cannot receive
+ *   contributions, cannot be converted to Roth, are exempt from the owner's
+ *   Uniform-Lifetime RMDs (they follow their own forced-distribution schedule),
+ *   and are never subject to the 10% early-withdrawal penalty.
+ * - Cliff-vesting equity compensation is not spendable before its vest year.
+ * - Traditional withdrawals before 59½ (approximated as age < 60) carry a 10%
+ *   penalty unless the Rule of 55 applies (employer plan, separation in/after
+ *   the year the owner turned 55, approximated by the owner's retirement age).
+ *   72(t) SEPP and inherited distributions are taken outside the need-based
+ *   flow and are penalty-free by construction.
+ * - HSA non-qualified withdrawals before 65 carry a 20% penalty; from 65 on
+ *   they are penalty-free (ordinary income only).
+ */
+/** Traditional pre-59½ early-withdrawal penalty rate (age approximated annually). */
+export const TRADITIONAL_EARLY_PENALTY_RATE = 0.1;
+/** HSA non-qualified withdrawal penalty rate before age 65 (IRC §223(f)(4)). */
+export const HSA_NON_QUALIFIED_PENALTY_RATE = 0.2;
+/** Can this account receive new contributions? (Inherited accounts cannot.) */
+export function acceptsContributions(account) {
+    return !(account.type === 'traditional' && account.inherited !== undefined);
+}
+/**
+ * Can this account's balance be converted to Roth? Only an owned (non-
+ * inherited) traditional account qualifies: inherited accounts follow the
+ * 10-year rule and are never convertible by a non-spouse beneficiary.
+ */
+export function isConvertibleToRoth(account) {
+    return account.type === 'traditional' && account.inherited === undefined;
+}
+/**
+ * Does this account follow the owner's own age-based RMDs (Uniform Lifetime /
+ * Joint Life)? Inherited accounts are exempt — they follow the beneficiary
+ * 10-year schedule in `strategies/inheritedIra.ts` instead.
+ */
+export function followsOwnerRmds(account) {
+    return account.type === 'traditional' && account.inherited === undefined;
+}
+/**
+ * Does this account participate in the owner's Form-8606 IRA aggregation for
+ * the nondeductible-basis pro-rata rule? Only the owner's own traditional
+ * IRAs aggregate: employer plans track after-tax money separately, and a
+ * beneficiary's inherited IRA has its own separate Form 8606.
+ */
+export function isAggregatedIra(account) {
+    return account.type === 'traditional' && account.kind === 'ira' && account.inherited === undefined;
+}
+/** Is a cliff-vesting equity-comp account vested (available for spending) in `year`? */
+export function isEquityCompVested(account, year) {
+    if (account.vestingMode === 'final')
+        return true;
+    if (account.vestDate === null)
+        return false;
+    return Number(account.vestDate.slice(0, 4)) <= year;
+}
+/** Is this account's balance available for need-based spending withdrawals in `year`? */
+export function isSpendableInYear(account, year) {
+    if (account.type === 'equityComp')
+        return isEquityCompVested(account, year);
+    return true;
+}
+/**
+ * Penalty rate on a need-based traditional withdrawal this year: 10% before
+ * 59½ (approximated as age < 60), waived for inherited accounts (never
+ * penalized), and waived by the Rule of 55 for an EMPLOYER plan the owner
+ * separated from in/after the year they turned 55 (IRAs never qualify).
+ */
+export function traditionalWithdrawalPenaltyRate(account, ctx) {
+    if (account.inherited !== undefined)
+        return 0;
+    if (ctx.ownerAgeAttained >= 60)
+        return 0;
+    const ruleOf55 = account.kind === 'employer' &&
+        ctx.ownerRetirementAge !== null &&
+        ctx.ownerRetirementAge >= 55 &&
+        ctx.ownerAgeAttained >= ctx.ownerRetirementAge;
+    return ruleOf55 ? 0 : TRADITIONAL_EARLY_PENALTY_RATE;
+}
+/**
+ * Penalty rate on the NON-QUALIFIED portion of an HSA withdrawal this year:
+ * 20% before age 65, none after. Qualified (medical) withdrawals are never
+ * penalized; the HSA subledger decides how much of a withdrawal is qualified.
+ */
+export function hsaNonQualifiedPenaltyRate(ownerAgeAttained) {
+    return ownerAgeAttained < 65 ? HSA_NON_QUALIFIED_PENALTY_RATE : 0;
+}

package/dist/strategies/inheritedIra.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Inherited (beneficiary) IRA 10-year rule (roadmap V8, §4 tax depth).
+ *
+ * Post-SECURE-Act, a non-spouse beneficiary must empty an inherited IRA by the
+ * end of the 10th year after the original owner's death. If the owner had
+ * already reached their required beginning date (RBD) — i.e. had started RMDs —
+ * the beneficiary must ALSO take an annual RMD in years 1–9, based on their own
+ * single life expectancy ("at least as rapidly", per the 2024 final regs). If
+ * the owner died before their RBD, no annual RMD is required during the window;
+ * the only requirement is to be empty by year 10.
+ *
+ * Inherited-IRA distributions are taxable ordinary income but are NEVER subject
+ * to the 10% early-withdrawal penalty, regardless of the beneficiary's age.
+ *
+ * The single-life divisor uses the repo's SSA period table
+ * (`baselineRemainingYears`) as a documented proxy for the IRS Single Life
+ * Table, and is recomputed each year rather than using the strict subtract-one
+ * method — a small, documented simplification consistent with the SEPP module.
+ */
+import type { Sex } from '../longevity/types.js';
+/** The account must be fully distributed by the END of this year. */
+export declare function inheritedTenYearDeadline(ownerDeathYear: number): number;
+export interface InheritedForcedInput {
+    /** Current projection year. */
+    year: number;
+    /** Calendar year the original owner died. */
+    ownerDeathYear: number;
+    /** Did the decedent reach their RBD (had started RMDs)? Drives years 1–9. */
+    decedentHadStartedRmds: boolean;
+    /** Current account balance. */
+    balance: number;
+    /** Start-of-year balance, used for the annual-RMD divisor. */
+    startBalance: number;
+    /** Beneficiary's attained age this year. */
+    beneficiaryAge: number;
+    beneficiarySex: Sex;
+}
+/**
+ * The forced distribution required from an inherited IRA this year:
+ *   - the full remaining balance in (and after) the 10th year — the final sweep;
+ *   - an annual single-life RMD in years 1–9 when the decedent had started RMDs;
+ *   - otherwise 0 (the beneficiary may still withdraw voluntarily).
+ * Never exceeds the current balance.
+ */
+export declare function inheritedForcedAmount(input: InheritedForcedInput): number;

package/dist/strategies/inheritedIra.js

@@ -0,0 +1,43 @@
+/**
+ * Inherited (beneficiary) IRA 10-year rule (roadmap V8, §4 tax depth).
+ *
+ * Post-SECURE-Act, a non-spouse beneficiary must empty an inherited IRA by the
+ * end of the 10th year after the original owner's death. If the owner had
+ * already reached their required beginning date (RBD) — i.e. had started RMDs —
+ * the beneficiary must ALSO take an annual RMD in years 1–9, based on their own
+ * single life expectancy ("at least as rapidly", per the 2024 final regs). If
+ * the owner died before their RBD, no annual RMD is required during the window;
+ * the only requirement is to be empty by year 10.
+ *
+ * Inherited-IRA distributions are taxable ordinary income but are NEVER subject
+ * to the 10% early-withdrawal penalty, regardless of the beneficiary's age.
+ *
+ * The single-life divisor uses the repo's SSA period table
+ * (`baselineRemainingYears`) as a documented proxy for the IRS Single Life
+ * Table, and is recomputed each year rather than using the strict subtract-one
+ * method — a small, documented simplification consistent with the SEPP module.
+ */
+import { baselineRemainingYears } from '../longevity/ssaPeriod2022.js';
+/** The account must be fully distributed by the END of this year. */
+export function inheritedTenYearDeadline(ownerDeathYear) {
+    return ownerDeathYear + 10;
+}
+/**
+ * The forced distribution required from an inherited IRA this year:
+ *   - the full remaining balance in (and after) the 10th year — the final sweep;
+ *   - an annual single-life RMD in years 1–9 when the decedent had started RMDs;
+ *   - otherwise 0 (the beneficiary may still withdraw voluntarily).
+ * Never exceeds the current balance.
+ */
+export function inheritedForcedAmount(input) {
+    const { year, ownerDeathYear, balance } = input;
+    if (balance <= 0 || year <= ownerDeathYear)
+        return 0;
+    if (year >= inheritedTenYearDeadline(ownerDeathYear))
+        return balance; // empty it by year 10
+    if (input.decedentHadStartedRmds) {
+        const le = Math.max(1, baselineRemainingYears(input.beneficiaryAge, input.beneficiarySex));
+        return Math.min(input.startBalance / le, balance);
+    }
+    return 0;
+}

package/dist/strategies/iraBasis.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Nondeductible traditional-IRA basis and the Form 8606 pro-rata rule
+ * (account/HSA/fixed-asset depth plan, step 5).
+ *
+ * When an owner's traditional IRAs hold after-tax (nondeductible) basis, every
+ * distribution and Roth conversion from ANY of that owner's IRAs is part
+ * basis, part pre-tax — in the ratio of total basis to the total aggregated
+ * IRA balance. The taxpayer cannot choose to distribute "just the basis"
+ * (IRS Form 8606, line 6 aggregation; IRC §408(d)(2)).
+ *
+ * Planning-grade simplifications (documented in domain rules §15):
+ * - The nontaxable fraction uses basis ÷ (aggregate balance measured just
+ *   before the year's distributions), which equals the 8606 method (year-end
+ *   balance + distributions) when growth is credited after distributions —
+ *   exactly the ledger's year ordering.
+ * - Employer plans are excluded from the aggregation (only IRAs aggregate),
+ *   and inherited IRAs are excluded (a beneficiary files a separate 8606).
+ * - Basis is entered in dollars and never indexed (basis is historical cost).
+ */
+export interface IraProRataYear {
+    /** Remaining nondeductible basis in the owner's aggregated IRAs. */
+    basis: number;
+    /**
+     * Nontaxable fraction applied to this year's IRA distributions/conversions:
+     * basis ÷ aggregate pre-distribution IRA balance, in [0, 1].
+     */
+    nontaxableFraction: number;
+}
+/**
+ * Fix the year's pro-rata fraction from the owner's aggregated pre-distribution
+ * IRA balance. Zero balance with positive basis returns fraction 1 (everything
+ * distributed is basis — the balance IS the basis or less, after losses).
+ */
+export declare function openIraProRataYear(basis: number, aggregateIraBalance: number): IraProRataYear;
+export interface IraDistributionSplit {
+    /** Portion of the distribution that is return of basis (not taxed). */
+    nontaxable: number;
+    /** Portion taxed as ordinary income. */
+    taxable: number;
+    /** Year state after the distribution (basis depleted by the nontaxable part). */
+    next: IraProRataYear;
+}
+/**
+ * Split one distribution (or Roth conversion) from the owner's aggregated IRAs
+ * under the year's fixed pro-rata fraction. Nontaxable is capped at the
+ * remaining basis so repeated draws can never recover more basis than exists.
+ */
+export declare function splitIraDistribution(state: IraProRataYear, amount: number): IraDistributionSplit;

package/dist/strategies/iraBasis.js

@@ -0,0 +1,46 @@
+/**
+ * Nondeductible traditional-IRA basis and the Form 8606 pro-rata rule
+ * (account/HSA/fixed-asset depth plan, step 5).
+ *
+ * When an owner's traditional IRAs hold after-tax (nondeductible) basis, every
+ * distribution and Roth conversion from ANY of that owner's IRAs is part
+ * basis, part pre-tax — in the ratio of total basis to the total aggregated
+ * IRA balance. The taxpayer cannot choose to distribute "just the basis"
+ * (IRS Form 8606, line 6 aggregation; IRC §408(d)(2)).
+ *
+ * Planning-grade simplifications (documented in domain rules §15):
+ * - The nontaxable fraction uses basis ÷ (aggregate balance measured just
+ *   before the year's distributions), which equals the 8606 method (year-end
+ *   balance + distributions) when growth is credited after distributions —
+ *   exactly the ledger's year ordering.
+ * - Employer plans are excluded from the aggregation (only IRAs aggregate),
+ *   and inherited IRAs are excluded (a beneficiary files a separate 8606).
+ * - Basis is entered in dollars and never indexed (basis is historical cost).
+ */
+/**
+ * Fix the year's pro-rata fraction from the owner's aggregated pre-distribution
+ * IRA balance. Zero balance with positive basis returns fraction 1 (everything
+ * distributed is basis — the balance IS the basis or less, after losses).
+ */
+export function openIraProRataYear(basis, aggregateIraBalance) {
+    if (basis <= 0)
+        return { basis: Math.max(0, basis), nontaxableFraction: 0 };
+    if (aggregateIraBalance <= 0)
+        return { basis, nontaxableFraction: 1 };
+    return { basis, nontaxableFraction: Math.min(1, basis / aggregateIraBalance) };
+}
+/**
+ * Split one distribution (or Roth conversion) from the owner's aggregated IRAs
+ * under the year's fixed pro-rata fraction. Nontaxable is capped at the
+ * remaining basis so repeated draws can never recover more basis than exists.
+ */
+export function splitIraDistribution(state, amount) {
+    if (amount <= 0)
+        return { nontaxable: 0, taxable: 0, next: state };
+    const nontaxable = Math.min(state.basis, amount * state.nontaxableFraction);
+    return {
+        nontaxable,
+        taxable: amount - nontaxable,
+        next: { basis: state.basis - nontaxable, nontaxableFraction: state.nontaxableFraction },
+    };
+}

package/dist/strategies/optimizer.d.ts

@@ -0,0 +1,307 @@
+/**
+ * Multi-year withdrawal / Roth-conversion optimizer (roadmap V8, PR 1).
+ *
+ * A true multi-year optimizer — unlike the greedy per-year `sizeRothConversion`
+ * sizer, this reasons over the whole horizon at once, which is the entire point
+ * of conversion planning: convert more now (paying tax in a low bracket) to
+ * shrink later RMDs and leave more in the never-haircut Roth. It is "just
+ * another strategy provider" (V8 spec §1.3): it emits a per-year schedule that
+ * the existing `simulate` ledger consumes via the Roth-conversion `optimized`
+ * mode — it does NOT run a parallel engine.
+ *
+ * Method: a mixed-integer linear program solved client-side by HiGHS-WASM (the
+ * `highs` package), proven viable by the PR 0 spike (measurements recorded in
+ * DOCS/features/optimizer.md §"Spike findings (historical)"). The LP is a *linearised* view of the
+ * ledger; `simulate` stays the source of truth, so callers re-run the real
+ * (nonlinear) ledger with the emitted schedule for exact numbers and surface
+ * any gap (V8 §3.1).
+ *
+ * Modeled exactly (the "big levers", V8 §6):
+ *   - Graduated federal ordinary tax as a CONVEX piecewise-linear cost from the
+ *     pack's real brackets — minimising tax fills the cheap band first with no
+ *     integer variables.
+ *   - IRMAA tier surcharges as binary step thresholds (the non-convex part that
+ *     makes this a MILP, not an LP).
+ *   - RMD floors as a linear lower bound on each year's taxable distribution
+ *     (floor = start-of-year traditional balance ÷ divisor).
+ *   - Three-bucket balances (owner traditional, inherited traditional, and
+ *     "other" = Roth + taxable + cash) with per-year growth and scheduled
+ *     contribution / employer-match inflows from the baseline probe, so a
+ *     plan whose solvency depends on future deposits is not misread as
+ *     infeasible.
+ *
+ * The optimizer-exact-ledger-convergence plan (Track 1) closed the
+ * original v1 simplifications, each opt-in via `OptimizerInput` so absent
+ * fields reproduce the v1 LP byte-for-byte:
+ *   - Taxable-gain realization (Step 2): `openingTaxable`/`taxableInflow` split
+ *     the lumped bucket into a taxable brokerage bucket — whose withdrawals
+ *     realize LTCG at `ltcgRate` on the opening gain fraction and lift IRMAA
+ *     MAGI — and the tax-free Roth/cash/HSA bucket. A single LTCG rate
+ *     linearizes the 0/15/20% stack; the exact ledger refines it.
+ *   - Bracketed state tax (Step 3): `stateBrackets` adds a convex state PWL
+ *     over the same `ti` base as the federal PWL, so progressive
+ *     (non-flat-override) states are priced with real brackets rather than
+ *     zero; a flat `stateEffectiveTaxPct` override keeps the flat `stateRate`.
+ *   - Taxable-SS phase-in (Step 3): `ssTaxability` swaps the fixed taxable-SS
+ *     constant for an in-solve convex PWL over provisional income, so the
+ *     solver sees the *marginal* tax torpedo (see `taxss` constraints below).
+ *   - IRMAA 2-year lookback (Step 4): `irmaaLookback` drives each premium
+ *     year's binaries off MAGI(year−2), matching the ledger's causality.
+ *   - OBBBA senior deduction (ground-truth 2026 law sync, Step 2):
+ *     `seniorDeduction` adds the per-person 65+ deduction plus a convex
+ *     phase-out floor over MAGI, so conversions in the phase-out band are
+ *     priced at bracket rate × (1 + phase-out rate) in-solve instead of the
+ *     deduction being ignored entirely.
+ *
+ * Remaining simplifications (refined when the schedule re-runs through
+ * `simulate`, and by the exact-ledger convergence loop — Step 1, in
+ * projection/optimizePlan.ts — which recaptures the exogenous inputs at the
+ * incumbent schedule and re-solves to a fixed point): a single LTCG rate and
+ * opening basis ratio for the taxable stack, the omitted 85%-of-benefit
+ * taxable-SS cap (conservative), unscaled stand-in packs for future years
+ * (matching the ledger's convention), and state retirement-income exclusions.
+ */
+import type { FilingStatus, ParameterPack } from '../params/types.js';
+/** One plan year of exogenous inputs the optimizer treats as given. */
+export interface OptimizerYear {
+    year: number;
+    pack: ParameterPack;
+    filingStatus: FilingStatus;
+    /**
+     * Ordinary taxable income before any conversion or discretionary traditional
+     * withdrawal: wages − pre-tax contributions, pensions/annuities, the taxable
+     * portion of Social Security, etc. Nominal dollars.
+     */
+    ordinaryIncomeBase: number;
+    /** After-tax cash needed this year beyond non-withdrawal inflows. Nominal. */
+    spendingNeed: number;
+    /** Net non-withdrawal cash already in hand (e.g. surplus SS/pension). Nominal. */
+    exogenousCash: number;
+    /** Uniform-Lifetime (or joint) RMD divisor when age-eligible; null = no RMD. */
+    rmdDivisor: number | null;
+    /** Forced inherited-traditional distribution from the baseline ledger. */
+    inheritedDistribution: number;
+    /** Inherited-IRA divisor recovered from the baseline forced distribution; null = no floor. */
+    inheritedDistributionDivisor: number | null;
+    /**
+     * Number of living people 65+. Drives the age-65 standard-deduction
+     * additions (`pack65Deduction`) and, when `seniorDeduction` is enabled, the
+     * OBBBA senior-deduction eligibility and amount (`amountPerPerson × this`).
+     */
+    peopleAged65Plus: number;
+    /**
+     * Baseline forced owner-traditional distribution (the probe's RMD, nominal).
+     * Not a constraint input — the RMD floor stays `trad ÷ rmdDivisor` on the
+     * endogenous balance. Used only to locate the linearization point for
+     * saturation skips: a 65+ RMD year whose forced income already sits past the
+     * senior-deduction full phase-out must skip the phase-out PWL exactly, and
+     * `ordinaryIncomeBase` excludes forced withdrawals (the LP re-decides them
+     * as `wt`). Default 0.
+     */
+    baselineRmd?: number;
+    /** Scales IRMAA thresholds for years beyond the published pack. */
+    inflationScale: number;
+    /** Nominal growth applied to end-of-year balances this year, e.g. 0.05. */
+    growth: number;
+    /**
+     * Flat state + local income-tax rate on taxable ordinary income (fraction).
+     * Carries the whole state tax under a flat `stateEffectiveTaxPct` override, or
+     * just the flat local rate when `stateBrackets` supplies the progressive state
+     * schedule (Step 3).
+     */
+    stateRate: number;
+    /**
+     * Convex state income-tax bracket PWL (Step 3): ascending segments over the
+     * same taxable-ordinary base as the federal PWL, mirroring `bracketSegments`.
+     * Present only for progressive (non-flat-override) states with an income tax;
+     * absent means the flat `stateRate` is the whole story (byte-identical LP).
+     * Retirement-income exclusions are left to the exact ledger to refine.
+     */
+    stateBrackets?: {
+        width: number | null;
+        rate: number;
+    }[];
+    /**
+     * Deposits landing in the owner-traditional bucket this year (scheduled
+     * employee contributions + employer match into traditional). The cash side of
+     * employee contributions is already inside `spendingNeed`; this is the asset
+     * side, so contribution-funded plans don't read as insolvent. Nominal.
+     */
+    tradInflow: number;
+    /** Deposits landing in the lumped other bucket this year (Roth/taxable/cash/HSA contributions + Roth match). Nominal. */
+    otherInflow: number;
+    /**
+     * Deposits landing specifically in the taxable brokerage / equity-comp bucket
+     * this year (a subset of `otherInflow`). Only meaningful when the taxable
+     * bucket is split out (Step 2); default 0 keeps the lumped-bucket behavior.
+     */
+    taxableInflow?: number;
+    /**
+     * In-solve taxable-SS PWL inputs (Step 3). When present with `ssBenefits > 0`,
+     * the LP replaces the fixed taxable-SS constant baked into
+     * `ordinaryIncomeBase` with a variable derived from provisional income, so
+     * the solver sees the *marginal* tax torpedo (each conversion dollar dragging
+     * 50–85¢ of SS into taxability) instead of the incumbent's average. Absent →
+     * the fixed-constant behavior (byte-identical LP).
+     */
+    ssTaxability?: {
+        /** Gross Social Security benefits this year (nominal). */
+        ssBenefits: number;
+        /** Taxable-SS portion already folded into `ordinaryIncomeBase` (subtracted out when the PWL is active). */
+        taxableSsBase: number;
+    };
+    /**
+     * Baseline realized capital gains + qualified dividends this year, EXCLUDING
+     * gains from taxable-account withdrawals (the LP re-decides those as `wtax`,
+     * so including them would double-count). Feeds both the SS phase-in's
+     * provisional income and the IRMAA MAGI base — the ledger's MAGI counts
+     * gains/dividends, so omitting them would understate tier triggers. Nominal;
+     * default 0.
+     */
+    capitalGainsBase?: number;
+    /**
+     * SSA-44 IRMAA redetermination applies to this premium year (the exact
+     * ledger prices its IRMAA on min(year t−2, year t−1 MAGI); see
+     * `healthcareConfigSchema.ssa44`). Under `irmaaLookback`, the year's IRMAA
+     * binaries are driven by year (t−1)'s MAGI instead of (t−2)'s — a
+     * single-source stand-in for the ledger's min that can only overstate the
+     * surcharge (conservative direction, refined by the exact-ledger
+     * tournament) while giving the solver the right marginal signal: a
+     * conversion in the estimate year now lifts this year's premium. Default
+     * false → the plain (t−2) lookback, byte-identical LP.
+     */
+    ssa44Redetermination?: boolean;
+}
+export type OptimizerSolveResult = {
+    Status: string;
+    ObjectiveValue?: number;
+    Columns?: Record<string, {
+        Primal?: number;
+    }>;
+};
+export type OptimizerSolver = (lp: string, opts?: Record<string, unknown>) => OptimizerSolveResult;
+export interface OptimizerInput {
+    years: OptimizerYear[];
+    /** Opening balances at the first year's start. Nominal. */
+    openingTrad: number;
+    /** Opening inherited traditional balance. Taxable and liquid, but never convertible. */
+    openingInheritedTrad: number;
+    /**
+     * Opening tax-free "other" bucket: Roth + cash + HSA (kept whole in the
+     * objective; withdrawals are tax-free). When the taxable bucket is split out
+     * (Step 2) this excludes taxable/equity-comp — those go in `openingTaxable`.
+     * When `openingTaxable` is 0/absent this is the original lumped bucket.
+     */
+    openingOther: number;
+    /**
+     * Opening taxable brokerage + equity-comp balance (Step 2, taxable-gain
+     * realization). Withdrawals realize LTCG on the gain fraction at `ltcgRate`,
+     * so the solver no longer treats taxable draws as free. Default 0 (no taxable
+     * bucket) reproduces the lumped-`openingOther` behavior exactly.
+     */
+    openingTaxable?: number;
+    /**
+     * Aggregate cost-basis fraction of the opening taxable balance (basis ÷
+     * balance, in [0,1]); `1 − this` is the gain fraction realized per taxable
+     * withdrawal dollar. A single opening ratio is a fair v1 linearization (the
+     * exact re-run prices true per-year basis depletion). Default 1 → no gain.
+     */
+    taxableBasisRatio?: number;
+    /**
+     * Single preferential LTCG rate applied to realized taxable gains inside the
+     * solve (fraction, e.g. 0.15). A single rate linearizes the 0/15/20% stack;
+     * the exact ledger refines it. Default 0.
+     */
+    ltcgRate?: number;
+    /**
+     * Model IRMAA on the 2-year MAGI lookback (Step 4): year t's Medicare
+     * surcharge binaries are driven by year (t−2)'s MAGI, matching the exact
+     * ledger — so a conversion at 63 anticipates the 65 premium in-solve.
+     * `buildOptimizerInput` always enables this in production; the field stays
+     * optional so direct `OptimizerInput` construction (golden tests,
+     * back-compat callers) defaults to the v1 same-year approximation with a
+     * byte-identical LP. Premium years without an in-horizon source (the first
+     * two years under lookback) carry exogenous premiums the ledger prices.
+     */
+    irmaaLookback?: boolean;
+    /**
+     * Price the OBBBA senior deduction in-solve (ground-truth 2026 law sync,
+     * Step 2). When enabled, eligible years (people 65+, pack carries the rule,
+     * year ≤ `lastApplicableYear`) get the per-person deduction added to the
+     * year's deduction constant plus a convex phase-out floor over MAGI, so the
+     * solver sees the phase-out band's marginal-rate spike (each conversion
+     * dollar clawing back 6¢ of deduction ⇒ bracket rate × 1.06) instead of
+     * ignoring the deduction entirely. The concave full-phase-out cap is omitted
+     * (same treatment and direction as the taxable-SS 85% cap: overstates the
+     * cost of mega-conversions, which the exact ledger refines), and years whose
+     * baseline MAGI is already past full phase-out skip the deduction exactly.
+     * `buildOptimizerInput` always enables this in production; absent, the v1
+     * LP is byte-identical.
+     */
+    seniorDeduction?: boolean;
+    /** Haircut on leftover traditional in the objective (V8 §1.4; ~0.22–0.24). */
+    liquidationRate: number;
+    /** Deflator to express the objective in today's dollars; argmax is unchanged. */
+    realDollarFactor?: number;
+    options?: {
+        /** HiGHS time limit in seconds (default 10). */
+        timeLimitSec?: number;
+        /** Optional per-year conversion ceiling, nominal. */
+        maxConversionPerYear?: number;
+        /**
+         * Resolve the wasm asset URL in a browser worker. Omit in Node (tests),
+         * where `highs` loads the wasm from disk.
+         */
+        locateFile?: (file: string) => string;
+        /** Test seam for deterministic solver-status coverage. */
+        solve?: OptimizerSolver;
+    };
+}
+export interface OptimizedYear {
+    year: number;
+    conversion: number;
+    /** Discretionary + RMD traditional withdrawal (taxable). */
+    withdrawTraditional: number;
+    /** Inherited traditional withdrawal (taxable, never convertible). */
+    withdrawInheritedTraditional: number;
+    /** Withdrawal from the tax-free Roth/cash/HSA bucket (tax-free in the LP). */
+    withdrawOther: number;
+    /** Withdrawal from the taxable brokerage bucket (realizes LTCG on the gain fraction). */
+    withdrawTaxable: number;
+    /** Realized long-term gains from this year's taxable withdrawal (gain fraction × withdrawTaxable). */
+    taxableGainRealized: number;
+    taxableOrdinary: number;
+    irmaaTier: number;
+    endTrad: number;
+    endInheritedTrad: number;
+    endOther: number;
+    /** End-of-year taxable brokerage balance (0 when the taxable bucket isn't split out). */
+    endTaxable: number;
+}
+export interface OptimizedSchedule {
+    status: 'optimal' | 'feasible' | 'infeasible' | 'timeout';
+    /** Ending after-tax wealth in today's dollars (the objective). */
+    endingAfterTax: number;
+    /** Cumulative modeled tax over the horizon (secondary readout, V8 §1.4). */
+    lifetimeTax: number;
+    schedule: OptimizedYear[];
+    /** Per-year conversions, ready to drop into the `optimized`/`manual` strategy. */
+    conversions: {
+        year: number;
+        amount: number;
+    }[];
+    solveMs: number;
+}
+interface BuiltModel {
+    lp: string;
+    binaryCount: number;
+    bigM: number;
+}
+/** Build the multi-year MILP in CPLEX LP format. Exported for golden tests. */
+export declare function buildOptimizerModel(input: OptimizerInput): BuiltModel;
+/**
+ * Solve the multi-year conversion/withdrawal MILP. Returns a per-year schedule
+ * plus a conversions array ready to feed the `optimized` Roth strategy.
+ */
+export declare function optimizeSchedule(input: OptimizerInput): Promise<OptimizedSchedule>;
+export {};