@retiregolden/engine 0.1.0

package/dist/spending/flexibleGoals.js

@@ -0,0 +1,136 @@
+/**
+ * Flexible one-time-goal scheduler. One scheduler instance belongs to one
+ * projection path, so goal resolution is stateful and deterministic: a goal can
+ * be funded, partially funded, or skipped at most once.
+ */
+const CLASSIFICATION_RANK = {
+    required: 0,
+    target: 1,
+    ideal: 2,
+    excess: 3,
+};
+const EPSILON = 0.005;
+/** Resolve a stored goal's optional flexibility fields to their defaults. */
+export function toSchedulableGoal(goal, index) {
+    const targetYear = goal.year;
+    const classification = goal.classification ?? 'target';
+    const flexibility = goal.flexibility ?? 'fixed';
+    const earliestYear = Math.min(goal.earliestYear ?? targetYear, targetYear);
+    const latestYear = Math.max(goal.latestYear ?? targetYear, targetYear);
+    const defaultMinFundingPct = flexibility === 'skippable' ? 0 : 100;
+    return {
+        id: goal.id,
+        classification,
+        flexibility,
+        earliestYear,
+        targetYear,
+        latestYear,
+        priority: goal.priority ?? index,
+        order: index,
+        amountTodayDollars: goal.amount,
+        minFundingPct: goal.minFundingPct ?? defaultMinFundingPct,
+        allowPartialFunding: goal.allowPartialFunding ?? false,
+    };
+}
+function result(goal, ctx, outcome, fundedNominal) {
+    const amountNominal = goal.amountTodayDollars * ctx.inflFactor;
+    return {
+        id: goal.id,
+        classification: goal.classification,
+        outcome,
+        amountNominal,
+        fundedNominal,
+        unfundedNominal: Math.max(0, amountNominal - fundedNominal),
+    };
+}
+function defaultBudget(ctx) {
+    if (ctx.availableBudget !== undefined)
+        return ctx.availableBudget;
+    return ctx.cutting ? 0 : null;
+}
+function canFullyFund(budget, amount) {
+    return budget === null || budget + EPSILON >= amount;
+}
+function consume(budget, amount) {
+    return budget === null ? null : Math.max(0, budget - amount);
+}
+function partialAmount(goal, budget, amount) {
+    if (!goal.allowPartialFunding || budget === null || budget <= EPSILON)
+        return 0;
+    const minimum = amount * Math.max(0, Math.min(100, goal.minFundingPct)) / 100;
+    if (budget + EPSILON < minimum)
+        return 0;
+    return Math.min(amount, budget);
+}
+function resolveBudget(ctx, beforeTarget, remainingBudget) {
+    if (beforeTarget || ctx.cutting)
+        return remainingBudget;
+    return null;
+}
+/**
+ * Build a scheduler for a plan's goals. Flexible goals are evaluated by
+ * classification, then explicit priority, then original list order so a target
+ * car replacement cannot be crowded out by a lower-layer ideal remodel.
+ */
+export function createGoalScheduler(goals) {
+    const ordered = [...goals].sort((a, b) => {
+        const classDelta = CLASSIFICATION_RANK[a.classification] - CLASSIFICATION_RANK[b.classification];
+        if (classDelta !== 0)
+            return classDelta;
+        const priorityDelta = a.priority - b.priority;
+        if (priorityDelta !== 0)
+            return priorityDelta;
+        return a.order - b.order;
+    });
+    const resolved = new Set();
+    return {
+        isResolved(id) {
+            return resolved.has(id);
+        },
+        planYear(year, ctx) {
+            const results = [];
+            let remainingBudget = defaultBudget(ctx);
+            for (const goal of ordered) {
+                if (resolved.has(goal.id))
+                    continue;
+                if (goal.flexibility === 'fixed') {
+                    if (year === goal.targetYear) {
+                        const funded = goal.amountTodayDollars * ctx.inflFactor;
+                        resolved.add(goal.id);
+                        results.push(result(goal, ctx, 'funded', funded));
+                    }
+                    continue;
+                }
+                if (year < goal.earliestYear || year > goal.latestYear)
+                    continue;
+                const beforeTarget = year < goal.targetYear;
+                if (beforeTarget && !ctx.canPullForward)
+                    continue;
+                const amount = goal.amountTodayDollars * ctx.inflFactor;
+                const effectiveBudget = resolveBudget(ctx, beforeTarget, remainingBudget);
+                if (canFullyFund(effectiveBudget, amount)) {
+                    if (effectiveBudget !== null)
+                        remainingBudget = consume(remainingBudget, amount);
+                    resolved.add(goal.id);
+                    results.push(result(goal, ctx, 'funded', amount));
+                    continue;
+                }
+                const partial = partialAmount(goal, effectiveBudget, amount);
+                if (partial > EPSILON) {
+                    remainingBudget = consume(remainingBudget, partial);
+                    resolved.add(goal.id);
+                    results.push(result(goal, ctx, 'partiallyFunded', partial));
+                    continue;
+                }
+                if (year < goal.latestYear) {
+                    results.push(result(goal, ctx, 'deferred', 0));
+                }
+                else {
+                    resolved.add(goal.id);
+                    results.push(result(goal, ctx, 'skipped', 0));
+                }
+            }
+            return { results, remainingBudget };
+        },
+    };
+}

