@retiregolden/engine 0.1.0

package/dist/decisions/spiaQuotes.js

@@ -0,0 +1,43 @@
+/**
+ * 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).
+ */
+const SPIA_PAYOUT_POINTS = [
+    [60, 0.055],
+    [65, 0.061],
+    [70, 0.069],
+    [75, 0.079],
+    [80, 0.093],
+    [85, 0.11],
+];
+/** Annual life-only SPIA payout rate (fraction of premium) at `startAge`. */
+export function spiaPayoutRate(startAge) {
+    const points = SPIA_PAYOUT_POINTS;
+    if (startAge <= points[0][0])
+        return points[0][1];
+    const last = points[points.length - 1];
+    if (startAge >= last[0])
+        return last[1];
+    for (let i = 0; i < points.length - 1; i++) {
+        const [a0, r0] = points[i];
+        const [a1, r1] = points[i + 1];
+        if (startAge >= a0 && startAge <= a1)
+            return r0 + ((r1 - r0) * (startAge - a0)) / (a1 - a0);
+    }
+    return last[1];
+}
+/**
+ * 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 const QLAC_DEFERRED_PAYOUT_RATE = 0.16;

package/dist/decisions/stochastic.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Optional stochastic attachments for exact-ledger decision evaluations.
+ *
+ * Deterministic evaluation remains the default authority. Callers opt into this
+ * helper when a policy explicitly ranks candidates by same-path Monte Carlo
+ * resilience.
+ */
+import { type SharedPathComparisonOptions } from '../montecarlo/sharedPaths.js';
+import type { DecisionContext, ExactDecisionEvaluation } from './types.js';
+export type AttachStochasticMetricsOptions = SharedPathComparisonOptions;
+export declare function attachStochasticMetrics(ctx: DecisionContext, evaluations: ExactDecisionEvaluation[], opts: AttachStochasticMetricsOptions): ExactDecisionEvaluation[];

package/dist/decisions/stochastic.js

@@ -0,0 +1,66 @@
+/**
+ * Optional stochastic attachments for exact-ledger decision evaluations.
+ *
+ * Deterministic evaluation remains the default authority. Callers opt into this
+ * helper when a policy explicitly ranks candidates by same-path Monte Carlo
+ * resilience.
+ */
+import { comparePlansOnSharedMarketPaths, } from '../montecarlo/sharedPaths.js';
+import { planForCandidate } from './evaluateCandidate.js';
+function metricsFromSummary(summary, seed) {
+    return {
+        pathCount: summary.pathCount,
+        seed,
+        successRate: summary.successRate,
+        requiredFloorSuccessRate: summary.requiredFloorSuccessRate,
+        targetLifestyleSuccessRate: summary.targetLifestyleSuccessRate,
+        p10EndingAfterTaxEstate: summary.endingAfterTaxEstate.percentiles.p10,
+        medianEndingAfterTaxEstate: summary.endingAfterTaxEstate.percentiles.p50,
+        expectedShortfallDollars: summary.downsideRisk.expectedShortfallDollars,
+        averageTargetShortfallDollars: summary.spendingShortfall.averageTargetShortfallDollars,
+    };
+}
+function attachment(baseline, candidate) {
+    return {
+        baseline,
+        candidate,
+        deltas: {
+            successRate: candidate.successRate - baseline.successRate,
+            requiredFloorSuccessRate: candidate.requiredFloorSuccessRate - baseline.requiredFloorSuccessRate,
+            targetLifestyleSuccessRate: candidate.targetLifestyleSuccessRate - baseline.targetLifestyleSuccessRate,
+            p10EndingAfterTaxEstate: candidate.p10EndingAfterTaxEstate - baseline.p10EndingAfterTaxEstate,
+            medianEndingAfterTaxEstate: candidate.medianEndingAfterTaxEstate - baseline.medianEndingAfterTaxEstate,
+            expectedShortfallDollars: candidate.expectedShortfallDollars - baseline.expectedShortfallDollars,
+            averageTargetShortfallDollars: candidate.averageTargetShortfallDollars - baseline.averageTargetShortfallDollars,
+        },
+    };
+}
+export function attachStochasticMetrics(ctx, evaluations, opts) {
+    const materialized = [
+        { evaluation: null, entry: { id: 'baseline', label: 'Current plan', plan: ctx.plan } },
+    ];
+    for (const evaluation of evaluations) {
+        const built = planForCandidate(ctx.plan, evaluation.candidate);
+        if (!built.ok)
+            continue;
+        materialized.push({
+            evaluation,
+            entry: { id: evaluation.candidate.id, label: evaluation.candidate.label, plan: built.plan },
+        });
+    }
+    const comparison = comparePlansOnSharedMarketPaths(materialized.map((item) => item.entry), opts);
+    const baselineSummary = comparison.rows.find((row) => row.id === 'baseline')?.summary;
+    if (!baselineSummary)
+        return evaluations;
+    const baseline = metricsFromSummary(baselineSummary, opts.seed);
+    const rowById = new Map(comparison.rows.map((row) => [row.id, row.summary]));
+    for (const item of materialized) {
+        if (!item.evaluation)
+            continue;
+        const summary = rowById.get(item.entry.id);
+        if (!summary)
+            continue;
+        item.evaluation.stochastic = attachment(baseline, metricsFromSummary(summary, opts.seed));
+    }
+    return evaluations;
+}

