@retiregolden/engine 0.1.0

package/dist/decisions/pensionElection.js

@@ -0,0 +1,239 @@
+/**
+ * Pension lump-sum vs annuity decision module (annuity-pension-and-home-equity
+ * decisions, step 3).
+ *
+ * Two complementary surfaces, verdicts framed as tradeoffs — never advice:
+ *  - deterministic PV math: the pension annuity's present value at a chosen
+ *    discount rate, its survivor-option value, and a sensitivity table over
+ *    discount rate × longevity — the classic "what does the lump sum have to
+ *    beat" view, golden-tested by hand;
+ *  - a scenario pair for the exact ledger / shared-path Monte Carlo: keep the
+ *    annuity vs take the lump sum (a tax-free direct rollover into a
+ *    traditional account in the election year — see the ledger's
+ *    pension-lump-sum block), so taxes, survivor interplay, and sequence risk
+ *    are priced by the engine rather than a side model.
+ */
+import { EMBEDDED_REAL_YIELD_CURVE } from '../params/index.js';
+/**
+ * Present value (valuation-year dollars) of the pension's payment stream:
+ * the full benefit while the owner lives (from startAge), then survivorPct of
+ * it while the survivor lives — the same continuation rule the ledger applies
+ * (survivor benefits require the owner to have reached the start age; a
+ * survivor election on a pension that never started pays nothing here too).
+ * Payments are nominal with COLA compounding from the start age; discounting
+ * is annual at year offsets from the valuation year.
+ */
+export function pensionAnnuityPresentValue(inputs) {
+    const annual = inputs.monthlyAmount * 12;
+    if (annual <= 0)
+        return 0;
+    const discount = 1 + inputs.discountRatePct / 100;
+    const horizonAge = Math.max(inputs.ownerDeathAge, inputs.survivor ? inputs.ownerCurrentAge + (inputs.survivor.deathAge - inputs.survivor.currentAge) : 0);
+    let pv = 0;
+    for (let ownerAge = Math.max(inputs.startAge, inputs.ownerCurrentAge); ownerAge <= horizonAge; ownerAge++) {
+        const t = ownerAge - inputs.ownerCurrentAge;
+        const grown = annual * Math.pow(1 + inputs.colaPct / 100, ownerAge - inputs.startAge);
+        const ownerAlive = ownerAge <= inputs.ownerDeathAge;
+        let paid = 0;
+        if (ownerAlive) {
+            paid = grown;
+        }
+        else if (inputs.survivor && inputs.ownerDeathAge >= inputs.startAge) {
+            const survivorAge = inputs.survivor.currentAge + t;
+            if (survivorAge <= inputs.survivor.deathAge)
+                paid = grown * (inputs.survivorPct / 100);
+        }
+        if (paid <= 0)
+            continue;
+        pv += paid / Math.pow(discount, t);
+    }
+    return pv;
+}
+/**
+ * Sensitivity of the annuity's PV to discount rate × owner longevity, against
+ * the lump-sum offer. Bounded: at most 5 × 5 cells.
+ */
+export function pensionLumpSumSensitivity(base, lumpSum, discountRatesPct, ownerDeathAges) {
+    const rates = discountRatesPct.slice(0, 5);
+    const ages = ownerDeathAges.slice(0, 5);
+    const rows = ages.map((ownerDeathAge) => ({
+        ownerDeathAge,
+        cells: rates.map((discountRatePct) => {
+            const presentValue = pensionAnnuityPresentValue({ ...base, ownerDeathAge, discountRatePct });
+            return {
+                discountRatePct,
+                presentValue,
+                ratioToLumpSum: lumpSum > 0 ? presentValue / lumpSum : 0,
+            };
+        }),
+    }));
+    return { rows, discountRatesPct: [...rates], lumpSum };
+}
+/**
+ * Curve-anchored nominal discount rate (percent): the embedded TIPS par real
+ * yield at the given horizon plus assumed inflation — the "market rate" column
+ * of the sensitivity table (a corporate-bond-style spread is the user's call).
+ */
+export function curveNominalDiscountRatePct(horizonYears, inflationPct) {
+    const points = EMBEDDED_REAL_YIELD_CURVE.points;
+    if (points.length === 0)
+        return inflationPct;
+    let real = points[points.length - 1].realYieldPct;
+    if (horizonYears <= points[0].maturityYears) {
+        real = points[0].realYieldPct;
+    }
+    else {
+        for (let i = 0; i < points.length - 1; i++) {
+            const a = points[i];
+            const b = points[i + 1];
+            if (horizonYears >= a.maturityYears && horizonYears <= b.maturityYears) {
+                real =
+                    a.realYieldPct +
+                        ((b.realYieldPct - a.realYieldPct) * (horizonYears - a.maturityYears)) / (b.maturityYears - a.maturityYears);
+                break;
+            }
+        }
+    }
+    return real + inflationPct;
+}
+function dobYear(dob) {
+    return Number(dob.slice(0, 4));
+}
+/**
+ * The concrete "take the lump sum" plan patch for a pension with an offer:
+ * installs the election, rolling into the largest owner-matched traditional
+ * account — or a new zero-balance rollover IRA when the plan has none. Shared
+ * by the candidate generator and the pension-election insight so both surfaces
+ * model the identical mechanics. Null when the pension carries no offer.
+ */
+export function pensionTakeLumpSumPatch(plan, pension, startYear) {
+    if (!pension.lumpSumOffer)
+        return null;
+    const ownerId = pension.ownerPersonId ?? plan.household.people[0]?.id ?? null;
+    const existing = plan.accounts
+        .filter((a) => a.type === 'traditional' && !a.inherited && (a.ownerPersonId === ownerId || a.ownerPersonId === null))
+        .sort((a, b) => b.balance - a.balance)[0];
+    // Namespaced by pension id so the synthetic rollover IRA cannot collide
+    // with a real user account id.
+    const rollover = existing
+        ? undefined
+        : {
+            id: `pension-rollover-${startYear}-${pension.id}`,
+            type: 'traditional',
+            kind: 'ira',
+            name: `${pension.name} rollover IRA`,
+            ownerPersonId: ownerId,
+            annualReturnPct: null,
+            balance: 0,
+            annualContribution: 0,
+        };
+    const rolloverAccountId = existing?.id ?? rollover.id;
+    const accounts = plan.accounts.map((a) => a.id === pension.id ? { ...pension, lumpSumElection: { rolloverAccountId } } : a);
+    return { accounts: rollover ? [...accounts, rollover] : accounts };
+}
+/**
+ * Scenario-pair candidates for pensions with a lump-sum offer on record:
+ * "take the lump sum" (via pensionTakeLumpSumPatch) and, when already
+ * elected, "keep the annuity" (removes the election). Bounded: ≤ 2 pensions,
+ * one candidate each; the exact ledger prices both.
+ */
+export const pensionLumpSumGenerator = {
+    id: 'pension-lump-sum',
+    generate(ctx) {
+        const plan = ctx.plan;
+        const startYear = ctx.simulateOptions.startYear;
+        const candidates = [];
+        const pensions = plan.accounts.filter((a) => a.type === 'pension' && a.lumpSumOffer !== undefined);
+        for (const pension of pensions.slice(0, 2)) {
+            const offer = pension.lumpSumOffer;
+            if (offer.electionYear < startYear)
+                continue; // election already past; nothing to model
+            if (pension.lumpSumElection) {
+                candidates.push({
+                    id: `pension-keep-annuity-${pension.id}`,
+                    source: 'heuristic',
+                    category: 'guaranteed-income',
+                    label: `Keep the ${pension.name} annuity`,
+                    explanation: 'Runs the plan with the lump-sum election removed, so the pension pays its lifetime annuity and the exact ledger prices what the lump sum gives up.',
+                    planPatch: {
+                        accounts: plan.accounts.map((a) => (a.id === pension.id ? { ...pension, lumpSumElection: undefined } : a)),
+                    },
+                });
+                continue;
+            }
+            const patch = pensionTakeLumpSumPatch(plan, pension, startYear);
+            if (!patch)
+                continue;
+            candidates.push({
+                id: `pension-lump-sum-${pension.id}`,
+                source: 'heuristic',
+                category: 'guaranteed-income',
+                label: `Take the ${pension.name} lump sum`,
+                explanation: `Rolls the $${Math.round(offer.amount).toLocaleString()} offer into a traditional IRA in ${offer.electionYear} (tax-free direct rollover) instead of the lifetime annuity, and reprices the whole plan on the exact ledger.`,
+                planPatch: patch,
+                metadata: { pensionId: pension.id, lumpSum: Math.round(offer.amount), electionYear: offer.electionYear },
+            });
+        }
+        return candidates;
+    },
+};
+/**
+ * The decision view's deterministic analysis for every pension carrying a
+ * lump-sum offer. Discount rates: the curve-anchored rate ± 1% and two fixed
+ * planning rates; longevity: planning age and ±3 years.
+ */
+export function analyzePensionElections(plan, startYear) {
+    const analyses = [];
+    for (const account of plan.accounts) {
+        if (account.type !== 'pension' || !account.lumpSumOffer)
+            continue;
+        const ownerId = account.ownerPersonId ?? plan.household.people[0]?.id;
+        const owner = plan.household.people.find((p) => p.id === ownerId) ?? plan.household.people[0];
+        if (!owner)
+            continue;
+        const other = plan.household.people.find((p) => p.id !== owner.id);
+        const ownerCurrentAge = startYear - dobYear(owner.dob);
+        const ownerPlanningAge = owner.longevity.planningAge;
+        const survivor = other !== undefined
+            ? { currentAge: startYear - dobYear(other.dob), deathAge: other.longevity.planningAge }
+            : undefined;
+        const base = {
+            monthlyAmount: account.monthlyAmount,
+            colaPct: account.colaPct,
+            survivorPct: account.survivorPct,
+            startAge: account.startAge,
+            ownerCurrentAge,
+            survivor,
+        };
+        const horizonYears = Math.max(5, ownerPlanningAge - ownerCurrentAge);
+        const curveRatePct = curveNominalDiscountRatePct(horizonYears, plan.assumptions.inflationPct);
+        const rates = [
+            Math.max(0.5, Math.round((curveRatePct - 1) * 10) / 10),
+            Math.round(curveRatePct * 10) / 10,
+            Math.round((curveRatePct + 1) * 10) / 10,
+            6,
+            7,
+        ].filter((r, i, arr) => arr.indexOf(r) === i);
+        const deathAges = [ownerPlanningAge - 3, ownerPlanningAge, ownerPlanningAge + 3].filter((a) => a > ownerCurrentAge);
+        analyses.push({
+            pensionId: account.id,
+            pensionName: account.name,
+            lumpSum: account.lumpSumOffer.amount,
+            electionYear: account.lumpSumOffer.electionYear,
+            presentValueAtCurveRate: pensionAnnuityPresentValue({
+                ...base,
+                ownerDeathAge: ownerPlanningAge,
+                discountRatePct: curveRatePct,
+            }),
+            curveRatePct,
+            presentValueSingleLife: pensionAnnuityPresentValue({
+                ...base,
+                survivorPct: 0,
+                ownerDeathAge: ownerPlanningAge,
+                discountRatePct: curveRatePct,
+            }),
+            sensitivity: pensionLumpSumSensitivity(base, account.lumpSumOffer.amount, rates, deathAges),
+        });
+    }
+    return analyses;
+}

