@retiregolden/engine 0.1.0

package/dist/decisions/decisionFixtures.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Named fixture plans for the ledger-native decision engine test suite
+ * (enhancement doc "Testing Strategy"). Test-only helper — not exported from
+ * the module index, so it never reaches the app bundle.
+ *
+ * Fixtures deliberately use flat inflation/returns so tests can reason about
+ * bracket, taxability, and basis effects without market noise.
+ */
+import { type Plan } from '../model/plan.js';
+import type { SimulateOptions } from '../projection/simulate.js';
+export declare const testIds: () => string;
+export declare const fixedNow: () => Date;
+export declare function validate(plan: Plan): Plan;
+export declare function simOptions(): SimulateOptions;
+/** Mostly traditional with a cash/taxable bridge: ripe for bracket-fill conversions. */
+export declare function tradHeavyPlan(): Plan;
+/** No traditional at all — every conversion candidate should execute $0 and stay non-beneficial. */
+export declare function noTraditionalPlan(): Plan;
+/** Inherited-only traditional: distributable under the 10-year rule but never convertible. */
+export declare function inheritedOnlyPlan(): Plan;
+/** Own plus inherited traditional: only the own balance is convertible. */
+export declare function mixedTraditionalPlan(): Plan;
+/** Late-career accumulator with scheduled contributions and an employer match. */
+export declare function accumulatorPlan(): Plan;
+/**
+ * Early retiree bridging on a taxable brokerage: spending is funded by selling
+ * shares, so candidate evaluation must price the realized gains implied by the
+ * account's basis ratio.
+ */
+export declare function taxableBridgePlan(basis: 'high' | 'low'): Plan;
+/**
+ * Social Security taxability edge: SS starts mid-horizon (claim at 70), so an
+ * identical conversion is priced differently before vs during benefit years —
+ * the provisional-income feedback only the exact ledger knows.
+ */
+export declare function ssTaxabilityPlan(): Plan;
+/** Lumpy one-time ordinary income in 2028 that stacks under any conversion that year. */
+export declare function oneTimeIncomePlan(): Plan;
+/**
+ * Asset-location fixture (asset-allocation-and-return-model-v2, step 5): a
+ * bond-heavy allocated brokerage next to a stock-heavy-capable traditional and
+ * Roth, where *where* classes are held changes the after-tax estate — bonds
+ * throw ordinary interest in taxable and inflate the heir-taxed traditional
+ * balance when they grow there instead.
+ */
+export declare function assetLocationPlan(): Plan;
+/** Married couple where the second spouse's earlier planning age creates survivor years. */
+export declare function survivorPlan(): Plan;

package/dist/decisions/decisionFixtures.js