package/dist/decisions/swrComparator.d.ts

@@ -0,0 +1,54 @@
+/**
+ * "Whose 4% rule?" comparator (spending-paths & SWR-lenses plan, Goal 3).
+ *
+ * Runs the currently-argued published safe-withdrawal-rate parameterizations
+ * on the user's own plan — not a generic 60/40 backtest — through the same
+ * deterministic exact ledger Results uses, so every rule prices taxes, ACA/
+ * IRMAA cliffs, healthcare, debts, and survivor years identically (same-path
+ * by construction). Presented as "published rules of thumb vs this plan's
+ * solver": each rule sets a constant-real initial spending level from the
+ * starting investable balance, which is the rules' own definition; none of
+ * them is "the answer" — the plan's solver is the plan-specific number.
+ *
+ * Parameterizations (each per its citation):
+ * - Bengen 2025: 4.7% — William Bengen, *A Richer Retirement* (Aug 2025);
+ *   SAFEMAX raised from 4.15% to ~4.7% with a seven-asset-class portfolio.
+ * - Morningstar 2026: 3.9% — Morningstar's *State of Retirement Income*
+ *   (2025 edition, for 2026 retirees; 30-year horizon, 90% success).
+ * - ERN CAPE: 1.75% + 0.5 × CAEY — Early Retirement Now's CAPE-based rule
+ *   (SWR series part 18), CAEY = 100/CAPE; conditions the rate on valuations.
+ */
+import type { Plan } from '../model/plan.js';
+import { type SimulateOptions } from '../projection/simulate.js';
+export type SwrRuleId = 'bengen-2025' | 'morningstar-2026' | 'ern-cape';
+/** Default CAPE for the ERN rule; matches the CAPE market-model default. */
+export declare const SWR_DEFAULT_CAPE = 25;
+export interface SwrRuleSpec {
+    id: SwrRuleId;
+    label: string;
+    /** One-line source citation shown with the number. */
+    citation: string;
+    initialRatePct: (cape: number) => number;
+}
+export declare const SWR_RULES: readonly SwrRuleSpec[];
+export interface SwrRuleResult {
+    id: SwrRuleId;
+    label: string;
+    citation: string;
+    initialRatePct: number;
+    /** rate × starting investable balance — the rule's spending level (today's $). */
+    initialAnnualSpend: number;
+    /** Exact-ledger outcome of spending that level constant-real on this plan. */
+    depletionYear: number | null;
+    endYear: number;
+    endingAfterTaxEstate: number;
+    lifetimeTaxesAndPenalties: number;
+}
+/**
+ * Price every published rule on the user's plan with one deterministic ledger
+ * run each. The variant plan spends the rule's level constant-real (phases
+ * cleared — the rules are defined constant-real) with any dynamic spending
+ * policy removed; everything else (accounts, taxes, healthcare, goals,
+ * horizon) is the user's own.
+ */
+export declare function compareSwrRules(plan: Plan, opts: SimulateOptions, cape?: number): SwrRuleResult[];

