Spending excess shortfall annual

Unfunded optional spending above the ideal lifestyle amount in the projection year.

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

Appears in: csv (excessShortfall)

Calculation records

• Spending layer shortfall attribution Formula record, justified by derivation

  Purpose: Attribute annual spending misses to required, target, ideal and excess layers.

  Statement: spending/layers.ts#attributeShortfall first reduces the spending attempted after any guardrail cut by the withdrawal shortfall to obtain actually funded dollars, then attributes the miss of each layer against those dollars: the target miss includes the deliberate guardrail cut as well as every attempted dollar the portfolio could not produce; the required miss is the floor minus actually funded dollars, floored at zero; ideal and excess misses are the gaps in their successive layers. No rounding.

  Formula: A=max(0,F-max(0,W)); Rmiss=max(0,R-A); Tmiss=max(0,T-A); Imiss=I-max(0,min(I,A-T)); Xmiss=X-max(0,min(X,A-T-I))

  • R,T,I,X: Required, target, ideal increment, excess increment (unit: nominal USD/year) (domain: nonnegative; T >= R)
  • F: Spending attempted after any guardrail cut (fundedSpending) (unit: nominal USD/year) (domain: nonnegative)
  • W: Withdrawal shortfall: attempted dollars the waterfall could not produce (unit: nominal USD/year) (domain: nonnegative)
  • A: Actually funded dollars, F less W (unit: nominal USD/year) (domain: nonnegative)

  Timing: annual after spending and withdrawals

  Rounding: none

  Limits:

  • The first derivation read fundedSpending as delivered dollars and expected a $15 target miss where production returns $20; the doc comment says attempted, so the worksheet was re-derived and now carries a second case (F=62, W=5) that exposes the guardrail cut in the required miss.

  Provenance: derived by codex, implemented by codex.

  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-layer-shortfall-attribution.md Mutation receipt: spending-layer-shortfall-attribution.mutation.md

  Evidence tests: layers.evidence.test.ts

  Implemented in: layers.ts

  Is the number of: spending-required-shortfall-annual, spending-target-shortfall-annual, spending-ideal-shortfall-annual, spending-excess-shortfall-annual

  Feeds: display-upside-shortfall-annual

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