RetireGolden

Calculation catalog › Taxes

Tax total annual

All tax charged for a projection year, excluding penalties.

Field: Total tax Unit: US dollars Basis: nominal dollars Computed by: Engine Status: Complete chain

Appears in: chart (tax); csv (tax); report (yearLedger); results-table (tax); survivor-page (Tax around the transition cell "a → b" (death year and first survivor year)); scenarios-page (Annual "Tax" and lifetime "Lifetime tax"); cash-flow-drilldown (settledTax use line); mcp (run_projection.years[].tax)

Calculation records

  • Annual composed tax Composition record, justified by derivation

    Purpose: What the year's published tax figure is composed of, and what it excludes.

    Statement: projection/internal/types/result.ts#YearResult.tax is the amount produced by the composed calculator built by tax/federalTax.ts#combineTaxCalculators: the federal total of regular income tax plus AMT plus NIIT, plus the state calculator amount, plus any further composed calculator amounts. Penalties are excluded from it, from AGI and from MAGI. Units: nominal USD per year. Rounding: none; the composition is an ordered fold.

    Formula: tax = federalTotal + stateAmount + sum of further calculator amounts

    • federalTotal: Regular income tax + AMT + NIIT (unit: usd/year) (domain: nonnegative)
    • stateAmount: State calculator amount (unit: usd/year) (domain: nonnegative)
    • penalties: Early-withdrawal and IRC 4974 amounts (unit: usd/year) (domain: never a member of tax)

    Timing: once per accepted tax evaluation in the projection year

    Rounding: none

    Limits:

    • The worksheet treats the federal and state amounts as outputs independently evidenced by their own worksheets and checks only the annual composition boundary, so the test composes two calculators that report the worksheet's stated 12,000 federal total and 3,000 state amount and asserts the composed 15,000 through both compute and computeResult. Those two calculators are test doubles standing in for the evidenced federal and state records; this record makes no claim about federal or state tax arithmetic
    • The 500 of penalties is asserted as excluded by composing the same calculators and showing the amount is unchanged: penalties never enter the calculator chain at all

    Provenance: derived by codex, implemented by claude.

    Independent review: cursor

    Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

    Worksheet: tax-total-annual.md Mutation receipt: tax-total-annual.mutation.md

    Evidence tests: federalTax.evidence.test.ts

    Implemented in: result.ts; federalTax.ts

    Is the number of: tax-total-annual

    Feeds: portfolio-need-annual, surplus-invested-annual, display-tax-plus-penalties-annual, display-total-spending-annual

