Spending required shortfall annual

Unfunded essential spending in the projection year.

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

Appears in: csv (requiredShortfall); results-table (Layer miss "Req"); scenarios-page (Annual "Required shortfall" and lifetime "Required-floor shortfall")

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

Records that feed this number

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

  Purpose: The must-fund layer a guardrail policy never cuts below, including goals it skipped.

  Statement: projection/internal/annualExpenseSummary.ts#annualExpenseSummary publishes YearExpenses.requiredSpending as requiredSpendingBase + skippedRequiredNominal, where requiredSpendingBase = systemRequired + requiredLifestyle + requiredGoalsFunded. systemRequired is the five system-computed costs the caller has already folded: debt service, property costs, healthcare, insurance premiums and net long-term care, the last being gross care cost less the LTC policy benefit. A required-classified goal the flexible-goal scheduler skipped stays in this layer as intended spending that never happened. Units: nominal USD per year. Rounding: none.

  Formula: requiredSpending = (systemRequired + requiredLifestyle + requiredGoalsFunded) + skippedRequiredNominal; systemRequired = debtService + propertyCosts + healthcare + insurancePremiums + careCost - ltcBenefit

  • systemRequired: The five system-computed costs, net of the LTC benefit (unit: usd/year) (domain: nonnegative in practice)
  • requiredLifestyle: Required-floor lifestyle layer (unit: usd/year) (domain: nonnegative)
  • requiredGoalsFunded: Required-classified goals funded this year (unit: usd/year) (domain: nonnegative)
  • skippedRequiredNominal: Nominal amount of required-classified goals the scheduler skipped (unit: usd/year) (domain: nonnegative; 0 outside guardrails)

  Timing: once per projection year, at the expense summary

  Rounding: none

  Limits:

  • Asserted at the annualExpenseSummary seam, which is the function that computes the field, because the worksheet states its inputs as already-folded year-row components: a real plan cannot present a chosen debt service, property cost, healthcare charge, care cost, LTC benefit and skipped-goal amount simultaneously at those exact values. The five system costs enter the seam as the systemRequired scalar the caller folds, so the test folds them the way the caller does and asserts the published field against the worksheet
  • The net-LTC term is gross care cost less the benefit; adding the gross without the offset is one of the worksheet's wrong readings
  • The layer summaries are not additional members of expenses.total; this figure describes how baseSpending was built

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

  Evidence tests: annualExpenseSummary.evidence.test.ts

  Implemented in: annualExpenseSummary.ts

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

  Feeds: spending-required-shortfall-annual

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