Year result LTCG zero headroom

Additional long-term capital gains available before leaving the zero-percent bracket.

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

Appears in: results-table (0% capital-gains headroom)

Calculation records

• 0% long-term-gains headroom: the unused layer under the 15% threshold Model record, justified by derivation

  Purpose: How much more long-term gain the year could realize and still pay 0% on it.

  Statement: YearResult.ltcgZeroHeadroom, computed by tax/federalTax.ts#zeroRateLtcgHeadroom, is 0 when taxable income with no extra gain already reaches the threshold where the 15 percent rate starts (capitalGains.rate15StartsAbove in the year's tax figures) for the filing status: the published figure in a year that has its own, and in a later year the latest published figure indexed to that year by the plan's general inflation, as the brackets and the deduction are; otherwise it is the largest extra gain, found by bisection to a $0.01 bracket, that keeps max(0, ordinary income excluding Social Security + gains + qualified dividends + the extra gain + the resulting taxable Social Security − deduction) at or under that threshold. The search brackets that gain in every case: its upper end is the threshold when taxable income at a gain equal to the threshold is above it, and otherwise the threshold + deduction − (ordinary income excluding Social Security + gains + qualified dividends), where taxable income before the floor is at least the threshold. Without benefits the slope above the zero floor is exactly 1, so the root is threshold − taxable income when income before the gain covers the deduction, and the threshold plus the unused deduction when it does not (single, 2026: $55,550 of room at $10,000 of ordinary income, $65,550 at $0). Units: nominal dollars of additional gain. Rounding: bisection to $0.01, so the published figure sits at or just under the exact root.

  Formula: headroom = 0 when taxable(0) >= T; else max{ g : taxable(g) <= T }, T = rate15StartsAbove[filingStatus]

  • T: 15% long-term-gains threshold for the filing status (unit: usd taxable income) (domain: positive)
  • taxable(g): Taxable income with g of extra long-term gain, including any resulting taxable Social Security (unit: usd) (domain: nondecreasing in g; slope 0 while floored at zero, then 1 to 1.85)
  • headroom: Additional gain still taxed at 0% (unit: usd) (domain: nonnegative)

  Timing: annual, priced with the year's federal detail after the funding fixed point

  Rounding: bisection stops at a $0.01 bracket width; the at-threshold branch returns exactly 0

  Limits:

  • Beyond the worksheet's inputs the evidence plan fixes: a 63-year-old single filer (under 65, so the deduction is the base 2026 standard deduction of $16,100 with no age addition), an uninflated recurring ordinary stream sized to $16,100 above the case's taxable income, zero inflation and zero return so the 2026 threshold is unindexed, no gains and no qualified dividends, and a cash account to absorb surplus and pay tax
  • Case A is asserted at the worksheet's absolute $0.005 because the bisection lands 0.002 under the exact $12,450 root; a test that demanded exactness would fail on the algorithm's own $0.01 stopping width, not on the identity
  • The at-threshold branch returns exactly 0 before any bisection, which is why Case B is compared with toBe rather than a tolerance
  • The benefits branch is out of scope here: the worksheet states the no-benefit subtraction, and the bisection exists precisely because that subtraction is wrong once §86 inclusion moves with the gain
  • Cases C and D, added under decision D-ZERO-RATE-HEADROOM on 2026-09-25, put ordinary income below the deduction: the same plan with a $10,000 ordinary stream, and with no income at all. Their search runs from the threshold to the threshold plus the unused deduction, a wider bracket than Case A's, so the bisection lands up to $0.008 under the root (55,549.994 and 65,549.992); each is asserted within the $0.01 stopping width and at or under the root, and away from the 49,450 that a search bounded by the threshold published before the decision. Cases A and B were derived by Codex and reviewed by Cursor; Cases C and D were worked by the implementer from the decision's evidence and independently checked on 2026-09-26 by a reviewer who is not the author, as the worksheet records. The worksheet's claim was reworded on 2026-09-27 to name the indexed threshold of a projected year, and Codex reviewed the reworded claim on 2026-09-29 (DOCS/calculations/reviews/REVIEW-2026-09-29-codex-2-cash-flow.md)

  Provenance: derived by claude, implemented by claude.

  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: year-result-ltcg-zero-headroom.md Mutation receipt: year-result-ltcg-zero-headroom.mutation.md

  Evidence tests: simulate.ltcgZeroHeadroom.evidence.test.ts

  Implemented in: federalTax.ts; annualFundingApplicationAndClosePhase.ts

  Is the number of: year-result-ltcg-zero-headroom

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