@@ -0,0 +1,253 @@
+/**
+ * Named fixture plans for the ledger-native decision engine test suite
+ * (enhancement doc "Testing Strategy"). Test-only helper — not exported from
+ * the module index, so it never reaches the app bundle.
+ *
+ * Fixtures deliberately use flat inflation/returns so tests can reason about
+ * bracket, taxability, and basis effects without market noise.
+ */
+import { createEmptyPlan, parsePlan } from '../model/plan.js';
+import { createFederalTaxCalculator } from '../tax/federalTax.js';
+let counter = 0;
+export const testIds = () => `dec-${++counter}`;
+export const fixedNow = () => new Date('2026-06-11T00:00:00.000Z');
+export function validate(plan) {
+    const parsed = parsePlan(plan);
+    if (!parsed.ok)
+        throw new Error(parsed.issues.join('; '));
+    return parsed.plan;
+}
+export function simOptions() {
+    return { startYear: 2026, taxCalculator: createFederalTaxCalculator() };
+}
+function base(personOverrides = {}) {
+    const plan = createEmptyPlan({ newId: testIds, now: fixedNow });
+    plan.household.people[0] = {
+        id: 'p1',
+        name: 'Pat',
+        dob: '1958-06-15', // 68 in 2026; RMDs from 73
+        sex: 'average',
+        retirementAge: 65,
+        longevity: { planningAge: 85, source: 'manual' },
+        ...personOverrides,
+    };
+    plan.assumptions.inflationPct = 0;
+    plan.assumptions.healthcareExtraInflationPct = 0;
+    plan.assumptions.defaultReturnPct = 0;
+    plan.assumptions.stateEffectiveTaxPct = 0;
+    plan.assumptions.heirTaxRatePct = 25;
+    plan.expenses.baseAnnual = 0;
+    plan.expenses.healthcare = { pre65MonthlyPremiumPerPerson: 0, applyAcaCredit: false, medicareExtrasMonthlyPerPerson: 0 };
+    return plan;
+}
+/** Mostly traditional with a cash/taxable bridge: ripe for bracket-fill conversions. */
+export function tradHeavyPlan() {
+    const plan = base();
+    plan.assumptions.defaultReturnPct = 4;
+    plan.expenses.baseAnnual = 45_000;
+    plan.accounts = [
+        { type: 'traditional', id: testIds(), name: '401k', ownerPersonId: 'p1', annualReturnPct: null, kind: 'ira', balance: 800_000, annualContribution: 0 },
+        { type: 'roth', id: testIds(), name: 'Roth', ownerPersonId: 'p1', annualReturnPct: null, kind: 'ira', balance: 0, annualContribution: 0 },
+        { type: 'taxable', id: testIds(), name: 'Brokerage', ownerPersonId: null, annualReturnPct: null, balance: 150_000, costBasis: 150_000, annualContribution: 0 },
+        { type: 'cash', id: testIds(), name: 'Cash', ownerPersonId: null, annualReturnPct: null, balance: 60_000, annualContribution: 0 },
+    ];
+    return validate(plan);
+}
+/** No traditional at all — every conversion candidate should execute $0 and stay non-beneficial. */
+export function noTraditionalPlan() {
+    const plan = base();
+    plan.expenses.baseAnnual = 30_000;
+    plan.accounts = [
+        { type: 'roth', id: testIds(), name: 'Roth', ownerPersonId: 'p1', annualReturnPct: 0, kind: 'ira', balance: 250_000, annualContribution: 0 },
+        { type: 'taxable', id: testIds(), name: 'Brokerage', ownerPersonId: null, annualReturnPct: 0, balance: 400_000, costBasis: 400_000, annualContribution: 0 },
+        { type: 'cash', id: testIds(), name: 'Cash', ownerPersonId: null, annualReturnPct: 0, balance: 50_000, annualContribution: 0 },
+    ];
+    return validate(plan);
+}
+/** Inherited-only traditional: distributable under the 10-year rule but never convertible. */
+export function inheritedOnlyPlan() {
+    const plan = base({ dob: '1960-01-01', longevity: { planningAge: 70, source: 'manual' } });
+    plan.accounts = [
+        {
+            type: 'traditional',
+            id: testIds(),
+            name: 'Inherited IRA',
+            ownerPersonId: 'p1',
+            annualReturnPct: 0,
+            kind: 'ira',
+            balance: 300_000,
+            annualContribution: 0,
+            inherited: { ownerDeathYear: 2024, decedentHadStartedRmds: false },
+        },
+        { type: 'roth', id: testIds(), name: 'Roth', ownerPersonId: 'p1', annualReturnPct: 0, kind: 'ira', balance: 0, annualContribution: 0 },
+        { type: 'cash', id: testIds(), name: 'Cash', ownerPersonId: null, annualReturnPct: 0, balance: 40_000, annualContribution: 0 },
+    ];
+    return validate(plan);
+}
+/** Own plus inherited traditional: only the own balance is convertible. */
+export function mixedTraditionalPlan() {
+    const plan = inheritedOnlyPlan();
+    return validate({
+        ...plan,
+        accounts: [
+            { type: 'traditional', id: testIds(), name: 'Own IRA', ownerPersonId: 'p1', annualReturnPct: 0, kind: 'ira', balance: 200_000, annualContribution: 0 },
+            ...plan.accounts,
+        ],
+    });
+}
+/** Late-career accumulator with scheduled contributions and an employer match. */
+export function accumulatorPlan() {
+    const plan = base({ dob: '1971-01-01', retirementAge: 62, longevity: { planningAge: 80, source: 'manual' } });
+    plan.expenses.baseAnnual = 50_000;
+    plan.accounts = [
+        {
+            type: 'traditional',
+            id: testIds(),
+            name: '401k',
+            ownerPersonId: 'p1',
+            annualReturnPct: 0,
+            kind: 'employer',
+            balance: 100_000,
+            annualContribution: 20_000,
+            employerMatch: { matchPct: 50, capPctOfPay: 6 },
+        },
+        { type: 'roth', id: testIds(), name: 'Roth', ownerPersonId: 'p1', annualReturnPct: 0, kind: 'ira', balance: 0, annualContribution: 0 },
+        { type: 'cash', id: testIds(), name: 'Cash', ownerPersonId: null, annualReturnPct: 0, balance: 50_000, annualContribution: 0 },
+    ];
+    plan.incomes = [
+        { type: 'wages', id: testIds(), personId: 'p1', annualGross: 150_000, endAge: null, realGrowthPct: 0 },
+        { type: 'socialSecurity', id: testIds(), personId: 'p1', piaMonthly: 2_500, earnings: null, claimAge: { years: 67, months: 0 } },
+    ];
+    return validate(plan);
+}
+/**
+ * Early retiree bridging on a taxable brokerage: spending is funded by selling
+ * shares, so candidate evaluation must price the realized gains implied by the
+ * account's basis ratio.
+ */
+export function taxableBridgePlan(basis) {
+    const plan = base({ dob: '1966-01-01', retirementAge: 60, longevity: { planningAge: 80, source: 'manual' } });
+    plan.expenses.baseAnnual = 60_000;
+    plan.accounts = [
+        { type: 'traditional', id: testIds(), name: 'IRA', ownerPersonId: 'p1', annualReturnPct: 0, kind: 'ira', balance: 400_000, annualContribution: 0 },
+        { type: 'roth', id: testIds(), name: 'Roth', ownerPersonId: 'p1', annualReturnPct: 0, kind: 'ira', balance: 0, annualContribution: 0 },
+        {
+            type: 'taxable',
+            id: testIds(),
+            name: 'Brokerage',
+            ownerPersonId: null,
+            annualReturnPct: 0,
+            balance: 600_000,
+            costBasis: basis === 'high' ? 580_000 : 120_000,
+            annualContribution: 0,
+        },
+        { type: 'cash', id: testIds(), name: 'Cash', ownerPersonId: null, annualReturnPct: 0, balance: 5_000, annualContribution: 0 },
+    ];
+    plan.incomes = [
+        { type: 'socialSecurity', id: testIds(), personId: 'p1', piaMonthly: 2_800, earnings: null, claimAge: { years: 70, months: 0 } },
+    ];
+    return validate(plan);
+}
+/**
+ * Social Security taxability edge: SS starts mid-horizon (claim at 70), so an
+ * identical conversion is priced differently before vs during benefit years —
+ * the provisional-income feedback only the exact ledger knows.
+ */
+export function ssTaxabilityPlan() {
+    const plan = base({ dob: '1964-01-01', retirementAge: 62, longevity: { planningAge: 85, source: 'manual' } });
+    plan.expenses.baseAnnual = 30_000;
+    plan.accounts = [
+        { type: 'traditional', id: testIds(), name: 'IRA', ownerPersonId: 'p1', annualReturnPct: 0, kind: 'ira', balance: 400_000, annualContribution: 0 },
+        { type: 'roth', id: testIds(), name: 'Roth', ownerPersonId: 'p1', annualReturnPct: 0, kind: 'ira', balance: 0, annualContribution: 0 },
+        { type: 'cash', id: testIds(), name: 'Cash', ownerPersonId: null, annualReturnPct: 0, balance: 500_000, annualContribution: 0 },
+    ];
+    plan.incomes = [
+        { type: 'socialSecurity', id: testIds(), personId: 'p1', piaMonthly: 3_000, earnings: null, claimAge: { years: 70, months: 0 } },
+    ];
+    return validate(plan);
+}
+/** Lumpy one-time ordinary income in 2028 that stacks under any conversion that year. */
+export function oneTimeIncomePlan() {
+    const plan = base({ dob: '1960-01-01', longevity: { planningAge: 72, source: 'manual' } });
+    plan.accounts = [
+        { type: 'traditional', id: testIds(), name: 'IRA', ownerPersonId: 'p1', annualReturnPct: 0, kind: 'ira', balance: 300_000, annualContribution: 0 },
+        { type: 'roth', id: testIds(), name: 'Roth', ownerPersonId: 'p1', annualReturnPct: 0, kind: 'ira', balance: 0, annualContribution: 0 },
+        { type: 'cash', id: testIds(), name: 'Cash', ownerPersonId: null, annualReturnPct: 0, balance: 250_000, annualContribution: 0 },
+    ];
+    plan.incomes = [
+        { type: 'oneTime', id: testIds(), label: 'Deferred comp payout', year: 2028, amount: 80_000, taxTreatment: 'ordinary' },
+    ];
+    return validate(plan);
+}
+/**
+ * Asset-location fixture (asset-allocation-and-return-model-v2, step 5): a
+ * bond-heavy allocated brokerage next to a stock-heavy-capable traditional and
+ * Roth, where *where* classes are held changes the after-tax estate — bonds
+ * throw ordinary interest in taxable and inflate the heir-taxed traditional
+ * balance when they grow there instead.
+ */
+export function assetLocationPlan() {
+    const plan = base({ dob: '1961-06-15', longevity: { planningAge: 90, source: 'manual' } });
+    plan.expenses.baseAnnual = 40_000;
+    const weights5050 = { usStocks: 50, intlStocks: 0, bonds: 50, cash: 0 };
+    plan.accounts = [
+        {
+            type: 'taxable',
+            id: testIds(),
+            name: 'Brokerage',
+            ownerPersonId: null,
+            annualReturnPct: null,
+            balance: 500_000,
+            costBasis: 350_000,
+            annualContribution: 0,
+            allocation: { mode: 'static', rebalancing: 'annual', weights: weights5050 },
+        },
+        {
+            type: 'traditional',
+            id: testIds(),
+            name: 'IRA',
+            ownerPersonId: 'p1',
+            annualReturnPct: null,
+            kind: 'ira',
+            balance: 500_000,
+            annualContribution: 0,
+            allocation: { mode: 'static', rebalancing: 'annual', weights: weights5050 },
+        },
+        {
+            type: 'roth',
+            id: testIds(),
+            name: 'Roth',
+            ownerPersonId: 'p1',
+            annualReturnPct: null,
+            kind: 'ira',
+            balance: 200_000,
+            annualContribution: 0,
+            allocation: { mode: 'static', rebalancing: 'annual', weights: weights5050 },
+        },
+        { type: 'cash', id: testIds(), name: 'Cash', ownerPersonId: null, annualReturnPct: 0, balance: 60_000, annualContribution: 0 },
+    ];
+    plan.incomes = [
+        { type: 'socialSecurity', id: testIds(), personId: 'p1', piaMonthly: 2_400, earnings: null, claimAge: { years: 67, months: 0 } },
+    ];
+    return validate(plan);
+}
+/** Married couple where the second spouse's earlier planning age creates survivor years. */
+export function survivorPlan() {
+    const plan = base({ dob: '1960-01-01', longevity: { planningAge: 90, source: 'manual' } });
+    plan.household.filingStatus = 'marriedFilingJointly';
+    plan.household.people.push({
+        id: 'p2',
+        name: 'Sam',
+        dob: '1958-01-01',
+        sex: 'average',
+        retirementAge: 65,
+        longevity: { planningAge: 78, source: 'manual' },
+    });
+    plan.expenses.baseAnnual = 40_000;
+    plan.accounts = [
+        { type: 'traditional', id: testIds(), name: 'IRA', ownerPersonId: 'p1', annualReturnPct: 0, kind: 'ira', balance: 600_000, annualContribution: 0 },
+        { type: 'roth', id: testIds(), name: 'Roth', ownerPersonId: 'p1', annualReturnPct: 0, kind: 'ira', balance: 0, annualContribution: 0 },
+        { type: 'cash', id: testIds(), name: 'Cash', ownerPersonId: null, annualReturnPct: 0, balance: 700_000, annualContribution: 0 },
+    ];
+    return validate(plan);
+}

