@retiregolden/engine 0.1.0

package/dist/strategies/rothBasis.js

@@ -0,0 +1,83 @@
+/**
+ * Roth ordering + 5-year rules (roadmap V8, §4 tax depth).
+ *
+ * A Roth distribution comes out in a fixed IRS order, and each layer is taxed
+ * differently before the account is "qualified" (owner 59½+ and the account 5+
+ * years old):
+ *   1. Contributions  — always tax- AND penalty-free, at any age.
+ *   2. Conversions    — oldest first; already taxed at conversion, so never
+ *                       income-taxed again, BUT a 10% recapture penalty applies
+ *                       to any layer tapped within 5 years while under 59½.
+ *   3. Earnings       — last out; before 59½ they are ordinary income PLUS the
+ *                       10% penalty (a non-qualified distribution).
+ *
+ * The engine approximates the 59½ boundary as "age 60 attained," matching the
+ * traditional early-withdrawal penalty elsewhere in the simulation, and folds
+ * the account's own 5-year clock into that age proxy (an existing Roth is
+ * almost always open >5 years by 59½). Conversions performed during the
+ * projection each carry their own explicit 5-year clock, which is the case that
+ * actually matters for the early-retirement "conversion ladder."
+ */
+/** The engine's 59½ proxy: no early-withdrawal penalty once age 60 is attained. */
+export const ROTH_QUALIFIED_AGE = 60;
+/** A conversion is "seasoned" (no recapture penalty) once this many years pass. */
+export const ROTH_SEASONING_YEARS = 5;
+/** An empty (fresh) basis state, e.g. for a brand-new Roth account. */
+export function emptyRothBasis(contributionBasis = 0) {
+    return { contributionBasis, conversionLayers: [] };
+}
+/**
+ * Split a Roth withdrawal into contribution / conversion / earnings buckets and
+ * the early-distribution tax + penalty it incurs. Pure: returns the post-
+ * withdrawal `next` state rather than mutating, so callers can probe a candidate
+ * withdrawal during the tax fixed-point and only commit once it converges.
+ *
+ * `amount` is assumed ≤ the account balance (the caller drains against available
+ * balance), so the remainder after contributions and conversions is earnings.
+ */
+export function splitRothWithdrawal(state, amount, year, age) {
+    const qualified = age >= ROTH_QUALIFIED_AGE;
+    let remaining = Math.max(0, amount);
+    // 1) Contributions — always tax- and penalty-free.
+    const contributions = Math.min(remaining, state.contributionBasis);
+    remaining -= contributions;
+    const contributionBasis = state.contributionBasis - contributions;
+    // 2) Conversions, oldest first. Tax-free (already taxed at conversion); a 10%
+    //    penalty applies to a layer tapped within 5 years while under 59½.
+    let conversions = 0;
+    let penalty = 0;
+    const conversionLayers = [];
+    for (const layer of state.conversionLayers) {
+        if (remaining <= 0) {
+            conversionLayers.push(layer);
+            continue;
+        }
+        const take = Math.min(remaining, layer.amount);
+        conversions += take;
+        remaining -= take;
+        // The recapture penalty applies only to the taxable share of the principal
+        // tapped; nondeductible basis that was converted recaptures nothing.
+        const taxableTake = layer.amount > 0 ? take * (layer.taxableAmount / layer.amount) : 0;
+        if (year - layer.year < ROTH_SEASONING_YEARS && !qualified)
+            penalty += taxableTake * 0.1;
+        const left = layer.amount - take;
+        if (left > 0)
+            conversionLayers.push({ year: layer.year, amount: left, taxableAmount: layer.taxableAmount - taxableTake });
+    }
+    // 3) Earnings — last out. Non-qualified (pre-59½) earnings are ordinary income
+    //    plus the 10% penalty; qualified earnings are tax- and penalty-free.
+    const earnings = remaining;
+    let taxableOrdinary = 0;
+    if (earnings > 0 && !qualified) {
+        taxableOrdinary = earnings;
+        penalty += earnings * 0.1;
+    }
+    return {
+        contributions,
+        conversions,
+        earnings,
+        penalty,
+        taxableOrdinary,
+        next: { contributionBasis, conversionLayers },
+    };
+}