package/dist/decisions/search.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Local search over the exact ledger (ledger-native decision engine, Phase 4).
+ *
+ * Coordinate descent on a Roth conversion schedule: one decision variable per
+ * schedule year (the conversion amount), coarse dollar steps first, then a
+ * smaller refinement pass. Every move is scored by running the mutated
+ * schedule through the exact ledger and applying the objective policy — cheap
+ * screens are never the final score. Deterministic under a fixed simulation
+ * budget: fixed year order, fixed step order, and a hard cap on evaluations.
+ */
+import { type EvaluateCandidateOptions } from './evaluateCandidate.js';
+import { type ObjectivePolicy } from './objectives.js';
+import type { DecisionContext, ExactDecisionEvaluation } from './types.js';
+export interface CoordinateDescentOptions {
+    /** Hard cap on exact-ledger simulations (including the seed evaluation). */
+    maxSimulations?: number;
+    /** First-pass step size in dollars. */
+    coarseStepDollars?: number;
+    /** Refinement-pass step size in dollars. */
+    fineStepDollars?: number;
+    /** Max full sweeps per step size. */
+    maxSweepsPerStep?: number;
+    /** A move must beat the incumbent primary metric by more than this. */
+    minimumImprovement?: number;
+    policy?: ObjectivePolicy;
+    evaluation?: EvaluateCandidateOptions;
+    /** Base plan patch every mutated schedule is applied on top of. */
+    basePatch?: Record<string, unknown>;
+}
+export interface CoordinateDescentResult {
+    bestConversions: Array<{
+        year: number;
+        amount: number;
+    }>;
+    bestEvaluation: ExactDecisionEvaluation;
+    /** True when search found a strictly better schedule than the seed. */
+    improved: boolean;
+    simulationCount: number;
+    /** Full sweeps performed across both step sizes. */
+    sweepCount: number;
+}
+/**
+ * Refine a conversion schedule by coordinate descent, keeping only moves the
+ * exact ledger prices as improvements under the policy's primary metric and
+ * hard constraints. Returns the seed evaluation unchanged when nothing beats it
+ * within the budget.
+ */
+export declare function refineConversionSchedule(ctx: DecisionContext, seedConversions: Array<{
+    year: number;
+    amount: number;
+}>, options?: CoordinateDescentOptions): CoordinateDescentResult;