package/dist/spending/guardrails.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Withdrawal-rate spending guardrails (planning-depth roadmap §4, Guyton–Klinger
+ * style). A path-level decision rule that rations the *discretionary* spending
+ * layer year by year: when the current withdrawal rate runs too far above the
+ * plan's starting rate the discretionary layer is cut, and when it falls back
+ * below the starting rate it is restored — the required floor is never touched.
+ *
+ * These functions are pure and deterministic. The ledger owns the per-year state
+ * (the running discretionary multiplier) and applies the funded spending through
+ * the same tax/withdrawal/estate mechanics as every other expense; nothing here
+ * builds its own cash-flow model.
+ *
+ * The withdrawal-rate signal is `targetSpending / startOfYearPortfolio`, compared
+ * to the same ratio in the first projection year. This is a documented
+ * simplification: it uses gross target spending (not net-of-guaranteed-income
+ * portfolio draws) as the withdrawal proxy, so it is well defined before the
+ * tax/withdrawal fixed point runs and cannot become circular with the very
+ * spending it is deciding.
+ */
+export interface GuardrailPolicy {
+    /**
+     * Which signal triggers adjustments. 'withdrawal-rate' (or absent) compares
+     * the current withdrawal rate to the starting rate (Guyton–Klinger style);
+     * 'risk-based' compares the real portfolio balance to solver-derived dollar
+     * thresholds that correspond to a target probability-of-success band.
+     */
+    mode?: 'withdrawal-rate' | 'risk-based';
+    /** Cut when current rate exceeds this % of the starting rate. Absent ⇒ 120. */
+    upperGuardrailPct?: number;
+    /** Raise when current rate falls below this % of the starting rate. Absent ⇒ 80. */
+    lowerGuardrailPct?: number;
+    /** Risk-based: cut when the real balance falls below this % of the starting portfolio. */
+    lowerBalanceThresholdPct?: number;
+    /** Risk-based: raise when the real balance rises above this % of the starting portfolio. */
+    upperBalanceThresholdPct?: number;
+    /** Each cut/raise moves the discretionary layer by this % of its full size. Absent ⇒ 10. */
+    adjustmentPct?: number;
+    /** Permit raises above the target lifestyle into ideal/excess layers. */
+    allowRaisesAboveTarget?: boolean;
+}
+export declare const DEFAULT_UPPER_GUARDRAIL_PCT = 120;
+export declare const DEFAULT_LOWER_GUARDRAIL_PCT = 80;
+export declare const DEFAULT_ADJUSTMENT_PCT = 10;
+export type GuardrailAction = 'hold' | 'cut' | 'raise';
+export interface GuardrailDecision {
+    /** Discretionary multiplier in [0, 1] after this year's decision. */
+    multiplier: number;
+    action: GuardrailAction;
+}
+/**
+ * One year's guardrail decision. `startingRate` and `currentRate` are the
+ * target-spending / start-of-year-portfolio ratios for the first projection year
+ * and this year respectively.
+ *
+ * - ratio above the upper band ⇒ cut the discretionary layer by `adjustmentPct`,
+ * - ratio below the lower band ⇒ restore it by `adjustmentPct`,
+ * - otherwise hold.
+ *
+ * The multiplier is clamped to [0, 1] so a cut never reaches below the required
+ * floor and a raise never overshoots full discretionary spending. `action` is
+ * reported as 'hold' when the multiplier does not actually move (already at a
+ * bound), so downstream counts reflect real adjustments only.
+ */
+export declare function nextGuardrailMultiplier(prevMultiplier: number, currentRate: number, startingRate: number, policy?: GuardrailPolicy, maxMultiplier?: number): GuardrailDecision;
+/**
+ * One year's risk-based guardrail decision. The signal is the real (deflated)
+ * start-of-year portfolio balance against dollar thresholds expressed as a
+ * percent of the starting portfolio. The thresholds come from the shared-path
+ * probability solver (engine/montecarlo/riskBasedGuardrails.ts): the balance
+ * levels at which the plan's probability of success leaves the user's target
+ * band. Below the lower threshold ⇒ cut the discretionary layer one
+ * `adjustmentPct` step; above the upper threshold ⇒ restore/raise one step.
+ *
+ * Missing or degenerate thresholds hold: a risk-based policy whose thresholds
+ * have not been solved yet adjusts nothing (it behaves like fixed target), so
+ * the mode can never act on made-up numbers.
+ */
+export declare function nextBalanceGuardrailMultiplier(prevMultiplier: number, currentRealBalance: number, startingBalance: number, policy?: GuardrailPolicy, maxMultiplier?: number): GuardrailDecision;