package/dist/decisions/swrComparator.js

@@ -0,0 +1,89 @@
+/**
+ * "Whose 4% rule?" comparator (spending-paths & SWR-lenses plan, Goal 3).
+ *
+ * Runs the currently-argued published safe-withdrawal-rate parameterizations
+ * on the user's own plan — not a generic 60/40 backtest — through the same
+ * deterministic exact ledger Results uses, so every rule prices taxes, ACA/
+ * IRMAA cliffs, healthcare, debts, and survivor years identically (same-path
+ * by construction). Presented as "published rules of thumb vs this plan's
+ * solver": each rule sets a constant-real initial spending level from the
+ * starting investable balance, which is the rules' own definition; none of
+ * them is "the answer" — the plan's solver is the plan-specific number.
+ *
+ * Parameterizations (each per its citation):
+ * - Bengen 2025: 4.7% — William Bengen, *A Richer Retirement* (Aug 2025);
+ *   SAFEMAX raised from 4.15% to ~4.7% with a seven-asset-class portfolio.
+ * - Morningstar 2026: 3.9% — Morningstar's *State of Retirement Income*
+ *   (2025 edition, for 2026 retirees; 30-year horizon, 90% success).
+ * - ERN CAPE: 1.75% + 0.5 × CAEY — Early Retirement Now's CAPE-based rule
+ *   (SWR series part 18), CAEY = 100/CAPE; conditions the rate on valuations.
+ */
+import { startingInvestableOf } from '../montecarlo/riskBasedGuardrails.js';
+import { summarizeProjection } from '../projection/compare.js';
+import { simulatePlan } from '../projection/simulate.js';
+/** Default CAPE for the ERN rule; matches the CAPE market-model default. */
+export const SWR_DEFAULT_CAPE = 25;
+export const SWR_RULES = [
+    {
+        id: 'bengen-2025',
+        label: 'Bengen 4.7%',
+        citation: 'William Bengen, A Richer Retirement (2025): SAFEMAX ≈ 4.7% with seven asset classes, 30-year horizon.',
+        initialRatePct: () => 4.7,
+    },
+    {
+        id: 'morningstar-2026',
+        label: 'Morningstar 3.9%',
+        citation: 'Morningstar, State of Retirement Income (2025, for 2026 retirees): 3.9% starting rate, 30 years, 90% success.',
+        initialRatePct: () => 3.9,
+    },
+    {
+        id: 'ern-cape',
+        label: 'ERN CAPE rule',
+        citation: 'Early Retirement Now, SWR series part 18: SWR = 1.75% + 0.5 × (100 ÷ CAPE).',
+        initialRatePct: (cape) => 1.75 + 0.5 * (100 / cape),
+    },
+];
+/**
+ * Price every published rule on the user's plan with one deterministic ledger
+ * run each. The variant plan spends the rule's level constant-real (phases
+ * cleared — the rules are defined constant-real) with any dynamic spending
+ * policy removed; everything else (accounts, taxes, healthcare, goals,
+ * horizon) is the user's own.
+ */
+export function compareSwrRules(plan, opts, cape = SWR_DEFAULT_CAPE) {
+    const startingInvestable = startingInvestableOf(plan);
+    return SWR_RULES.map((rule) => {
+        const ratePct = rule.initialRatePct(cape);
+        const initialAnnualSpend = (ratePct / 100) * startingInvestable;
+        const variant = {
+            ...plan,
+            expenses: {
+                ...plan.expenses,
+                baseAnnual: initialAnnualSpend,
+                phases: [],
+                spendingPolicy: undefined,
+                // The annual upside layers fund on top of baseAnnual in fixed-target
+                // mode; a rule advertised as spending exactly rate × portfolio must
+                // not inherit them or it simulates rule + upside and reads worse.
+                // requiredAnnual is cleared too: it never adds spending, but clearing
+                // it makes the variant's lifestyle stack exactly the rule level.
+                idealAnnual: undefined,
+                excessAnnual: undefined,
+                requiredAnnual: undefined,
+            },
+        };
+        const result = simulatePlan(variant, opts);
+        const summary = summarizeProjection(variant, result);
+        return {
+            id: rule.id,
+            label: rule.label,
+            citation: rule.citation,
+            initialRatePct: ratePct,
+            initialAnnualSpend,
+            depletionYear: summary.depletionYear,
+            endYear: result.endYear,
+            endingAfterTaxEstate: summary.endingAfterTaxEstate,
+            lifetimeTaxesAndPenalties: summary.lifetimeTaxesAndPenalties,
+        };
+    });
+}

