Spending excess requested annual

Optional spending above the ideal lifestyle amount attempted during the projection year.

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

Appears in: csv (excessSpending)

Calculation records

• Annual excess-layer requested spending Composition record, justified by derivation

  Purpose: The incremental opportunistic layer above ideal spending.

  Statement: projection/internal/annualExpenseSummary.ts#annualExpenseSummary publishes YearExpenses.excessSpending as excessSpendingBase + skippedExcessNominal, with excessSpendingBase = excessLifestyle + excessGoalsFunded. It is an increment above ideal, so the identity the worksheet derives holds exactly: excessSpending = intendedSpending - targetSpending - idealSpending. Units: nominal USD per year. Rounding: none.

  Formula: excessSpending = excessLifestyle + excessGoalsFunded + skippedExcessNominal = intendedSpending - targetSpending - idealSpending

  • excessLifestyle: Annual opportunistic lifestyle layer above ideal (unit: usd/year) (domain: nonnegative)
  • excessGoalsFunded: Excess-classified goals funded this year (unit: usd/year) (domain: nonnegative)
  • skippedExcessNominal: Nominal amount of excess-classified goals the scheduler skipped (unit: usd/year) (domain: nonnegative)

  Timing: once per projection year, at the expense summary

  Rounding: none

  Limits:

  • Asserted at the annualExpenseSummary seam, which is the function that computes all five layer fields at once, because the worksheet states its inputs as published year-row components. The seam call is given inputs that realize the worksheet's stated requiredSpending, targetSpending, idealSpending and intendedSpending exactly, and the published excessSpending is then read
  • The identity is asserted against the same call's other published fields rather than re-entered constants
  • Failing to remove the ideal increment, or treating excess as everything above required, are the worksheet's two wrong readings and are asserted against

  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: spending-excess-requested-annual.md Mutation receipt: spending-excess-requested-annual.mutation.md

  Evidence tests: annualExpenseSummary.evidence.test.ts

  Implemented in: annualExpenseSummary.ts

  Is the number of: spending-excess-requested-annual

  Feeds: display-upside-spending-annual

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