package/dist/spending/guardrails.js

@@ -0,0 +1,100 @@
+/**
+ * Withdrawal-rate spending guardrails (planning-depth roadmap §4, Guyton–Klinger
+ * style). A path-level decision rule that rations the *discretionary* spending
+ * layer year by year: when the current withdrawal rate runs too far above the
+ * plan's starting rate the discretionary layer is cut, and when it falls back
+ * below the starting rate it is restored — the required floor is never touched.
+ *
+ * These functions are pure and deterministic. The ledger owns the per-year state
+ * (the running discretionary multiplier) and applies the funded spending through
+ * the same tax/withdrawal/estate mechanics as every other expense; nothing here
+ * builds its own cash-flow model.
+ *
+ * The withdrawal-rate signal is `targetSpending / startOfYearPortfolio`, compared
+ * to the same ratio in the first projection year. This is a documented
+ * simplification: it uses gross target spending (not net-of-guaranteed-income
+ * portfolio draws) as the withdrawal proxy, so it is well defined before the
+ * tax/withdrawal fixed point runs and cannot become circular with the very
+ * spending it is deciding.
+ */
+export const DEFAULT_UPPER_GUARDRAIL_PCT = 120;
+export const DEFAULT_LOWER_GUARDRAIL_PCT = 80;
+export const DEFAULT_ADJUSTMENT_PCT = 10;
+function clampRange(x, max) {
+    const hi = Math.max(0, Number.isFinite(max) ? max : 1);
+    if (!Number.isFinite(x))
+        return Math.min(1, hi);
+    return Math.min(hi, Math.max(0, x));
+}
+/**
+ * One year's guardrail decision. `startingRate` and `currentRate` are the
+ * target-spending / start-of-year-portfolio ratios for the first projection year
+ * and this year respectively.
+ *
+ * - ratio above the upper band ⇒ cut the discretionary layer by `adjustmentPct`,
+ * - ratio below the lower band ⇒ restore it by `adjustmentPct`,
+ * - otherwise hold.
+ *
+ * The multiplier is clamped to [0, 1] so a cut never reaches below the required
+ * floor and a raise never overshoots full discretionary spending. `action` is
+ * reported as 'hold' when the multiplier does not actually move (already at a
+ * bound), so downstream counts reflect real adjustments only.
+ */
+export function nextGuardrailMultiplier(prevMultiplier, currentRate, startingRate, policy = {}, maxMultiplier = 1) {
+    const upper = (policy.upperGuardrailPct ?? DEFAULT_UPPER_GUARDRAIL_PCT) / 100;
+    const lower = (policy.lowerGuardrailPct ?? DEFAULT_LOWER_GUARDRAIL_PCT) / 100;
+    const adj = (policy.adjustmentPct ?? DEFAULT_ADJUSTMENT_PCT) / 100;
+    const prev = clampRange(prevMultiplier, maxMultiplier);
+    // An undefined signal (no starting portfolio, non-finite current rate) holds:
+    // there is nothing to compare against, so spending is left where it is.
+    if (!(startingRate > 0) || !Number.isFinite(currentRate) || currentRate < 0) {
+        return { multiplier: prev, action: 'hold' };
+    }
+    const ratio = currentRate / startingRate;
+    if (ratio > upper) {
+        const multiplier = clampRange(prev - adj, maxMultiplier);
+        return { multiplier, action: multiplier < prev - 1e-9 ? 'cut' : 'hold' };
+    }
+    if (ratio < lower) {
+        const multiplier = clampRange(prev + adj, maxMultiplier);
+        return { multiplier, action: multiplier > prev + 1e-9 ? 'raise' : 'hold' };
+    }
+    return { multiplier: prev, action: 'hold' };
+}
+/**
+ * One year's risk-based guardrail decision. The signal is the real (deflated)
+ * start-of-year portfolio balance against dollar thresholds expressed as a
+ * percent of the starting portfolio. The thresholds come from the shared-path
+ * probability solver (engine/montecarlo/riskBasedGuardrails.ts): the balance
+ * levels at which the plan's probability of success leaves the user's target
+ * band. Below the lower threshold ⇒ cut the discretionary layer one
+ * `adjustmentPct` step; above the upper threshold ⇒ restore/raise one step.
+ *
+ * Missing or degenerate thresholds hold: a risk-based policy whose thresholds
+ * have not been solved yet adjusts nothing (it behaves like fixed target), so
+ * the mode can never act on made-up numbers.
+ */
+export function nextBalanceGuardrailMultiplier(prevMultiplier, currentRealBalance, startingBalance, policy = {}, maxMultiplier = 1) {
+    const adj = (policy.adjustmentPct ?? DEFAULT_ADJUSTMENT_PCT) / 100;
+    const prev = clampRange(prevMultiplier, maxMultiplier);
+    const lowerPct = policy.lowerBalanceThresholdPct;
+    const upperPct = policy.upperBalanceThresholdPct;
+    if (!(startingBalance > 0) || !Number.isFinite(currentRealBalance) || currentRealBalance < 0) {
+        return { multiplier: prev, action: 'hold' };
+    }
+    const lower = lowerPct !== undefined && lowerPct > 0 ? (lowerPct / 100) * startingBalance : null;
+    const upper = upperPct !== undefined && upperPct > 0 ? (upperPct / 100) * startingBalance : null;
+    // An inverted pair (lower ≥ upper) is degenerate; hold rather than oscillate.
+    if (lower !== null && upper !== null && lower >= upper) {
+        return { multiplier: prev, action: 'hold' };
+    }
+    if (lower !== null && currentRealBalance < lower) {
+        const multiplier = clampRange(prev - adj, maxMultiplier);
+        return { multiplier, action: multiplier < prev - 1e-9 ? 'cut' : 'hold' };
+    }
+    if (upper !== null && currentRealBalance > upper) {
+        const multiplier = clampRange(prev + adj, maxMultiplier);
+        return { multiplier, action: multiplier > prev + 1e-9 ? 'raise' : 'hold' };
+    }
+    return { multiplier: prev, action: 'hold' };
+}