package/dist/strategies/rothConversion.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Roth-conversion sizing (roadmap V3).
+ *
+ * Fill-to-target strategies size each year's conversion so a chosen metric
+ * lands on a ceiling:
+ *   - topOfBracket: federal taxable income fills the chosen rate bracket
+ *   - irmaaTier:    MAGI stays just under a chosen IRMAA tier threshold
+ *   - acaCliff:     MAGI stays just under 400% FPL (pre-65 credit cliff)
+ *   - fixedMagi:    MAGI lands on a user-set nominal ceiling
+ *
+ * Sizing is solved by bisection against the federal tax engine, because the
+ * metrics are monotone in the conversion amount but kinked (taxable Social
+ * Security phases in at up to 1.85× per converted dollar). The sizing model
+ * is always the federal engine, regardless of which TaxCalculator the
+ * projection runs — strategies target federal-law boundaries by definition.
+ *
+ * Threshold scaling matches the projection's expense model: IRMAA thresholds
+ * and the FPL index at general inflation beyond the published pack; bracket
+ * bounds stay at the latest pack's nominal values (as the tax engine itself
+ * does for stand-in years).
+ */
+import type { Plan } from '../model/plan.js';
+import type { FilingStatus, ParameterPack } from '../params/types.js';
+import type { TaxYearInput } from '../projection/types.js';
+export type FillTarget = Extract<Plan['strategies']['rothConversion'], {
+    mode: 'fillToTarget';
+}>;
+export interface ConversionSizingInput {
+    year: number;
+    pack: ParameterPack;
+    filingStatus: FilingStatus;
+    /** Ordinary income before any conversion (wages − pre-tax contributions + RMD − QCD + pensions etc.). */
+    ordinaryIncomeBase: number;
+    /** Capital gains known before withdrawals (one-time events). */
+    capitalGains: number;
+    /** Qualified dividends known before withdrawals; included in MAGI and preferential stacking. */
+    qualifiedDividends?: number;
+    ssBenefits: number;
+    peopleAged65Plus: number;
+    /** Living household size (FPL). */
+    householdSize: number;
+    /** Scale applied to IRMAA thresholds / FPL for years beyond the pack. */
+    inflationScale: number;
+    /** Itemized deductions (nominal) so bracket/MAGI targets use the right deduction. */
+    itemizedDeductions?: TaxYearInput['itemizedDeductions'];
+}
+export type SizingResult = {
+    ok: true;
+    amount: number;
+} | {
+    ok: false;
+    reason: 'bad_target' | 'already_over_ceiling';
+};
+/** Largest conversion keeping the strategy's metric at or under its ceiling. */
+export declare function sizeRothConversion(strategy: FillTarget, input: ConversionSizingInput): SizingResult;

package/dist/strategies/rothConversion.js

