@retiregolden/engine 0.1.0

package/dist/projection/compare.js

@@ -0,0 +1,216 @@
+/**
+ * Projection summaries and the convert-vs-don't comparison (roadmap V3).
+ * Scenario diffing generalizes in V4; this covers the headline question.
+ */
+import { simulatePlan } from './simulate.js';
+function isoYear(isoDate) {
+    return Number(isoDate.slice(0, 4));
+}
+/**
+ * Resolve an account's estate destination for the after-tax estate metric.
+ * Explicit `estateBeneficiary` wins; otherwise the legacy defaults reproduce the
+ * old flat haircut exactly: pre-tax (traditional) balances go to a taxed heir,
+ * an HSA follows its legacy `beneficiary` shorthand, and everything else passes
+ * to a (untaxed) spouse-equivalent.
+ */
+function resolveEstateDestination(account) {
+    if ('estateBeneficiary' in account && account.estateBeneficiary) {
+        return {
+            destination: account.estateBeneficiary.destination,
+            charityPct: account.estateBeneficiary.charityPct ?? 0,
+        };
+    }
+    if (account.type === 'hsa') {
+        return { destination: account.beneficiary === 'nonSpouse' ? 'nonSpouse' : 'spouse', charityPct: 0 };
+    }
+    if (account.type === 'traditional')
+        return { destination: 'nonSpouse', charityPct: 0 };
+    return { destination: 'spouse', charityPct: 0 };
+}
+export function summarizeProjection(plan, result) {
+    let taxes = 0;
+    let conversions = 0;
+    for (const y of result.years) {
+        taxes += y.tax + y.penalties;
+        conversions += y.rothConversion;
+    }
+    const endingByCategory = { cash: 0, taxable: 0, traditional: 0, roth: 0, hsa: 0 };
+    const last = result.years[result.years.length - 1];
+    if (last) {
+        for (const account of plan.accounts) {
+            if (account.type in endingByCategory) {
+                endingByCategory[account.type] += last.balances[account.id] ?? 0;
+            }
+        }
+    }
+    // --- estate depth (guaranteed-income-and-estate-depth) --------------------
+    // Discount each account's ending balance on the way to heirs/charity, so the
+    // summary can explain how every class was treated. Pre-tax classes are taxed
+    // at a class heir rate (heirTaxByClass override, else the flat heirTaxRatePct);
+    // charity carve-outs pass untaxed; Roth/taxable (stepped-up)/cash pass free.
+    // With no beneficiary fields set anywhere the defaults reproduce the old flat
+    // haircut exactly, so existing plans stay byte-identical.
+    // Scope: the breakdown covers investable account classes only. Property,
+    // debts, TIPS-ladder face, insurance cash value, and any HECM loan (already
+    // netted into endingNetWorth with its non-recourse cap) ride through
+    // netWorth without per-account rows here, so the breakdown's rows sum to
+    // the investable slice of the estate, not the whole headline figure.
+    const flatHeirRate = plan.assumptions.heirTaxRatePct / 100;
+    const heirRateFor = (category) => {
+        const byClass = plan.assumptions.heirTaxByClass;
+        if (category === 'traditional' && byClass?.traditional !== undefined)
+            return byClass.traditional / 100;
+        if (category === 'hsa' && byClass?.hsa !== undefined)
+            return byClass.hsa / 100;
+        return flatHeirRate;
+    };
+    // Nondeductible IRA basis passes to the heir tax-free (Form 8606); allocate it
+    // across traditional accounts by balance so per-account heir tax nets it out.
+    const basisTotal = Math.min(result.endingNondeductibleIraBasis, endingByCategory.traditional);
+    const estateBreakdown = [];
+    if (last) {
+        for (const account of plan.accounts) {
+            // Equity comp is stepped-up at death like a taxable account, and it is part
+            // of ending net worth, so it must appear in the breakdown (and honor a
+            // charity destination) to keep endingAfterTaxEstate consistent — otherwise
+            // it would silently pass untaxed but be un-markable and invisible here.
+            const category = (account.type === 'equityComp' ? 'taxable' : account.type);
+            if (!(category in endingByCategory))
+                continue;
+            const grossBalance = last.balances[account.id] ?? 0;
+            if (grossBalance <= 0)
+                continue;
+            const { destination, charityPct } = resolveEstateDestination(account);
+            let taxablePretaxBase = 0;
+            if (category === 'traditional') {
+                const allocatedBasis = endingByCategory.traditional > 0 ? basisTotal * (grossBalance / endingByCategory.traditional) : 0;
+                taxablePretaxBase = Math.max(0, grossBalance - allocatedBasis);
+            }
+            else if (category === 'hsa' && destination !== 'spouse') {
+                // An HSA passing to anyone but a spouse is a fully taxable distribution.
+                taxablePretaxBase = grossBalance;
+            }
+            const heirTaxRatePct = heirRateFor(category) * 100;
+            const charityFraction = destination === 'charity' ? Math.min(1, charityPct / 100) : 0;
+            const charityAmount = grossBalance * charityFraction;
+            // A spouse rollover is untaxed; otherwise the non-charity slice of the
+            // pre-tax base is taxed at the class heir rate.
+            const heirTax = destination === 'spouse' ? 0 : taxablePretaxBase * (1 - charityFraction) * heirRateFor(category);
+            estateBreakdown.push({
+                accountId: account.id,
+                name: account.name,
+                category,
+                grossBalance,
+                destination,
+                taxablePretaxBase,
+                heirTaxRatePct,
+                charityAmount,
+                heirTax,
+                netToHeirs: grossBalance - charityAmount - heirTax,
+            });
+        }
+    }
+    const heirTax = estateBreakdown.reduce((sum, b) => sum + b.heirTax, 0);
+    const estateToCharity = estateBreakdown.reduce((sum, b) => sum + b.charityAmount, 0);
+    // FIRE metrics computation
+    const startYear = result.startYear;
+    const inflationRate = plan.assumptions.inflationPct / 100;
+    const defaultReturn = plan.assumptions.defaultReturnPct / 100;
+    const realReturn = defaultReturn - inflationRate;
+    const primary = plan.household.people[0];
+    const birthYear = primary ? isoYear(primary.dob) : 1980;
+    const retirementAge = primary?.retirementAge ?? 65;
+    const targetYear = birthYear + retirementAge;
+    // 1. Savings rates
+    const savingsRates = result.years.map((y) => {
+        const savings = y.contributions + y.employerMatch + y.surplusInvested;
+        const gross = y.incomes.total;
+        const ratePct = gross > 0 ? Math.max(0, Math.min(100, (savings / gross) * 100)) : 0;
+        return { year: y.year, ratePct };
+    });
+    // 2. Average pre-retirement savings rate
+    const preRetirementRates = savingsRates.filter((r) => r.year < targetYear);
+    const averagePreRetirementSavingsRatePct = preRetirementRates.length > 0
+        ? preRetirementRates.reduce((acc, r) => acc + r.ratePct, 0) / preRetirementRates.length
+        : 0;
+    // 3. FI Number
+    const targetResult = result.years.find((y) => y.year === Math.max(startYear, targetYear)) ?? result.years[0];
+    const nominalSpendingAtFI = targetResult
+        ? targetResult.expenses.total + targetResult.tax + targetResult.penalties
+        : plan.expenses.baseAnnual;
+    const yearsToFIYear = targetResult ? targetResult.year - startYear : 0;
+    const annualSpendingAtFIToday = nominalSpendingAtFI / Math.pow(1 + inflationRate, yearsToFIYear);
+    const swr = (plan.assumptions.safeWithdrawalRatePct ?? 4) / 100;
+    const fiNumber = annualSpendingAtFIToday / swr;
+    // 4. FI Year and Age
+    let fiYear = null;
+    let fiAge = null;
+    for (const y of result.years) {
+        const deflatedInvestable = y.investableTotal / Math.pow(1 + inflationRate, y.year - startYear);
+        if (deflatedInvestable >= fiNumber) {
+            fiYear = y.year;
+            fiAge = y.year - birthYear;
+            break;
+        }
+    }
+    // 5. Coast FIRE Number
+    const currentAge = startYear - birthYear;
+    const yearsToRetire = Math.max(0, retirementAge - currentAge);
+    const coastFireNumber = fiNumber / Math.pow(1 + realReturn, yearsToRetire);
+    return {
+        lifetimeTaxesAndPenalties: taxes,
+        lifetimeRothConversions: conversions,
+        endingInvestable: result.endingInvestable,
+        endingNetWorth: result.endingNetWorth,
+        // What heirs receive: net worth less heir tax and less any charitable
+        // bequests (charity leaves the heirs' estate but is never taxed). With no
+        // charity destination this equals net worth − heir tax, as before.
+        endingAfterTaxEstate: result.endingNetWorth - estateToCharity - heirTax,
+        endingEstateHeirTax: heirTax,
+        endingEstateToCharity: estateToCharity,
+        estateBreakdown,
+        endingByCategory,
+        depletionYear: result.depletionYear,
+        warnings: result.warnings,
+        savingsRates,
+        averagePreRetirementSavingsRatePct,
+        fiNumber,
+        fiYear,
+        fiAge,
+        coastFireNumber,
+    };
+}
+/** Runs the plan as-is and with conversions disabled, for side-by-side display. */
+export function compareRothConversion(plan, opts) {
+    const disabled = {
+        ...plan,
+        strategies: { ...plan.strategies, rothConversion: { mode: 'none' } },
+    };
+    return {
+        withConversions: summarizeProjection(plan, simulatePlan(plan, opts)),
+        withoutConversions: summarizeProjection(disabled, simulatePlan(disabled, opts)),
+    };
+}
+/**
+ * The "LTC stress" comparison: how a deterministic care episode hits the plan,
+ * and what the LTC policy does about it.
+ *
+ * noCare and careUninsured both hold LTC out, so they differ only by the care
+ * episode — `noCare − careUninsured` is the raw care shock, free of premium
+ * effects. careInsured adds the policies back, so `careInsured − careUninsured`
+ * is the policy's value *net of its premiums* (it can be negative if lifetime
+ * premiums exceed the benefits paid). The UI labels it as such.
+ */
+export function compareLtcStress(plan, opts) {
+    const run = (p) => summarizeProjection(p, simulatePlan(p, opts));
+    const withoutLtc = plan.insurance.filter((i) => i.kind !== 'ltc');
+    const noCare = { ...plan, careEvents: [], insurance: withoutLtc };
+    const careUninsured = { ...plan, insurance: withoutLtc };
+    return {
+        noCare: run(noCare),
+        careUninsured: run(careUninsured),
+        careInsured: run(plan),
+        hasCareEvents: plan.careEvents.length > 0,
+        hasLtcPolicy: plan.insurance.some((i) => i.kind === 'ltc'),
+    };
+}