package/dist/spending/layers.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Spending-layer helpers (planning-depth roadmap §4). Pure functions the ledger
+ * uses to split annual lifestyle spending into a required floor and a
+ * discretionary layer, and to attribute a portfolio shortfall to the required
+ * vs. target layers. Keeping these out of `simulate.ts` makes the layer math
+ * unit-testable without running a full projection.
+ *
+ * System-computed costs (healthcare, debt service, property carrying costs,
+ * insurance premiums, net long-term-care) are treated as required by the ledger
+ * and are not modeled here; this file owns only the lifestyle split and the
+ * shortfall attribution, which operate on the whole spending stack.
+ */
+export interface LifestyleSplit {
+    /** Nominal required-floor lifestyle spending. */
+    requiredLifestyle: number;
+    /** Nominal discretionary lifestyle spending (the layer a guardrail can cut). */
+    discretionaryLifestyle: number;
+}
+/**
+ * Split a year's nominal lifestyle spending into required and discretionary
+ * layers. The required floor is clamped to the target so the two layers always
+ * sum back to `baseAnnualNominal` (the migrated fixed-target total).
+ */
+export declare function splitLifestyle(baseAnnualNominal: number, requiredAnnualNominal: number): LifestyleSplit;
+export interface AnnualSpendingLayers extends LifestyleSplit {
+    /** Nominal target-lifestyle layer above the required floor. */
+    targetLifestyle: number;
+    /** Nominal annual ideal layer above the target lifestyle. */
+    idealLifestyle: number;
+    /** Nominal annual excess/opportunistic layer above ideal. */
+    excessLifestyle: number;
+}
+/**
+ * Split annual lifestyle spending into the four modeled layers. `baseAnnual`
+ * remains the target lifestyle for compatibility; ideal/excess are explicit
+ * upside layers above that target and default to zero for older saved plans.
+ */
+export declare function splitAnnualSpendingLayers(input: {
+    baseAnnualNominal: number;
+    requiredAnnualNominal: number;
+    idealAnnualNominal?: number;
+    excessAnnualNominal?: number;
+}): AnnualSpendingLayers;
+export interface ShortfallAttributionInput {
+    /** Must-fund spending this year (system costs + required lifestyle + required goals). */
+    requiredSpending: number;
+    /** Full target spending with no guardrail cut (required + target lifestyle/goals). */
+    targetSpending: number;
+    /** Incremental ideal spending above the target lifestyle. */
+    idealSpending?: number;
+    /** Incremental excess/opportunistic spending above ideal. */
+    excessSpending?: number;
+    /** Spending actually attempted after any guardrail cut (`expenses.total`). */
+    fundedSpending: number;
+    /** Dollars the withdrawal waterfall could not produce for the funded need. */
+    withdrawalShortfall: number;
+}
+export interface ShortfallAttribution {
+    /** Required-floor spending the portfolio could not cover — the serious failure signal. */
+    requiredShortfall: number;
+    /** Target-lifestyle miss: the guardrail's deliberate cut plus any shortfall that ate discretionary. */
+    targetShortfall: number;
+    /** Ideal-layer miss after target spending has first claim on funded dollars. */
+    idealShortfall: number;
+    /** Excess-layer miss after required, target, and ideal have first claim. */
+    excessShortfall: number;
+}
+/**
+ * Attribute a portfolio shortfall across the spending layers.
+ *
+ * The target-lifestyle miss is a superset of the required-floor miss: it is
+ * everything spent below the full target, i.e. the guardrail's deliberate
+ * discretionary cut plus every dollar the portfolio could not produce.
+ *
+ * The required-floor miss is only the part of the withdrawal shortfall that eats
+ * below the floor — a genuine shortfall is charged to funded discretionary
+ * spending first and reaches the floor only once discretionary is exhausted — so
+ * `requiredShortfall` stays a clean "ran out of money for essentials" signal.
+ * Consequently `targetShortfall ≥ requiredShortfall` always.
+ */
+export declare function attributeShortfall(input: ShortfallAttributionInput): ShortfallAttribution;