@@ -0,0 +1,83 @@
+/**
+ * Roth-conversion sizing (roadmap V3).
+ *
+ * Fill-to-target strategies size each year's conversion so a chosen metric
+ * lands on a ceiling:
+ *   - topOfBracket: federal taxable income fills the chosen rate bracket
+ *   - irmaaTier:    MAGI stays just under a chosen IRMAA tier threshold
+ *   - acaCliff:     MAGI stays just under 400% FPL (pre-65 credit cliff)
+ *   - fixedMagi:    MAGI lands on a user-set nominal ceiling
+ *
+ * Sizing is solved by bisection against the federal tax engine, because the
+ * metrics are monotone in the conversion amount but kinked (taxable Social
+ * Security phases in at up to 1.85× per converted dollar). The sizing model
+ * is always the federal engine, regardless of which TaxCalculator the
+ * projection runs — strategies target federal-law boundaries by definition.
+ *
+ * Threshold scaling matches the projection's expense model: IRMAA thresholds
+ * and the FPL index at general inflation beyond the published pack; bracket
+ * bounds stay at the latest pack's nominal values (as the tax engine itself
+ * does for stand-in years).
+ */
+import { computeFederalTax } from '../tax/federalTax.js';
+function metricFor(target, detail) {
+    return target === 'topOfBracket' ? detail.taxableIncome : detail.magi;
+}
+function ceilingFor(strategy, input) {
+    const { pack, filingStatus } = input;
+    switch (strategy.target) {
+        case 'topOfBracket': {
+            const brackets = pack.federalTax.brackets[filingStatus];
+            const i = brackets.findIndex((b) => b.ratePct === strategy.targetValue);
+            if (i < 0 || i + 1 >= brackets.length)
+                return null; // unknown rate or open-ended top bracket
+            return brackets[i + 1].lowerBound;
+        }
+        case 'irmaaTier': {
+            const tier = strategy.targetValue;
+            if (tier === null || !Number.isInteger(tier) || tier < 1 || tier > pack.medicare.irmaaTiers.length)
+                return null;
+            return pack.medicare.irmaaTiers[tier - 1].magiOver[filingStatus] * input.inflationScale;
+        }
+        case 'acaCliff': {
+            const fpl = pack.federalPovertyLine.firstPerson +
+                pack.federalPovertyLine.perAdditionalPerson * Math.max(0, input.householdSize - 1);
+            return fpl * input.inflationScale * (pack.aca.maxFplPctForCredit / 100);
+        }
+        case 'fixedMagi':
+            return strategy.targetValue !== null && strategy.targetValue > 0 ? strategy.targetValue : null;
+    }
+}
+/** Largest conversion keeping the strategy's metric at or under its ceiling. */
+export function sizeRothConversion(strategy, input) {
+    const ceiling = ceilingFor(strategy, input);
+    if (ceiling === null)
+        return { ok: false, reason: 'bad_target' };
+    const metricAt = (conversion) => metricFor(strategy.target, computeFederalTax({
+        year: input.year,
+        filingStatus: input.filingStatus,
+        ordinaryIncome: input.ordinaryIncomeBase + conversion,
+        capitalGains: input.capitalGains,
+        qualifiedDividends: input.qualifiedDividends ?? 0,
+        ssBenefits: input.ssBenefits,
+        peopleAged65Plus: input.peopleAged65Plus,
+        itemizedDeductions: input.itemizedDeductions,
+    }));
+    const base = metricAt(0);
+    if (base >= ceiling)
+        return { ok: false, reason: 'already_over_ceiling' };
+    // Taxable income can rise $0 per converted dollar until deductions are
+    // consumed, so expand the upper bound until it brackets the ceiling.
+    let lo = 0;
+    let hi = Math.max(ceiling - base, 1_000);
+    for (let i = 0; i < 30 && metricAt(hi) <= ceiling; i++)
+        hi *= 2;
+    for (let i = 0; i < 60 && hi - lo > 0.01; i++) {
+        const mid = (lo + hi) / 2;
+        if (metricAt(mid) > ceiling)
+            hi = mid;
+        else
+            lo = mid;
+    }
+    return { ok: true, amount: lo };
+}

