Income ordinary dividends annual

Ordinary dividend income recognized during the projection year.

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

Appears in: csv (ordinaryDividends)

Calculation records

• 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

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.ordinaryDividends)