package/dist/spending/layers.js

@@ -0,0 +1,67 @@
+/**
+ * Spending-layer helpers (planning-depth roadmap §4). Pure functions the ledger
+ * uses to split annual lifestyle spending into a required floor and a
+ * discretionary layer, and to attribute a portfolio shortfall to the required
+ * vs. target layers. Keeping these out of `simulate.ts` makes the layer math
+ * unit-testable without running a full projection.
+ *
+ * System-computed costs (healthcare, debt service, property carrying costs,
+ * insurance premiums, net long-term-care) are treated as required by the ledger
+ * and are not modeled here; this file owns only the lifestyle split and the
+ * shortfall attribution, which operate on the whole spending stack.
+ */
+/**
+ * Split a year's nominal lifestyle spending into required and discretionary
+ * layers. The required floor is clamped to the target so the two layers always
+ * sum back to `baseAnnualNominal` (the migrated fixed-target total).
+ */
+export function splitLifestyle(baseAnnualNominal, requiredAnnualNominal) {
+    const requiredLifestyle = Math.min(Math.max(0, requiredAnnualNominal), Math.max(0, baseAnnualNominal));
+    return {
+        requiredLifestyle,
+        discretionaryLifestyle: Math.max(0, baseAnnualNominal - requiredLifestyle),
+    };
+}
+/**
+ * Split annual lifestyle spending into the four modeled layers. `baseAnnual`
+ * remains the target lifestyle for compatibility; ideal/excess are explicit
+ * upside layers above that target and default to zero for older saved plans.
+ */
+export function splitAnnualSpendingLayers(input) {
+    const { requiredLifestyle, discretionaryLifestyle } = splitLifestyle(input.baseAnnualNominal, input.requiredAnnualNominal);
+    return {
+        requiredLifestyle,
+        discretionaryLifestyle,
+        targetLifestyle: discretionaryLifestyle,
+        idealLifestyle: Math.max(0, input.idealAnnualNominal ?? 0),
+        excessLifestyle: Math.max(0, input.excessAnnualNominal ?? 0),
+    };
+}
+/**
+ * Attribute a portfolio shortfall across the spending layers.
+ *
+ * The target-lifestyle miss is a superset of the required-floor miss: it is
+ * everything spent below the full target, i.e. the guardrail's deliberate
+ * discretionary cut plus every dollar the portfolio could not produce.
+ *
+ * The required-floor miss is only the part of the withdrawal shortfall that eats
+ * below the floor — a genuine shortfall is charged to funded discretionary
+ * spending first and reaches the floor only once discretionary is exhausted — so
+ * `requiredShortfall` stays a clean "ran out of money for essentials" signal.
+ * Consequently `targetShortfall ≥ requiredShortfall` always.
+ */
+export function attributeShortfall(input) {
+    const requiredSpending = Math.max(0, input.requiredSpending);
+    const targetSpending = Math.max(requiredSpending, input.targetSpending);
+    const idealSpending = Math.max(0, input.idealSpending ?? 0);
+    const excessSpending = Math.max(0, input.excessSpending ?? 0);
+    const actualFunded = Math.max(0, input.fundedSpending - Math.max(0, input.withdrawalShortfall));
+    const idealFunded = Math.max(0, Math.min(idealSpending, actualFunded - targetSpending));
+    const excessFunded = Math.max(0, Math.min(excessSpending, actualFunded - targetSpending - idealSpending));
+    return {
+        requiredShortfall: Math.max(0, requiredSpending - actualFunded),
+        targetShortfall: Math.max(0, targetSpending - actualFunded),
+        idealShortfall: Math.max(0, idealSpending - idealFunded),
+        excessShortfall: Math.max(0, excessSpending - excessFunded),
+    };
+}

