Cash flow reconciliation totals

Per year, the total of funded sources, the total of funded uses, the unfunded (shortfall) uses, and the paired transfer debit and credit totals that the identity-bearing cash-flow ledger reconciles.

Field: Cash-flow reconciliation totals Unit: US dollars Basis: nominal dollars Computed by: Engine Status: Complete chain

Appears in: cash-flow-drilldown (YearCashFlowDialog summary tiles "Sources", "Funded uses", "Shortfall" and Sankey props); cash-flow-drilldown (YearCashFlowSankey aria-label: 'Cash flow for YEAR. Source total $X. Funded uses $Y. Shortfall $Z.' and, on the transfers view, 'Transfers for YEAR. Debits $X. Credits $Y.')

Calculation records

• Annual cash-flow reconciliation: the three identity totals Composition record, justified by derivation

  Purpose: The three annual identities a published cash-flow report must satisfy, and the tolerance each is judged at.

  Statement: projection/annualCashFlowReconciliation.ts#reconcileYearCashFlow publishes three identity totals. Cash: sourceTotal = spendableSources + portfolioFunding + loanProceeds, destinationTotal = fundedHouseholdUses + settledTax + penalties + contributions + surplusInvestment, difference = sourceTotal - destinationTotal, judged against cashIdentityTolerancePlanDollars, which capture sets to CASH_FLOW_CASH_IDENTITY_TOLERANCE_PLAN_DOLLARS (the annual funding tolerance, half a cent). Uses: dispositionTotal = fundedUses + unfundedUses, difference = requestedUses - dispositionTotal. Transfers: difference = debits - credits. Both use and transfer identities are judged against tolerancePlanDollars, which capture sets to CASH_FLOW_RECONCILIATION_TOLERANCE_PLAN_DOLLARS (1e-6). A comparison fails only when the absolute difference is STRICTLY GREATER than its tolerance, so a difference exactly at the bound reconciles. Units: nominal Plan dollars per year. Rounding: none; the totals are unrounded binary floats.

  Formula: cashDifference = (spendable + portfolioFunding + loanProceeds) - (fundedHouseholdUses + tax + penalties + contributions + surplus); useDifference = requested - (funded + unfunded); transferDifference = debits - credits

  • spendable, portfolioFunding, loanProceeds: Source-line roles summed into the cash source total (unit: usd/year) (domain: nonnegative)
  • fundedHouseholdUses: Funded lifestyle, goal, debt, property, healthcare, insurance and care uses (unit: usd/year) (domain: nonnegative)
  • cashIdentityTolerance: Cash conservation bound, the annual funding tolerance (unit: usd) (domain: 0.005 at capture)
  • tolerance: Strict structural bound for use, transfer and lineage checks (unit: usd) (domain: 1e-6 at capture)

  Timing: once per captured projection year, after every economic commit

  Rounding: none

  Limits:

  • Asserted at reconcileYearCashFlow, the production function that computes all three identities, with published lines carrying the worksheet's amounts, and with the two tolerances taken from the capture module's own exported constants rather than written in
  • The three identities are asserted on ONE line set (three sources, fourteen use lines covering the closed use vocabulary, three paired transfers), as the re-derived worksheet states them, with the cash destination total equal to the funded-use total on that single year. The first derivation stated a cash destination total of $100,000 beside a funded-use total of $90,000; both are the same sum of fundedPlanDollars over the same use lines, so it was re-derived after the identity-total comments were completed, re-approved by the reviewer, and its test rebuilt and receipt re-executed on this pull request
  • The "strictly greater" rule is asserted directly: a cash difference of exactly the tolerance reconciles, and the worksheet's first wrong reading (judging the cash residual at the structural 1e-6 bound) is asserted to be rejected

  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: cash-flow-reconciliation-totals.md Mutation receipt: cash-flow-reconciliation-totals.mutation.md

  Evidence tests: annualCashFlowReconciliation.evidence.test.ts

  Implemented in: annualCashFlowReconciliation.ts; annualCashFlowCapture.ts; cashFlow.ts

  Is the number of: cash-flow-reconciliation-totals

Records that feed this number

• Cash-flow line amounts and the annual cash identity Composition record, justified by derivation

  Purpose: Which reported lines are cash on each side, so the same dollar is never counted twice.

  Statement: The Plan-dollar amounts on projection/internal/types/cashFlow.ts#YearCashFlowCashSourceLine, #YearCashFlowUseLine and #YearCashFlowTransferLine obey the source-side annual cash identity reconciled by projection/annualCashFlowReconciliation.ts#reconcileYearCashFlow: spendable sources plus portfolio funding plus loan proceeds equal funded household uses plus settled tax plus penalties plus contributions plus surplus investment. A #YearCashFlowPostSolveDepositLine sits outside that identity, as does a tax-character annotation. Units: nominal Plan USD. Rounding: none.

  Formula: sourceTotal = spendable + portfolioFunding + loanProceeds; destinationTotal = fundedUses + tax + penalties + contributions + surplus; difference = sourceTotal - destinationTotal

  • spendable: Spendable-source lines (unit: usd) (domain: role spendableSource)
  • portfolioFunding: Portfolio-funding lines (unit: usd) (domain: role portfolioFunding)
  • loanProceeds: Loan-proceeds lines (unit: usd) (domain: role loanProceeds)
  • postSolveDeposit: Receipt deposited after the solve (unit: usd) (domain: excluded from both sides)

  Timing: once per captured projection year

  Rounding: none

  Limits:

  • Asserted at the production reconciler with the worksheet's eight published totals as line amounts, plus its 5,000 post-solve life-insurance deposit and a 5,000 contribution transfer pair. Plan assumptions beyond the worksheet's inputs: the account and property identities the line ids carry, and the reconciler's own published tolerances, which are imported rather than written in
  • The identity is asserted on the published totals, not re-derived: the test reads sourceTotalPlanDollars, destinationTotalPlanDollars and differencePlanDollars from the reconciliation result

  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: cash-flow-line-plan-dollars.md Mutation receipt: cash-flow-line-plan-dollars.mutation.md

  Evidence tests: annualCashFlowReconciliation.evidence.test.ts

  Implemented in: cashFlow.ts; annualCashFlowReconciliation.ts

  Is the number of: cash-flow-line-plan-dollars

  Feeds: cash-flow-reconciliation-totals

• 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

• 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/cashFlow.ts (YearCashFlowCashIdentityTotals.sourceTotalPlanDollars / YearCashFlowUseIdentityTotals.fundedUsesPlanDollars, unfundedUsesPlanDollars / YearCashFlowTransferIdentityTotals.debitsPlanDollars, creditsPlanDollars)