Income taxable interest annual

Taxable interest credited to the household during the projection year.

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

Appears in: csv (taxableInterest)

Calculation records

• Annual taxable interest distributed by a taxable account Formula record, justified by derivation

  Purpose: The interest a taxable account generates on its start-of-year balance.

  Statement: projection/internal/distributedTaxableYieldRows.ts#distributedTaxableYieldRows computes, for each taxable account whose start-of-year balance is strictly positive, interest = startBalance x interestYieldPct / 100, and projection/internal/annualIncomeSetup.ts#annualIncomeSetup folds those rows into the published projection/internal/types/result.ts#YearResult.incomes.taxableInterest. The rate is the account's own interestYieldPct when set, else the allocation blend's interest yield, else 0, each floored at 0; the start-of-year balance is the prior year's closing balance, and a zero or negative one produces no yield row at all. reinvestDividends decides where the generated cash goes, never whether it is characterized as interest. Units: nominal USD per year. Rounding: none.

  Formula: interest = startBalance * max(0, interestYieldPct ?? blendedInterestYieldPct ?? 0) / 100

  • startBalance: Start-of-year balance, the prior year's close (unit: usd) (domain: strictly positive, else no row)
  • interestYieldPct: Account interest yield, in percent of the start balance (unit: percent/year) (domain: nonnegative; overrides the allocation blend)

  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, so nothing but the stated yields can move the year; the account carries no allocation, so the defaults case exercises the no-blend fallback the worksheet names
  • A percent, not a fraction: 2.25 means 2.25 percent, and reading it as a fraction is one of the worksheet's wrong readings
  • The interest field is characterization, not cash delivery; with reinvestment on, the same dollars are credited back to the account and add nothing to the year's cash inflows

  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-taxable-interest-annual.md Mutation receipt: income-taxable-interest-annual.mutation.md

  Evidence tests: distributedTaxableYieldRows.evidence.test.ts

  Implemented in: distributedTaxableYieldRows.ts; annualIncomeSetup.ts; result.ts

  Is the number of: income-taxable-interest-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.taxableInterest)