package/dist/decisions/evaluateCandidate.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared exact-ledger candidate evaluator (ledger-native decision engine,
+ * Phase 1).
+ *
+ * One evaluation = one deterministic `simulatePlan` run of the candidate plan,
+ * compared against a shared baseline run. All recommendation surfaces (Roth &
+ * Tax Optimizer validation, tournaments, Insights previews, local search) go
+ * through here so income, capital gains, Social Security taxability, ACA,
+ * IRMAA, RMD, and inherited-IRA effects are priced by the ledger exactly once
+ * — never re-derived in candidate logic.
+ */
+import type { Plan } from '../model/plan.js';
+import { type ProjectionSummary } from '../projection/compare.js';
+import type { ProjectionResult } from '../projection/types.js';
+import type { DecisionCandidate, DecisionContext, ExactDecisionEvaluation } from './types.js';
+export interface EvaluateCandidateOptions {
+    /** Dollars around zero treated as matching the baseline. */
+    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;
+    /**
+     * Reuse an already-simulated candidate result instead of re-running the
+     * ledger (e.g. the optimizer post-processor simulates schedules itself).
+     * The caller is responsible for it matching the candidate exactly.
+     */
+    candidateResult?: ProjectionResult;
+}
+export declare const DECISION_NEUTRAL_TOLERANCE_DOLLARS = 1;
+export declare const DECISION_MINIMUM_REQUESTED_CONVERSION_DOLLARS = 1;
+export declare const DECISION_MATERIAL_SHORTFALL_DOLLARS = 1000;
+export declare const DECISION_MATERIAL_SHORTFALL_PCT = 0.05;
+/** Years the money lasts: depletion year, or one past the horizon when it never depletes. */
+export declare function lastsThroughYear(result: ProjectionResult): number;
+/** Build a fresh decision context, running the shared baseline once (or reusing a caller's run). */
+export declare function createDecisionContext(plan: Plan, simulateOptions: DecisionContext['simulateOptions'], baseline?: {
+    result: ProjectionResult;
+    summary?: ProjectionSummary;
+}, taxCalculatorForPlan?: DecisionContext['taxCalculatorForPlan']): DecisionContext;
+/**
+ * Materialize the concrete plan a candidate describes: scenario patch first
+ * (validated through the plan schema), then any explicit conversion schedule
+ * installed as an `optimized` Roth strategy.
+ */
+export declare function planForCandidate(plan: Plan, candidate: Pick<DecisionCandidate, 'planPatch' | 'conversions'>): {
+    ok: true;
+    plan: Plan;
+} | {
+    ok: false;
+    error: string;
+};
+/** First year the plan's own (non-inherited) traditional balance is exhausted, or null. */
+export declare function findTraditionalDepletionYear(plan: Plan, result: ProjectionResult, toleranceDollars: number): number | null;
+/**
+ * Run one candidate through the exact ledger and compare it with the shared
+ * baseline. Deterministic: same plan + candidate + options ⇒ same evaluation.
+ */
+export declare function evaluateCandidate(ctx: DecisionContext, candidate: DecisionCandidate, options?: EvaluateCandidateOptions): ExactDecisionEvaluation;