package/dist/projection/flatTax.d.ts

@@ -0,0 +1,7 @@
+import type { TaxCalculator } from './types.js';
+/**
+ * V1 placeholder: one flat effective rate over all income, with 85% of Social
+ * Security included (the statutory maximum taxable share). Replaced by the
+ * real federal engine in roadmap phase V2 — do not add precision here.
+ */
+export declare function createFlatTaxCalculator(effectiveRatePct: number): TaxCalculator;

package/dist/projection/flatTax.js

@@ -0,0 +1,14 @@
+/**
+ * V1 placeholder: one flat effective rate over all income, with 85% of Social
+ * Security included (the statutory maximum taxable share). Replaced by the
+ * real federal engine in roadmap phase V2 — do not add precision here.
+ */
+export function createFlatTaxCalculator(effectiveRatePct) {
+    const rate = effectiveRatePct / 100;
+    return {
+        compute(input) {
+            const base = input.ordinaryIncome + input.capitalGains + (input.qualifiedDividends ?? 0) + 0.85 * input.ssBenefits;
+            return Math.max(0, base * rate);
+        },
+    };
+}

package/dist/projection/optimizePlan.d.ts

@@ -0,0 +1,328 @@
+/**
+ * Plan → optimizer bridge + orchestration (roadmap V8, PR 1).
+ *
+ * Turns a whole Plan into the optimizer's linearised `OptimizerInput`, runs the
+ * MILP (strategies/optimizer.ts), and writes the result back as an `optimized`
+ * Roth-conversion strategy. The pure solver stays UI- and ledger-agnostic; this
+ * module is where it meets the real engine.
+ *
+ * The bridge derives each year's exogenous inputs from a single BASELINE
+ * projection (conversions stripped) via `captureOptimizerInputs` — so spending,
+ * healthcare/IRMAA/ACA, Social Security, and RMDs are taken at their
+ * no-conversion levels and held fixed for the LP (V8 §3.1: the LP is a
+ * linearisation; re-running `simulate` with the emitted schedule reports exact
+ * numbers and any gap). Balances, growth, and inflation come straight from the
+ * plan.
+ */
+import type { Plan } from '../model/plan.js';
+import { type ObjectivePolicy, type ObjectivePolicyId } from '../decisions/index.js';
+import { type OptimizedSchedule, type OptimizerInput } from '../strategies/optimizer.js';
+import { type ProjectionSummary } from './compare.js';
+import { type SimulateOptions } from './simulate.js';
+import type { ProjectionResult } from './types.js';
+export interface OptimizePlanOptions {
+    startYear: number;
+    /** Same calculator the baseline/comparison run uses (federal ± state). */
+    taxCalculator: SimulateOptions['taxCalculator'];
+    /**
+     * Haircut on leftover traditional in the objective. Defaults to the plan's
+     * `heirTaxRatePct` so the optimizer's objective matches the after-tax-estate
+     * metric (`summarizeProjection`). Fraction is `pct / 100`.
+     */
+    liquidationRatePct?: number;
+    solver?: OptimizerInput['options'];
+    /**
+     * Coordinate-descent refinement of a winning candidate schedule over the
+     * exact ledger (decision-engine Phase 4). Off by default — the worker path
+     * enables it with a bounded simulation budget.
+     */
+    search?: ExactLedgerSearchOptions | false;
+    /**
+     * Objective policy the tournament ranks by (sustainable-spending plan,
+     * Step 5). Omitted or `max-after-tax-estate` keeps the original tournament
+     * behavior; any other policy re-ranks the same exact-ledger evaluations
+     * through the shared `rankEvaluations` under that policy's constraints.
+     */
+    policy?: ObjectivePolicy;
+    /**
+     * Exact-ledger convergence loop (optimizer-exact-ledger-convergence Track 1,
+     * Step 1). Off/undefined
+     * or `maxIterations ≤ 1` reproduces the single-solve schedule byte-for-byte.
+     * When enabled, the MILP is re-solved against exogenous inputs recaptured from
+     * the exact-ledger run of the incumbent schedule (taxable-SS phase-in and
+     * IRMAA/ACA-priced spending become exact at the incumbent), iterating to a
+     * fixed point so the recommendation is *optimal on the exact ledger to
+     * tolerance* rather than "best found within a single linearization".
+     */
+    convergence?: ExactLedgerConvergenceOptions | false;
+}
+export interface ExactLedgerSearchOptions {
+    /** Hard cap on extra exact-ledger simulations spent refining the winner. */
+    maxSimulations?: number;
+}
+export interface ExactLedgerConvergenceOptions {
+    /**
+     * Hard cap on outer solve+sim iterations, including the first solve. `≤ 1`
+     * disables the loop (single solve = today's schedule). Default
+     * `DEFAULT_CONVERGENCE_ITERATIONS`.
+     */
+    maxIterations?: number;
+    /**
+     * Stop once no year's conversion moves more than this between iterations
+     * (nominal dollars). Default `DEFAULT_CONVERGENCE_SCHEDULE_TOLERANCE_DOLLARS`.
+     */
+    scheduleToleranceDollars?: number;
+    /**
+     * Stop once the exact-ledger after-tax estate improves by less than this over
+     * the previous iteration (nominal dollars). Default
+     * `DEFAULT_CONVERGENCE_OBJECTIVE_TOLERANCE_DOLLARS`.
+     */
+    objectiveToleranceDollars?: number;
+    /**
+     * Trust-region step limit: the largest per-year conversion change adopted in a
+     * single iteration (nominal dollars), damping SLP oscillation. Default
+     * `DEFAULT_CONVERGENCE_MAX_YEAR_STEP_DOLLARS`.
+     */
+    maxYearStepDollars?: number;
+    /**
+     * Relaxation factor in `(0, 1]`: fraction of the solved step taken each
+     * iteration before the trust-region clamp. `1` (default) takes the full step;
+     * lower values damp harder.
+     */
+    dampingFactor?: number;
+}
+export interface ExactLedgerConvergenceDiagnostics {
+    /** True when the loop actually ran (enabled and `maxIterations > 1`). */
+    enabled: boolean;
+    /** Outer solves performed (1 = first solve only). */
+    iterations: number;
+    /** True when the schedule/objective settled within tolerance before the cap. */
+    converged: boolean;
+    /** Exact after-tax estate at the final schedule minus at the first solve (nominal). */
+    estateGainOverFirstSolveDollars: number;
+    /** Largest per-year conversion move on the final adopted iteration (nominal). */
+    finalMaxYearMoveDollars: number;
+    /**
+     * Which schedule the pipeline kept after post-processing both: the converged
+     * schedule, or the first solve when its post-processed (trim + estate-prune)
+     * form priced higher on the exact ledger — SLP converges to a local optimum,
+     * and the post-processor can rescue a raw first solve into a better cleaned
+     * schedule. Absent when the loop never adopted a step.
+     */
+    keptSchedule?: 'converged' | 'first-solve';
+}
+/**
+ * Build the optimizer input from a probe projection.
+ *
+ * By default the probe is a conversion-free baseline, so the LP's exogenous
+ * inputs (taxable SS, RMD divisors, spending, healthcare/IRMAA) are taken at
+ * their no-conversion levels and held fixed for the solve. The exact-ledger
+ * convergence loop (Step 1) passes the *incumbent* schedule as `probeSourcePlan`
+ * so those same inputs are recaptured at the schedule the solver last emitted —
+ * the SLP re-linearization that turns the solver's optimum into the exact-ledger
+ * optimum by iteration (see `optimizePlan`).
+ */
+export declare function buildOptimizerInput(plan: Plan, opts: OptimizePlanOptions, probeSourcePlan?: Plan): OptimizerInput;
+export interface OptimizePlanResult {
+    schedule: OptimizedSchedule;
+    input: OptimizerInput;
+    postProcessed: ExactLedgerPostProcessing | null;
+    tournament: ExactLedgerTournament;
+    /**
+     * Convergence-loop diagnostics (Step 1). Always present: reports `enabled:
+     * false` on the default single-solve path so callers can render it uniformly.
+     */
+    convergence: ExactLedgerConvergenceDiagnostics;
+}
+export interface SimpleCandidateEvaluation {
+    id: string;
+    label: string;
+    /** Total conversions the exact ledger executed under this candidate strategy. */
+    executedConversionTotal: number;
+    afterTaxEstateDelta: number;
+    lifetimeTaxDelta: number;
+    moneyLastsYearsDelta: number;
+}
+export interface ExactLedgerTournament {
+    /** Objective policy that ranked this tournament (default `max-after-tax-estate`). */
+    policyId: ObjectivePolicyId;
+    /** All simple-candidate evaluations, in fixed generation order. */
+    candidates: SimpleCandidateEvaluation[];
+    /**
+     * Who supplies the recommended schedule: the post-processed MILP, a simple
+     * candidate, the plan's own already-applied conversion strategy
+     * ('incumbent': nothing evaluated beat the current plan, so no change is
+     * recommended), or nobody.
+     */
+    winnerSource: 'milp' | 'candidate' | 'incumbent' | 'none';
+    winnerCandidateId: string | null;
+    winnerLabel: string | null;
+    /**
+     * The recommended per-year schedule (exact-ledger executed amounts; empty
+     * when winnerSource is 'none'; the plan's current executed conversions when
+     * winnerSource is 'incumbent').
+     */
+    winnerConversions: {
+        year: number;
+        amount: number;
+    }[];
+    /** Exact comparison for the winner; null for 'incumbent' (a plan's delta vs itself is zero) and 'none'. */
+    winnerValidation: ExactLedgerValidation | null;
+    /** Candidate's exact estate delta over the displaced MILP schedule; 0 when no MILP comparison was made. */
+    marginOverMilpDollars: number;
+    /** True when Phase 4 local search improved the winning candidate schedule. */
+    searchRefined: boolean;
+    /** Exact-ledger simulations spent by local search (0 when search was off or skipped). */
+    searchSimulations: number;
+}
+/**
+ * Exact-ledger evaluations of a small fixed set of simple conversion
+ * strategies (post-processor plan Phase 5; validation plan "candidate strategy
+ * comparisons"). Each candidate is one deterministic `simulatePlan` run of the
+ * plan with a fill-to-target Roth strategy over the whole horizon, priced with
+ * the same summary metrics the recommendation gate uses.
+ */
+export declare function evaluateSimpleConversionCandidates(plan: Plan, baselineResult: ProjectionResult, simulateOptions: SimulateOptions): SimpleCandidateEvaluation[];
+/**
+ * The bounded exact-ledger tournament (post-processor plan Phase 5): compare
+ * the post-processed MILP schedule against the simple candidates and recommend
+ * whichever wins on the exact after-tax estate. The MILP's linearisation can
+ * over-convert past its own objective's break-even (its bracket, IRMAA, and
+ * liquidity approximations diverge over long horizons), and on trad-heavy
+ * fixtures a plain bracket fill beats the cleaned schedule by 2× — so the
+ * winner, not the solver, supplies the recommendation. A candidate must beat
+ * a recommendable MILP by a material margin (default $1k) to avoid churn on
+ * ties, must never shorten money-lasts relative to the schedule it would
+ * replace, and its schedule is exact-ledger executed amounts by construction.
+ * Cost: six extra deterministic `simulatePlan` runs.
+ */
+export declare function runExactLedgerTournament(plan: Plan, baselineResult: ProjectionResult, postProcessed: ExactLedgerPostProcessing | null, simulateOptions: SimulateOptions, options?: {
+    switchMarginDollars?: number;
+    search?: ExactLedgerSearchOptions | false;
+    policy?: ObjectivePolicy;
+}): ExactLedgerTournament;
+export type ExactLedgerRecommendationState = 'beneficial' | 'neutral' | 'rejected' | 'unexecutable';
+export type ExactLedgerRecommendationSchedule = 'cleaned' | 'none';
+export interface ExactLedgerValidationOptions {
+    /** Dollars around zero treated as matching the current exact plan. */
+    neutralToleranceDollars?: number;
+    /** Minimum total requested conversions before execution-ratio diagnostics matter. */
+    minimumRequestedConversionDollars?: number;
+    /** Absolute shortfall before requested-vs-executed mismatch is material. */
+    materialConversionShortfallDollars?: number;
+    /** Percent shortfall before requested-vs-executed mismatch is material. */
+    materialConversionShortfallPct?: number;
+}
+export interface ExactLedgerValidation {
+    baseline: ProjectionSummary;
+    candidate: ProjectionSummary;
+    afterTaxEstateDelta: number;
+    endingNetWorthDelta: number;
+    lifetimeTaxDelta: number;
+    moneyLastsYearsDelta: number;
+    requestedConversionTotal: number;
+    executedConversionTotal: number;
+    executedConversionRatio: number;
+    firstMateriallyUnexecutedYear: number | null;
+    traditionalDepletionYear: number | null;
+    recommendationState: ExactLedgerRecommendationState;
+}
+export interface ExactLedgerScheduleAdjustment {
+    year: number;
+    requested: number;
+    executed: number;
+    cleaned: number;
+    reason: 'ledger-capped' | 'dropped-zero' | 'estate-pruned' | 'rounding';
+}
+export interface ExactLedgerPostProcessingOptions extends ExactLedgerValidationOptions {
+    /** Maximum raw -> executed -> rerun stabilization passes. */
+    maxIterations?: number;
+    /** Maximum trailing-year prune candidates evaluated (one exact simulation each). */
+    maxPruneIterations?: number;
+}
+export interface ExactLedgerPostProcessing {
+    rawSchedule: OptimizedSchedule;
+    cleanedSchedule: OptimizedSchedule;
+    rawValidation: ExactLedgerValidation;
+    cleanedValidation: ExactLedgerValidation;
+    rawResult: ProjectionResult;
+    cleanedResult: ProjectionResult;
+    adjustments: ExactLedgerScheduleAdjustment[];
+    stabilized: boolean;
+    iterationCount: number;
+    /** Trailing-year prune candidates evaluated (0 when the prune pass did not run). */
+    pruneIterationCount: number;
+    recommendationSchedule: ExactLedgerRecommendationSchedule;
+}
+/**
+ * Compare a proposed conversion schedule with the exact projection ledger.
+ *
+ * The solver can request conversions that the ledger later caps because
+ * spending, RMDs, or prior conversions drained the own traditional balance.
+ * Since the decision engine landed this is a thin adapter over the shared
+ * `evaluateCandidate` core (Phase 1): the exact candidate run stays
+ * authoritative, classified by after-tax estate first, with execution mismatch
+ * as a separate blocking state ('diagnostic' in engine terms, 'unexecutable'
+ * here for the optimizer UI contract).
+ */
+export declare function evaluateExactLedgerSchedule(plan: Plan, requestedConversions: {
+    year: number;
+    amount: number;
+}[], baselineResult: ProjectionResult, candidateResult: ProjectionResult, options?: ExactLedgerValidationOptions): ExactLedgerValidation;
+/**
+ * Turn a raw optimizer schedule into the schedule the exact ledger can execute.
+ *
+ * The MILP is useful as a candidate generator, but only the ledger knows the
+ * real account balances, withdrawals, taxes, ACA/IRMAA effects, and conversion
+ * caps. This pass trims raw requested conversions to exact execution, reruns the
+ * ledger, and returns the cleaned schedule plus diagnostics.
+ */
+export declare function postProcessExactLedgerSchedule(plan: Plan, rawSchedule: OptimizedSchedule, baselineResult: ProjectionResult, simulateOptions: SimulateOptions, options?: ExactLedgerPostProcessingOptions): ExactLedgerPostProcessing;
+/** Run the optimizer end-to-end on a plan: MILP → (convergence loop) → post-processing → tournament. */
+export declare function optimizePlan(plan: Plan, opts: OptimizePlanOptions): Promise<OptimizePlanResult>;
+export interface ClaimAgeCoOptimization {
+    /** True when claim-age co-optimization actually ran. */
+    enabled: boolean;
+    /** Claim combinations optimized, including the current claim (1 when off). */
+    combinationsEvaluated: number;
+    /** Label of the winning claim change, or null when the current claim won. */
+    winningClaimLabel: string | null;
+    /**
+     * The plan patch (new incomes array) that produced the joint optimum, or null
+     * when the current claim ages won. Callers apply this to recommend the claim
+     * change alongside the returned conversion schedule.
+     */
+    winningClaimPatch: {
+        incomes: Plan['incomes'];
+    } | null;
+    /** Exact after-tax estate of the joint (claim, schedule) optimum. */
+    jointExactEstate: number;
+    /** Exact after-tax estate of the current-claim optimum (the comparison floor). */
+    currentClaimExactEstate: number;
+}
+export interface OptimizePlanWithClaimResult extends OptimizePlanResult {
+    /** The plan whose optimum is returned — the current plan, or a claim-patched copy. */
+    optimizedPlan: Plan;
+    claimAge: ClaimAgeCoOptimization;
+}
+/**
+ * Co-optimized SS claim age (Step 5). Alternate-minimize: run the full
+ * conversion optimum (convergence loop + tournament) at the current claim ages
+ * and at each bounded claim candidate from `socialSecurityClaimGenerator`, then
+ * keep the (claim, schedule) pair with the best *absolute* exact-ledger after-tax
+ * estate. A claim switch must clear a small margin to avoid churn. The grid is
+ * bounded (≤ 2 streams × 3 canonical ages), so the cost is a small multiple of a
+ * single optimize; the exact ledger prices every pair, so the tournament remains
+ * the guardrail for each. Returns the winning plan (current or claim-patched) and
+ * its optimizer result plus a diagnostic of the joint decision.
+ */
+export declare function optimizePlanCoOptimizingClaimAge(plan: Plan, opts: OptimizePlanOptions): Promise<OptimizePlanWithClaimResult>;
+/**
+ * Return a copy of the plan with the optimizer's conversions installed as an
+ * `optimized` strategy. The UI's "accept as manual" simply rewrites the same
+ * conversions under the `manual` mode.
+ */
+export declare function withOptimizedConversions(plan: Plan, conversions: {
+    year: number;
+    amount: number;
+}[], optimizedAtIso?: string): Plan;