Records that feed this number

  • Capital-loss carryforward netting Composition record, justified by derivation

    Purpose: Spend a capital-loss pool against current gains first, then report the annual ordinary-offset slice on the capital-gain line.

    Statement: tax/federalTax.ts#applyCapitalLossCarryforward applies an annual capital-loss pool first against current gains, then reports up to the annual ordinary-offset limit as a negative capital-gain-line amount without changing ordinary income, and carries the unused pool forward. The offset is not capped by ordinary income. Units: nominal USD. Rounding: none.

    Formula: usedAgainstGains = min(C, max(G, 0)); availableLoss = C - usedAgainstGains + max(-G, 0); usedAgainstOrdinary = min(availableLoss, L); netCapitalGain = max(G, 0) - usedAgainstGains - usedAgainstOrdinary; remaining = availableLoss - usedAgainstOrdinary

    • C: Opening carryforward pool (unit: usd) (domain: nonnegative after the max(0, .) floor)
    • G: Signed current capital result; a loss is negative (unit: usd) (domain: any finite number)
    • L: Annual ordinary-offset limit, year2026.federalTax.capitalLossOrdinaryOffsetLimit (unit: usd/year) (domain: nonnegative after the max(0, .) floor)

    Timing: one tax year; the projection threads the depleting pool year to year

    Rounding: none

    Limits:

    • Ordinary income is never reduced directly: the deductible loss rides the capital-gain line, so subtracting the offset from ordinary income instead publishes a different AGI cascade
    • One pool, no short-term / long-term split, and the section 1212 preservation of a deduction wasted in a year with no taxable income to absorb it is not modeled; both are stated planning simplifications on the function

    Provenance: derived by codex, implemented by claude.

    Independent review: cursor

    Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

    Worksheet: capital-loss-carryforward-netting.md Mutation receipt: capital-loss-carryforward-netting.mutation.md

    Evidence tests: federalTax.evidence.test.ts

    Implemented in: federalTax.ts

    Is the number of: tax-loss-carryforward-remaining-annual, tax-loss-carryforward-used-against-gains-annual, tax-loss-carryforward-used-against-ordinary-annual

    Feeds: tax-total-annual, display-loss-carryforward-used-annual, display-tax-free-gains-room-annual

  • Cash-flow tax-character amount Composition record, justified by derivation

    Purpose: Why a tax annotation on a cash line never becomes a second cash source or use.

    Statement: projection/internal/types/cashFlow.ts#YearCashFlowTaxCharacter.amountPlanDollars, whether attached to a source line, a transfer line or standalone metadata, is a nominal tax-only annotation that is excluded from every cash conservation identity and from every transfer debit and credit total. A capitalGain annotation may be negative for a realized loss; other character kinds are nonnegative. Units: nominal Plan USD. Rounding: none.

    Formula: sourceTotal counts physical amounts only; attached taxCharacter contributes 0 to every money total

    • amountPlanDollars: Characterized amount on the annotation (unit: usd) (domain: signed for capitalGain)
    • physical amount: The line the annotation is attached to (unit: usd) (domain: nonnegative)

    Timing: once per captured projection year

    Rounding: none

    Limits:

    • Asserted at the production reconciler with the worksheet's 100,000 physical taxable-account withdrawal carrying a 30,000 capital-gain character and 20,000 of other physical sources, so the published cash source total stays 120,000. Plan assumptions beyond the worksheet's inputs: the account identity the line ids carry, and a matching set of funded uses so the year's cash identity still balances
    • The worksheet's third wrong reading is asserted as a rule rather than a number: the same reconciliation is run with a negative capital-gain character to show a realized loss is accepted and still contributes nothing to the cash totals

    Provenance: derived by codex, implemented by claude.

    Independent review: cursor

    Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

    Worksheet: cash-flow-tax-character-amount.md Mutation receipt: cash-flow-tax-character-amount.mutation.md

    Evidence tests: annualCashFlowReconciliation.evidence.test.ts

    Implemented in: cashFlow.ts; annualCashFlowReconciliation.ts

    Is the number of: cash-flow-tax-character-amount

    Feeds: tax-total-annual

  • Conversion tax funding gcd reduction Formula record, justified by derivation

    Purpose: Represent exact rational tax-funding cents in canonical lowest terms.

    Statement: actions/conversionTaxFundingEvidence.ts#reducedConversionTaxFundingExactCentAmount reduces a nonnegative exact rational cent amount N/D by gcd(N,D) to a unique lowest-terms numerator and denominator, returning null for a negative numerator, nonpositive denominator, or reduced fields outside the safe-integer domain.

    Formula: g=gcd(N,D); reduced=(N/g,D/g)

    • N: Exact amount numerator (unit: cent-numerator) (domain: integer >= 0)
    • D: Exact amount denominator (unit: 1) (domain: integer > 0)

    Timing: one exact liability evidence amount

    Rounding: none; canonical integer ratio

    Limits:

    • No direct census family: internal/counterfactualAnnualLiability.ts consumes the reducer when converting an annual liability into exact-cent evidence. tax-total-annual is the nearest liability family; the reduced pair is not a published tax. Invalid domain or unsafe reduced fields return null.

    Provenance: derived by codex, implemented by codex.

    Independent review: cursor

    Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

    Worksheet: conversion-tax-funding-gcd-reduction.md Mutation receipt: conversion-tax-funding-gcd-reduction.mutation.md

    Evidence tests: conversionTaxFundingEvidence.evidence.test.ts

    Implemented in: conversionTaxFundingEvidence.ts

    Feeds: tax-total-annual

  • Exact cent rational half up Formula record, justified by derivation

    Purpose: Quantize an exact rational cent amount once, with halves upward.

    Statement: actions/exactCentProRata.ts#exactCentNearestHalfUp rounds a nonnegative exact rational count of minor units N/D once to a whole minor unit, with exact halves upward.

    Formula: q = floor(N/D); r = N mod D; cents = q + [2r >= D]

    • N: Exact numerator (unit: cent-numerator) (domain: integer >= 0)
    • D: Exact denominator (unit: 1) (domain: integer > 0)

    Timing: one liability quantization

    Rounding: exact integer half up

    Limits:

    • No direct census family: actions/conversionTaxFundingEvidence.ts quantizes the annual counterfactual liability difference with this function; tax-total-annual is the nearest liability family, not this evidence amount itself.

    Provenance: derived by codex, implemented by codex.

    Independent review: cursor

    Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

    Worksheet: exact-cent-rational-half-up.md Mutation receipt: exact-cent-rational-half-up.mutation.md

    Evidence tests: exactCentProRata.evidence.test.ts

    Implemented in: exactCentProRata.ts

    Feeds: tax-total-annual

  • Federal AMT screen Composition record, justified by derivation

    Purpose: Price the planning-grade alternative minimum tax as tentative minimum tax less regular tax, floored at zero.

    Statement: tax/federalTax.ts#amtExemptionAmount, #amtOrdinaryRateTax, #tentativeMinimumTax and #computeFederalTax compute the 2026 single-filer AMT screen as tentative minimum tax on AMTI after its phased exemption, with preferential-rate awareness, less regular tax but not below zero. With no preferential income the tentative tax is 26% through the 28%-rate threshold and 28% above it. Units: nominal USD. Rounding: none stated.

    Formula: E' = max(0, E - q x max(0, A - P)); X = max(0, A - E'); TMT = 0.26 x min(X, T28) + 0.28 x max(0, X - T28); AMT = max(0, TMT - regularTax)

    • A: Alternative minimum taxable income (taxable income plus modeled add-backs) (unit: usd/year) (domain: nonnegative)
    • E: AMT exemption for the filing status, from the tax parameters (unit: usd/year) (domain: positive)
    • P: Exemption phase-out start, from the tax parameters (unit: usd/year) (domain: positive)
    • q: Exemption phase-out rate, from the tax parameters (unit: fraction) (domain: 0 <= q <= 1)
    • T28: 28%-rate threshold on taxable excess, from the tax parameters (unit: usd/year) (domain: positive)
    • regularTax: Ordinary bracket tax plus stacked preferential tax (unit: usd/year) (domain: nonnegative)

    Timing: one tax year

    Rounding: none stated

    Limits:

    • A planning screen, not a full Form 6251 claim: modeled add-backs are the section 63(c) standard deduction or itemized SALT plus the section 151 senior deduction, and the rest of the Form 6251 adjustments are out of scope
    • The pinned rate and exemption helpers are not exported, so the evidence asserts them through computeFederalTax. The worksheet's AMTI of 200,000 and regular tax of 20,000 are not themselves calculator inputs: the test reaches them from real inputs (130,275 of ordinary income, which after the 16,100 standard deduction leaves 114,175 of taxable income and exactly 20,000 of bracket tax, plus 69,725 of advanced amtPreferenceItems, which with the 16,100 standard-deduction add-back makes AMTI 200,000). Any other construction of the same two figures is a different set of inputs.

    Provenance: derived by codex, implemented by claude.

    Independent review: cursor

    Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

    Worksheet: federal-amt-screen.md Mutation receipt: federal-amt-screen.mutation.md

    Evidence tests: federalTax.evidence.test.ts

    Implemented in: federalTax.ts

    Is the number of: tax-amt-annual

    Feeds: tax-total-annual

  • Federal long-term capital gain stacking Formula record, justified by derivation

    Purpose: Tax preferential income in the taxable-income interval immediately above ordinary taxable income.

    Statement: tax/federalTax.ts#capitalGainsTaxStacked and #computeFederalTax tax 2026 single-filer annual long-term capital gains and qualified dividends by stacking preferential income above ordinary taxable income across the 0%, 15% and 20% thresholds. Each rate applies to the intersection of the preferential interval with its rate band, so the ordinary base is never taxed again. Units: nominal USD. Rounding: none stated.

    Formula: from = ordinaryTaxable; to = from + preferential; at15 = max(0, min(to, t20) - max(from, t15)); at20 = max(0, to - max(from, t20)); tax = 0.15 x at15 + 0.20 x at20

    • ordinaryTaxable: Taxable income other than preferential income (unit: usd/year) (domain: nonnegative)
    • preferential: Long-term gains plus qualified dividends inside taxable income (unit: usd/year) (domain: nonnegative)
    • t15: year2026.capitalGains.rate15StartsAbove for the filing status (unit: usd/year) (domain: positive)
    • t20: year2026.capitalGains.rate20StartsAbove for the filing status (unit: usd/year) (domain: positive and above t15)

    Timing: one tax year

    Rounding: none stated

    Limits:

    • No direct census family: the stacked preferential tax is a component of the published annual tax, not a separately published figure
    • The helper is not exported; the evidence asserts the published capitalGainsTax of computeFederalTax, reaching the worksheet's 45,000 of ordinary taxable income and 10,000 of preferential income from real income inputs net of the 2026 single standard deduction

    Provenance: derived by codex, implemented by claude.

    Independent review: cursor

    Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

    Worksheet: federal-ltcg-stacking.md Mutation receipt: federal-ltcg-stacking.mutation.md

    Evidence tests: federalTax.evidence.test.ts

    Implemented in: federalTax.ts

    Feeds: tax-total-annual

  • Federal ordinary bracket tax Formula record, justified by derivation

    Purpose: Apply each marginal rate to the part of ordinary taxable income that falls in its bracket.

    Statement: tax/federalTax.ts#bracketTax and #computeFederalTax compute 2026 federal ordinary income tax by applying each single-filer marginal rate to the part of annual ordinary taxable income in that bracket, partitioning taxable income into nonoverlapping layers rather than applying the top marginal rate to every dollar. No rounding is stated. Units: nominal USD.

    Formula: tax = sum over brackets i of r_i x max(0, min(T, L_(i+1)) - L_i)

    • T: Ordinary taxable income (unit: usd/year) (domain: nonnegative)
    • L_i: Lower bound of bracket i, from year2026.federalTax.brackets (unit: usd/year) (domain: nondecreasing, first bound 0)
    • r_i: Marginal rate of bracket i (unit: fraction) (domain: 0 < r_i < 1)

    Timing: one tax year

    Rounding: none stated

    Limits:

    • No direct census family: the ordinary bracket tax is a component of the published annual tax, not a separately published figure
    • bracketTax is not exported; the evidence asserts the published ordinaryTax of computeFederalTax, reaching the worksheet's 60,000 of ordinary taxable income from an ordinary income of 60,000 plus the 2026 single standard deduction

    Provenance: derived by codex, implemented by claude.

    Independent review: cursor

    Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

    Worksheet: federal-ordinary-bracket-tax.md Mutation receipt: federal-ordinary-bracket-tax.mutation.md

    Evidence tests: federalTax.evidence.test.ts

    Implemented in: federalTax.ts

    Feeds: tax-total-annual

  • Federal standard deduction with the age-65 addition Composition record, justified by derivation

    Purpose: Compose the basic standard deduction with the per-person age-65 addition.

    Statement: params/index.ts#standardDeduction and #age65StandardDeductionAddition, consumed by tax/federalTax.ts#computeFederalTax, compute the 2026 single-filer standard deduction as the basic annual deduction plus the per-person age-65 addition times the number of qualifying people. This is distinct from the separate OBBBA senior deduction, which rides on top of whichever deduction base wins. Units: nominal USD. Rounding: none; the published parameter values and the head count are integers.

    Formula: deduction = D + n x A

    • D: Basic standard deduction, year2026.federalTax.standardDeduction for the filing status (unit: usd/year) (domain: positive)
    • A: Per-person age-65 addition, year2026.federalTax.age65Addition for the filing status (unit: usd/person/year) (domain: positive)
    • n: Living household members aged 65 or older (unit: people) (domain: integer >= 0)

    Timing: one tax year

    Rounding: none

    Limits:

    • No direct census family: the deduction is a component of the published annual tax, not a separately published figure
    • The OBBBA senior deduction is a separate allowance added to the elected base, so computeFederalTax's published `deduction` equals this composition only where the senior deduction is zero. The evidence asserts standardDeduction directly and then reads the composed figure back out of computeFederalTax at a MAGI past the senior-deduction phase-out, where the published seniorDeduction is 0.

    Provenance: derived by codex, implemented by claude.

    Independent review: cursor

    Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

    Worksheet: federal-standard-deduction-age-65.md Mutation receipt: federal-standard-deduction-age-65.mutation.md

    Evidence tests: federalTax.evidence.test.ts

    Implemented in: index.ts; federalTax.ts

    Feeds: tax-total-annual

  • Federal taxable Social Security tiers Formula record, justified by derivation

    Purpose: Tier the taxable share of Social Security benefits off provisional income.

    Statement: tax/federalTax.ts#taxableSocialSecurity computes annual taxable Social Security from provisional income (AGI excluding Social Security, plus tax-exempt interest, plus the foreign-exclusion addback, plus half of gross benefits) using the 2026 tax parameters’ statutorily unindexed single-filer 50% and 85% tier thresholds. Units: nominal USD. Rounding: none stated.

    Formula: P = agiExcludingSs + max(0, taxExemptInterest) + max(0, foreignAddback) + 0.5 x B; taxable = 0 when P <= a; min(0.5B, 0.5(P - a)) when a < P <= b; min(0.85B, 0.85(P - b) + min(0.5B, 0.5(b - a))) when P > b

    • B: Gross Social Security benefits (unit: usd/year) (domain: positive; a nonpositive benefit returns 0)
    • P: Provisional income (unit: usd/year) (domain: any finite number)
    • a: year2026.ssBenefitTaxation.tier50Start for the filing status (unit: usd/year) (domain: positive)
    • b: year2026.ssBenefitTaxation.tier85Start for the filing status (unit: usd/year) (domain: positive and above a)

    Timing: one tax year

    Rounding: none stated

    Limits:

    • No direct census family: the taxable share is an input to the published annual tax and to AGI, not a separately published figure
    • The tier thresholds are unindexed by design, so more of a benefit becomes taxable as a nominal plan runs on; the record claims the tiering, not the threshold policy

    Provenance: derived by codex, implemented by claude.

    Independent review: cursor

    Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

    Worksheet: federal-taxable-social-security-tiers.md Mutation receipt: federal-taxable-social-security-tiers.mutation.md

    Evidence tests: federalTax.evidence.test.ts

    Implemented in: federalTax.ts

    Feeds: tax-total-annual

  • Annual ordinary dividends distributed by a taxable account Formula record, justified by derivation

    Purpose: The non-qualified remainder of a taxable account's generated dividends.

    Statement: projection/internal/distributedTaxableYieldRows.ts#distributedTaxableYieldRows computes, for each taxable account whose start-of-year balance is strictly positive, ordinaryDividends = dividends - qualified, where dividends = startBalance x dividendYieldPct / 100 and qualified applies the resolved qualified ratio; projection/internal/annualIncomeSetup.ts#annualIncomeSetup folds those rows into the published projection/internal/types/result.ts#YearResult.incomes.ordinaryDividends. Qualified and ordinary dividends partition the same dividends and never add on top of them. Units: nominal USD per year. Rounding: none.

    Formula: ordinaryDividends = dividends - dividends * clamp(qualifiedRatio ?? blendedQualifiedRatio ?? 0.85, 0, 1), dividends = startBalance * dividendYieldPct / 100

    • dividends: Generated dividends on the start balance (unit: usd/year) (domain: nonnegative)
    • qualifiedRatio: Qualified share of dividends (unit: 1) (domain: clamped to [0, 1]; absent falls back to the blend, then to 0.85)

    Timing: once per taxable account per projection year, before the wage pass

    Rounding: none

    Limits:

    • Asserted on two real simulatePlan runs of the projection's first year, where the start-of-year balance is the plan balance. Plan assumptions beyond the worksheet's inputs: a single 51-year-old filing single in KY with a zero state rate, zero inflation, zero account return and cost basis equal to balance; the account carries no allocation, so the defaults case exercises the 0.85 fallback
    • The subtraction is performed in binary floating point, so the explicit case's $700 arrives as 700.0000000000002 and is compared under the worksheet's half-cent tolerance rather than exactly
    • This is the ordinary share of dividends only; taxable interest is a separate member of taxable yield

    Provenance: derived by codex, implemented by claude.

    Independent review: cursor

    Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

    Worksheet: income-ordinary-dividends-annual.md Mutation receipt: income-ordinary-dividends-annual.mutation.md

    Evidence tests: distributedTaxableYieldRows.evidence.test.ts

    Implemented in: distributedTaxableYieldRows.ts; annualIncomeSetup.ts; result.ts

    Is the number of: income-ordinary-dividends-annual

    Feeds: tax-total-annual, magi-annual

  • Annual qualified dividends distributed by a taxable account Formula record, justified by derivation

    Purpose: The qualified share of a taxable account's generated dividends.

    Statement: projection/internal/distributedTaxableYieldRows.ts#distributedTaxableYieldRows computes, for each taxable account whose start-of-year balance is strictly positive, dividends = startBalance x dividendYieldPct / 100 and qualified = dividends x clamp(qualifiedRatio ?? blendedQualifiedRatio ?? DEFAULT_QUALIFIED_DIVIDEND_RATIO, 0, 1), and projection/internal/annualIncomeSetup.ts#annualIncomeSetup folds those rows into the published projection/internal/types/result.ts#YearResult.incomes.qualifiedDividends. DEFAULT_QUALIFIED_DIVIDEND_RATIO is 0.85, a fraction rather than a percent. Units: nominal USD per year. Rounding: none.

    Formula: qualified = (startBalance * dividendYieldPct / 100) * min(1, max(0, qualifiedRatio ?? blendedQualifiedRatio ?? 0.85))

    • startBalance: Start-of-year balance, the prior year's close (unit: usd) (domain: strictly positive, else no row)
    • dividendYieldPct: Account dividend yield, in percent of the start balance (unit: percent/year) (domain: nonnegative)
    • qualifiedRatio: Qualified share of dividends (unit: 1) (domain: clamped to [0, 1]; absent falls back to the blend, then to 0.85)

    Timing: once per taxable account per projection year, before the wage pass

    Rounding: none

    Limits:

    • Asserted on two real simulatePlan runs of the projection's first year, where the start-of-year balance is the plan balance. Plan assumptions beyond the worksheet's inputs: a single 51-year-old filing single in KY with a zero state rate, zero inflation, zero account return and cost basis equal to balance; the account carries no allocation, so the defaults case exercises the 0.85 fallback rather than a blend
    • The default is 0.85 as a fraction; reading it as 85 percent of a percent is one of the worksheet's wrong readings and the clamp to [0, 1] is what stops it
    • An explicit account ratio wins over the blend and over the default, so the explicit case proves precedence, not just arithmetic

    Provenance: derived by codex, implemented by claude.

    Independent review: cursor

    Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

    Worksheet: income-qualified-dividends-annual.md Mutation receipt: income-qualified-dividends-annual.mutation.md

    Evidence tests: distributedTaxableYieldRows.evidence.test.ts

    Implemented in: distributedTaxableYieldRows.ts; annualIncomeSetup.ts; result.ts

    Is the number of: income-qualified-dividends-annual

    Feeds: tax-total-annual, magi-annual

  • Annual taxable interest distributed by a taxable account Formula record, justified by derivation

    Purpose: The interest a taxable account generates on its start-of-year balance.

    Statement: projection/internal/distributedTaxableYieldRows.ts#distributedTaxableYieldRows computes, for each taxable account whose start-of-year balance is strictly positive, interest = startBalance x interestYieldPct / 100, and projection/internal/annualIncomeSetup.ts#annualIncomeSetup folds those rows into the published projection/internal/types/result.ts#YearResult.incomes.taxableInterest. The rate is the account's own interestYieldPct when set, else the allocation blend's interest yield, else 0, each floored at 0; the start-of-year balance is the prior year's closing balance, and a zero or negative one produces no yield row at all. reinvestDividends decides where the generated cash goes, never whether it is characterized as interest. Units: nominal USD per year. Rounding: none.

    Formula: interest = startBalance * max(0, interestYieldPct ?? blendedInterestYieldPct ?? 0) / 100

    • startBalance: Start-of-year balance, the prior year's close (unit: usd) (domain: strictly positive, else no row)
    • interestYieldPct: Account interest yield, in percent of the start balance (unit: percent/year) (domain: nonnegative; overrides the allocation blend)

    Timing: once per taxable account per projection year, before the wage pass

    Rounding: none

    Limits:

    • Asserted on two real simulatePlan runs of the projection's first year, where the start-of-year balance is the plan balance. Plan assumptions beyond the worksheet's inputs: a single 51-year-old filing single in KY with a zero state rate, zero inflation, zero account return and cost basis equal to balance, so nothing but the stated yields can move the year; the account carries no allocation, so the defaults case exercises the no-blend fallback the worksheet names
    • A percent, not a fraction: 2.25 means 2.25 percent, and reading it as a fraction is one of the worksheet's wrong readings
    • The interest field is characterization, not cash delivery; with reinvestment on, the same dollars are credited back to the account and add nothing to the year's cash inflows

    Provenance: derived by codex, implemented by claude.

    Independent review: cursor

    Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

    Worksheet: income-taxable-interest-annual.md Mutation receipt: income-taxable-interest-annual.mutation.md

    Evidence tests: distributedTaxableYieldRows.evidence.test.ts

    Implemented in: distributedTaxableYieldRows.ts; annualIncomeSetup.ts; result.ts

    Is the number of: income-taxable-interest-annual

    Feeds: tax-total-annual, magi-annual

  • Parameter provenance catalog Data record, justified by dataset

    Purpose: Preserve the ordered source catalog that accompanies parameter assumptions.

    Statement: params/provenance.ts#PARAMETER_PROVENANCE is a human-maintained ordered catalog of 40 stable assumption-group IDs, labels, key-figure summaries, publishers, and URLs surfaced to users; it does not itself calculate tax or benefit amounts.

    Limits:

    • No direct census family: actions/annualQcdTaxCharacterPostPass.ts reads the rmd-qcd entry as source provenance for QCD tax-character evidence feeding annual tax. This is a metadata dependency, not a numerical tax formula. The worksheet checks ordered IDs, count and uniqueness, not correctness or freshness of the summaries. Per-entry authorities need independent verification on refresh.

    Dataset: RetireGolden parameter provenance catalog; DOCS/calculations/taxes/parameter-provenance-catalog.md, extracted 2026-09-14 and revised 2026-09-27, 2026-09-28 and 2026-10-08 (one ACA entry per coverage year; the Social Security tax rate, credit and CPI-U sources; SSA's period life table and its earlier edition; the 2027 HSA limits and the enacted state figures; the District of Columbia row restated on its permanent law) , as of 2026-10-08 , retrieved 2026-09-17

    Provenance: derived by claude, implemented by claude-subagent.

    Independent review: codex

    Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

    Worksheet: parameter-provenance-catalog.md Mutation receipt: parameter-provenance-catalog.mutation.md

    Evidence tests: provenance.evidence.test.ts

    Implemented in: provenance.ts

    Feeds: tax-total-annual

  • QCD income offset and qualified slice Composition record, justified by derivation

    Purpose: Separate the physical charitable gift from the slice of it that is excluded from income.

    Statement: projection/internal/types/result.ts#YearResult.qcd publishes the gross physical gift while its excludable income offset is the qualified from-RMD slice less the remaining section 408(d)(8)(A) second-sentence offset; projection/internal/annualLegacyQcdOwnerCharacterPlan.ts#annualLegacyQcdOwnerCharacterPlan computes that character, with the qualification ceiling being the owner's aggregate includible IRA amount (pre-distribution owned-IRA balance less aggregate basis) rather than the taxable fraction of the RMD. Gift beyond the RMD carries no offset; gift beyond aggregate includible dollars is non-qualified ordinary distribution charged to the from-RMD portion first; rmd stays gross. Units: nominal USD. Rounding: none.

    Formula: qualified = min(gift, max(0, preDistribution - basis)); offsetApplied = min(qualified, max(0, section219 - alreadyTaken)); nonQualified = gift - qualified; nonQualifiedFromRmd = min(fromRmd, nonQualified); qualifiedFromRmd = fromRmd - nonQualifiedFromRmd; incomeOffsetDelta = min(qualifiedFromRmd, qualified - offsetApplied)

    • gift: Gross physical gift for the owner-year (unit: usd/year) (domain: nonnegative)
    • fromRmd: Part of the gift that satisfied the RMD (unit: usd/year) (domain: 0 <= fromRmd <= gift)
    • preDistribution: Pre-distribution aggregate owned-IRA balance (unit: usd) (domain: nonnegative)
    • basis: Aggregate nondeductible IRA basis (unit: usd) (domain: nonnegative)
    • section219: Post-70.5 deductible section 219 contributions, net of reductions already consumed (unit: usd) (domain: nonnegative)

    Timing: one owner-year

    Rounding: none; the cross-year donor-offset ledger is carried in integer cents

    Limits:

    • The qualification ceiling is statutory: section 408(d)(8)(B), last sentence, treats a distribution as a qualified charitable distribution only to the extent it would be includible in gross income, and section 408(d)(8)(D) measures that extent as if every IRA of the owner were one contract distributed in full, which is the aggregate includible amount (pre-distribution owned-IRA balance less aggregate basis) this record uses; the second sentence of section 408(d)(8)(A) supplies the post-70.5 section 219 reduction. The allocation of the non-qualified remainder between the from-RMD and beyond-RMD portions has no statutory text and is an engine convention: the remainder is charged to the from-RMD portion first. Either order gives the same total ordinary inclusion (25,000 on the worksheet inputs: 50,000 - 35,000 + 10,000 under a qualified-first allocation, 50,000 - 30,000 + 5,000 under the engine's), so tax-total-annual and magi-annual do not depend on the order; only the split between the two published character rows does. The worksheet was first derived on the qualified-first order and re-derived on the engine's; the evidence pins the re-derived 30,000 and 5,000 and is green. The gross gift (YearResult.qcd) and the gross RMD are written by the gift planner and the RMD phase, not by the character planner this test exercises, so they are not asserted here.
    • The evidence asserts the qualified slice through the exported plan builder rather than reading a private local: the slice is recovered from the published qualifiedFromRmd and nonQualifiedBeyondRmd rows
    • An unprovable or contradictory offset history falls back to a zero exclusion rather than guessing, and writes nothing to the cross-year ledger; this record is asserted on a provable history

    Provenance: derived by codex, implemented by claude.

    Independent review: cursor

    Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

    Worksheet: qcd-income-offset-qualified-slice.md Mutation receipt: qcd-income-offset-qualified-slice.mutation.md

    Evidence tests: annualLegacyQcdOwnerCharacterPlan.evidence.test.ts

    Implemented in: result.ts; annualLegacyQcdOwnerCharacterPlan.ts; annualLegacyQcdGiftPlan.ts

    Is the number of: qcd-annual

    Feeds: tax-total-annual, magi-annual

  • QCD per-donor limit and age-70.5 annual proxy Data record, justified by derivation

    Purpose: Cap each donor at the indexed annual QCD limit and gate eligibility on the annual age proxy.

    Statement: projection/internal/types/result.ts#YearResult.qcd caps each donor at year2026.rmd.qcdAnnualLimit multiplied by the applicable limit-growth factor, and uses an annual proxy for age 70.5: eligible at attained age 71, or at attained age 70 when the birth month is June or earlier. projection/internal/annualLegacyQcdGiftPlan.ts#annualLegacyQcdGiftPlan applies both, with the household scalar capped at the sum of the per-donor caps and unused capacity never pooled into a donor who has already exhausted their own limit. Units: nominal USD per donor per year. Rounding: none; a full drain of a source publishes whole ledger cents.

    Formula: eligible(p) = alive(p) and (age(p) >= 71 or (age(p) = 70 and birthMonth(p) <= 6)); cap = qcdAnnualLimit x limitGrowth; requested = min(qcdAnnual x inflFactor, cap x donorCount)

    • qcdAnnualLimit: year2026.rmd.qcdAnnualLimit (unit: usd/donor/year) (domain: positive)
    • limitGrowth: Limit-growth factor to the projection year: 1 in a year whose QCD limit the IRS has published in its notice of retirement-plan limits, otherwise the inflation path from that limit's latest published year (unit: 1) (domain: positive)
    • age(p): Attained age of person p this year (unit: years) (domain: integer >= 0)
    • birthMonth(p): Birth month of person p (unit: month) (domain: integer 1..12)

    Timing: one projection year, per donor

    Rounding: none

    Limits:

    • The age gate is an annual proxy for 70.5, not a dated test: a July-born donor attaining 70 is refused for the whole year even though the statute would admit the second half of it
    • The cap is per donor, not per household: a two-donor plan carries twice the capacity, and the scalar arm never pools one donor's unused capacity into another
    • The evidence exercises the scalar arm (no named QCD request); a named request returns an empty plan from this helper and is a different path
    • Restated 2026-09-28 under decision D-2027-ROLLOVER: the growth factor and the named arm read the QCD limit's own publication (params/index.ts#componentScale, actions/annualQcdTaxCharacterPostPass.ts#qcdLimitPublishedFor), not the whole set of published figures. The named arm executes only in a tax year whose limit is published, so a gift dated in a year whose November notice has landed executes even while that year's brackets are projected; every year through 2026 reads exactly as before

    Provenance: derived by codex, implemented by claude.

    Independent review: grok

    Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

    Worksheet: qcd-limit-and-age-proxy.md Mutation receipt: qcd-limit-and-age-proxy.mutation.md

    Evidence tests: annualLegacyQcdGiftPlan.evidence.test.ts

    Implemented in: result.ts; annualLegacyQcdGiftPlan.ts; index.ts; annualQcdTaxCharacterPostPass.ts

    Is the number of: qcd-annual

    Feeds: tax-total-annual, magi-annual

  • State income tax figures already enacted for 2027 and later Data record, justified by derivation

    Purpose: Price 2027 and later years with the state income tax figures the states have already enacted for them without conditions, instead of the 2026 figures, and correct the 2026 figures the survey of every state found wrong.

    Statement: params/state/index.ts#stateParamsFor resolves a state for a year after the latest published state figures (2026) by applying every enacted year module at or before it in order (params/state/data/enacted2027.ts to enacted2033.ts): each field an entry names replaces the field for every filing status it carries, a field named as null ends, and a field no entry names keeps the 2026 figure. The fields a statute changes include the rate schedules, the standard deduction, retirement exclusions, surtax bands, state-specific blocks and whether a state taxes income at all. What is loaded, each with its own rule record: Indiana 2.9% from 2027; Mississippi 3.75%, 3.5%, 3.25% and 3% over 2027 to 2030; Montana 4.7% and 5.4% at 65,000, 97,500 and 130,000 from 2027; Nebraska 3.99% from 2027; North Carolina 3.49%, 3.24% from 2030 and 2.99% from 2033; the Hawaii Act 24 tables for 2027 and 2029 and its standard deduction steps in 2028, 2030 and 2031; New York’s five lowest rates cut 0.1 point for 2027 to 2032 and an 8.82% top rate from 2033; Rhode Island’s surtax over 1,000,000 dollars (1%, 2%, 3% over 2027 to 2029) and its Social Security modification without the age test from 2027; Virginia’s standard deduction steps in 2027, 2028 and 2030; Georgia’s 70,000 dollar retirement exclusion at 65 or older from 2027 and its military retirement exclusion of up to 65,000 dollars under 65 from 2027 (HB 266); Delaware’s military pension steps over 2027 to 2029; Illinois’s 1,000 dollar exemption from 2029; Maine’s standard deduction following the federal one from 2027; Maryland’s public-safety retirement subtraction steps to 2030; the end of Oregon’s retirement income credit from 2032; the end of Colorado’s under-55 military retirement subtraction from 2029; the end of California’s military exclusions from 2030 and of its top three bands from 2031; and Washington’s 9.9% tax above a 1,000,000 dollar deduction from 2028, the deduction indexed every second year from 2029 as its statute provides. The same change corrects 2026: Arkansas’s 3.7% top rate, the District of Columbia’s own deduction of 15,000 and 30,000 dollars for 2026 to 2029 under its permanent act, D.C. Law 26-189, in force from October 2, 2026 (indexed from 2027, federal from 2030), Maryland’s indexed deduction, capital gain surtax and public-safety subtraction, Virginia’s personal exemptions, Rhode Island’s 50,000 dollar pension cap and Social Security modification, California’s military exclusions, and the federal senior deduction carried into Arizona, Colorado and Idaho. This list is what has been verified against the statutes; the survey of all 51 jurisdictions, recorded state by state in DOCS/domain/state-tax-research/later-years-survey-2026-09-28.md, covers every other state. Each loaded figure is carried forward nominally until a later enacted step, except the standard deductions the code moves. Two are indexed by their own statutes and projected on those schedules at the plan’s inflation (tax/stateEnactedLaw.ts#statutorilyIndexedStandardDeduction): Washington’s, every second year from 2029, rounded to the nearest 1,000 dollars, and the District of Columbia’s, every year from 2027 to 2029, cumulative from a 2025 base and rounded down to a multiple of 50 dollars. A deduction loaded as the federal one, Maine’s from 2027 and the District of Columbia’s from 2030, moves with the federal deduction the projection carries (params/state/index.ts#conformStateStandardDeduction). The projection prices state tax for each year through tax/stateTax.ts#computeStateTaxYearResult, which reads stateParamsFor. Units: percent rates and nominal USD amounts. Rounding: the whole-dollar base taxes the Hawaii and New York tables print, and the two indexed deductions, Washington’s to the nearest 1,000 dollars and the District of Columbia’s down to a multiple of 50 dollars; nothing else.

    Formula: params(S, Y) = figures(S, latest published year) with, for each enacted year E with published year < E <= Y in ascending order, every field entry(E, S) names replaced (or removed when named as null); tax(S, Y) = state tax of params(S, Y) on the state base

    • S: State of residence for the year (unit: code) (domain: two letter code)
    • Y: Tax year (unit: year) (domain: integer)
    • E: An enacted year with figures for S (unit: year) (domain: 2027 to 2033, as listed in the statement)

    Timing: once per projection year and state of residence

    Rounding: none

    Limits:

    • Changes that apply only when a condition is met are not loaded, so the engine overstates the rate in any year one is triggered; each is decided on a known date and revisited then. Colorado’s TABOR temporary rate cut (C.R.S. 39-22-627): none for 2026, because the State Controller certified on September 8, 2026 that revenue fell $175.9 million short of the Referendum C cap; the next estimate is due October 1, 2027. Georgia’s rate cut, standard deduction and dependent exemption steps under HB 463: the Office of Planning and Budget’s determination as of December 1, 2026, and each December 1 after. Minnesota’s one-year first-tier cut: the commissioner, by December 15, 2026 (Minn. Stat. 290.036). Oklahoma’s quarter-point cuts: the State Board of Equalization, preliminary in December 2026 and final in February 2027, for 2028 at the earliest (68 O.S. 2355). Michigan’s one-year cut below 4.25%: the January 2027 revenue conference (MCL 206.51). South Carolina’s top-rate cut: the Board of Economic Advisors forecast in effect on February 15, 2027 (S.C. Code 12-6-510(C)(2)). Kansas’s rate cuts (the August 15 determination under K.S.A. 79-32,110c), Missouri’s top-rate cuts (RSMo 143.011.4) and West Virginia’s rate cut (the August 15, 2026 determination under W. Va. Code 11-21-4h): determinations not yet published. Indiana’s 0.05-point cuts from 2030 on a budget agency determination (IC 6-3-2-1(b)(9) to (15)); Mississippi’s cuts from 2031 when the reserve fund is full (2025 H.B. 1, section 2); North Carolina’s quarter-point cuts to 2.49% from 2035 when General Fund revenue exceeds its trigger (G.S. 105-153.7(a1)).
    • The District of Columbia’s own standard deduction for 2026 to 2029, loaded on 2026-09-28 under an emergency act, D.C. Act 26-416, rests from October 2, 2026 on the permanent D.C. Law 26-189, which ended its congressional review that day and applies from 2025: a basic deduction of 15,000 dollars single, 22,500 head of household and 30,000 joint plus the IRC 63(c)(3) addition, indexed from a 2025 base, and the federal deduction from 2030. The Office of Tax and Revenue’s 2026 D-40ES, written before the act, enters the federal 16,100, 24,150 and 32,200 dollars on its estimate worksheet; its 2026 D-40 booklet, due about January 2027, is checked against the loaded amounts.
    • Washington’s section 302(3) add-back is not modeled: a filer who owes the RCW 82.87 capital gains tax that year adds the Washington capital gains taxed under it, plus the RCW 82.87.060(1) deduction, back into the income-tax base, with the section 205 credit for the capital gains tax; the engine leaves every long-term gain out of the Washington base, as it leaves out the capital gains excise itself.
    • Two enacted changes have a vote pending and are loaded as current law, to be revisited when the vote is decided: Washington’s income tax from 2028, which Initiative 645 on the November 3, 2026 ballot would repeal, and the end of California’s top three bands from 2031, which Proposition 3 on the same ballot would prevent.
    • A figure a state statute indexes is held at its latest published amount in every later year, not projected at the plan’s inflation, so tax is overstated by more each year the projection runs: among the figures loaded here, Nebraska’s thresholds at their 2026 amounts from 2027 (the 2027 schedule is in draft only), Montana’s breaks at their 2027 amounts from 2028, Rhode Island’s surtax threshold at 1,000,000 dollars from 2028 and its Social Security limits at the 2025 amounts, Maryland’s deduction at its 2026 amounts from 2027, and Illinois’s exemption at 2,925 dollars for 2027 and 2028. This is the registered approximation neb-rev-stat-77-2715-03-3-indexed-brackets-held-nominal, which lists every figure the survey found indexed. Two deductions are the exception, each projected on its statute’s own schedule at the plan’s inflation: Washington’s (every second year from 2029, by one year’s inflation, rounded to 1,000 dollars) and the District of Columbia’s (every year from 2027 to 2029, cumulative from a 2025 base, rounded down to a multiple of 50 dollars, until the federal deduction returns in 2030).
    • The plan models single and married filing jointly. Head of household and qualifying surviving spouse need dependents, which the plan does not collect, so a state’s head-of-household schedule or deduction is used only on a state return whose filing status is set to head of household (in the planner, the state filing status under Assumptions, State tax worksheet facts), and Delaware’s new domicile test for the pension subtraction at 60 or older, which needs a domicile history the plan does not hold, is assumed to be met.
    • A state’s own rule for military retired pay and Survivor Benefit Plan annuities is modeled on a pension tagged Military retirement or Military survivor benefit: in full where the state’s rule is full (Alabama, Arizona, Arkansas, Connecticut, Hawaii, Illinois, Indiana, Iowa, Kansas, Louisiana, Maine, Massachusetts, Michigan, Minnesota, Mississippi, Nebraska, New Jersey, New York, North Dakota, Ohio, Oklahoma, Pennsylvania, Rhode Island, South Carolina, West Virginia and Wisconsin), capped or tested where it is (California, Colorado, Delaware, Georgia, Idaho, Maryland, Montana, New Mexico, Virginia and Vermont), as a credit in Utah, and for a survivor annuity in the District of Columbia and Missouri. What remains, each overstating tax unless it says otherwise. North Carolina’s full deduction for a retiree with 20 years of service or a medical retirement, or vested by August 12, 1989, and for that retiree’s survivor; Kentucky’s full exclusion of the share of a federal or military pension earned before 1998; and Oregon’s federal pension subtraction pro-rated by service before October 1, 1991: each turns on a service history the plan does not hold. Montana’s five-year window is read from the pension’s first payment, because the plan holds no residency start or claim history, and errs both ways (mt-mca-15-30-2120-3-n-military-retirement-subtraction). Georgia’s second $17,500 and Montana’s wage limit read earned income from wage streams only, as a recurring income names no person. A survivor annuity keeps the general retirement rule in Michigan, Oklahoma and Pennsylvania, and needs a plan code in Kansas, where the law does not plainly reach it; Nebraska excludes one in full through its public-pension flag although its statute does not name it, which may understate tax; Delaware’s treatment of one is not settled. A survivor’s share of a pension tagged Military retirement is priced as retired pay, not as a survivor annuity. New Mexico’s $30,000 is the 2025 law, and the 2026 session was not checked. An Idaho military retiree under 62 who is neither disabled nor working gets the lawful zero, but the year is marked incomplete. Vermont’s phase-out ratio is not rounded to two decimals as its worksheet rounds it, a difference of a few dollars. Railroad Retirement Act annuities are not a limit: every state subtracts them under 45 U.S.C. 231m (usc-45-231m-state-tax-bar).

    Provenance: derived by claude, implemented by claude-subagent.

    Independent review: codex

    Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

    Worksheet: state-enacted-tax-year-figures.md Mutation receipt: state-enacted-tax-year-figures.mutation.md

    Evidence tests: enacted2027.evidence.test.ts

    Implemented in: year2026.ts; enacted2027.ts; enacted2028.ts; enacted2029.ts; enacted2030.ts; enacted2031.ts; enacted2032.ts; enacted2033.ts; index.ts; stateTax.ts; stateEnactedLaw.ts

    Feeds: tax-total-annual, relocation-lifetime-state-local-tax

  • Annual realized gains, signed and composed Composition record, justified by derivation

    Purpose: The year's net realized capital result across its three signed sources.

    Statement: projection/internal/types/result.ts#YearResult.realizedGains, assembled by projection/internal/annualYearResultAssembly.ts#annualYearResultAssembly, is the signed sum, in stated order, of gain embedded in taxable withdrawals, gain from rebalancing sales, and gain from named retirement-action executions. Each component is signed, so a loss from one source offsets gains from the others rather than being floored separately. Units: nominal USD per year. Rounding: none.

    Formula: realizedGains = withdrawal + rebalance + retirementAction

    • withdrawal: Gain embedded in taxable-account withdrawals (unit: usd) (domain: signed)
    • rebalance: Gain realized by rebalancing sales (unit: usd) (domain: signed)
    • retirementAction: Gain or loss from named retirement-action executions (unit: usd) (domain: signed)

    Timing: once per projection year, at year-result assembly

    Rounding: none

    Limits:

    • Asserted at the exported assembly boundary with the worksheet's three signed components verbatim and every other assembly channel at zero, so nothing unstated can reach the published field. Plan assumptions beyond the worksheet's inputs: an empty balance-sheet snapshot and a zero ladder value, neither of which this field reads
    • The record covers the composition boundary only; each component's own arithmetic is evidenced by the withdrawal, rebalancing and retirement-action records

    Provenance: derived by codex, implemented by claude.

    Independent review: cursor

    Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

    Worksheet: tax-realized-gains-annual.md Mutation receipt: tax-realized-gains-annual.mutation.md

    Evidence tests: annualYearResultAssembly.evidence.test.ts

    Implemented in: result.ts; annualYearResultAssembly.ts

    Is the number of: tax-realized-gains-annual

    Feeds: tax-total-annual

  • Annual tax-exempt interest, and the ACA-year maximum Formula record, justified by derivation

    Purpose: Municipal interest the year really generates, raised to an attested household total in an ACA year.

    Statement: projection/internal/types/result.ts#YearResult.taxExemptInterest is the account-generated federally tax-exempt interest total, except in a year with an active ACA contract whose taxExemptInterest state is known, when it is max(attested household total, plan-generated subset). Generated account interest is the stated taxable-account balance times taxExemptInterestYieldPct/100. Cash and balances always follow the generated figure. Units: nominal USD per year. Rounding: none.

    Formula: generated = B x q; published = known ACA contract ? max(attested, generated) : generated

    • B: Taxable-account start-of-year balance (unit: usd) (domain: nonnegative)
    • q: Tax-exempt interest yield (unit: 1) (domain: taxExemptInterestYieldPct / 100)
    • attested: Household tax-exempt interest on a known ACA contract (unit: usd/year) (domain: nonnegative)

    Timing: once per projection year, after the account yield pass

    Rounding: none

    Limits:

    • Both cases asserted as the published field of a real simulatePlan 2026 row: one municipal sleeve at the worksheet's 200,000 balance and 2-percent tax-exempt yield, zero account return and zero inflation. Plan assumptions beyond the worksheet's inputs: a 60-year-old filing single in KY at a zero state rate, the sleeve does not reinvest its yield, and Case B adds a 2026 ACA contract at a 500-per-month enrollment premium whose taxExemptInterest state is known at the worksheet's 6,000; the enrollment premium is what makes the contract active and is not read by this field
    • The ACA maximum characterizes income only; the test also asserts that the generated 4,000 remains the cash-real income member in Case A

    Provenance: derived by codex, implemented by claude.

    Independent review: cursor

    Gates (6 of 6 pass): fixture registers a test: pass; pins resolve: pass; families exist: pass; worksheet exists: pass; mutation receipt exists: pass; provenance independent: pass

    Worksheet: year-result-tax-exempt-interest.md Mutation receipt: year-result-tax-exempt-interest.mutation.md

    Evidence tests: simulate.evidence.test.ts

    Implemented in: result.ts; annualAggregateRothConversionPhase.ts

    Is the number of: year-result-tax-exempt-interest

    Feeds: income-total-annual, tax-total-annual

Engine source: engine/src/projection/internal/types/result.ts (YearResult.tax)

The evidence links on this page (each record's worksheet, mutation receipt, evidence tests and implementation, and the source links) are pinned to engine commit 2624dbdba9fd, committed 2026-10-11. The live calculation index and output-family census links point at the repository's main branch, so you can check this snapshot against them.

← All output families Tax-rule registry