v0.3: Required Savings solver, Fixed-Pct strategy, Black Swan + Withdrawal event fields on TimelineRow

[fall-development-rob]

Summary

Implements CONTRACT-016 (engine solver/strategy contract) plus the four supporting ADRs from the shore-crest-education foundation. Four headline changes:

1. findRequiredSavings reverse solver (ADR-025) — bisects contrib_amount over [0, upperBound] (default 100_000), capped at 24 iterations and 300 internal MC runs, returning the SolverResult shape from DDD-009. Mirrors findEarliestRetirementAge's call shape; the optimizer's public signature is unchanged.

2. Fixed-Pct withdrawal strategy (ADR-026) — adds calculateFixedPctWithdrawal({ fixed_withdrawal_pct, priorEndBalance, availableBalance? }) plus a 'Fixed-Pct' case on the dispatcher. The Scenario.withdrawal_strategy enum is widened additively (legacy scenarios still validate); fixed_withdrawal_pct defaults to 4 in DEFAULT_SCENARIO.

3. TimelineRow populated with black_swan_loss and withdrawal_event (ADR-026 / ADR-027) — every row in both runProjection and runAdvancedProjection now carries:

   • black_swan_loss: number (nominal-$ loss in the shock year, 0 everywhere else; advanced mode aggregates per-item losses across liquid investments only, per ADR-027 §2)
   • withdrawal_event: 'standard' | 'cut' | 'raise' | 'band' (cut/raise only when GK guardrails fire; band only when an Age-Banded phase matched; standard otherwise — including Fixed-Pct, per CONTRACT-016)

4. Sensitivity & Backtest force-disable Black Swan (ADR-027 §"Sensitivity ignores the shock" / §"Backtest ignores the shock") — runSensitivityAnalysis and runHistoricalBacktest clone the scenario and set black_swan_enabled: false before each per-band / per-window projection.

Schema mapping

CONTRACT-016 introduces new Guyton-Klinger field names (guyton_guard_up_pct, guyton_guard_down_pct, guyton_cut_pct, guyton_raise_pct, guyton_max_cut_per_year_pct). Per the engine-side constraint, the dispatcher maps the new names onto the existing gk_* engine internals rather than renaming. New names are accepted as optional Scenario fields and consulted first; legacy gk_* fields remain authoritative when the new names are absent.

Version

Bumped 0.2.0 -> 0.3.0. Not published to npm — this PR only pushes the branch.

Test plan

• npm run build clean
• npm run lint clean
• node src/__tests__/smoke.test.mjs — 22/22 assertions pass, covering:
  • calculateFixedPctWithdrawal returns 4% of prior balance with default params (incl. zero, cap, and negative-clamp edge cases)
  • runProjection populates black_swan_loss correctly on the shock year and zero elsewhere; every row has both new fields
  • runProjection with the runSensitivityAnalysis wrapper never receives black_swan_enabled: true and no projection produces a shock row
  • findRequiredSavings returns a feasible answer for a moderate scenario, respects the 24-iteration cap, and returns { feasible: false, reason: 'plan_never_succeeds' } when no solution exists
  • Fixed-Pct strategy runs end-to-end through runProjection with withdrawal_event === 'standard' per CONTRACT-016
• Calculator app picks up the rebuilt dist/ via the existing symlink at apps/calculator/node_modules/@robotixai/calculator-engine — verified locally; downstream UI agents (2b/2c/2d) will integrate.

References

• shore-crest-education docs/contracts/CONTRACT-016-engine-solver-strategy.md
• shore-crest-education docs/adrs/ADR-025-reverse-solvers.md
• shore-crest-education docs/adrs/ADR-026-withdrawal-strategies.md
• shore-crest-education docs/adrs/ADR-027-black-swan-stress-event.md