package/dist/strategies/sepp.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 72(t) Substantially Equal Periodic Payments (roadmap V8, §4 tax depth).
+ *
+ * A 72(t) SEPP lets someone tap a traditional IRA/401(k) before 59½ without the
+ * 10% early-withdrawal penalty, IF they take a fixed series of "substantially
+ * equal" payments for the LONGER of five years or until age 59½. Modifying the
+ * series early triggers retroactive penalties; the engine assumes the schedule
+ * is honored (it doesn't model busting).
+ *
+ * Two of the three IRS-sanctioned methods are supported:
+ *   - 'rmd':          payment = balance ÷ life-expectancy divisor, recomputed
+ *                     each year (varies with the balance).
+ *   - 'amortization': payment fixed at the first SEPP year, amortizing that
+ *                     year's balance over the life expectancy at the chosen
+ *                     interest rate (IRS Notice 2022-6 allows up to 120% of the
+ *                     federal mid-term AFR; we use a flat assumed rate).
+ *
+ * The life-expectancy divisor uses the repo's SSA period table
+ * (`baselineRemainingYears`) as a documented proxy for the IRS Single Life
+ * Table — close enough for a planning tool and avoids carrying a second table.
+ */
+import type { Sex } from '../longevity/types.js';
+export type SeppMethod = 'rmd' | 'amortization';
+/** Assumed 72(t) interest rate for the amortization method (the common 5% floor). */
+export declare const SEPP_AMORTIZATION_RATE_PCT = 5;
+/**
+ * A SEPP must run for the LONGER of 5 years or until age 59½ (≈ the engine's
+ * age-60 penalty boundary). Active in the year the owner attains `age` when the
+ * election has started and neither condition has yet been satisfied.
+ */
+export declare function seppActive(startAge: number, age: number): boolean;
+/**
+ * The penalty-free SEPP distribution for the year, by method.
+ *  - rmd:          `balance` is the current start-of-year balance.
+ *  - amortization: `balance` is the FIRST SEPP year's balance and `age` should
+ *                  be `startAge`; the result is fixed for the whole series.
+ */
+export declare function seppAnnualAmount(method: SeppMethod, balance: number, age: number, sex: Sex, ratePct?: number): number;

package/dist/strategies/sepp.js

@@ -0,0 +1,53 @@
+/**
+ * 72(t) Substantially Equal Periodic Payments (roadmap V8, §4 tax depth).
+ *
+ * A 72(t) SEPP lets someone tap a traditional IRA/401(k) before 59½ without the
+ * 10% early-withdrawal penalty, IF they take a fixed series of "substantially
+ * equal" payments for the LONGER of five years or until age 59½. Modifying the
+ * series early triggers retroactive penalties; the engine assumes the schedule
+ * is honored (it doesn't model busting).
+ *
+ * Two of the three IRS-sanctioned methods are supported:
+ *   - 'rmd':          payment = balance ÷ life-expectancy divisor, recomputed
+ *                     each year (varies with the balance).
+ *   - 'amortization': payment fixed at the first SEPP year, amortizing that
+ *                     year's balance over the life expectancy at the chosen
+ *                     interest rate (IRS Notice 2022-6 allows up to 120% of the
+ *                     federal mid-term AFR; we use a flat assumed rate).
+ *
+ * The life-expectancy divisor uses the repo's SSA period table
+ * (`baselineRemainingYears`) as a documented proxy for the IRS Single Life
+ * Table — close enough for a planning tool and avoids carrying a second table.
+ */
+import { baselineRemainingYears } from '../longevity/ssaPeriod2022.js';
+/** Assumed 72(t) interest rate for the amortization method (the common 5% floor). */
+export const SEPP_AMORTIZATION_RATE_PCT = 5;
+/**
+ * A SEPP must run for the LONGER of 5 years or until age 59½ (≈ the engine's
+ * age-60 penalty boundary). Active in the year the owner attains `age` when the
+ * election has started and neither condition has yet been satisfied.
+ */
+export function seppActive(startAge, age) {
+    if (age < startAge)
+        return false;
+    return age < 60 || age - startAge < 5;
+}
+/**
+ * The penalty-free SEPP distribution for the year, by method.
+ *  - rmd:          `balance` is the current start-of-year balance.
+ *  - amortization: `balance` is the FIRST SEPP year's balance and `age` should
+ *                  be `startAge`; the result is fixed for the whole series.
+ */
+export function seppAnnualAmount(method, balance, age, sex, ratePct = SEPP_AMORTIZATION_RATE_PCT) {
+    if (balance <= 0)
+        return 0;
+    const lifeExpectancy = Math.max(1, baselineRemainingYears(age, sex));
+    if (method === 'rmd')
+        return balance / lifeExpectancy;
+    // Amortization: level payment amortizing `balance` over `lifeExpectancy` years
+    // at `ratePct`. With r = 0 this degenerates to balance ÷ years.
+    const r = ratePct / 100;
+    if (r === 0)
+        return balance / lifeExpectancy;
+    return (balance * r) / (1 - Math.pow(1 + r, -lifeExpectancy));
+}

package/dist/tax/aca.d.ts

@@ -0,0 +1,40 @@
+/**
+ * ACA premium tax credit for pre-65 retirees (post-2025 law: enhanced credits
+ * expired, 400% FPL cliff restored). The credit is computed against MAGI and
+ * the household's poverty-line ratio; $1 over the cliff forfeits everything —
+ * a first-class constraint on Roth conversions and gain harvesting.
+ *
+ * @see DOCS/domain/domain-rules-reference.md §8
+ */
+import type { ParameterPack } from '../params/types.js';
+export interface AcaResult {
+    /** MAGI as a percentage of the federal poverty line. */
+    fplPct: number;
+    /** Expected annual contribution toward the benchmark premium. */
+    expectedContribution: number;
+    credit: number;
+    netAnnualPremium: number;
+    /** True when income sits above the credit cutoff (the cliff). */
+    overCliff: boolean;
+}
+/** Piecewise-linear applicable percentage for a poverty-line ratio. */
+export declare function acaApplicablePct(pack: ParameterPack, fplPct: number): number;
+/**
+ * Net marketplace premium after the credit.
+ *
+ * `fullAnnualPremium` is the household's unsubsidized premium, which v1 also
+ * uses as the benchmark-plan proxy (separate benchmark entry is a later
+ * refinement). `fplScale` indexes the poverty line for years past the pack.
+ */
+export declare function acaNetAnnualPremium(pack: ParameterPack, householdSize: number, magi: number, fullAnnualPremium: number, fplScale?: number): AcaResult;
+/**
+ * Net marketplace premium when coverage varies by month (the age-65 transition
+ * year). The PTC is a monthly credit — each covered month gets
+ * `max(0, premium_m − expectedContribution/12)` — so a member covered for five
+ * months owes five-twelfths of the household expected contribution, not all of
+ * it. With twelve equal covered months this matches `acaNetAnnualPremium`;
+ * months with zero premium (no marketplace coverage) earn no credit.
+ */
+export declare function acaNetAnnualPremiumByMonth(pack: ParameterPack, householdSize: number, magi: number, 
+/** Household marketplace premium per calendar month (length 12; 0 = not covered). */
+monthlyPremiums: readonly number[], fplScale?: number): AcaResult;

package/dist/tax/aca.js

@@ -0,0 +1,82 @@
+/**
+ * ACA premium tax credit for pre-65 retirees (post-2025 law: enhanced credits
+ * expired, 400% FPL cliff restored). The credit is computed against MAGI and
+ * the household's poverty-line ratio; $1 over the cliff forfeits everything —
+ * a first-class constraint on Roth conversions and gain harvesting.
+ *
+ * @see DOCS/domain/domain-rules-reference.md §8
+ */
+/** Piecewise-linear applicable percentage for a poverty-line ratio. */
+export function acaApplicablePct(pack, fplPct) {
+    const points = pack.aca.applicablePctBreakpoints;
+    if (fplPct <= points[0].fplPct)
+        return points[0].applicablePct;
+    for (let i = 1; i < points.length; i++) {
+        const prev = points[i - 1];
+        const next = points[i];
+        if (fplPct <= next.fplPct) {
+            const t = (fplPct - prev.fplPct) / (next.fplPct - prev.fplPct);
+            return prev.applicablePct + t * (next.applicablePct - prev.applicablePct);
+        }
+    }
+    return points[points.length - 1].applicablePct;
+}
+/**
+ * Net marketplace premium after the credit.
+ *
+ * `fullAnnualPremium` is the household's unsubsidized premium, which v1 also
+ * uses as the benchmark-plan proxy (separate benchmark entry is a later
+ * refinement). `fplScale` indexes the poverty line for years past the pack.
+ */
+export function acaNetAnnualPremium(pack, householdSize, magi, fullAnnualPremium, fplScale = 1) {
+    const fpl = (pack.federalPovertyLine.firstPerson + pack.federalPovertyLine.perAdditionalPerson * Math.max(0, householdSize - 1)) *
+        fplScale;
+    const fplPct = fpl > 0 ? (magi / fpl) * 100 : Infinity;
+    const overCliff = fplPct > pack.aca.maxFplPctForCredit;
+    if (overCliff || fullAnnualPremium <= 0) {
+        return { fplPct, expectedContribution: 0, credit: 0, netAnnualPremium: fullAnnualPremium, overCliff };
+    }
+    const expectedContribution = (acaApplicablePct(pack, fplPct) / 100) * magi;
+    const credit = Math.max(0, fullAnnualPremium - expectedContribution);
+    return {
+        fplPct,
+        expectedContribution,
+        credit,
+        netAnnualPremium: fullAnnualPremium - credit,
+        overCliff,
+    };
+}
+/**
+ * Net marketplace premium when coverage varies by month (the age-65 transition
+ * year). The PTC is a monthly credit — each covered month gets
+ * `max(0, premium_m − expectedContribution/12)` — so a member covered for five
+ * months owes five-twelfths of the household expected contribution, not all of
+ * it. With twelve equal covered months this matches `acaNetAnnualPremium`;
+ * months with zero premium (no marketplace coverage) earn no credit.
+ */
+export function acaNetAnnualPremiumByMonth(pack, householdSize, magi, 
+/** Household marketplace premium per calendar month (length 12; 0 = not covered). */
+monthlyPremiums, fplScale = 1) {
+    const fullAnnualPremium = monthlyPremiums.reduce((sum, premium) => sum + premium, 0);
+    const fpl = (pack.federalPovertyLine.firstPerson + pack.federalPovertyLine.perAdditionalPerson * Math.max(0, householdSize - 1)) *
+        fplScale;
+    const fplPct = fpl > 0 ? (magi / fpl) * 100 : Infinity;
+    const overCliff = fplPct > pack.aca.maxFplPctForCredit;
+    if (overCliff || fullAnnualPremium <= 0) {
+        return { fplPct, expectedContribution: 0, credit: 0, netAnnualPremium: fullAnnualPremium, overCliff };
+    }
+    const expectedContribution = (acaApplicablePct(pack, fplPct) / 100) * magi;
+    let credit = 0;
+    for (const premium of monthlyPremiums) {
+        if (premium <= 0)
+            continue;
+        credit += Math.max(0, premium - expectedContribution / 12);
+    }
+    return {
+        fplPct,
+        expectedContribution,
+        credit,
+        netAnnualPremium: fullAnnualPremium - credit,
+        overCliff,
+    };
+}

package/dist/tax/federalTax.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 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 type { FilingStatus, ParameterPack } from '../params/types.js';
+import { type TaxCalculator, type TaxYearInput } from '../projection/types.js';
+export interface FederalTaxDetail {
+    year: number;
+    /** True when this year's figures use a stand-in parameter pack. */
+    usesStandInPack: boolean;
+    taxableSocialSecurity: number;
+    agi: number;
+    magi: number;
+    deduction: number;
+    seniorDeduction: number;
+    /** True when the itemized total beat the standard deduction this year. */
+    itemized: boolean;
+    taxableIncome: number;
+    /** Taxable income taxed at ordinary rates (after preferential carve-out). */
+    ordinaryTaxable: number;
+    /** LTCG + qualified dividends taxed via stacking. */
+    preferentialIncome: number;
+    ordinaryTax: number;
+    capitalGainsTax: number;
+    /** AMT add-backs and preference items included in AMTI. */
+    amtPreferenceItems: number;
+    alternativeMinimumTaxableIncome: number;
+    amtExemption: number;
+    tentativeMinimumTax: number;
+    alternativeMinimumTax: number;
+    niit: number;
+    totalTax: number;
+    /** Additional long-term gains realizable this year still taxed at 0% (gain-harvesting headroom). */
+    zeroRateLtcgHeadroom: number;
+}
+/**
+ * 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 declare function zeroRateLtcgHeadroom(pack: ParameterPack, filingStatus: FilingStatus, ordinaryExcludingSs: number, currentGains: number, currentQualifiedDividends: number, ssBenefits: number, deduction: number): number;
+/**
+ * Taxable share of Social Security benefits (IRC §86).
+ * Provisional income = AGI excluding SS + 50% of benefits (tax-exempt interest not modeled).
+ */
+export declare function taxableSocialSecurity(pack: ParameterPack, filingStatus: FilingStatus, agiExcludingSs: number, ssBenefits: number): number;
+/** One year's result of applying a capital-loss carryforward to income. */
+export interface CarryforwardNetting {
+    /** Ordinary income — unchanged; the deductible loss rides the capital line, not ordinary income. */
+    ordinaryAfter: number;
+    /**
+     * Net capital gain after the pool absorbs realized gains and the deductible
+     * net loss is taken: positive when gains remain, negative (down to
+     * −ordinaryOffsetLimit) when a net loss is deducted. Feeds the tax engine's
+     * signed `capitalGains` input.
+     */
+    netCapitalGain: number;
+    /** Realized gains the pool absorbed this year. */
+    usedAgainstGains: number;
+    /** Net loss deducted against income this year (≤ the annual limit); reduces AGI. */
+    usedAgainstOrdinary: number;
+    /** Pool carried into next year. */
+    remaining: number;
+}
+/**
+ * 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 declare function applyCapitalLossCarryforward(carryforward: number, ordinaryIncome: number, capitalGains: number, ordinaryOffsetLimit: number): CarryforwardNetting;
+export declare function computeFederalTax(input: TaxYearInput): FederalTaxDetail;
+/** Federal engine behind the projection's pluggable interface. */
+export declare function createFederalTaxCalculator(): TaxCalculator;
+export declare function combineTaxCalculators(...calculators: TaxCalculator[]): TaxCalculator;