package/dist/decisions/search.js

@@ -0,0 +1,110 @@
+/**
+ * Local search over the exact ledger (ledger-native decision engine, Phase 4).
+ *
+ * Coordinate descent on a Roth conversion schedule: one decision variable per
+ * schedule year (the conversion amount), coarse dollar steps first, then a
+ * smaller refinement pass. Every move is scored by running the mutated
+ * schedule through the exact ledger and applying the objective policy — cheap
+ * screens are never the final score. Deterministic under a fixed simulation
+ * budget: fixed year order, fixed step order, and a hard cap on evaluations.
+ */
+import { evaluateCandidate } from './evaluateCandidate.js';
+import { maximizeAfterTaxEstate } from './objectives.js';
+const DEFAULT_MAX_SIMULATIONS = 48;
+const DEFAULT_COARSE_STEP = 10_000;
+const DEFAULT_FINE_STEP = 2_500;
+const DEFAULT_MAX_SWEEPS_PER_STEP = 3;
+const DEFAULT_MINIMUM_IMPROVEMENT = 1;
+/** Extra coordinate years past the seed's last conversion (taper discovery). */
+const TAPER_EXTENSION_YEARS = 8;
+function normalizeSchedule(conversions) {
+    return conversions
+        .map((c) => ({ year: c.year, amount: Math.round(c.amount * 100) / 100 }))
+        .filter((c) => c.amount > 0)
+        .sort((a, b) => a.year - b.year);
+}
+/**
+ * Refine a conversion schedule by coordinate descent, keeping only moves the
+ * exact ledger prices as improvements under the policy's primary metric and
+ * hard constraints. Returns the seed evaluation unchanged when nothing beats it
+ * within the budget.
+ */
+export function refineConversionSchedule(ctx, seedConversions, options = {}) {
+    const policy = options.policy ?? maximizeAfterTaxEstate;
+    const maxSimulations = options.maxSimulations ?? DEFAULT_MAX_SIMULATIONS;
+    const coarseStep = options.coarseStepDollars ?? DEFAULT_COARSE_STEP;
+    const fineStep = options.fineStepDollars ?? DEFAULT_FINE_STEP;
+    const maxSweepsPerStep = options.maxSweepsPerStep ?? DEFAULT_MAX_SWEEPS_PER_STEP;
+    const minimumImprovement = options.minimumImprovement ?? DEFAULT_MINIMUM_IMPROVEMENT;
+    let simulationCount = 0;
+    let sweepCount = 0;
+    const makeCandidate = (conversions, moveId) => ({
+        id: `search-${moveId}`,
+        source: 'search',
+        category: 'roth',
+        label: 'Locally refined conversion schedule',
+        explanation: 'Coordinate-descent mutation of the incumbent schedule, priced on the exact ledger.',
+        planPatch: options.basePatch,
+        conversions,
+    });
+    const evaluate = (conversions, moveId) => {
+        simulationCount++;
+        return evaluateCandidate(ctx, makeCandidate(conversions, moveId), options.evaluation);
+    };
+    let bestConversions = normalizeSchedule(seedConversions);
+    let bestEvaluation = evaluate(bestConversions, 'seed');
+    let bestScore = policy.primaryMetric(bestEvaluation, ctx);
+    let improved = false;
+    // Coordinate set: the seed's years plus a bounded extension past the last
+    // seed year. Mutating only seed years can never ADD a conversion year, which
+    // locks out taper shapes ("fill hard until RMDs, then convert smaller
+    // amounts") — the years after a windowed fill ends are exactly where those
+    // live. Bounded and deterministic: at most `TAPER_EXTENSION_YEARS` extra
+    // coordinates, in ascending year order.
+    const seedYears = bestConversions.map((c) => c.year);
+    const lastSeedYear = seedYears.length > 0 ? seedYears[seedYears.length - 1] : ctx.baselineResult.startYear - 1;
+    const extensionYears = ctx.baselineResult.years
+        .map((year) => year.year)
+        .filter((year) => year > lastSeedYear)
+        .slice(0, TAPER_EXTENSION_YEARS);
+    const years = [...seedYears, ...extensionYears];
+    const steps = coarseStep === fineStep ? [coarseStep] : [coarseStep, fineStep];
+    for (const step of steps) {
+        for (let sweep = 0; sweep < maxSweepsPerStep; sweep++) {
+            if (simulationCount >= maxSimulations)
+                break;
+            sweepCount++;
+            let sweepImproved = false;
+            for (const year of years) {
+                for (const direction of [1, -1]) {
+                    if (simulationCount >= maxSimulations)
+                        break;
+                    const current = bestConversions.find((c) => c.year === year)?.amount ?? 0;
+                    const mutated = Math.max(0, current + direction * step);
+                    if (mutated === current)
+                        continue;
+                    const candidateConversions = normalizeSchedule([
+                        ...bestConversions.filter((c) => c.year !== year),
+                        { year, amount: mutated },
+                    ]);
+                    if (candidateConversions.length === 0)
+                        continue;
+                    const evaluation = evaluate(candidateConversions, `${year}-${direction > 0 ? 'up' : 'down'}-${step}`);
+                    if (policy.constraintViolations(evaluation, ctx).length > 0)
+                        continue;
+                    const score = policy.primaryMetric(evaluation, ctx);
+                    if (score > bestScore + minimumImprovement) {
+                        bestConversions = candidateConversions;
+                        bestEvaluation = evaluation;
+                        bestScore = score;
+                        sweepImproved = true;
+                        improved = true;
+                    }
+                }
+            }
+            if (!sweepImproved)
+                break;
+        }
+    }
+    return { bestConversions, bestEvaluation, improved, simulationCount, sweepCount };
+}