package/dist/decisions/evaluateCandidate.js

@@ -0,0 +1,193 @@
+/**
+ * Shared exact-ledger candidate evaluator (ledger-native decision engine,
+ * Phase 1).
+ *
+ * One evaluation = one deterministic `simulatePlan` run of the candidate plan,
+ * compared against a shared baseline run. All recommendation surfaces (Roth &
+ * Tax Optimizer validation, tournaments, Insights previews, local search) go
+ * through here so income, capital gains, Social Security taxability, ACA,
+ * IRMAA, RMD, and inherited-IRA effects are priced by the ledger exactly once
+ * — never re-derived in candidate logic.
+ */
+import { applyScenarioPatch } from '../scenarios/scenarios.js';
+import { summarizeProjection } from '../projection/compare.js';
+import { simulatePlan } from '../projection/simulate.js';
+export const DECISION_NEUTRAL_TOLERANCE_DOLLARS = 1;
+export const DECISION_MINIMUM_REQUESTED_CONVERSION_DOLLARS = 1;
+export const DECISION_MATERIAL_SHORTFALL_DOLLARS = 1_000;
+export const DECISION_MATERIAL_SHORTFALL_PCT = 0.05;
+/** Years the money lasts: depletion year, or one past the horizon when it never depletes. */
+export function lastsThroughYear(result) {
+    return result.depletionYear ?? result.endYear + 1;
+}
+/** Build a fresh decision context, running the shared baseline once (or reusing a caller's run). */
+export function createDecisionContext(plan, simulateOptions, baseline, taxCalculatorForPlan) {
+    const baselineResult = baseline?.result ?? simulatePlan(plan, simulateOptions);
+    return {
+        plan,
+        baselineResult,
+        baselineSummary: baseline?.summary ?? summarizeProjection(plan, baselineResult),
+        simulateOptions,
+        taxCalculatorForPlan,
+    };
+}
+/**
+ * Materialize the concrete plan a candidate describes: scenario patch first
+ * (validated through the plan schema), then any explicit conversion schedule
+ * installed as an `optimized` Roth strategy.
+ */
+export function planForCandidate(plan, candidate) {
+    let candidatePlan = plan;
+    if (candidate.planPatch) {
+        const applied = applyScenarioPatch(plan, candidate.planPatch);
+        if (!applied.ok)
+            return { ok: false, error: `This candidate can't be applied to the plan: ${applied.issues.join('; ')}` };
+        candidatePlan = applied.plan;
+    }
+    if (candidate.conversions) {
+        candidatePlan = {
+            ...candidatePlan,
+            strategies: {
+                ...candidatePlan.strategies,
+                rothConversion: { mode: 'optimized', conversions: candidate.conversions },
+            },
+        };
+    }
+    return { ok: true, plan: candidatePlan };
+}
+function aggregateByYear(conversions) {
+    const byYear = new Map();
+    for (const conversion of conversions) {
+        byYear.set(conversion.year, (byYear.get(conversion.year) ?? 0) + conversion.amount);
+    }
+    return byYear;
+}
+function buildConversionExecution(requested, candidateResult, options) {
+    const requestedByYear = aggregateByYear(requested);
+    const requestedTotal = requested.reduce((sum, conversion) => sum + conversion.amount, 0);
+    const executedTotal = candidateResult.years.reduce((sum, year) => sum + year.rothConversion, 0);
+    let firstMateriallyUnexecutedYear = null;
+    for (const year of [...requestedByYear.keys()].sort((a, b) => a - b)) {
+        const requestedAmount = requestedByYear.get(year) ?? 0;
+        const executedAmount = candidateResult.years.find((y) => y.year === year)?.rothConversion ?? 0;
+        const materialShortfall = Math.max(options.materialConversionShortfallDollars, requestedAmount * options.materialConversionShortfallPct);
+        if (requestedAmount - executedAmount > materialShortfall) {
+            firstMateriallyUnexecutedYear = year;
+            break;
+        }
+    }
+    return {
+        requestedTotal,
+        executedTotal,
+        executedRatio: requestedTotal > 0 ? Math.min(1, executedTotal / requestedTotal) : 1,
+        firstMateriallyUnexecutedYear,
+        executedByYear: candidateResult.years
+            .filter((year) => year.rothConversion > 1)
+            .map((year) => ({ year: year.year, amount: Math.round(year.rothConversion * 100) / 100 })),
+    };
+}
+/** First year the plan's own (non-inherited) traditional balance is exhausted, or null. */
+export function findTraditionalDepletionYear(plan, result, toleranceDollars) {
+    const ownTraditionalIds = new Set(plan.accounts.filter((account) => account.type === 'traditional' && !account.inherited).map((account) => account.id));
+    if (ownTraditionalIds.size === 0)
+        return null;
+    for (const year of result.years) {
+        let balance = 0;
+        for (const accountId of ownTraditionalIds)
+            balance += year.balances[accountId] ?? 0;
+        if (balance <= toleranceDollars)
+            return year.year;
+    }
+    return null;
+}
+function classifyRecommendationState(args) {
+    if (args.afterTaxEstateDelta > args.neutralToleranceDollars)
+        return 'beneficial';
+    if (args.conversionExecution) {
+        const { requestedTotal, executedTotal } = args.conversionExecution;
+        const materialShortfall = Math.max(args.materialConversionShortfallDollars, requestedTotal * args.materialConversionShortfallPct);
+        if (requestedTotal >= args.minimumRequestedConversionDollars && requestedTotal - executedTotal > materialShortfall) {
+            return 'diagnostic';
+        }
+    }
+    if (args.afterTaxEstateDelta < -args.neutralToleranceDollars)
+        return 'rejected';
+    return 'neutral';
+}
+/** Diagnostic-only evaluation for a candidate whose patch failed plan validation. */
+function invalidCandidateEvaluation(ctx, candidate, error) {
+    return {
+        candidate,
+        baselineSummary: ctx.baselineSummary,
+        candidateSummary: ctx.baselineSummary,
+        candidateResult: ctx.baselineResult,
+        deltas: { endingAfterTaxEstate: 0, endingNetWorth: 0, lifetimeTax: 0, moneyLastsYears: 0 },
+        conversionExecution: null,
+        traditionalDepletionYear: null,
+        diagnostics: [error],
+        recommendationState: 'diagnostic',
+    };
+}
+/**
+ * Run one candidate through the exact ledger and compare it with the shared
+ * baseline. Deterministic: same plan + candidate + options ⇒ same evaluation.
+ */
+export function evaluateCandidate(ctx, candidate, options = {}) {
+    const neutralToleranceDollars = options.neutralToleranceDollars ?? DECISION_NEUTRAL_TOLERANCE_DOLLARS;
+    const minimumRequestedConversionDollars = options.minimumRequestedConversionDollars ?? DECISION_MINIMUM_REQUESTED_CONVERSION_DOLLARS;
+    const materialConversionShortfallDollars = options.materialConversionShortfallDollars ?? DECISION_MATERIAL_SHORTFALL_DOLLARS;
+    const materialConversionShortfallPct = options.materialConversionShortfallPct ?? DECISION_MATERIAL_SHORTFALL_PCT;
+    const built = planForCandidate(ctx.plan, candidate);
+    if (!built.ok)
+        return invalidCandidateEvaluation(ctx, candidate, built.error);
+    // A patch may change tax assumptions (e.g. a relocation candidate clearing
+    // the flat state-rate override); when the context carries a per-plan tax
+    // stack factory, price the candidate with its own stack.
+    const candidateSimulateOptions = ctx.taxCalculatorForPlan
+        ? { ...ctx.simulateOptions, taxCalculator: ctx.taxCalculatorForPlan(built.plan) }
+        : ctx.simulateOptions;
+    const candidateResult = options.candidateResult ?? simulatePlan(built.plan, candidateSimulateOptions);
+    const candidateSummary = summarizeProjection(built.plan, candidateResult);
+    const conversionExecution = candidate.conversions
+        ? buildConversionExecution(candidate.conversions, candidateResult, {
+            materialConversionShortfallDollars,
+            materialConversionShortfallPct,
+        })
+        : null;
+    const deltas = {
+        endingAfterTaxEstate: candidateSummary.endingAfterTaxEstate - ctx.baselineSummary.endingAfterTaxEstate,
+        endingNetWorth: candidateSummary.endingNetWorth - ctx.baselineSummary.endingNetWorth,
+        lifetimeTax: candidateSummary.lifetimeTaxesAndPenalties - ctx.baselineSummary.lifetimeTaxesAndPenalties,
+        moneyLastsYears: lastsThroughYear(candidateResult) - lastsThroughYear(ctx.baselineResult),
+    };
+    const diagnostics = [];
+    if (conversionExecution && conversionExecution.firstMateriallyUnexecutedYear !== null) {
+        diagnostics.push(`Your plan could not execute the requested conversion in ${conversionExecution.firstMateriallyUnexecutedYear}: ` +
+            `requested $${Math.round(conversionExecution.requestedTotal).toLocaleString()} in total, ` +
+            `executed $${Math.round(conversionExecution.executedTotal).toLocaleString()}.`);
+    }
+    if (deltas.moneyLastsYears < 0) {
+        diagnostics.push(`Money lasts ${-deltas.moneyLastsYears} year(s) less than the baseline.`);
+    }
+    if (candidateResult.depletionYear !== null && ctx.baselineResult.depletionYear === null) {
+        diagnostics.push(`Introduces portfolio depletion in ${candidateResult.depletionYear}.`);
+    }
+    return {
+        candidate,
+        baselineSummary: ctx.baselineSummary,
+        candidateSummary,
+        candidateResult,
+        deltas,
+        conversionExecution,
+        traditionalDepletionYear: findTraditionalDepletionYear(built.plan, candidateResult, neutralToleranceDollars),
+        diagnostics,
+        recommendationState: classifyRecommendationState({
+            afterTaxEstateDelta: deltas.endingAfterTaxEstate,
+            conversionExecution,
+            neutralToleranceDollars,
+            minimumRequestedConversionDollars,
+            materialConversionShortfallDollars,
+            materialConversionShortfallPct,
+        }),
+    };
+}

