Surplus invested annual

Surplus cash flow invested this year into cash, else taxable, else unassigned.

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

Appears in: cash-flow-drilldown (Summary "Surplus" figure and surplusInvestment use/transfer lines)

Calculation records

• Annual surplus invested, floored at zero Formula record, justified by derivation

  Purpose: The residual cash a year ends with, after every stated use, and where it lands.

  Statement: projection/internal/types/result.ts#YearResult.surplusInvested is max(0, accepted cash inflows - expenses.total - contributions - tax - penalties) at the accepted funding fixed point. The credited surplus goes to the lowest-id cash account, otherwise the lowest-id taxable account with equal cost-basis growth, otherwise unassigned cash with a warning; the amount has no cap. Units: nominal USD per year. Rounding: none.

  Formula: surplusInvested = max(0, I - X - C - T - P)

  • I: Accepted cash inflows at the funding fixed point (unit: usd/year) (domain: nonnegative)
  • X: expenses.total for the year (unit: usd/year) (domain: nonnegative)
  • C: Contributions credited (unit: usd/year) (domain: nonnegative)
  • T: Composed tax (unit: usd/year) (domain: nonnegative)
  • P: Penalties (unit: usd/year) (domain: nonnegative)

  Timing: once per projection year, at the accepted funding fixed point

  Rounding: none

  Limits:

  • Asserted as the published field of a real simulatePlan 2026 row that carries all five of the worksheet's members. Plan assumptions beyond the worksheet's inputs: a 55-year-old filing single in KY, so no Medicare or marketplace premium can move expenses.total off 50,000; cash inflows split into an 80,000 wage and a 20,000 tax-free recurring receipt, so a flat 10-percent test calculator prices tax at exactly 8,000 while inflows are exactly 100,000; the 10,000 of contributions go to one taxable brokerage account; and the 2,000 of penalties are the IRC 4974 excise on a completed five-year deadline year (opening benefit 12,000, 4,000 distributed by the 2026 deadline) asserted on an inherited Roth account
  • That excise is the only penalty a surplus year can carry: the early-withdrawal and HSA penalties are charged on need-based withdrawals, and a year whose inflows exceed its uses takes none, so no plan can produce both a positive surplus and an early-withdrawal penalty
  • The flat test calculator is a test double, not the shipped calculator; it is used only to realize the worksheet's stated tax member exactly, and the record makes no claim about federal tax 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: surplus-invested-annual.md Mutation receipt: surplus-invested-annual.mutation.md

  Evidence tests: simulate.evidence.test.ts

  Implemented in: result.ts; annualFundingApplicationAndClosePhase.ts

  Is the number of: surplus-invested-annual

  Feeds: accounts-balance-per-account-annual, cash-flow-reconciliation-totals

Records that feed this number

• Annual composed tax Composition record, justified by derivation

  Purpose: What the year's published tax figure is composed of, and what it excludes.

  Statement: projection/internal/types/result.ts#YearResult.tax is the amount produced by the composed calculator built by tax/federalTax.ts#combineTaxCalculators: the federal total of regular income tax plus AMT plus NIIT, plus the state calculator amount, plus any further composed calculator amounts. Penalties are excluded from it, from AGI and from MAGI. Units: nominal USD per year. Rounding: none; the composition is an ordered fold.

  Formula: tax = federalTotal + stateAmount + sum of further calculator amounts

  • federalTotal: Regular income tax + AMT + NIIT (unit: usd/year) (domain: nonnegative)
  • stateAmount: State calculator amount (unit: usd/year) (domain: nonnegative)
  • penalties: Early-withdrawal and IRC 4974 amounts (unit: usd/year) (domain: never a member of tax)

  Timing: once per accepted tax evaluation in the projection year

  Rounding: none

  Limits:

  • The worksheet treats the federal and state amounts as outputs independently evidenced by their own worksheets and checks only the annual composition boundary, so the test composes two calculators that report the worksheet's stated 12,000 federal total and 3,000 state amount and asserts the composed 15,000 through both compute and computeResult. Those two calculators are test doubles standing in for the evidenced federal and state records; this record makes no claim about federal or state tax arithmetic
  • The 500 of penalties is asserted as excluded by composing the same calculators and showing the amount is unchanged: penalties never enter the calculator chain at all

  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-total-annual.md Mutation receipt: tax-total-annual.mutation.md

  Evidence tests: federalTax.evidence.test.ts

  Implemented in: result.ts; federalTax.ts

  Is the number of: tax-total-annual

  Feeds: portfolio-need-annual, surplus-invested-annual, display-tax-plus-penalties-annual, display-total-spending-annual

• Annual contributions credited after limit trimming Formula record, justified by derivation

  Purpose: How much of the desired contribution each owner is actually allowed to put in.

  Statement: projection/internal/types/result.ts#YearResult.contributions, planned by projection/internal/annualContributionsAndEmployerMatch.ts#annualContributionsAndEmployerMatch, sums the contributions actually credited after each desired amount is trimmed to its applicable group limit and to compensation. A jointly owned account's desired amount follows joint-account-contributions. The IRA limit in params/data/year2026.ts#year2026 is 7,500 for 2026, shared per owner across that owner's traditional and Roth IRAs, with a separate age-50 catch-up only when applicable. Units: nominal USD per year. Rounding: none.

  Formula: contributions = sum over owners and accounts of min(desired, group limit, compensation)

  • desired: Plan annual contribution for the account (unit: usd/year) (domain: nonnegative)
  • group limit: Per-owner IRA limit plus any applicable catch-up (unit: usd/year) (domain: 7,500 for 2026)
  • compensation: Owner wages available to support the contribution (unit: usd/year) (domain: nonnegative)

  Timing: once per projection year, after wages land

  Rounding: none

  Limits:

  • Asserted as the published field of a real simulatePlan 2026 row built from the worksheet's inputs: two owners aged 40 and 45 with one traditional IRA each, desired 6,000 and 9,000, wages 50,000 each, and zero general inflation. Plan assumptions beyond the worksheet's inputs: the household files jointly in KY at a zero state rate, both IRAs open at a zero balance with zero returns, there are no other accounts and no spending, and the 2026 IRA limit is read from the published parameters rather than written into the test
  • Both owners are under 50, so the test isolates the base limit and evidences no catch-up band

  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: year-result-contributions.md Mutation receipt: year-result-contributions.mutation.md

  Evidence tests: simulate.evidence.test.ts

  Implemented in: result.ts; annualContributionsAndEmployerMatch.ts

  Is the number of: year-result-contributions

  Feeds: surplus-invested-annual, cash-flow-reconciliation-totals

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