package/dist/spending/shapePresets.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Spending-shape presets (spending-paths & SWR-lenses plan, Goal 1).
+ *
+ * Named, research-sourced spending shapes that compile to ordinary
+ * `expenses.phases` rows — the anti-drift rule from the shipped spending
+ * profiles: presets generate visible, editable phase rows at creation time and
+ * never live-couple saved plans to research constants.
+ *
+ * Shapes (multipliers on the primary person's age clock, always vs. the
+ * inflation-adjusted baseline):
+ * - constant-real: no phases — spending holds level in real terms (the classic
+ *   Bengen assumption).
+ * - smile: Blanchett's *average* retiree — a real decline through
+ *   mid-retirement that late-life healthcare partly reverses. The shipped
+ *   two-step calibration (−10% at 75, −20% at 85) approximates that path's
+ *   overall level without an explicit late step-up; edit the generated rows
+ *   to add one if desired.
+ * - smirk: Blanchett's 2025–26 finding for the *median* retiree — a steady
+ *   ~1%/yr real decline with no late uptick (only the sickest tail drives the
+ *   average's uptick). Shape-aware plans support meaningfully higher initial
+ *   withdrawals than constant-real; the solver-per-shape view quantifies that
+ *   on the user's own plan.
+ * - custom annual real delta: the same compilation at a user-chosen %/yr.
+ *
+ * A steady per-year drift is compiled as 5-year steps (the compounded
+ * multiplier at each step age) so the generated rows stay reviewable — a
+ * documented approximation, editable like any hand-entered phase.
+ */
+import type { ExpensePhase } from '../model/plan.js';
+export type SpendingShapeId = 'flat' | 'smile' | 'frontLoaded' | 'smirk';
+/** Blanchett-median real spending drift used by the smirk preset (%/yr). */
+export declare const SMIRK_ANNUAL_REAL_DELTA_PCT = -1;
+/**
+ * Compile a steady annual real spending drift into 5-year phase steps from
+ * retirement to age 100: at each step age the multiplier is the fully
+ * compounded (1 + delta)^(yearsSinceRetirement), rounded to 2 decimals and
+ * clamped to the phase schema's [0, 3] range. A zero delta compiles to no
+ * phases (constant-real).
+ */
+export declare function annualDeltaPhases(deltaPct: number, retirementAge: number): ExpensePhase[];
+/** Compile a named shape to phase rows (see module docs for each calibration). */
+export declare function spendingShapePhases(shape: SpendingShapeId, retirementAge: number): ExpensePhase[];

package/dist/spending/shapePresets.js

@@ -0,0 +1,77 @@
+/**
+ * Spending-shape presets (spending-paths & SWR-lenses plan, Goal 1).
+ *
+ * Named, research-sourced spending shapes that compile to ordinary
+ * `expenses.phases` rows — the anti-drift rule from the shipped spending
+ * profiles: presets generate visible, editable phase rows at creation time and
+ * never live-couple saved plans to research constants.
+ *
+ * Shapes (multipliers on the primary person's age clock, always vs. the
+ * inflation-adjusted baseline):
+ * - constant-real: no phases — spending holds level in real terms (the classic
+ *   Bengen assumption).
+ * - smile: Blanchett's *average* retiree — a real decline through
+ *   mid-retirement that late-life healthcare partly reverses. The shipped
+ *   two-step calibration (−10% at 75, −20% at 85) approximates that path's
+ *   overall level without an explicit late step-up; edit the generated rows
+ *   to add one if desired.
+ * - smirk: Blanchett's 2025–26 finding for the *median* retiree — a steady
+ *   ~1%/yr real decline with no late uptick (only the sickest tail drives the
+ *   average's uptick). Shape-aware plans support meaningfully higher initial
+ *   withdrawals than constant-real; the solver-per-shape view quantifies that
+ *   on the user's own plan.
+ * - custom annual real delta: the same compilation at a user-chosen %/yr.
+ *
+ * A steady per-year drift is compiled as 5-year steps (the compounded
+ * multiplier at each step age) so the generated rows stay reviewable — a
+ * documented approximation, editable like any hand-entered phase.
+ */
+/** Blanchett-median real spending drift used by the smirk preset (%/yr). */
+export const SMIRK_ANNUAL_REAL_DELTA_PCT = -1;
+const STEP_YEARS = 5;
+const LAST_STEP_AGE = 100;
+/**
+ * Compile a steady annual real spending drift into 5-year phase steps from
+ * retirement to age 100: at each step age the multiplier is the fully
+ * compounded (1 + delta)^(yearsSinceRetirement), rounded to 2 decimals and
+ * clamped to the phase schema's [0, 3] range. A zero delta compiles to no
+ * phases (constant-real).
+ */
+export function annualDeltaPhases(deltaPct, retirementAge) {
+    if (deltaPct === 0)
+        return [];
+    // Phase rows require fromAge in [40, 110]; start stepping after retirement.
+    const startAge = Math.min(Math.max(Math.round(retirementAge), 40), 105);
+    const phases = [];
+    for (let age = startAge + STEP_YEARS; age <= LAST_STEP_AGE; age += STEP_YEARS) {
+        const multiplier = Math.pow(1 + deltaPct / 100, age - startAge);
+        phases.push({ fromAge: age, multiplier: Math.min(3, Math.max(0, Math.round(multiplier * 100) / 100)) });
+    }
+    return phases;
+}
+/** Compile a named shape to phase rows (see module docs for each calibration). */
+export function spendingShapePhases(shape, retirementAge) {
+    switch (shape) {
+        case 'flat':
+            return [];
+        case 'smile':
+            return [
+                { fromAge: 75, multiplier: 0.9 },
+                { fromAge: 85, multiplier: 0.8 },
+            ];
+        case 'smirk':
+            return annualDeltaPhases(SMIRK_ANNUAL_REAL_DELTA_PCT, retirementAge);
+        case 'frontLoaded': {
+            const boostFrom = Math.min(Math.max(retirementAge, 40), 100);
+            // The +10% travel boost only covers the pre-75 window and always settles
+            // back to baseline at 75. If retirement starts at/after 75 there is no
+            // early window to boost, so stay flat (matches the UI label and doc).
+            if (boostFrom >= 75)
+                return [];
+            return [
+                { fromAge: boostFrom, multiplier: 1.1 },
+                { fromAge: 75, multiplier: 1 },
+            ];
+        }
+    }
+}

package/dist/strategies/accountEligibility.d.ts

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