Income qualified dividends annual

Qualified dividend income recognized during the projection year.

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

Appears in: csv (qualifiedDividends)

Calculation records

• 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

Records that feed this number

• Blended taxable yields and dividend-weighted qualified share Formula record, justified by derivation

  Purpose: The interest yield, dividend yield and qualified share a taxable account's allocation implies.

  Statement: For weights w and class parameters: interestYieldPct = sum of w_i x interestYieldPct_i; dividendYieldPct = sum of w_i x dividendYieldPct_i; qualified = sum of w_i x dividendYieldPct_i x qualifiedRatioPct_i/100; qualifiedRatio = qualified/dividendYieldPct when dividendYieldPct > 0, else DEFAULT_QUALIFIED_DIVIDEND_RATIO = 0.85. Units: the two yields in percent of balance per year; the ratio a fraction in [0, 1]. Rounding: none. In the ledger an account-level interestYieldPct, dividendYieldPct or qualifiedRatio overrides the blend field by field, and the published rows are start-of-year balance x yield/100.

  Formula: I = sum_i w_i I_i; D = sum_i w_i D_i; Q = (sum_i w_i D_i q_i/100) / D when D > 0, else 0.85

  • w_i: Fraction of the account in class i (unit: 1) (domain: w_i >= 0)
  • I_i, D_i: Interest and dividend yield of class i (unit: percent of balance/year) (domain: >= 0)
  • q_i: Qualified share of class i's dividends (unit: percent) (domain: 0 <= q_i <= 100)
  • I, D: Blended interest and dividend yields (unit: percent of balance/year) (domain: >= 0)
  • Q: Dividend-dollar-weighted qualified share (unit: 1) (domain: 0 <= Q <= 1)

  Timing: annual; applied to the start-of-year balance

  Rounding: none

  Limits:

  • The qualified share is dividend-dollar-weighted, so a class with no dividends contributes nothing to the ratio however large its weight
  • A blend with zero dividends returns the 0.85 fallback rather than 0 or NaN; the fallback is a convention for the unallocated case, not a sourced class parameter
  • Weights are taken as given, not normalized
  • The published income rows are balance x yield in the ledger (distributedTaxableYieldRows.ts), so this record feeds those families and is not their value

  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-blended-taxable-yield.md Mutation receipt: allocation-blended-taxable-yield.mutation.md

  Evidence tests: assetClasses.evidence.test.ts

  Implemented in: assetClasses.ts

  Feeds: income-taxable-yield-annual, income-taxable-interest-annual, income-qualified-dividends-annual, income-ordinary-dividends-annual

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