package/dist/decisions/generators.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Normalized candidate generators (ledger-native decision engine, Phase 2).
+ *
+ * Every recommendation source is a `CandidateGenerator`: pure, bounded, and
+ * fast — no simulate() calls, just concrete plan patches or conversion
+ * schedules. Generation never decides whether something is recommended; the
+ * exact-ledger evaluation does.
+ */
+import type { OptimizedSchedule } from '../strategies/optimizer.js';
+import type { CandidateGenerator, DecisionCandidate } from './types.js';
+/**
+ * The simple fill-to-target Roth strategies of the bounded tournament: bracket
+ * fills, the ACA cliff cap, and the first IRMAA tier cap over the whole
+ * horizon, plus *windowed* bracket fills that stop at income boundaries (SS
+ * claim / RMD start) — under a sequential withdrawal order, spending draws fill
+ * the cheap brackets themselves once cash/taxable deplete or income starts, so
+ * "fill high early, then stop" beats any whole-horizon fill on bridge-shaped
+ * plans. Generated unconditionally — a plan with no convertible traditional
+ * simply executes $0 and evaluates neutral.
+ */
+export declare const simpleRothConversionGenerator: CandidateGenerator;
+/** The do-nothing alternative, only meaningful when the plan currently converts. */
+export declare const noConversionGenerator: CandidateGenerator;
+/** Withdrawal-order alternatives to whatever the plan currently uses. */
+export declare const withdrawalOrderGenerator: CandidateGenerator;
+export interface ProbabilityBandSpendingGuardrailOptions {
+    /** Floor as a percent of target annual spending when the plan has no floor yet. */
+    requiredFloorPct?: number;
+    /** Lower Monte Carlo success band the candidate is meant to defend. */
+    lowerSuccessPct?: number;
+    /** Upper Monte Carlo success band where raises/upside become available. */
+    upperSuccessPct?: number;
+}
+/**
+ * Probability-band safe-spend guardrail candidates. Generation is deliberately
+ * pure: the candidate carries the success band as metadata and a concrete
+ * ledger-native guardrail patch; exact/stochastic surfaces can then evaluate it
+ * through the shared decision and Monte Carlo runners without private models.
+ */
+export declare function probabilityBandSpendingGuardrailGenerator(options?: ProbabilityBandSpendingGuardrailOptions): CandidateGenerator;
+/**
+ * Bounded Social Security claim-age candidates: for up to two SS streams, the
+ * three canonical claim ages (62 / FRA / 70) that differ from the current
+ * claim. Each candidate replaces the whole incomes array (scenario patches
+ * replace arrays wholesale, keeping the patch order-safe).
+ */
+export declare const socialSecurityClaimGenerator: CandidateGenerator;
+/**
+ * Asset-location candidates (asset-allocation-and-return-model-v2, step 5).
+ *
+ * Proposes swapping *where* classes are held while leaving the household's
+ * total dollars in each class unchanged: bonds move toward traditional
+ * (sheltering their ordinary-income yield and slowing the RMD/heir-taxed
+ * balance), US stocks move toward taxable (qualified dividends + basis
+ * machinery) or Roth (sheltering the highest expected growth). Swaps pair the
+ * largest eligible static-allocation accounts and are expressed as plan
+ * patches over the accounts array; the exact ledger prices every candidate —
+ * generation never decides. Bounded: at most 3 candidates.
+ */
+export declare const assetLocationGenerator: CandidateGenerator;
+/**
+ * Full Social Security claiming grid for the optimizer page: every whole-year
+ * claim combination from 62-70 (respecting current age) for up to two claiming
+ * streams. When a stream's current claim age is a whole year within range, that
+ * combination reproduces the current plan; a current claim age with months, below
+ * 62, above 70, or already past is not emitted here. Bounded: 9 single-person
+ * candidates or 81 couple candidates.
+ */
+export declare const socialSecurityClaimGridGenerator: CandidateGenerator;
+/**
+ * Wrap MILP optimizer output (raw and post-processed schedules) as candidates.
+ * The solver is one candidate generator among several — never the authority.
+ */
+export declare function milpScheduleGenerator(schedules: {
+    raw?: OptimizedSchedule | null;
+    cleanedConversions?: Array<{
+        year: number;
+        amount: number;
+    }> | null;
+}): CandidateGenerator;
+/**
+ * Annuity purchase candidates (guaranteed-income-and-estate-depth, step 6;
+ * ladders added by annuity-pension-and-home-equity, step 1): no purchase /
+ * cover-the-floor SPIA / a laddered version of the same SPIA (three dated
+ * tranches, so rising age-payout rates and shorter rate lock-in are priced) /
+ * QLAC at the cap. Each is a concrete, bounded plan patch that adds (or
+ * removes) annuity purchases; the exact ledger prices the liquidity ↓ /
+ * durability ↑ / estate Δ tradeoff — generation never decides. Bounded: at
+ * most four candidates. Payout rates come from the sourced default table in
+ * ./spiaQuotes (user-entered purchases carry their own quotes).
+ */
+export declare const annuityPurchaseGenerator: CandidateGenerator;
+/**
+ * Social Security bridge / TIPS-ladder candidates
+ * (social-security-bridge-and-tips-ladder, step 3): fund the gap years between
+ * retirement and each claimant's chosen claim age with a TIPS bridge ladder
+ * paying the forgone age-62 benefit, purchased from the largest liquid
+ * account; plus the remove-the-ladders alternative when the plan already has
+ * some. Bounded (≤ one bridge per person + one removal); the exact ledger
+ * prices the liquidity ↓ / durability ↑ tradeoff — generation never decides.
+ */
+export declare const bridgeLadderGenerator: CandidateGenerator;
+/** Wrap a modelable Insights detector action as a decision candidate generator. */
+export declare function insightActionGenerator(args: {
+    id: string;
+    category: DecisionCandidate['category'];
+    label: string;
+    explanation: string;
+    planPatch: Record<string, unknown>;
+}): CandidateGenerator;