Display loss carryforward used annual

Capital-loss carryforward applied this year against gains and against ordinary income, combined.

Field: Loss carryforward used Unit: US dollars Basis: nominal dollars Computed by: UI transformation Status: Complete chain

Appears in: csv (lossCarryforwardUsed)

Calculation records

• Capital-loss carryforward used in the year Composition record, justified by derivation

  Purpose: How much of the capital-loss carryforward the year used, as the ledger download reports it.

  Statement: projection/yearFigures.ts#capitalLossCarryforwardUsed publishes capitalLossUsedAgainstGains + capitalLossUsedAgainstOrdinary for the year, both from one call of tax/federalTax.ts#applyCapitalLossCarryforward in the ledger (IRC 1211(b), 1212(b)). Units: nominal USD. Rounding: none; the ledger download rounds to whole dollars.

  Formula: used = usedAgainstGains + usedAgainstOrdinary; usedAgainstGains = min(P, G+); usedAgainstOrdinary = min(P - usedAgainstGains + G-, L)

  • P: Opening carryforward pool (unit: usd) (domain: nonnegative)
  • G+ / G-: The year's own realized gain / loss (unit: usd) (domain: nonnegative)
  • L: Annual loss offset limit (unit: usd) (domain: 3,000)

  Timing: annual

  Rounding: none

  Limits:

  • When the year also realizes a net loss of its own, the figure exceeds the fall in the carried balance by that loss, which joined the pool before the $3,000 offset
  • The single-pool, $3,000-for-every-filing-status and 1212(b)(2) limits of the carryforward itself are carried by the carryforward records

  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: display-loss-carryforward-used-annual.md Mutation receipt: display-loss-carryforward-used-annual.mutation.md

  Evidence tests: yearFigures.evidence.test.ts

  Implemented in: yearFigures.ts; federalTax.ts

  Is the number of: display-loss-carryforward-used-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

Transformations

• Add capitalLossUsedAgainstGains and capitalLossUsedAgainstOrdinary in projection/yearFigures.ts#capitalLossCarryforwardUsed.