package/dist/decisions/tournament.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Generalized exact-ledger tournament (ledger-native decision engine, Phase 3).
+ *
+ * 1. gather candidates from the selected generators,
+ * 2. dedupe candidates with equivalent patches/schedules,
+ * 3. evaluate each through the exact ledger,
+ * 4. rank by the objective policy's primary metric and hard constraints,
+ * 5. return the ranked field, the winner, and why each loser lost.
+ *
+ * Deterministic: generation order, dedupe (first occurrence wins), stable
+ * ranking with candidate-id tie-breaks, and a fixed evaluation bound.
+ */
+import { type EvaluateCandidateOptions } from './evaluateCandidate.js';
+import { type ObjectivePolicy } from './objectives.js';
+import type { CandidateGenerator, DecisionCandidate, DecisionContext, ExactDecisionEvaluation } from './types.js';
+/** Equivalence key for a candidate's concrete change (patch + normalized schedule). */
+export declare function candidateEquivalenceKey(candidate: DecisionCandidate): string;
+/** Drop candidates whose patch/schedule is equivalent to an earlier one (first wins). */
+export declare function dedupeCandidates(candidates: DecisionCandidate[]): DecisionCandidate[];
+export interface RankedDecision {
+    evaluation: ExactDecisionEvaluation;
+    /** Policy primary metric (higher is better). */
+    primaryValue: number;
+    /** Hard-constraint violations; non-empty ⇒ ineligible to win. */
+    constraintViolations: string[];
+    eligible: boolean;
+    /** Why this candidate is not the recommendation (null for the winner). */
+    lossReason: string | null;
+}
+export interface DecisionTournamentResult {
+    policyId: ObjectivePolicy['id'];
+    /** Every evaluated candidate, best first (ineligible candidates rank below eligible ones). */
+    ranked: RankedDecision[];
+    /** Best eligible candidate that actually improves the primary metric, or null. */
+    winner: RankedDecision | null;
+    /** Exact-ledger simulations spent (one per unique candidate). */
+    simulationCount: number;
+}
+export interface DecisionTournamentOptions {
+    policy?: ObjectivePolicy;
+    /** Safety bound on exact evaluations; candidates beyond it are dropped deterministically. */
+    maxCandidates?: number;
+    /** Minimum primary-metric improvement before anything is recommended. */
+    minimumImprovement?: number;
+    evaluation?: EvaluateCandidateOptions;
+}
+/** Rank pre-computed evaluations under a policy (shared by tournament and tests). */
+export declare function rankEvaluations(evaluations: ExactDecisionEvaluation[], ctx: DecisionContext, policy?: ObjectivePolicy, minimumImprovement?: number): {
+    ranked: RankedDecision[];
+    winner: RankedDecision | null;
+};
+/** Gather → dedupe → exact-evaluate → rank. */
+export declare function runDecisionTournament(ctx: DecisionContext, generators: CandidateGenerator[], options?: DecisionTournamentOptions): DecisionTournamentResult;

package/dist/decisions/tournament.js

