@retiregolden/engine 0.1.0

package/dist/tax/federalTax.js

@@ -0,0 +1,249 @@
+/**
+ * Federal income tax (planning-grade), replacing the V1 flat placeholder.
+ *
+ * Computation order per year:
+ *   1. Taxable Social Security via provisional income (unindexed thresholds)
+ *   2. AGI = ordinary + capital gains + taxable SS; MAGI ≈ AGI (no foreign
+ *      exclusions or tax-exempt interest modeled)
+ *   3. Deductions: standard + age-65 additions + OBBBA senior deduction
+ *      (2025–2028, 6%-of-MAGI phase-out); itemized not modeled in v1
+ *   4. Ordinary brackets on non-preferential taxable income
+ *   5. LTCG/qualified-dividend stacking at 0/15/20% on top of ordinary
+ *   6. NIIT 3.8% on investment income over the (unindexed) MAGI threshold
+ *   7. Planning-grade AMT screen: modeled add-backs/preference items (notably
+ *      standard deduction or itemized SALT), AMT exemption/phaseout, and
+ *      preferential-rate-aware tentative minimum tax.
+ *
+ * Out of scope here (see DOCS/features/taxes.md): credits, full Form 6251
+ * adjustments, early-withdrawal penalties (projection-level), IRMAA
+ * (expense-side), state.
+ *
+ * @see DOCS/domain/domain-rules-reference.md §§1–3
+ */
+import { packForYear, standardDeduction } from '../params/index.js';
+import { taxParameterFilingStatus } from '../projection/types.js';
+/**
+ * Itemized-deduction total (SALT capped) from its components, or 0 when none.
+ * The OBBBA high-income SALT phase-out is not modeled (see pack `saltCap`).
+ */
+function itemizedTotal(pack, items) {
+    if (!items)
+        return 0;
+    const salt = Math.min(Math.max(0, items.stateAndLocalTaxes), pack.federalTax.saltCap);
+    return salt + Math.max(0, items.mortgageInterest) + Math.max(0, items.charitable);
+}
+/**
+ * Room left in the 0% long-term-capital-gains bracket this year: additional
+ * preferential income that could be realized and still be taxed at 0%. Gains
+ * stack on top of ordinary taxable income, so the 0% layer runs up to the 15%
+ * threshold.
+ *
+ * For retirees on Social Security this is NOT simply `threshold − taxableIncome`:
+ * realizing gains raises provisional income, which can make more of the benefit
+ * taxable, so taxable income climbs faster than $1 per gain dollar. We solve for
+ * the largest additional gain that keeps taxable income at the threshold,
+ * modeling that SS phase-in (the dominant interaction). The deduction is held
+ * fixed — the second-order senior-deduction MAGI phase-out is not modeled.
+ * @see DOCS/domain/domain-rules-reference.md §2
+ */
+export function zeroRateLtcgHeadroom(pack, filingStatus, ordinaryExcludingSs, currentGains, currentQualifiedDividends, ssBenefits, deduction) {
+    const threshold = pack.capitalGains.rate15StartsAbove[filingStatus];
+    const taxableIncomeAt = (extraGains) => {
+        const agiExcludingSs = ordinaryExcludingSs + currentGains + currentQualifiedDividends + extraGains;
+        const taxableSs = taxableSocialSecurity(pack, filingStatus, agiExcludingSs, ssBenefits);
+        return Math.max(0, agiExcludingSs + taxableSs - deduction);
+    };
+    if (taxableIncomeAt(0) >= threshold)
+        return 0;
+    // Monotonic increasing in extraGains (slope 1–1.85); binary-search the largest
+    // gain that keeps taxable income at the threshold. `threshold` brackets the
+    // root since the slope is ≥ 1 and taxableIncomeAt(0) ≥ 0.
+    let lo = 0;
+    let hi = threshold;
+    for (let i = 0; i < 60 && hi - lo > 0.01; i++) {
+        const mid = (lo + hi) / 2;
+        if (taxableIncomeAt(mid) <= threshold)
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+function bracketTax(brackets, taxable) {
+    let tax = 0;
+    for (let i = 0; i < brackets.length; i++) {
+        const lower = brackets[i].lowerBound;
+        const upper = i + 1 < brackets.length ? brackets[i + 1].lowerBound : Infinity;
+        if (taxable <= lower)
+            break;
+        tax += (Math.min(taxable, upper) - lower) * (brackets[i].ratePct / 100);
+    }
+    return tax;
+}
+/**
+ * Taxable share of Social Security benefits (IRC §86).
+ * Provisional income = AGI excluding SS + 50% of benefits (tax-exempt interest not modeled).
+ */
+export function taxableSocialSecurity(pack, filingStatus, agiExcludingSs, ssBenefits) {
+    if (ssBenefits <= 0)
+        return 0;
+    const t50 = pack.ssBenefitTaxation.tier50Start[filingStatus];
+    const t85 = pack.ssBenefitTaxation.tier85Start[filingStatus];
+    const provisional = agiExcludingSs + 0.5 * ssBenefits;
+    if (provisional <= t50)
+        return 0;
+    if (provisional <= t85)
+        return Math.min(0.5 * ssBenefits, 0.5 * (provisional - t50));
+    const tier1 = Math.min(0.5 * ssBenefits, 0.5 * (t85 - t50));
+    return Math.min(0.85 * ssBenefits, 0.85 * (provisional - t85) + tier1);
+}
+/** OBBBA senior deduction (per person 65+, 6% MAGI phase-out, expires after lastApplicableYear). */
+function seniorDeductionAmount(pack, year, filingStatus, peopleAged65Plus, magi) {
+    const rule = pack.federalTax.seniorDeduction;
+    if (!rule || peopleAged65Plus <= 0 || year > rule.lastApplicableYear)
+        return 0;
+    const base = rule.amountPerPerson * peopleAged65Plus;
+    const phaseOut = Math.max(0, magi - rule.magiPhaseOutStart[filingStatus]) * (rule.phaseOutRatePct / 100);
+    return Math.max(0, base - phaseOut);
+}
+/** LTCG/QDI stacked on top of ordinary taxable income at 0/15/20%. */
+function capitalGainsTaxStacked(pack, filingStatus, ordinaryTaxable, preferentialIncome) {
+    if (preferentialIncome <= 0)
+        return 0;
+    const t15 = pack.capitalGains.rate15StartsAbove[filingStatus];
+    const t20 = pack.capitalGains.rate20StartsAbove[filingStatus];
+    const from = ordinaryTaxable;
+    const to = ordinaryTaxable + preferentialIncome;
+    // The layer below t15 is the 0% bracket and contributes no tax.
+    const at15 = Math.max(0, Math.min(to, t20) - Math.max(from, t15));
+    const at20 = Math.max(0, to - Math.max(from, t20));
+    return at15 * 0.15 + at20 * 0.2;
+}
+function amtExemptionAmount(pack, filingStatus, amti) {
+    const rule = pack.federalTax.amt;
+    const base = rule.exemption[filingStatus];
+    const phaseOut = Math.max(0, amti - rule.exemptionPhaseOutStart[filingStatus]) * (rule.exemptionPhaseOutRatePct / 100);
+    return Math.max(0, base - phaseOut);
+}
+function amtOrdinaryRateTax(pack, taxableExcess) {
+    if (taxableExcess <= 0)
+        return 0;
+    const rule = pack.federalTax.amt;
+    const firstLayer = Math.min(taxableExcess, rule.rate28StartsAbove) * (rule.rate26Pct / 100);
+    const secondLayer = Math.max(0, taxableExcess - rule.rate28StartsAbove) * (rule.rate28Pct / 100);
+    return firstLayer + secondLayer;
+}
+function tentativeMinimumTax(pack, filingStatus, taxableExcess, preferentialIncome) {
+    if (taxableExcess <= 0)
+        return 0;
+    const amtPreferentialIncome = Math.min(Math.max(0, preferentialIncome), taxableExcess);
+    const ordinaryAmtExcess = taxableExcess - amtPreferentialIncome;
+    return (amtOrdinaryRateTax(pack, ordinaryAmtExcess) +
+        capitalGainsTaxStacked(pack, filingStatus, ordinaryAmtExcess, amtPreferentialIncome));
+}
+/**
+ * Apply a net capital-loss carryforward to one year (IRC §1211(b)/§1212): net
+ * against this year's realized gains first, then deduct up to `ordinaryOffsetLimit`
+ * ($3,000) of the remainder as a net capital loss — a *negative* figure on the
+ * return's capital-gain line that reduces AGI (and so provisional income, taxable
+ * SS, and MAGI) regardless of how much other income there is, **not** an offset
+ * capped at ordinary income. The rest carries forward indefinitely. Pure — the
+ * projection threads the depleting pool year-to-year and feeds the netted figures
+ * to BOTH the federal and state calculators, so the AGI cascade falls out. Single
+ * pool, no short-/long-term split (a documented planning simplification); the
+ * §1212 carryover-worksheet preservation of a deduction "wasted" in a year with
+ * no taxable income to absorb it is not modeled (immaterial outside zero-income
+ * years). @see DOCS/features/taxes.md
+ */
+export function applyCapitalLossCarryforward(carryforward, ordinaryIncome, capitalGains, ordinaryOffsetLimit) {
+    const pool = Math.max(0, carryforward);
+    const netGains = Math.max(0, capitalGains);
+    const ordinary = Math.max(0, ordinaryIncome);
+    const usedAgainstGains = Math.min(pool, netGains);
+    let remaining = pool - usedAgainstGains;
+    const usedAgainstOrdinary = Math.min(remaining, Math.max(0, ordinaryOffsetLimit));
+    remaining -= usedAgainstOrdinary;
+    return {
+        ordinaryAfter: ordinary,
+        netCapitalGain: netGains - usedAgainstGains - usedAgainstOrdinary,
+        usedAgainstGains,
+        usedAgainstOrdinary,
+        remaining,
+    };
+}
+export function computeFederalTax(input) {
+    const { year, filingStatus } = input;
+    const taxStatus = taxParameterFilingStatus(filingStatus);
+    const ordinary = Math.max(0, input.ordinaryIncome);
+    // `capitalGains` is signed: after a carryforward absorbs realized gains, the
+    // deductible net loss (≤ the annual limit) arrives negative — the 1040 carries
+    // it on the capital-gain line, so it reduces AGI / provisional income / taxable
+    // SS / MAGI even when there is little or no other income.
+    const netCapital = input.capitalGains;
+    const gains = Math.max(0, netCapital);
+    const qualifiedDividends = Math.max(0, input.qualifiedDividends ?? 0);
+    const ss = Math.max(0, input.ssBenefits);
+    const { pack, isStandIn } = packForYear(year);
+    const agiExcludingSs = ordinary + netCapital + qualifiedDividends; // a net capital loss can drive this below zero
+    const taxableSs = taxableSocialSecurity(pack, taxStatus, agiExcludingSs, ss);
+    const agi = Math.max(0, agiExcludingSs + taxableSs); // floor for reporting / MAGI / IRMAA / ACA
+    const magi = agi;
+    const senior = seniorDeductionAmount(pack, year, taxStatus, input.peopleAged65Plus, magi);
+    // The OBBBA senior deduction applies whether you take the standard deduction or
+    // itemize, so it rides on top of whichever base is larger.
+    const standardBase = standardDeduction(pack, taxStatus, input.peopleAged65Plus);
+    const itemized = itemizedTotal(pack, input.itemizedDeductions);
+    const useItemized = itemized > standardBase;
+    const deduction = Math.max(standardBase, itemized) + senior;
+    const taxableIncome = Math.max(0, agi - deduction);
+    const preferentialIncome = Math.min(gains + qualifiedDividends, taxableIncome);
+    const ordinaryTaxable = taxableIncome - preferentialIncome;
+    const ordinaryTax = bracketTax(pack.federalTax.brackets[taxStatus], ordinaryTaxable);
+    const capitalGainsTax = capitalGainsTaxStacked(pack, taxStatus, ordinaryTaxable, preferentialIncome);
+    const saltPreference = useItemized ? Math.min(Math.max(0, input.itemizedDeductions?.stateAndLocalTaxes ?? 0), pack.federalTax.saltCap) : 0;
+    const standardDeductionAddback = useItemized ? 0 : deduction;
+    const amtPreferenceItems = Math.max(0, input.amtPreferenceItems ?? 0) + saltPreference + standardDeductionAddback;
+    const alternativeMinimumTaxableIncome = Math.max(0, taxableIncome + amtPreferenceItems);
+    const amtExemption = amtExemptionAmount(pack, taxStatus, alternativeMinimumTaxableIncome);
+    const amtTaxableExcess = Math.max(0, alternativeMinimumTaxableIncome - amtExemption);
+    const tmt = tentativeMinimumTax(pack, taxStatus, amtTaxableExcess, gains + qualifiedDividends);
+    const regularIncomeTax = ordinaryTax + capitalGainsTax;
+    const alternativeMinimumTax = Math.max(0, tmt - regularIncomeTax);
+    const investmentIncome = gains + qualifiedDividends + Math.max(0, input.taxableInterestIncome ?? 0) + Math.max(0, input.ordinaryDividends ?? 0);
+    const niitBase = Math.min(investmentIncome, Math.max(0, magi - pack.niit.magiThreshold[taxStatus]));
+    const niit = niitBase * (pack.niit.ratePct / 100);
+    return {
+        year,
+        usesStandInPack: isStandIn,
+        taxableSocialSecurity: taxableSs,
+        agi,
+        magi,
+        deduction,
+        seniorDeduction: senior,
+        itemized: useItemized,
+        taxableIncome,
+        ordinaryTaxable,
+        preferentialIncome,
+        ordinaryTax,
+        capitalGainsTax,
+        amtPreferenceItems,
+        alternativeMinimumTaxableIncome,
+        amtExemption,
+        tentativeMinimumTax: tmt,
+        alternativeMinimumTax,
+        niit,
+        totalTax: regularIncomeTax + alternativeMinimumTax + niit,
+        zeroRateLtcgHeadroom: zeroRateLtcgHeadroom(pack, taxStatus, ordinary + Math.min(0, netCapital), gains, qualifiedDividends, ss, deduction),
+    };
+}
+/** Federal engine behind the projection's pluggable interface. */
+export function createFederalTaxCalculator() {
+    return {
+        compute: (input) => computeFederalTax(input).totalTax,
+    };
+}
+export function combineTaxCalculators(...calculators) {
+    return {
+        compute: (input) => calculators.reduce((sum, c) => sum + c.compute(input), 0),
+    };
+}

package/dist/tax/medicare.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Medicare premiums with IRMAA, per person 65+.
+ *
+ * IRMAA brackets are cliffs determined by MAGI from two years prior. Beyond
+ * the latest parameter pack, premiums are indexed at the healthcare inflation
+ * rate and bracket thresholds at general inflation (both are statutorily
+ * indexed; this is the projection's stand-in).
+ *
+ * @see DOCS/domain/domain-rules-reference.md §7
+ */
+import type { FilingStatus, ParameterPack } from '../params/types.js';
+export interface MedicarePremiumResult {
+    partBAnnual: number;
+    partDSurchargeAnnual: number;
+    /** 0 = standard premium; 1–5 = IRMAA tier. */
+    irmaaTier: number;
+    /** True when an IRMAA tier with an unverified Part D surcharge was hit. */
+    partDSurchargeUnverified: boolean;
+}
+export declare function medicareAnnualPremiumPerPerson(pack: ParameterPack, magiTwoYearsPrior: number, filingStatus: FilingStatus, thresholdScale?: number, premiumScale?: number): MedicarePremiumResult;

package/dist/tax/medicare.js

@@ -0,0 +1,36 @@
+/**
+ * Medicare premiums with IRMAA, per person 65+.
+ *
+ * IRMAA brackets are cliffs determined by MAGI from two years prior. Beyond
+ * the latest parameter pack, premiums are indexed at the healthcare inflation
+ * rate and bracket thresholds at general inflation (both are statutorily
+ * indexed; this is the projection's stand-in).
+ *
+ * @see DOCS/domain/domain-rules-reference.md §7
+ */
+import { irmaaTierForMagi } from '../params/index.js';
+export function medicareAnnualPremiumPerPerson(pack, magiTwoYearsPrior, filingStatus, thresholdScale = 1, premiumScale = 1) {
+    const tier = irmaaTierForMagi(pack, magiTwoYearsPrior, filingStatus, thresholdScale);
+    const base = pack.medicare.partBStandardMonthly;
+    let partDSurchargeMonthly = 0;
+    let partDSurchargeUnverified = false;
+    let applicablePct = 25;
+    if (tier > 0) {
+        const t = pack.medicare.irmaaTiers[tier - 1];
+        applicablePct = t.applicablePct;
+        if (t.partDSurchargeMonthly === null) {
+            partDSurchargeUnverified = true;
+        }
+        else {
+            partDSurchargeMonthly = t.partDSurchargeMonthly;
+        }
+    }
+    // Standard premium is 25% of program cost; IRMAA tiers pay a larger share.
+    const partBMonthly = base * (applicablePct / 25) * premiumScale;
+    return {
+        partBAnnual: partBMonthly * 12,
+        partDSurchargeAnnual: partDSurchargeMonthly * 12 * premiumScale,
+        irmaaTier: tier,
+        partDSurchargeUnverified,
+    };
+}

package/dist/tax/propertySale.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Fixed-asset (property) disposition tax treatment (account/HSA/fixed-asset
+ * depth plan, step 6).
+ *
+ * With a cost basis on the property account, a sale is priced exactly instead
+ * of via the legacy tax-free `expectedNetProceeds` estimate:
+ *
+ *   amount realized = sale price − selling costs
+ *   gain            = amount realized − adjusted basis
+ *   ordinary part   = min(gain, depreciation recapture)   (never excludable)
+ *   capital part    = gain − ordinary part − §121 exclusion (primary residence)
+ *
+ * §121 exclusion: $250k single / $500k joint (parameter pack; statutory and
+ * never indexed — IRS Topic 701 / Pub 523). Depreciation attributable to
+ * post-May-1997 business use cannot be excluded under §121 and is recaptured
+ * as ordinary income (planning-grade stand-in for the §1250 25% cap). A loss
+ * on personal-use property is nondeductible, so gain floors at zero.
+ */
+import type { ParameterPack, FilingStatus } from '../params/types.js';
+export interface PropertySaleInput {
+    /** Projected market value in the sale year (nominal dollars). */
+    salePrice: number;
+    /** Adjusted cost basis (purchase + improvements, historical dollars). */
+    costBasis: number;
+    /** Selling costs as a percent of the sale price (commissions, closing). */
+    sellingCostPct?: number;
+    /** Primary residence: apply the §121 exclusion to the capital gain. */
+    primaryResidence?: boolean;
+    /** Accumulated depreciation recaptured as ordinary income (≤ gain). */
+    depreciationRecapture?: number;
+    filingStatus: FilingStatus;
+    pack: ParameterPack;
+}
+export interface PropertySaleResult {
+    /** Cash entering the portfolio: sale price − selling costs (taxes ride the normal flow). */
+    netProceeds: number;
+    /** Gain taxed as ordinary income (depreciation recapture). */
+    ordinaryGain: number;
+    /** Gain taxed as long-term capital gain, after any §121 exclusion. */
+    capitalGain: number;
+    /** Gain shielded by the §121 exclusion. */
+    excludedGain: number;
+    /** Selling costs deducted from the amount realized. */
+    sellingCosts: number;
+}
+export declare function propertySaleTax(input: PropertySaleInput): PropertySaleResult;

package/dist/tax/propertySale.js

@@ -0,0 +1,35 @@
+/**
+ * Fixed-asset (property) disposition tax treatment (account/HSA/fixed-asset
+ * depth plan, step 6).
+ *
+ * With a cost basis on the property account, a sale is priced exactly instead
+ * of via the legacy tax-free `expectedNetProceeds` estimate:
+ *
+ *   amount realized = sale price − selling costs
+ *   gain            = amount realized − adjusted basis
+ *   ordinary part   = min(gain, depreciation recapture)   (never excludable)
+ *   capital part    = gain − ordinary part − §121 exclusion (primary residence)
+ *
+ * §121 exclusion: $250k single / $500k joint (parameter pack; statutory and
+ * never indexed — IRS Topic 701 / Pub 523). Depreciation attributable to
+ * post-May-1997 business use cannot be excluded under §121 and is recaptured
+ * as ordinary income (planning-grade stand-in for the §1250 25% cap). A loss
+ * on personal-use property is nondeductible, so gain floors at zero.
+ */
+export function propertySaleTax(input) {
+    const sellingCosts = Math.max(0, input.salePrice) * (Math.max(0, input.sellingCostPct ?? 0) / 100);
+    const amountRealized = Math.max(0, input.salePrice) - sellingCosts;
+    // Personal-use losses are nondeductible; gain floors at zero.
+    const gain = Math.max(0, amountRealized - Math.max(0, input.costBasis));
+    const ordinaryGain = Math.min(gain, Math.max(0, input.depreciationRecapture ?? 0));
+    const gainAfterRecapture = gain - ordinaryGain;
+    const exclusionCap = input.primaryResidence ? input.pack.federalTax.section121Exclusion[input.filingStatus] : 0;
+    const excludedGain = Math.min(gainAfterRecapture, exclusionCap);
+    return {
+        netProceeds: amountRealized,
+        ordinaryGain,
+        capitalGain: gainAfterRecapture - excludedGain,
+        excludedGain,
+        sellingCosts,
+    };
+}

package/dist/tax/stateTax.d.ts

@@ -0,0 +1,66 @@
+/**
+ * State income tax (V5, "big levers"). State taxable income starts from
+ * ordinary income plus capital gains (most states tax gains as ordinary) plus
+ * the federally taxable Social Security amount only where the state taxes SS,
+ * minus the major retirement-income exclusion and the state standard
+ * deduction; brackets then apply.
+ *
+ * A single calculator instance resolves the right state+year from each
+ * TaxYearInput, so mid-retirement moves and year-specific packs work without
+ * rebuilding it. The plan's flat effective-rate override takes precedence when
+ * set above zero (a manual correction); otherwise a modeled pack is used, and
+ * unmodeled states contribute zero until their pack ships.
+ *
+ * @see DOCS/features/taxes.md
+ */
+import { type StateTaxParams } from '../params/state/index.js';
+import { type TaxCalculator, type TaxYearInput } from '../projection/types.js';
+export interface ComputeStateTaxOptions {
+    /**
+     * Pre-computed federally taxable Social Security to add to the state base
+     * instead of recomputing it here. Split-year residency uses this: taxable SS
+     * must be derived once from full-year income against full-year federal
+     * thresholds, then apportioned to each state — recomputing it per partial-year
+     * slice against annual thresholds would understate it.
+     */
+    taxableSocialSecurityOverride?: number;
+    /** Optional flat local rate (percent) applied to computed state taxable income. */
+    localRatePct?: number;
+}
+export interface StateTaxDetail {
+    taxableIncome: number;
+    stateTax: number;
+    localTax: number;
+    totalTax: number;
+}
+export declare function computeStateTaxableIncome(params: StateTaxParams, input: TaxYearInput, opts?: ComputeStateTaxOptions): number;
+export declare function computeStateTaxDetail(params: StateTaxParams, input: TaxYearInput, opts?: ComputeStateTaxOptions): StateTaxDetail;
+export declare function computeStateTax(params: StateTaxParams, input: TaxYearInput, opts?: ComputeStateTaxOptions): number;
+export interface StateTaxOptions {
+    /** Flat effective rate (percent). When > 0 it overrides modeled packs. */
+    overridePct?: number;
+    /** Flat local income-tax rate (percent), applied to state taxable income. */
+    localPct?: number;
+}
+export interface StateTaxYearOptions extends StateTaxOptions {
+    /**
+     * Transform the resolved state params before computing. Used by the
+     * relocation-compare driver attribution to re-price a year with one state
+     * feature neutralized (e.g. "as if this state taxed Social Security");
+     * with no transform the result is exactly what the calculator charged.
+     */
+    mapParams?: (params: StateTaxParams) => StateTaxParams;
+}
+/**
+ * Full state+local tax for one TaxYearInput — the single computation behind
+ * `createStateTaxCalculator`, exported so callers can re-price a recorded
+ * ledger year (relocation-compare drivers) through the identical path,
+ * including the flat override and split-year residency proration.
+ */
+export declare function computeStateTaxYearTotal(input: TaxYearInput, opts?: StateTaxYearOptions): number;
+/**
+ * State tax behind the projection's pluggable interface. Resolves residence
+ * (input.state) and year per call so it composes with the federal calculator
+ * via combineTaxCalculators and handles mid-plan relocation.
+ */
+export declare function createStateTaxCalculator(opts?: StateTaxOptions): TaxCalculator;

package/dist/tax/stateTax.js

@@ -0,0 +1,198 @@
+/**
+ * State income tax (V5, "big levers"). State taxable income starts from
+ * ordinary income plus capital gains (most states tax gains as ordinary) plus
+ * the federally taxable Social Security amount only where the state taxes SS,
+ * minus the major retirement-income exclusion and the state standard
+ * deduction; brackets then apply.
+ *
+ * A single calculator instance resolves the right state+year from each
+ * TaxYearInput, so mid-retirement moves and year-specific packs work without
+ * rebuilding it. The plan's flat effective-rate override takes precedence when
+ * set above zero (a manual correction); otherwise a modeled pack is used, and
+ * unmodeled states contribute zero until their pack ships.
+ *
+ * @see DOCS/features/taxes.md
+ */
+import { stateParamsFor } from '../params/state/index.js';
+import { taxableSocialSecurity } from './federalTax.js';
+import { packForYear } from '../params/index.js';
+import { taxParameterFilingStatus } from '../projection/types.js';
+function bracketTax(brackets, taxable) {
+    let tax = 0;
+    for (let i = 0; i < brackets.length; i++) {
+        const lower = brackets[i].lowerBound;
+        const upper = i + 1 < brackets.length ? brackets[i + 1].lowerBound : Infinity;
+        if (taxable <= lower)
+            break;
+        tax += (Math.min(taxable, upper) - lower) * (brackets[i].ratePct / 100);
+    }
+    return tax;
+}
+/** Retirement income excluded from state taxable income, per the state's rule. */
+function retirementExclusion(rule, retirementIncome, agesAlive) {
+    const r = rule;
+    const income = Math.max(0, retirementIncome);
+    if (r.kind === 'none' || income === 0)
+        return 0;
+    const eligibleCount = r.minAge === undefined ? agesAlive.length : agesAlive.filter((a) => a >= r.minAge).length;
+    if (eligibleCount === 0)
+        return 0;
+    if (r.kind === 'full')
+        return income;
+    return Math.min(income, (r.capPerPerson ?? 0) * eligibleCount);
+}
+export function computeStateTaxableIncome(params, input, opts = {}) {
+    if (!params.hasIncomeTax)
+        return 0;
+    const taxStatus = taxParameterFilingStatus(input.filingStatus);
+    const ordinary = Math.max(0, input.ordinaryIncome);
+    const qualifiedDividends = Math.max(0, input.qualifiedDividends ?? 0);
+    // Signed: a capital-loss carryforward arrives as a negative net capital gain,
+    // which reduces state taxable income (and its SS base) just like it does federally.
+    const netCapital = params.capitalLossCarryforwardConformity === 'currentYearOnly'
+        ? Math.max(0, input.realizedCapitalGainsBeforeCarryforward ?? input.capitalGains)
+        : input.capitalGains;
+    const taxableCapitalPct = (params.capitalGainsTaxablePct ?? (params.capitalGainsAsOrdinary ? 100 : 0)) / 100;
+    const ss = Math.max(0, input.ssBenefits);
+    // Interest on U.S. government obligations (Treasury/TIPS) is exempt from
+    // state income tax in every state (31 U.S.C. §3124). It arrives inside
+    // ordinaryIncome, so subtract it from the state base here.
+    const usGovInterest = Math.min(ordinary, Math.max(0, input.usGovernmentInterest ?? 0));
+    let taxable = ordinary - usGovInterest + qualifiedDividends;
+    if (taxableCapitalPct > 0)
+        taxable += netCapital * taxableCapitalPct;
+    if (params.taxesSocialSecurity && ss > 0) {
+        if (opts.taxableSocialSecurityOverride !== undefined) {
+            taxable += Math.max(0, opts.taxableSocialSecurityOverride);
+        }
+        else {
+            const { pack } = packForYear(input.year);
+            taxable += taxableSocialSecurity(pack, taxStatus, ordinary + qualifiedDividends + netCapital, ss);
+        }
+    }
+    const privateRetirement = input.privateRetirementIncome ?? input.retirementIncome ?? 0;
+    const publicPension = input.publicPensionIncome ?? 0;
+    const agesAlive = input.agesAlive ?? [];
+    if (params.retirementRuleShared) {
+        // One all-retirement rule copied into both buckets: a capped exclusion
+        // applies once to the combined retirement income, not once per bucket.
+        taxable -= retirementExclusion(params.retirementPrivate, privateRetirement + publicPension, agesAlive);
+    }
+    else {
+        taxable -= retirementExclusion(params.retirementPrivate, privateRetirement, agesAlive);
+        taxable -= retirementExclusion(params.retirementPublic, publicPension, agesAlive);
+    }
+    taxable -= params.standardDeduction[taxStatus];
+    return Math.max(0, taxable);
+}
+export function computeStateTaxDetail(params, input, opts = {}) {
+    const taxableIncome = computeStateTaxableIncome(params, input, opts);
+    const taxStatus = taxParameterFilingStatus(input.filingStatus);
+    const stateTax = params.hasIncomeTax ? bracketTax(params.brackets[taxStatus], taxableIncome) : 0;
+    const localTax = taxableIncome * (Math.max(0, opts.localRatePct ?? 0) / 100);
+    return { taxableIncome, stateTax, localTax, totalTax: stateTax + localTax };
+}
+export function computeStateTax(params, input, opts = {}) {
+    return computeStateTaxDetail(params, input, opts).stateTax;
+}
+function scaleExclusion(rule, scale) {
+    return rule.capPerPerson === undefined ? rule : { ...rule, capPerPerson: rule.capPerPerson * scale };
+}
+function prorateParams(params, scale) {
+    return {
+        ...params,
+        standardDeduction: {
+            single: params.standardDeduction.single * scale,
+            marriedFilingJointly: params.standardDeduction.marriedFilingJointly * scale,
+        },
+        brackets: {
+            single: params.brackets.single.map((b) => ({ ...b, lowerBound: b.lowerBound * scale })),
+            marriedFilingJointly: params.brackets.marriedFilingJointly.map((b) => ({ ...b, lowerBound: b.lowerBound * scale })),
+        },
+        retirementPrivate: scaleExclusion(params.retirementPrivate, scale),
+        retirementPublic: scaleExclusion(params.retirementPublic, scale),
+    };
+}
+function prorateInput(input, scale, state) {
+    return {
+        ...input,
+        state,
+        stateResidency: undefined,
+        ordinaryIncome: input.ordinaryIncome * scale,
+        capitalGains: input.capitalGains * scale,
+        realizedCapitalGainsBeforeCarryforward: input.realizedCapitalGainsBeforeCarryforward === undefined
+            ? undefined
+            : input.realizedCapitalGainsBeforeCarryforward * scale,
+        taxableInterestIncome: (input.taxableInterestIncome ?? 0) * scale,
+        usGovernmentInterest: input.usGovernmentInterest === undefined ? undefined : input.usGovernmentInterest * scale,
+        ordinaryDividends: (input.ordinaryDividends ?? 0) * scale,
+        qualifiedDividends: (input.qualifiedDividends ?? 0) * scale,
+        ssBenefits: input.ssBenefits * scale,
+        retirementIncome: input.retirementIncome === undefined ? undefined : input.retirementIncome * scale,
+        privateRetirementIncome: input.privateRetirementIncome === undefined ? undefined : input.privateRetirementIncome * scale,
+        publicPensionIncome: input.publicPensionIncome === undefined ? undefined : input.publicPensionIncome * scale,
+    };
+}
+/**
+ * Full state+local tax for one TaxYearInput — the single computation behind
+ * `createStateTaxCalculator`, exported so callers can re-price a recorded
+ * ledger year (relocation-compare drivers) through the identical path,
+ * including the flat override and split-year residency proration.
+ */
+export function computeStateTaxYearTotal(input, opts = {}) {
+    const overrideRate = Math.max(0, opts.overridePct ?? 0) / 100;
+    const localRatePct = Math.max(0, opts.localPct ?? 0);
+    const localRate = localRatePct / 100;
+    const resolveParams = (code) => {
+        const params = stateParamsFor(code, input.year);
+        return params && opts.mapParams ? opts.mapParams(params) : params;
+    };
+    if (overrideRate > 0) {
+        // The flat effective rate approximates a state return, so it still
+        // honors the universal U.S.-government-interest exemption.
+        const base = Math.max(0, Math.max(0, input.ordinaryIncome) - Math.max(0, input.usGovernmentInterest ?? 0)) +
+            Math.max(0, input.capitalGains) +
+            Math.max(0, input.qualifiedDividends ?? 0);
+        return base * (overrideRate + localRate);
+    }
+    if (input.stateResidency && input.stateResidency.length > 0) {
+        // Taxable SS is a full-year federal computation: derive it once from
+        // annual income and thresholds, then apportion it to each state by
+        // months of residency (recomputing per slice would understate it).
+        let annualTaxableSs = 0;
+        if (input.ssBenefits > 0) {
+            const { pack } = packForYear(input.year);
+            annualTaxableSs = taxableSocialSecurity(pack, taxParameterFilingStatus(input.filingStatus), Math.max(0, input.ordinaryIncome) + Math.max(0, input.qualifiedDividends ?? 0) + input.capitalGains, input.ssBenefits);
+        }
+        return input.stateResidency.reduce((sum, segment) => {
+            const months = Math.min(12, Math.max(0, segment.months));
+            if (months <= 0)
+                return sum;
+            const params = resolveParams(segment.state);
+            if (!params)
+                return sum;
+            const scale = months / 12;
+            const detail = computeStateTaxDetail(prorateParams(params, scale), prorateInput(input, scale, segment.state), {
+                taxableSocialSecurityOverride: annualTaxableSs * scale,
+                localRatePct,
+            });
+            return sum + detail.totalTax;
+        }, 0);
+    }
+    if (!input.state)
+        return 0;
+    const params = resolveParams(input.state);
+    return params ? computeStateTaxDetail(params, input, { localRatePct }).totalTax : 0;
+}
+/**
+ * State tax behind the projection's pluggable interface. Resolves residence
+ * (input.state) and year per call so it composes with the federal calculator
+ * via combineTaxCalculators and handles mid-plan relocation.
+ */
+export function createStateTaxCalculator(opts = {}) {
+    return {
+        compute(input) {
+            return computeStateTaxYearTotal(input, opts);
+        },
+    };
+}

package/dist/testing/money.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tolerance assertions for money and percentages. Deliberately framework-free
+ * (a thrown Error fails a test in any runner), so `@retiregolden/engine/testing/*`
+ * carries no runtime dependency on vitest for consumers.
+ */
+export declare function expectMoney(actual: number, expected: number, tolerance?: number): void;
+export declare function expectPercent(actual: number, expected: number, tolerance?: number): void;