package/dist/decisions/spendingSolver.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Sustainable-spending solver (planning-depth roadmap §4 / Phase 3).
+ *
+ * Answers "how much can this plan spend every year?" with the exact ledger:
+ * bisection over `expenses.baseAnnual` (today's dollars), where a spending
+ * level is feasible only when the full `simulatePlan` run never depletes and
+ * the ending after-tax estate stays at or above the requested floor (the
+ * bequest target, entered in today's dollars and inflated to nominal
+ * end-of-plan dollars). Spending phases, one-time goals, healthcare, taxes, and
+ * every other ledger cross-effect apply unchanged — the solver never builds
+ * its own cash-flow approximation. Deterministic under a hard simulation cap:
+ * fixed probe sequence, integer-dollar midpoints, no randomness.
+ */
+import { type EvaluateCandidateOptions } from './evaluateCandidate.js';
+import type { DecisionContext, ExactDecisionEvaluation } from './types.js';
+export interface SustainableSpendingOptions {
+    /** Hard cap on exact-ledger simulations (bracketing probes + bisection). */
+    maxSimulations?: number;
+    /** Stop when the feasible/infeasible bracket is at most this wide. */
+    resolutionDollars?: number;
+    /**
+     * Ending after-tax estate must stay at or above this (bequest target), in
+     * today's dollars; the solver inflates it to nominal end-of-plan dollars
+     * before comparing against the nominal ending estate.
+     */
+    estateFloorTodayDollars?: number;
+    /** Base plan patch applied under every probed spending level. */
+    basePatch?: Record<string, unknown>;
+    /**
+     * `candidateResult` is excluded: every probe must simulate its own spending
+     * level, so a cached projection would poison the feasibility test.
+     */
+    evaluation?: Omit<EvaluateCandidateOptions, 'candidateResult'>;
+}
+export interface SustainableSpendingResult {
+    /**
+     * Highest feasible annual base spending found (today's dollars), or null
+     * when even zero base spending depletes or breaks the estate floor.
+     */
+    maxBaseAnnual: number | null;
+    /**
+     * maxBaseAnnual minus the current base spending — the basePatch's override
+     * when present, else the plan's own (negative ⇒ overspending today).
+     */
+    spendingSlackDollars: number | null;
+    /** Exact-ledger evaluation of the plan at `maxBaseAnnual`. */
+    bestEvaluation: ExactDecisionEvaluation | null;
+    /** True when the bracket converged to `resolutionDollars` within the budget. */
+    converged: boolean;
+    /**
+     * Why the next-higher probed spending level failed — the constraint that
+     * binds the answer. Null when no infeasible level was probed (unbounded
+     * spending) or the solve bailed out on a diagnostic evaluation.
+     */
+    limitingConstraint: 'depletion' | 'estate-floor' | null;
+    simulationCount: number;
+    diagnostics: string[];
+}
+/**
+ * Shared interactive-surface budget: the "How much can I spend?" page and the
+ * Insights spending-headroom detector both solve with this bound so their
+ * answers agree exactly (the solver is deterministic under a fixed budget).
+ */
+export declare const SPENDING_SOLVER_UI_BUDGET = 25;
+/**
+ * Find the maximum sustainable annual base spending by exact-ledger bisection.
+ * Returns a lower-bound answer (with `converged: false` and a diagnostic) when
+ * the simulation budget runs out before the bracket tightens.
+ */
+export declare function solveMaxSustainableSpending(ctx: DecisionContext, options?: SustainableSpendingOptions): SustainableSpendingResult;

package/dist/decisions/spendingSolver.js

@@ -0,0 +1,180 @@
+/**
+ * Sustainable-spending solver (planning-depth roadmap §4 / Phase 3).
+ *
+ * Answers "how much can this plan spend every year?" with the exact ledger:
+ * bisection over `expenses.baseAnnual` (today's dollars), where a spending
+ * level is feasible only when the full `simulatePlan` run never depletes and
+ * the ending after-tax estate stays at or above the requested floor (the
+ * bequest target, entered in today's dollars and inflated to nominal
+ * end-of-plan dollars). Spending phases, one-time goals, healthcare, taxes, and
+ * every other ledger cross-effect apply unchanged — the solver never builds
+ * its own cash-flow approximation. Deterministic under a hard simulation cap:
+ * fixed probe sequence, integer-dollar midpoints, no randomness.
+ */
+import { evaluateCandidate, planForCandidate } from './evaluateCandidate.js';
+import { nominalDollarsAtPlanEnd } from './objectives.js';
+const DEFAULT_MAX_SIMULATIONS = 24;
+const DEFAULT_RESOLUTION_DOLLARS = 500;
+/**
+ * Shared interactive-surface budget: the "How much can I spend?" page and the
+ * Insights spending-headroom detector both solve with this bound so their
+ * answers agree exactly (the solver is deterministic under a fixed budget).
+ */
+export const SPENDING_SOLVER_UI_BUDGET = 25;
+/** First doubling probe when the plan's own base spending is (near) zero. */
+const MINIMUM_BRACKET_PROBE_DOLLARS = 20_000;
+/** Doubling stops here; past this the plan's income plainly outruns spending. */
+const UNBOUNDED_SPENDING_DOLLARS = 100_000_000;
+function spendingCandidate(basePatch, baseAnnual) {
+    const baseExpenses = basePatch?.['expenses'];
+    return {
+        id: `sustainable-spending-${baseAnnual}`,
+        source: 'search',
+        category: 'spending',
+        label: `Base spending $${Math.round(baseAnnual).toLocaleString()}/yr`,
+        explanation: 'Sustainable-spending probe: the exact ledger runs the whole plan at this base spending level.',
+        planPatch: {
+            ...basePatch,
+            expenses: {
+                ...(baseExpenses && typeof baseExpenses === 'object' ? baseExpenses : {}),
+                baseAnnual,
+            },
+        },
+    };
+}
+/**
+ * Find the maximum sustainable annual base spending by exact-ledger bisection.
+ * Returns a lower-bound answer (with `converged: false` and a diagnostic) when
+ * the simulation budget runs out before the bracket tightens.
+ */
+export function solveMaxSustainableSpending(ctx, options = {}) {
+    const maxSimulations = options.maxSimulations ?? DEFAULT_MAX_SIMULATIONS;
+    const resolutionDollars = options.resolutionDollars ?? DEFAULT_RESOLUTION_DOLLARS;
+    const estateFloorTodayDollars = options.estateFloorTodayDollars ?? 0;
+    // Runtime guard behind the Omit: a cached candidateResult from a JS caller
+    // would make every probe reuse one projection instead of simulating its own.
+    const evaluationOptions = { ...options.evaluation };
+    delete evaluationOptions.candidateResult;
+    // Every probe runs on the basePatch-applied plan, so both the "current"
+    // spending reference (bracketing seed + slack basis) and the inflation used
+    // to inflate the estate floor must come from that patched plan, not the
+    // unpatched baseline. An invalid patch falls back to the plan; the first
+    // probe then returns a diagnostic evaluation and the solve bails out.
+    const patchedBase = options.basePatch ? planForCandidate(ctx.plan, { planPatch: options.basePatch }) : null;
+    const effectivePlan = patchedBase?.ok ? patchedBase.plan : ctx.plan;
+    const currentBaseAnnual = effectivePlan.expenses.baseAnnual;
+    // Amortized spending (ABW) computes the year's lifestyle target from the
+    // portfolio itself and ignores `baseAnnual`, so bisecting baseAnnual would
+    // simulate the identical plan at every probe — the "max fixed spending
+    // level" question has no answer there. Bail out with a diagnostic instead
+    // of burning the budget on indistinguishable probes.
+    if (effectivePlan.expenses.spendingPolicy?.mode === 'abw') {
+        return {
+            maxBaseAnnual: null,
+            spendingSlackDollars: null,
+            bestEvaluation: null,
+            converged: false,
+            limitingConstraint: null,
+            simulationCount: 0,
+            diagnostics: [
+                'This plan uses amortized spending (ABW), which recomputes annual spending from the portfolio each year — there is no fixed base-spending level to solve for. Switch the spending policy to fixed target or guardrails to use this solver.',
+            ],
+        };
+    }
+    const diagnostics = [];
+    let simulationCount = 0;
+    let bestFeasible = null;
+    // Reason the current upper (infeasible) bracket bound failed; tightening the
+    // bracket keeps this in sync with the bound the answer finally rests against.
+    let limitingConstraint = null;
+    const probe = (baseAnnual) => {
+        simulationCount++;
+        const evaluation = evaluateCandidate(ctx, spendingCandidate(options.basePatch, baseAnnual), evaluationOptions);
+        const depleted = evaluation.candidateResult.depletionYear !== null;
+        const breaksFloor = evaluation.candidateSummary.endingAfterTaxEstate <
+            nominalDollarsAtPlanEnd(estateFloorTodayDollars, effectivePlan, evaluation.candidateResult);
+        const feasible = evaluation.recommendationState !== 'diagnostic' && !depleted && !breaksFloor;
+        if (feasible && (bestFeasible === null || baseAnnual > bestFeasible.amount)) {
+            bestFeasible = { amount: baseAnnual, evaluation };
+        }
+        if (!feasible && evaluation.recommendationState !== 'diagnostic') {
+            limitingConstraint = depleted ? 'depletion' : 'estate-floor';
+        }
+        return { feasible, evaluation };
+    };
+    const finish = (lower, upper) => {
+        const converged = lower !== null && upper !== null && upper - lower <= resolutionDollars;
+        if (!converged && lower !== null) {
+            diagnostics.push(`Stopped before converging to $${resolutionDollars.toLocaleString()}; the result is a feasible lower bound.`);
+        }
+        return {
+            maxBaseAnnual: bestFeasible?.amount ?? null,
+            spendingSlackDollars: bestFeasible ? bestFeasible.amount - currentBaseAnnual : null,
+            bestEvaluation: bestFeasible?.evaluation ?? null,
+            converged,
+            limitingConstraint,
+            simulationCount,
+            diagnostics,
+        };
+    };
+    // Bracket the answer starting from the current base spending.
+    const seedAmount = Math.max(0, Math.round(currentBaseAnnual));
+    const seed = probe(seedAmount);
+    if (seed.evaluation.recommendationState === 'diagnostic') {
+        diagnostics.push(...seed.evaluation.diagnostics);
+        return finish(null, null);
+    }
+    let lower;
+    let upper;
+    if (seed.feasible) {
+        lower = seedAmount;
+        upper = null;
+        let next = Math.max(seedAmount * 2, MINIMUM_BRACKET_PROBE_DOLLARS);
+        while (simulationCount < maxSimulations) {
+            if (next > UNBOUNDED_SPENDING_DOLLARS) {
+                diagnostics.push('Spending appears unbounded at the probed range — guaranteed income outruns spending at every tested level.');
+                return finish(lower, upper);
+            }
+            if (probe(next).feasible) {
+                lower = next;
+                next *= 2;
+            }
+            else {
+                upper = next;
+                break;
+            }
+        }
+    }
+    else {
+        upper = seedAmount;
+        if (upper === 0) {
+            diagnostics.push('Even zero base spending depletes the portfolio or breaks the estate floor.');
+            return finish(null, upper);
+        }
+        if (simulationCount >= maxSimulations) {
+            diagnostics.push('Simulation budget exhausted before any feasible spending level was found.');
+            return finish(null, upper);
+        }
+        if (probe(0).feasible) {
+            lower = 0;
+        }
+        else {
+            diagnostics.push('Even zero base spending depletes the portfolio or breaks the estate floor.');
+            return finish(null, upper);
+        }
+    }
+    // Bisect the bracket down to the requested resolution.
+    while (lower !== null &&
+        upper !== null &&
+        upper - lower > resolutionDollars &&
+        simulationCount < maxSimulations) {
+        const mid = Math.round((lower + upper) / 2);
+        if (mid === lower || mid === upper)
+            break;
+        if (probe(mid).feasible)
+            lower = mid;
+        else
+            upper = mid;
+    }
+    return finish(lower, upper);
+}

package/dist/decisions/spiaQuotes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Sourced default SPIA payout-rate table (annuity-pension-and-home-equity
+ * decisions, step 2).
+ *
+ * Approximate single-life immediate-annuity annual payout rates (fraction of
+ * premium per year, life-only) by start age — compiled from public quote
+ * aggregators (Blueprint-Income-style annuity marketplaces and insurer
+ * calculators, mid-2026 rates). Planning defaults only: RetireGolden never
+ * fetches live quotes; a user-entered quote always wins. Linear interpolation
+ * between anchors; clamped outside the table.
+ *
+ * Refresh with the annual parameter packs (DOCS/maintenance-schedule.md).
+ */
+/** Annual life-only SPIA payout rate (fraction of premium) at `startAge`. */
+export declare function spiaPayoutRate(startAge: number): number;
+/**
+ * Approximate deferred-QLAC annual payout rate (fraction of premium) for a
+ * purchase today starting at 80–85: deferral compounds mortality credits well
+ * above immediate rates. Same public-quote provenance as the SPIA table.
+ */
+export declare const QLAC_DEFERRED_PAYOUT_RATE = 0.16;