@@ -0,0 +1,104 @@
+/**
+ * Generalized exact-ledger tournament (ledger-native decision engine, Phase 3).
+ *
+ * 1. gather candidates from the selected generators,
+ * 2. dedupe candidates with equivalent patches/schedules,
+ * 3. evaluate each through the exact ledger,
+ * 4. rank by the objective policy's primary metric and hard constraints,
+ * 5. return the ranked field, the winner, and why each loser lost.
+ *
+ * Deterministic: generation order, dedupe (first occurrence wins), stable
+ * ranking with candidate-id tie-breaks, and a fixed evaluation bound.
+ */
+import { evaluateCandidate } from './evaluateCandidate.js';
+import { maximizeAfterTaxEstate } from './objectives.js';
+/** Stable stringify: object keys sorted recursively so patch key order never matters. */
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (typeof value === 'object' && value !== null) {
+        const entries = Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`);
+        return `{${entries.join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+/** Equivalence key for a candidate's concrete change (patch + normalized schedule). */
+export function candidateEquivalenceKey(candidate) {
+    const conversions = candidate.conversions
+        ? [...candidate.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)
+        : null;
+    return canonicalJson({ patch: candidate.planPatch ?? null, conversions });
+}
+/** Drop candidates whose patch/schedule is equivalent to an earlier one (first wins). */
+export function dedupeCandidates(candidates) {
+    const seen = new Set();
+    const unique = [];
+    for (const candidate of candidates) {
+        const key = candidateEquivalenceKey(candidate);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        unique.push(candidate);
+    }
+    return unique;
+}
+const DEFAULT_MAX_CANDIDATES = 32;
+const DEFAULT_MINIMUM_IMPROVEMENT = 1;
+/** Rank pre-computed evaluations under a policy (shared by tournament and tests). */
+export function rankEvaluations(evaluations, ctx, policy = maximizeAfterTaxEstate, minimumImprovement = DEFAULT_MINIMUM_IMPROVEMENT) {
+    const rows = evaluations.map((evaluation) => {
+        const constraintViolations = policy.constraintViolations(evaluation, ctx);
+        return {
+            evaluation,
+            primaryValue: policy.primaryMetric(evaluation, ctx),
+            constraintViolations,
+            eligible: constraintViolations.length === 0,
+            lossReason: null,
+        };
+    });
+    const tieBreak = (row) => policy.tieBreaker ? policy.tieBreaker(row.evaluation, ctx) : row.evaluation.deltas.endingAfterTaxEstate;
+    rows.sort((a, b) => {
+        if (a.eligible !== b.eligible)
+            return a.eligible ? -1 : 1;
+        if (a.primaryValue !== b.primaryValue)
+            return b.primaryValue - a.primaryValue;
+        const tie = tieBreak(b) - tieBreak(a);
+        if (tie !== 0)
+            return tie;
+        return a.evaluation.candidate.id < b.evaluation.candidate.id ? -1 : 1;
+    });
+    const winner = rows.find((row) => row.eligible && row.primaryValue > minimumImprovement) ?? null;
+    for (const row of rows) {
+        if (row === winner)
+            continue;
+        if (!row.eligible) {
+            row.lossReason = `violates ${policy.label.toLowerCase()} constraints: ${row.constraintViolations.join('; ')}`;
+        }
+        else if (winner) {
+            row.lossReason = `${policy.primaryMetricLabel} trails the winner by ${Math.round(winner.primaryValue - row.primaryValue).toLocaleString()}`;
+        }
+        else {
+            row.lossReason = `${policy.primaryMetricLabel} does not improve on the current plan`;
+        }
+    }
+    return { ranked: rows, winner };
+}
+/** Gather → dedupe → exact-evaluate → rank. */
+export function runDecisionTournament(ctx, generators, options = {}) {
+    const policy = options.policy ?? maximizeAfterTaxEstate;
+    const maxCandidates = options.maxCandidates ?? DEFAULT_MAX_CANDIDATES;
+    const minimumImprovement = options.minimumImprovement ?? DEFAULT_MINIMUM_IMPROVEMENT;
+    const gathered = [];
+    for (const generator of generators)
+        gathered.push(...generator.generate(ctx));
+    const unique = dedupeCandidates(gathered).slice(0, maxCandidates);
+    const evaluations = unique.map((candidate) => evaluateCandidate(ctx, candidate, options.evaluation));
+    const { ranked, winner } = rankEvaluations(evaluations, ctx, policy, minimumImprovement);
+    return { policyId: policy.id, ranked, winner, simulationCount: evaluations.length };
+}

package/dist/decisions/types.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Ledger-native decision engine — shared candidate/evaluation contract
+ * (DOCS/enhancements/ledger-native-decision-engine.md, Phase 1).
+ *
+ * A candidate is a concrete, bounded change to the plan (a scenario-style
+ * patch, a Roth conversion schedule, or both). Candidates are proposed by
+ * generators (MILP, detectors, heuristics, search); they are never trusted
+ * directly. `evaluateCandidate` runs every candidate through the exact ledger
+ * (`simulatePlan`) against a shared baseline, and only that exact comparison
+ * decides whether a candidate is beneficial.
+ */
+import type { Plan } from '../model/plan.js';
+import type { ProjectionSummary } from '../projection/compare.js';
+import type { SimulateOptions } from '../projection/simulate.js';
+import type { ProjectionResult, TaxCalculator } from '../projection/types.js';
+export type DecisionSource = 'milp' | 'detector' | 'heuristic' | 'scenario-sweep' | 'search';
+export type DecisionCategory = 'roth' | 'withdrawal' | 'social-security' | 'tax-cliff' | 'spending' | 'insurance' | 'geography' | 'asset-location' | 'guaranteed-income';
+export interface DecisionCandidate {
+    id: string;
+    source: DecisionSource;
+    category: DecisionCategory;
+    label: string;
+    explanation: string;
+    /**
+     * Scenario-style deep-override of the plan (same merge semantics as
+     * `applyScenarioPatch`: objects merge, arrays/primitives replace).
+     */
+    planPatch?: Record<string, unknown>;
+    /**
+     * Explicit Roth conversion schedule, installed as an `optimized` strategy
+     * after any planPatch is applied. Requested amounts — the exact ledger may
+     * execute less (balance caps), which evaluation reports as diagnostics.
+     */
+    conversions?: Array<{
+        year: number;
+        amount: number;
+    }>;
+    metadata?: Record<string, unknown>;
+}
+/** Everything a generator or evaluator needs; baseline is computed once and shared. */
+export interface DecisionContext {
+    plan: Plan;
+    baselineResult: ProjectionResult;
+    baselineSummary: ProjectionSummary;
+    simulateOptions: SimulateOptions;
+    /**
+     * Build the tax stack from a candidate's own (patched) plan instead of
+     * pricing it with `simulateOptions.taxCalculator`. Needed when a candidate
+     * patch changes tax assumptions (flat state-rate override, local rate) —
+     * e.g. relocation previews — so the evaluation matches the surface that
+     * proposed it. Absent ⇒ the shared calculator, as before.
+     */
+    taxCalculatorForPlan?: (plan: Plan) => TaxCalculator;
+}
+export interface DecisionDeltas {
+    endingAfterTaxEstate: number;
+    endingNetWorth: number;
+    lifetimeTax: number;
+    moneyLastsYears: number;
+}
+export interface StochasticDecisionMetrics {
+    pathCount: number;
+    seed: number;
+    successRate: number;
+    requiredFloorSuccessRate: number;
+    targetLifestyleSuccessRate: number;
+    p10EndingAfterTaxEstate: number;
+    medianEndingAfterTaxEstate: number;
+    expectedShortfallDollars: number;
+    averageTargetShortfallDollars: number;
+}
+export interface StochasticDecisionAttachment {
+    baseline: StochasticDecisionMetrics;
+    candidate: StochasticDecisionMetrics;
+    deltas: {
+        successRate: number;
+        requiredFloorSuccessRate: number;
+        targetLifestyleSuccessRate: number;
+        p10EndingAfterTaxEstate: number;
+        medianEndingAfterTaxEstate: number;
+        expectedShortfallDollars: number;
+        averageTargetShortfallDollars: number;
+    };
+}
+/**
+ * 'beneficial' | 'neutral' | 'rejected' come from the exact after-tax-estate
+ * comparison. 'diagnostic' marks evaluations that must not become
+ * recommendations for structural reasons: an invalid patch, or a conversion
+ * schedule the ledger could not materially execute as requested.
+ */
+export type DecisionRecommendationState = 'beneficial' | 'neutral' | 'rejected' | 'diagnostic';
+/** Requested-vs-executed accounting for conversion-schedule candidates. */
+export interface ConversionExecution {
+    requestedTotal: number;
+    executedTotal: number;
+    /** min(1, executed/requested); 1 when nothing was requested. */
+    executedRatio: number;
+    firstMateriallyUnexecutedYear: number | null;
+    /** Per-year amounts the exact ledger actually executed (years > $1 only). */
+    executedByYear: Array<{
+        year: number;
+        amount: number;
+    }>;
+}
+export interface ExactDecisionEvaluation {
+    candidate: DecisionCandidate;
+    baselineSummary: ProjectionSummary;
+    candidateSummary: ProjectionSummary;
+    /** Full exact-ledger run for the candidate; not structured-clone-light — strip before posting to workers/UI. */
+    candidateResult: ProjectionResult;
+    deltas: DecisionDeltas;
+    /** Present when the candidate carries (or its patch produces) a conversion schedule. */
+    conversionExecution: ConversionExecution | null;
+    /** First year the candidate's own (non-inherited) traditional balance hits zero, when the plan has any. */
+    traditionalDepletionYear: number | null;
+    /** Optional same-path Monte Carlo attachment for opt-in robust ranking. */
+    stochastic?: StochasticDecisionAttachment;
+    diagnostics: string[];
+    recommendationState: DecisionRecommendationState;
+}
+export interface CandidateGenerator {
+    id: string;
+    /** Pure and bounded: no simulate() calls, small fixed candidate count. */
+    generate(ctx: DecisionContext): DecisionCandidate[];
+}

package/dist/decisions/types.js

@@ -0,0 +1,12 @@
+/**
+ * Ledger-native decision engine — shared candidate/evaluation contract
+ * (DOCS/enhancements/ledger-native-decision-engine.md, Phase 1).
+ *
+ * A candidate is a concrete, bounded change to the plan (a scenario-style
+ * patch, a Roth conversion schedule, or both). Candidates are proposed by
+ * generators (MILP, detectors, heuristics, search); they are never trusted
+ * directly. `evaluateCandidate` runs every candidate through the exact ledger
+ * (`simulatePlan`) against a shared baseline, and only that exact comparison
+ * decides whether a candidate is beneficial.
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Root entry — the core loop: validate a plan, run the ledger.
+ *
+ * Deep subpath imports are the primary API surface
+ * (`@retiregolden/engine/projection/simulate`,
+ * `@retiregolden/engine/montecarlo/run`, `@retiregolden/engine/params`, …);
+ * this root re-exports just enough to parse a plan and run a projection.
+ */
+export { CURRENT_PLAN_SCHEMA_VERSION, planSchema, type Plan } from './model/plan.js';
+export { migratePlanToCurrent } from './model/migrations.js';
+export { simulatePlan, type SimulateOptions } from './projection/simulate.js';
+export type { ProjectionResult, YearResult } from './projection/types.js';
+export { summarizeProjection } from './projection/compare.js';

package/dist/index.js

@@ -0,0 +1,12 @@
+/**
+ * Root entry — the core loop: validate a plan, run the ledger.
+ *
+ * Deep subpath imports are the primary API surface
+ * (`@retiregolden/engine/projection/simulate`,
+ * `@retiregolden/engine/montecarlo/run`, `@retiregolden/engine/params`, …);
+ * this root re-exports just enough to parse a plan and run a projection.
+ */
+export { CURRENT_PLAN_SCHEMA_VERSION, planSchema } from './model/plan.js';
+export { migratePlanToCurrent } from './model/migrations.js';
+export { simulatePlan } from './projection/simulate.js';
+export { summarizeProjection } from './projection/compare.js';

package/dist/insights/detectors/annuitizationHeadroom.d.ts

@@ -0,0 +1,11 @@
+import type { Detector } from '../types.js';
+/**
+ * "You plan for a long life but hold no guaranteed income — annuitization
+ * headroom" (annuity-pension-and-home-equity, step 5). Fires for
+ * longevity-anxious plans (a planning age of 95+) with meaningful liquid
+ * savings, no annuity on the books, and no pension income covering the same
+ * ground. The action previews a cover-the-floor SPIA as a scenario so the
+ * ledger — not the card — prices the liquidity/estate tradeoff; the Monte
+ * Carlo annuitization sweep is the full solver view.
+ */
+export declare const annuitizationHeadroom: Detector;