Tax realized gains annual

Taxable-account capital gains realized during the projection year.

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

Appears in: csv (realizedGains)

Calculation records

• 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

Records that feed this number

• Rebalance turnover: the fraction sold to reach the target weights Formula record, justified by derivation

  Purpose: How much of an account a rebalance sells, the sum of the overweight class differences.

  Statement: turnover = sum over the indices of current of max(0, current_i - target_i), with a missing target_i read as 0. Units: fraction of account value sold. Rounding: none. In the ledger a turnover above 1e-9 on a taxable account with a positive balance sells min(balance, turnover x balance) through the basis machinery; other account types retarget without a sale.

  Formula: turnover = sum_i max(0, c_i - t_i)

  • c_i: Current weight of class i (unit: 1) (domain: sum 1)
  • t_i: Target weight of class i (unit: 1) (domain: sum 1)
  • turnover: Fraction of the account sold (unit: 1) (domain: 0 <= turnover <= 1 for normalized vectors)

  Timing: once per year at the rebalance

  Rounding: none

  Limits:

  • Sells only: buys are the mirror image under conserved value, so summing the positive differences counts each dollar moved once
  • No validation that the two vectors sum to one; an unnormalized pair returns an unnormalized fraction
  • The worksheet says none yet: the census exposes no turnover family. The traced consumer is annualRebalanceToTarget.ts, whose taxable rebalancing sale realizes the gain published as YearResult.realizedGains, so tax-realized-gains-annual is named as the nearest fed family
  • Only taxable accounts realize anything; on tax-advantaged accounts the ledger retargets the weights without a sale

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

  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: allocation-rebalance-turnover.md Mutation receipt: allocation-rebalance-turnover.mutation.md

  Evidence tests: assetClasses.evidence.test.ts

  Implemented in: assetClasses.ts

  Feeds: tax-realized-gains-annual

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